API
API
1. Общий принцип работы
Все запросы отправляются по протоколу HTTP на адрес http://api.kma1.biz/. Метод запроса - GET или POST (для больших запросов рекомендуем использовать метод POST, поскольку GET имеет ограничения на размер запроса). Обязательными полями являются:
method - метод запроса, полный список методов тут;
authid - ID авторизации, не используется в методе auth, о получении ID см. раздел авторизация;
authhash - авторизационный хэш, аналогично authid генерируется при авторизации.
Все остальные параметры зависят от метода, который вызывается.
Сама работа производится по следующему принципу:
- отправляем запрос авторизации;
- получаем в ответ ID и хэш для отправки любых других запросов;
- сохраняем ID и хэш;
- с полученными авторизационными данными делаем запросы к серверу.
Внимание!
На время бета-тестирования действует временное ограничение на запросы - 100 запросов в минуту. При превышении числа запросов в результате будет приходить ошибка. Помните: даже запрос с ошибкой учитывается в количестве запросов! Т.е. если вы получили ошибку "Timeout error!" - от времени запроса с ошибкой надо отсчитать 5 секунд и только тогда делать следующий.
Это не распространяется на запросы авторизации - их таймаут учитывается отдельно и составляет 10 секунд (из соображений безопасности). Т.е. делать запросы авторизации чаще, чем раз в 10 секунд нельзя, но можно сразу после запроса авторизации делать запрос любого другого метода АПИ.
Ответ на запрос приходит в формате JSON. Обязательными полями ответа являются:
code - код ошибки (если 0 - ошибки небыло);
msg - текст сообщения об ошибке (если нет ошибки - пустое поле).
Все остальные поля ответа зависят от запрашиваемого метода.2. Авторизация
Авторизация производится один раз, результатом успешной авторизации является получение хэша и ID авторизации, которые потом можно будет применять в запросах. Авторизацию можно пройти повторно - ID будет возвращен старый, хэш обновится. Срока давности хэш не имеет.
Параметры запроса для авторизации:
method=auth - метод auth;
username=[email] - e-mail, указанный вами при регистрации;
pass=[password] - пароль для входа в кабинет адверта.
Пример запроса авторизации (здесь и далее в примерах для наглядности используется метод GET):
http://api.kma1.biz/?method=auth&username=vasia@pupkin.ru&pass=myGreatPass
Если в ходе запроса не возникло ошибок, ответ будет примерно таким:
{"code":0,"msg":"","authid":100,"authhash":"65c6b816fc4e5a47fb1d5ceb5f3ca802"}
Соответственно поля authid и authhash сохраняем для дальнейшего применения в запросах.3. Доступные методы
auth
Запрос авторизации. Подробности в разделе "Авторизация".getoffers
Получение списка офферов. Никаких входящих параметров не требуется. В случае успешного выполнения запроса в итоговом выводе будет массив offers, содержащий следующие поля:
_id - идентификатор оффера;
name - название оффера;
logo - полный путь к логотипу;
target - целевое действие (заявка, подтвержденная заявка и т.п.);
codes - список кодов стран, где доступен оффер, с комиссиями по странам (если пусто - доступен везде);
itemprice - цена товара по каждому ГЕО (по умолчанию 0);
comission - базовый размер отчислений, если нет отдельных комиссий по странам (руб.);
offerlevel - уровень оффера;
sources - источники траффика;
category - категория оффера.
Если оффер доступен везде - то поле codes будет пустым, а комиссия будет в поле comission. Если для оффера есть разделение комиссий по странам, то в поле comission будет 0, а в поле codes будет массив, где ключом является код страны, а значением - комиссия в рублях для этой страны.
getlandings
Получение списка лендингов для оффера. Поля для передачи:
campaignid - ID оффера.
В случае успешного выполнения запроса в итоговом выводе будет массив landings, содержащий следующие поля:
name - название лендинга;
url - ссылка для перехода.
getlayers
Получение списка прелендингов для оффера. Поля для передачи:
campaignid - ID оффера.
В случае успешного выполнения запроса в итоговом выводе будет массив layers, содержащий следующие поля:
name - название прелендинга;
url - ссылка для перехода;
land_url - ссылка на лендинг.getnews
Получение списка новостей для оффера или за определенную дату. Поля для передачи:
campaignid - ID оффера;
date - дата в формате "YYYY-MM-DD".
Как минимум один из параметров должен быть указан. Если указан campaignid - будут возвращены новости только по данному офферу. Если указать только дату - будут возвращены все новости за указанную дату. В случае успешного выполнения запроса в итоговом выводе будет массив news, отсортированный в порядке добавления новостей и содержащий следующие поля:
datetime - дата и время новости;
title - заголовок новости;
text - текст новости.getstatuses
Получение статусов заказов. Поля для передачи:
campaignid - ID оффера, к которому относится заказ (возвращается в постбэке, в поле {campaignid});
ids - список номеров заказов, текстом через запятую.
Пример запроса:
http://api.kma1.biz/?method=getstatuses&authid=100&authhash=65c6b816fc4e5a47fb1d5ceb5f3ca802&campaignid=686f236a&ids=10500037
Пример ответа:
{"code":0,"msg":"","statuses":[{"id":"10500037","status":"D","comment":"Отклонен"}]}
В поле statuses содержится массив статусов (для тех заказов, которые были обнаружены), а именно:
id - id заказа;
comment - текстовый комментарий от рекламодателя, где он указывает причину отклонения, а также статус выкупа;
status - статус заказа:
- P - в обработке;
- A - принят;
- D - отклонен;
- F - фейк.
Внимание!
На стадии бета-тестирования допускается не более 10 000 номеров заказов в одном запросе. При передаче большего количества номеров будут возвращены статусы только первых 10 000, остальные проигнорированы. Сообщение об ошибке при этом не выводится.
addlead
Передача лидов.
Обязательные параметры:
name - имя заказчика;
phone - телефон заказчика;
channel - код потока;
ip - IP адрес заказчика.
Необязательные параметры:
data1 - субайди 1;
data2 - субайди 2;
data3 - субайди 3;
data4 - субайди 4;
data5 - субайди 5;
ismobile - признак мобильного лида, 1 - мобильный, 0 - обычный
return_page - если указана переменная со значением 1, тогда в ответе будет html страница успешного заказа.
Пример запроса:
http://api.kma1.biz/?method=addlead&authid=100&authhash=65c6b816fc4e5a47fb1d5ceb5f3ca802&name=Петр&phone=89992340984&channel=Uey384&ip=95.28.123.56&ismobile=1
Пример ответа:
{"code":0,"msg":"","orderid":1003748811}Внимание!
Необходимая кодировка - UTF-8, время жизни authid и authhash - до следующей авторизации.
getbalance
Получение информации о балансе.
Параметров нет.
В случае успешного выполнения запроса в ответе будет массив balance, содержащий следующие поля:
pending - массив баланса в ожидании;
hold - массив баланса в холде;
approve - массив баланса доступного к выводу.
Пример запроса:
http://api.kma1.biz/?method=getbalance&authid=100&authhash=65c6b816fc4e5a47fb1d5ceb5f3ca802
Пример ответа:
{"balance": {"pending": {"RUB": 123, "USD": 456, "EUR": 789}, "hold": {"RUB": 123, "USD": 456, "EUR": 789}, "approve": {"RUB": 123, "USD": 456, "EUR": 789}}}4. Сообщения об ошибках
В случае возникновения в ходе работы скрипта ошибки ответ сервера будет выглядеть примерно так:
{"code":2,"msg":"Invalid request data!"}
Список сообщений об ошибках с кодами:
1: "Invalid request" - запрос не соответствует формату (например, нет поля method);
2: "Invalid request data!" - отсутствуют обязательные для запроса поля (authid, например);
3: "Username or pass incorrect!" - при авторизации неверно указаны имя пользователя или пароль;
4: "Timeout error!" - вы шлете запросы слишком часто. Подробнее в разделе "Общий принцип работы";
5: "Internal error!" - непредвиденная ошибка, обратитесь к разработчикам;
6: "Invalid auth data!" - некорректный authid или authhash;
7: "Invalid method!" - метод не найден на сервере. Список поддерживаемых методов можно найти тут: Доступные методы;
8: "[some_text]" - ошибка возникла при выполнении метода. Детальное описание будет в поле msg ответа, код у всех "ошибок метода" одинаковый;
9: "Permission denied" - нет прав доступа на добавление лида по API;
10: "Something wrong, try later." - возникла неизвестная ошибка. Повторите запрос через 1 минуту.