Описание АПИ - интерфейса
(API - application programming interface)
для программного взаимодействия с сервисом
Подключение к АПИ
Подключение к АПИ доступно только зарегистрированным пользователям. Для выполнения запроса на постановку ордера требуется получить в личном кабинете код подтверждения. Для оплаты ордера с личного счета нужно пополнить баланс .
Для активации АПИ нужно обратиться в поддержку с темой «Подключение АПИ» и предоставить Ваш логин и IP-адрес сервера, с которого будут осуществляться запросы. После одобрения и активации АПИ Вы получите идентификатор, который должен отправляться в каждом запросе (параметр “id’).
Структура запросов и ответов
Запросы и ответы выполняются согласно спецификации JSON-RPC 2.0
Все запросы отправляются по адресу https:///api/
* все запросы содержат идентификатор запроса "id", который возвращается в ответах
* все запросы в параметрах содержат секцию идентификации: "secure":{"login":"ВашЛогин","pass":"ВашПароль"}
* любые непредусмотренные параметры игнорируются
* все ответы содержат секцию "error", которая в случае ошибки содержит код и описание ошибки, а в случае удачи – не содержит данных.
Запрос содержит id, метод и параметры.
id - "id" - идентификатор, полученный в поддержке при регистрации API,
метод - "method" - указывает серверу, какая операция должна быть выполнена,
параметры - "params" - содержат секцию "secure" для идентификации на сервере, и перемерты, необходимые для конкретного метода,
например:
{"jsonrpc":"2.0","id":"Ваш_id","method":"get_valute","params":{"operator":"kievstar","secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
Ответ содержит id, результат в случае удачного завершения, или код и описание ошибки,
например:
{"jsonrpc":"2.0","id":"Ваш_id,"error":"","result":{"valute":"UAH"}}
В случае ошибки:
{"jsonrpc":"2.0","id":Ваш_id,"error":{"code":-32601,"message":"Method not found"}}
Запросы могут быть Информационные и Платежные.
Более подробно каждый запрос будет рассматриваться ниже.
Информационные запросы
get_balance - получение баланса Личного счета.
параметры: - не требуются
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"get_balance",”params":{"secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа: {"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"balance":"15.4264"}}
get_history - получение истории по счету.
параметры:
last - (необязательный) вывести последние операции. При отсутствии параметра выводятся ВСЕ операции.
mode - (необязательный) - режим вывода [api, receive, spend, all]
api - операции через АПИ,
receive - получено,
spend - отправлено,
all - ВСЕ.
При отсутствии параметра выводятся ВСЕ операции.
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"get_balance","params":{"last":"5","mode":"api","secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа:
{"jsonrpc":"2.0","id":Ваш_id,"error":"","result":[
{"timestamp":"1532130832","data":"Jul 21 2018 02:53:52","operation":"tricolor_ediny 37001234567890 1000RUR","batch":"15321308329826","amnt":"-16.22","mode":"api"}]}
get_available - получение списка с указанием категорий и стран доступных операторов/провайдеров.
параметры: - не требуются
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"get_available","params":{"secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа:
{"jsonrpc":"2.0","id":Ваш_id,"error":"", "result":{"sng":{"mobileru":["mts","beeline","tele2","megafon","motiv","yotaphone"] ...
* вывод в формате: категория -> страна -> оператор/провайдер
** категории: sng - мобильные, phones - стационарные, inettv - провайдеры интернет/тв, other - другие
list_available - получение списка БЕЗ указания категорий и стран доступных операторов/провайдеров.
параметры: - не требуются
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"list_available","params":{"secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа:
{"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"operator":["mts","beeline","tele2","megafon" ...
get_operator_properies - получение свойств оператора.
параметры:
operator - (обязательный) название оператора (должно быть в списке доступных операторов/провайдеров).
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"get_operator_properies","params":{"operator":"tricolor","secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа:
{"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"tricolor":{
"nameRu":"Триколор ТВ",
"nameEn":"Tricolor TV",
"operator_link":"http://www. tricolor. tv/",
"digits_count":"12-14",
"ex_num":"",
"min_sum":"40",
"max_sum":"",
"sim":"",
"region_ru":"тип платежа",
"region_en":"payment type",
"fieldnameru":"ID приемника",
"fieldnameen":"receiver ID",
"pattern":"",
"instant":0,
"ps":""}}}
назначение полей:
nameRu, nameEn - название рус/англ.
operator_link - ссылка на сайт оператора/провайдера
digits_count - число цифр в номере
ex_num - образец номера телефона/провайдера
min_sum, max_sum - мин/макс. допустимая сумма к оплате
region_ru, region_en - рус/англ. название дополнительного поля, например, тип платежа, регион и т. д
fieldnameru, fieldnameen - рус/англ название данных, которые должно содержать поле [account] для методов [get_for_pay] и [set_order]
pattern - шаблон для поля [account] методов [get_for_pay] и [set_order]
instant - моментальное пополнение или нет (на данный ммент ВСЕ пополнения в ручном режиме)
sim, ps - служебные поля или не используется
* если оператор имеет дополнительное поле [регион], выводится список регионов, например:
"payment type":{"ediny":"Пакет «Единый»", "childmonth":"Пакет «Детский месяц»", "allfutball":"Пакет «Весь футбол»", ...
get_region - получение поля [регион] (если есть) в виде списка.
параметры:
operator - (обязательный) название оператора (должно быть в списке доступных операторов/провайдеров).
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"get_region","params":{"operator":"tricolor","secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа:
{"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"region":["ediny","childmonth","childyear","multiroom", … ]}}
get_valute - получение валюты, поступающей на счет оператора/провайдкера.
параметры:
operator - (обязательный) название оператора (должно быть в списке доступных операторов/провайдеров).
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"get_valute","params":{"operator":"tricolor","secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа: {"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"valute":"RUR"}}
Запросы на получение суммы к оплате
* методы "get_for_pay" и "multi_for_pay" рекомендуется использовать для проверки правильности данных для пополнения (оператор, сумма, номер счета оператора/провайдера)
** суммы к оплате, полученные методами "get_for_pay" и "multi_for_pay" могут незначительно отличаться от реальных сумм к оплате, полученных методами "set_order" и "multi_order"
* если запросы не содержат параметра pay_method – будет получена сумма к оплате с личного счета
** если pay_method указан – будет получена сумма к оплате в валюте выбранной платежной системы
get_for_pay - получение суммы к оплате.
параметры:
operator - (обязательный) название оператора (должно быть в списке доступных операторов/провайдеров).
region - (если есть - обязательный, если нет - не должно быть) название региона (должно быть в списке, полученном методом [get_region]).
Account(обязательный) номер телефона/счета.
sum - (обязательный) сумма пополнения (не должна быть меньше min_sum и больше max_sum. если max_sum не указана - без ограничений).
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"get_for_pay","params":{"operator":"tricolor","secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа: {"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"amount":"0.78"}}
multi_for_pay - получение суммы к оплате для мульти-ордеров.
параметры:
параметры должны содержать секцию "orders", состоящую из нескольких объектов - ордеров:
operator - (обязательный) название оператора (должно быть в списке доступных операторов/провайдеров).
region - (если есть - обязательный, если нет - не должно быть) название региона (должно быть в списке, полученном методом [get_region]).
Account(обязательный) номер телефона/счета.
sum - (обязательный) сумма пополнения (не должна быть меньше min_sum и больше max_sum. если max_sum не указана - без ограничений).
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"multi_for_pay","params":{"orders":[
{"operator":"tricolor","sum":50,"account":"48012345678910","region":"personal"},
("operator"=>"kievstar","sum"=>21,"account"=>"0981234567")],
"secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа:
{"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"orders":[
{"operator":"tricolor","sum":40,"account":"48012345678910","region":"personal","order_result":{"amount":"0.61"}},
{"operator":"kievstar","sum":21,"account":"0981234567","order_result":{"amount":"0.78"}}],
"amount":2.13}}
Платежные запросы
* Запросы должны содержать обязательный параметр [Код Подтверждения](pin) в секции идентификации:
"secure":{"login":"ВашЛогин","pass":"ВашПароль","pin":"КодПодтверждения"}
set_order - постановка ордера на пополнение.
параметры:
operator - (обязательный) название оператора (должно быть в списке доступных операторов/провайдеров).
region - (если есть - обязательный, если нет - не должно быть) название региона (должно быть в списке, полученном методом [get_region]).
Account(обязательный) номер телефона/счета.
sum - (обязательный) сумма, на которую нужно пополнить счет телефона/провайдера (не должна быть меньше min_sum и больше max_sum. если max_sum не указана - без ограничений).
образец запроса: {"jsonrpc":"2.0","id":Ваш_id,"method":"set_order","params":{"operator":"tricolor","sum":50,"account":"48012345678910","region":"personal","secure":{"login":"ВашЛогин","pass":"ВашПароль","pin":"КодПодтверждения"}}}
образец ответа: {"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"order_id":"103481","transaction_id":"15326946612906"}}
multi_order - постановка мульти-ордеров на пополнение.
параметры должны содержать секцию "orders", состоящую из нескольких объектов - ордеров:
параметры:
operator - (обязательный) название оператора (должно быть в списке доступных операторов/провайдеров).
region - (если есть - обязательный, если нет - не должно быть) название региона (должно быть в списке, полученном методом [get_region]).
Account(обязательный) номер телефона/счета.
sum - (обязательный) сумма, на которую нужно пополнить счет телефона/провайдера (не должна быть меньше min_sum и больше max_sum. если max_sum не указана - без ограничений).
образец запроса: {"jsonrpc":"2.0","id":Ваш_id,"method":"multi_order","params":{"orders":[
{"operator":"tricolor","sum":50,"account":"48012345678910","region":"personal"},
{"operator":"kievstar","sum":21,"account":"0981234567"}],
"secure":{"login":"ВашЛогин","pass":"ВашПароль","pin":"КодПодтверждения"}}}
образец ответа: {"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"orders":[
{"operator":"tricolor","sum":40,"account":"48012345678910","region":"personal","order_result":{"amount":"0.61","order_id":"104985","transaction_id":"15346240635338"}},
{"operator":"kievstar","sum":21,"account":"0981234567","order_result":{"amount":"0.78","order_id":"104987","transaction_id":"15346240639086"}}],
"amount":1.39,"order_id":"104986","transaction_id":"15346240633318","pay_account":""}
check_order - проверка статуса ордера.
- в связи с тем, что пополнение выполняется в ручном режиме, проверять статус следует с интервалом 3-4 минуты (т. к. информация о поступивших платежах обновляется каждые 3 минуты)
параметры:
order_id - (обязательный) номер заявки (полученный методом [set_order]).
transaction_id - (обязательный) номер транзакции (полученный методом [set_order]).
образец запроса: {"jsonrpc":"2.0",”method":"check_order","params":{"order_id":"103481","transaction_id":"15326946612906","secure":{"login":"ВашЛогин","pass":"ВашПароль"}}}
образец ответа: {"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"status":"in_process..."}}
* некоторые варианты статуса:
0 : - ордер не оплачен или в ожидании оплаты
in_process... : - ордер в процессе выполнения
1 : - ордер выполнен
WAIT : - ордер в ожидании (возможно: проблемы с пополнением, пользователю отправлено сообщение, пополнение временно недоступно и др.)
RETURN : - средства возвращены пользователю
Платежные запросы с пост-оплатой
Сценарий запроса с пост-оплатой:
Создать ордер или мульти-ордер,Параметры для методов set_order и multi_order должны содержать дополнительный параметр pay_method.
Возможные значения pay_method : (“PM”: Perfect Money, “payeer”: payeer, “BTC”: BitCioin, “p24noFee” приват24 без комиссии, “pers” : личный счет)
Если указан pay_method “pers” (или не указан параметр pay_method) – оплата будет осуществлена с личного счета
образец запроса:
{"jsonrpc":"2.0","id":Ваш_id,"method":"set_order",
"params":{“pay_method“:”PM”,"operator":"kievstar","sum":21,"account":"0981234567","secure":{"login":"ВашЛогин","pass":"ВашПароль","pin":"КодПодтверждения"}}}
*результат будет содержать кроме order_id и transaction_id реквизиты для оплаты - pay_account – аккаунт/адрес/карту для оплаты, и amount – сумму к оплате.
образец ответа: {"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"order_id":"103481","transaction_id":"15326946612906",”pay_account”:”U1398029”,”amount”:”0.67”}
Оплатить ордер через Ваш АПИ платежной системы, указанной в параметре pay_method.Номер транзакции “batch_num” будет использован для метода payment_notice.
Сообщить об оплате методом payment_notice. Параметры order_id и transaction_id – получены методом set_order или multi_order.образец запроса:
{"jsonrpc":"2.0",”method":"payment_notice","params":{“pay_method“:”PM”,"order_id":"103481","transaction_id":"15326946612906",”batch_num”:” 225990376”}}
образец ответа:
{"jsonrpc":"2.0","id":Ваш_id,"error":"","result":{"status":"in_process...","batch":"225990376"}}
Образец скрипта для работы с платежными запросами с пост-оплатой можно скачать на странице описания АПИ
Данный скрипт содержит функции и классы для работы с платежными системами, а также ссылки на описание и инструкции по установке и настройке АПИ платежных систем.
На данный момент доступны такие платежные системы: Perfect Money, Payeer, BitCoin и Приват24
Возможные ошибки
wrong_id: - неверный параметр “id”
ip_not_mach: - IP-адрес не совпадает с зарегистрированным
not_permissions: - для доступа к АПИ Вы не имеете полномочий/не зарегистрированы/заблокированы
method_not_set, incorrect_method: - запрос не содержит метод, или указан несуществующий метод
login_not_found: - нет пользователя с таким логином
incorrect_password, incorrect_pin: - неверный пароль, неверный Код Подтверждения
operator_not_set, operator_not_exist: - оператор отсутствует в запросе или нет такого оператора
account_notmatch_pattern: - номер телефона/счета не соответствует шаблону
sum_not_set, sum_isnot_int, sum_less_min, sum_more_max: - сумма отсутствует в запросе, не целое число, больше или меньше допустимой
order_id_not_set, transaction_id_not_set: - отсутствуют обязательные параметры для проверки ордера
order_notfound_in_database: - ордер не найден в базе данных
operator_not_have_region, region_not_set, region_not_exist: - оператор не содержит регион, регион отсутствует в запросе, нет такого региона
insufficient_funds: - недостаточно средств на личном счете для постановки ордера на пополнение
unknown_valute: - не удалось получить валюту оператора
incorrect_mode: - при получении истории указан некорректный режим
Ограничения
Запросы принимаются только с IP-адреса сервера, который предоставил пользователь в письме к администрации. Если в течение 10 минут поступит более 200 запросов, IP-адрес, с которого поступили запросы, будет заблокирован автоматически. Для разблокировки потребуется обращение в поддержку. Если будет выставлено более 20 неоплаченных пост-оплатных ордеров – метод set_order и multi_order вернет ошибку too_many_orders. Через ~12 часов блокировка будет автоматически снята.
