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 минуту.