Keysa REST API

API служит для получения доступа к работе с запросами в проектах, а также автоматизации работы с нашим сервисом и ещё более быстрого составления рекламных кампаний

Общие сведения:

  • Весь API работает по протоколу HTTPS
  • Авторизация осуществляется по при помощи авторизационного ключа в заголовках запроса
  • Все данные доступны только в формате JSON
  • Базовый домен — api.keysa.ru
  • Все ответы сервиса в кодировке UTF-8
  • Все запросы к сервису должны быть в кодировке UTF-8
  • API широко использует информирование при помощи кодов ответов HTTP
  • Используемые технологии: HTTP/1.1, JSON, URI Template, REST
  • Для связи по вопросам работы с API, а так же в случае найденных ошибок пользуйтесь электронной почтой api@keysa.ru

API keysa.ru может использоваться для загрузки запросов из сторонних программ-сборщиков в нашу базу данных, выгрузки списка запросов и управления списками кейсов.




Для получения ключа необходима авторизация



Документация:

Общие положения

  • Все запросы к API производятся на URL https://keysa.ru
  • Все параметры запросов передаются в заголовках запроса вида X-Request-*
  • Авторизация в сервисе осуществляется в заголовках запроса вида X-Auth-*
  • Для всех запросов к серверу необходимо указывать используемую верию API. Текущая версия является 1 (первой).
    Пример: X-Request-Ver: 1
  • В общем виде ответы сервиса имеют вид: {"result": 1, ..}, где result может быть 1 (в случае успешного ответа) и 0 (в случае ошибки). В последнем случае ответ сервиса будет выглядеть следующим образом: {"result":0, "errors": ["Текст первой ошибки", "Текст второй ошибки"]}

Авторизация

Авторизация в сервисе производится при помощи двух заголовков: X-Auth-Id, который является вашим идентификатором и X-Auth-Key, который является уникальным ключом доступа к API. Эти заголовки должны передаваться вместе с каждым запросом к сервису.
Пример на PHP:

$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$options = array(
	CURLOPT_URL    => "https://keysa.ru/sites/",
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

Коды ответов HTTP

Помимо текстового вывода ошибок API также возвращает ошибки кодами HTTP. Ниже представлена таблица с возможными ответами.

Код Описание
200 Запрос успешно выполнен
404 Запрашиваемый URL не найден в сервисе
409 Не указана версия API в заголовке запроса X-Request-Ver, или указанная версия недоступна
401 Авторизация в сервисе не пройдена, проверьте заголовки запроса X-Auth-Id и X-Auth-Key
400 Запрос невозможно выполнить с переданными параметрами. Подробный текст ошибки необходимо искать в возвращаемых данных
405 HTTP метод запроса не поддерживается сервисом. Сверьтесь с документацией

Управление проектами

URL запроса: /sites/
GET

Возвращает список проектов

Необязательные заголовки запроса
Заголовок Значение
X-Request-Archive Указатель на выборку архивных проектов. Если нужно получить список архивированных проектов необходимое значение в таком случае — 1. В противном случае — 0.

GET /sites/ HTTP/1.1

Пример ответа:

{
"result":1,
"items":[
		{
		"id":186,
		"name":"Тестовый проект",
		"cdate":"2016-03-02 01:15:27",
		"cdate_rus":"2 марта 2016 г. 01:15"
		}
	]
}

Расшифровка массива items

Поле Значение
id Уникальный идентификатор проекта
name Имя проекта. Задается пользователем
cdate Дата создания проекта в формате ГГГГ-ММ-ДД ЧЧ:ММ:СС
cdate_rus Дата создания проекта на русском языке, более понятная человеку

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$url = "/sites/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "GET",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

POST

Создает проект

Обязательные заголовки запроса
Заголовок Значение
X-Request-Name Название создаваемого проекта закодированное в base64

POST /sites/ HTTP/1.1

Пример ответа:

{"result":1,"id":187}
Поле Значение
id Уникальный идентификатор созданного проекта

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Name: ".base64_encode("Новый проект");
$url = "/sites/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "POST",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

DELETE

Удаляет проект

Обязательные заголовки запроса
Заголовок Значение
X-Request-Id Уникальный идентификатор проекта, который необходимо удалить

DELETE /sites/ HTTP/1.1

Пример ответа:

{"result":1}

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Id: 187";
$url = "/sites/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "DELETE",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

PUT

Обновление имени проекта

Обязательные заголовки запроса
Заголовок Значение
X-Request-Id Уникальный идентификатор проекта, которому требуется обновить название
X-Request-Name Новое название проекта закодированное в base64

PUT /sites/ HTTP/1.1

Пример ответа:

{"result":1}

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Id: 187";
$add_headers[] = "X-Request-Name: ".base64_encode("Мой проект");
$url = "/sites/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "PUT",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

PATCH

Запуск обработки проекта. После загрузки ключевых слов в проект он «замораживается» и ожидает либо дальнейшей догрузки ключевых слов, либо выполнения этой команды. Команда обрабатывает загруженные запросы и позволяет с ними работать пользователю в дальнейшем

Обязательные заголовки запроса
Заголовок Значение
X-Request-Id Уникальный идентификатор проекта, который будет отправлен на обработку

PATCH /sites/ HTTP/1.1

Пример ответа:

{"result":1}

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Id: 187";
$url = "/sites/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "PATCH",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

OPTIONS

Архивация или разархивация проекта. Если в настоящий момент проект в архиве - будет выполнена разархивация. Если в настоящий момент проект рабочий, то будет выполнена архивация

Обязательные заголовки запроса
Заголовок Значение
X-Request-Id Уникальный идентификатор проекта, который будет отправлен на архивацию/разархивацию

OPTIONS /sites/ HTTP/1.1

Пример ответа:

{"result":1}

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Id: 187";
$url = "/sites/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "OPTIONS",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

Управление кейсами в проекте

URL запроса: /sites/lists/
GET

Возвращает список кейсов в проекте

Обязательные заголовки запроса
Заголовок Значение
X-Request-Site Уникальный идентификатор проекта, для которого нужно получить список кейсов.

GET /sites/lists/ HTTP/1.1

Пример ответа:

{
"result":1,
"items":[
		{
		"id":241,
		"name":"ноутбуки",
		"nqueries":73,
		"direct_error":0,
		"adwords_error":0
		}
	]
}

Расшифровка массива items

Поле Значение
id Уникальный идентификатор кейса
name Имя кейса
nqueries Кол-во запросов в кейсе
direct_error Наличие ошибок в заполнении РК для Я.Директ
adwords_error Наличие ошибок в заполнении РК для Adwords

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Site: 123456";
$url = "/sites/lists/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "GET",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

POST

Создает новый кейс в проекте

Обязательные заголовки запроса
Заголовок Значение
X-Request-Site Уникальный идентификатор проекта, в котором нужно создать кейс
X-Request-Name Название создаваемого проекта закодированное в base64

POST /sites/lists/ HTTP/1.1

Пример ответа:

{"result":1,"id":187}
Поле Значение
id Уникальный идентификатор созданного проекта

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Site: 123456";
$add_headers[] = "X-Request-Name: ".base64_encode("Новый кейс");
$url = "/sites/lists/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "POST",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

DELETE

Удаляет кейс из проекта. После удаление запросы из кейса попадают в "неразобранное"

Обязательные заголовки запроса
Заголовок Значение
X-Request-Site Уникальный идентификатор проекта, в котором необходимо удалить кейс
X-Request-Id Уникальный идентификатор кейса, который необходимо удалить

DELETE /sites/lists/ HTTP/1.1

Пример ответа:

{"result":1}

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Id: 187";
$add_headers[] = "X-Request-Site: 123456";
$url = "/sites/lists/";
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "DELETE",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

Управление запросами в проекте

URL запроса: /sites/queries/
POST

Добавляет запросы в проект. Добавлять запросы в проект можно несколькими запросами. Доступно добавление запросов как строк, так и JSON (см. пример). После окончания добавления необходимо обратиться к методу PATCH /sites/

Обязательные заголовки запроса
Заголовок Значение
X-Request-Site Уникальный идентификатор проекта, в который загружаются запросы.

POST /sites/queries/ HTTP/1.1

Пример ответа:

{"result":1}

Пример запроса на PHP:

$baseurl = "https://keysa.ru";
$curl = curl_init();
$add_headers = [];
$add_headers[] = "X-Auth-Id: 123456";
$add_headers[] = "X-Auth-Key: c4ca4239a0b923820ecc509a6f75849b";
$add_headers[] = "X-Request-Ver: 1";
$add_headers[] = "X-Request-Site: 123456";
$url = "/sites/queries/";
// вариант 1 отправки запросов
$body = "купить ноутбук\nкупить ноутбук в москве\nкупить б/у ноутбук в москве";
// вариант 2 отправки запросов
$body = json_encode ( 
	array (
		0 => 'купить ноутбук',
		1 => 'купить ноутбук в москве',
		2 => 'купить б/у ноутбук в москве',
	)
);
$options = array(
	CURLOPT_URL    => $baseurl.$url,
	CURLOPT_FOLLOWLOCATION => false,
	CURLOPT_CUSTOMREQUEST => "POST",
	CURLOPT_HTTPHEADER => $add_headers,
	CURLOPT_HEADER => false,
	CURLOPT_RETURNTRANSFER => 1,
	CURLOPT_TIMEOUT    => 5,
	CURLOPT_SSLVERSION => 1,
	CURLOPT_POSTFIELDS => $body,
	CURLOPT_SSL_VERIFYPEER => 0, 
	CURLOPT_SSL_VERIFYHOST => 0,
);
curl_setopt_array($curl, $options);
$response = json_decode(curl_exec($curl));

Зарегистрируйтесь
и попробуйте бесплатно!

Используйте для логина только латинские символы, цифры, знак минус и подчёркивание
Необходим для подтверждения вашей регистрации и уведомлений.
Ваш пароль для авторизации на сайте.
Проверка пароля.
close
loader

Обработка данных...