Инструменты пользователя
api-2.0
Различия
Здесь показаны различия между двумя версиями данной страницы.
| Следущая версия | Предыдущая версия | ||
|
api-2.0 [2014/04/02 10:35] admin создано |
api-2.0 [2017/07/27 12:07] admin удалено |
||
|---|---|---|---|
| Строка 1: | Строка 1: | ||
| - | h1. API 2.0 | ||
| - | {{TOC}} | ||
| - | API построено на REST архитектуре. JSON возвращается в ответ на все запросы к API, в том числе и при возникновении ошибок. Имеет предсказуемые, ресурсо-ориентированные URL-адреса, использует HTTP-коды для передачи состояния ошибок, а также использует встроенные функции HTTP-аутентификации и методы GET, POST, PUT, DELETE. | ||
| - | h1. Запросы от OnPay к сайту мерчанта | + | ===== Check ===== |
| - | + | ||
| - | h2. Check | + | |
| Для check запроса используются параметры: | Для check запроса используются параметры: | ||
| Строка 20: | Строка 15: | ||
| Пример запроса: | Пример запроса: | ||
| - | <pre><code class="json">{ | + | <code class="json"> |
| - | "type":"check", | + | { |
| - | "pay_for":"55446", | + | "type":"check", |
| - | "expired_at":"2014-02-03T18:43:21+04:00" | + | "pay_for":"55446", |
| - | "amount":50000, | + | "expired_at":"2014-02-03T18:43:21+04:00" |
| - | "way":"RUR", | + | "amount":50000, |
| - | "mode":"fix", | + | "way":"RUR", |
| - | "signature":"82f67760dbc5331963b7e00bc6df77f1" | + | "mode":"fix", |
| - | }</code></pre> | + | "signature":"82f67760dbc5331963b7e00bc6df77f1" |
| + | } | ||
| + | </code> | ||
| - | h3. Ответ мерчанта | + | Ответ мерчанта |
| | Название | Тип | Описание | | | Название | Тип | Описание | | ||
| Строка 39: | Строка 36: | ||
| Пример: | Пример: | ||
| - | <pre><code class="json"> | + | <code class="json"> |
| { | { | ||
| - | "code":0, | + | "code":0, |
| - | "type":"check", | + | "type":"check", |
| - | "pay_for":"55446", | + | "pay_for":"55446", |
| - | "signature":"172de16ada92791b3753b3121d471f5c" | + | "signature":"172de16ada92791b3753b3121d471f5c" |
| } | } | ||
| - | </code></pre> | + | </code> |
| - | h2. Pay | + | ===== Pay ===== |
| Для pay запроса используются параметры: | Для pay запроса используются параметры: | ||
| Строка 66: | Строка 63: | ||
| | balance.amount | bigint | Сумма, зачисляемая на баланс | | | balance.amount | bigint | Сумма, зачисляемая на баланс | | ||
| | balance.way | string | Валюта зачисления на баланс | | | balance.way | string | Валюта зачисления на баланс | | ||
| + | | order.from_amount | float | Сумма из ордера, которую должен был заплатить плательщик | | ||
| + | | order.from_way | string | Валюта из ордера, в которой должен был заплатить плательщик | | ||
| + | | order.to_amount | float | Сумма из ордера, которая должна была поступить на баланс магазина | | ||
| + | | order.to_way | string | Валюта из ордера, в которой должен был пополниться баланс магазина | | ||
| Пример запроса: | Пример запроса: | ||
| - | <pre><code class="json"> | + | <code class="json"> |
| { | { | ||
| - | "type":"pay", | + | "type": "pay", |
| - | "pay_for":"55446", | + | "pay_for": "55446", |
| - | "signature":"82f67760dbc5331963b7e00bc6df77f1", | + | "signature": "82f67760dbc5331963b7e00bc6df77f1", |
| - | "user":{ | + | "user": { |
| - | "email":"mail@mail.ru", | + | "email": "mail@mail.ru", |
| - | "phone":"9631478946", | + | "phone": "9631478946", |
| - | "note":"" | + | "note": "" |
| - | }, | + | }, |
| - | "payment":{ | + | "payment": { |
| - | "id":7121064, | + | "id": 7121064, |
| - | "date_time":"2013-12-05T12:07:09+04:00", | + | "date_time": "2013-12-05T12:07:09+04:00", |
| - | "amount":10200, | + | "amount": 10200, |
| - | "way":"USD", | + | "way": "USD", |
| - | "rate":33121445, | + | "rate": 33121445, |
| - | "release_at":null | + | "release_at": null |
| - | }, | + | }, |
| - | "balance":{ | + | "balance": { |
| - | "amount":"3300", | + | "amount": 3378.39, |
| - | "way":"RUR" | + | "way": "RUR" |
| - | } | + | }, |
| + | "order": { | ||
| + | "from_amount": 102.00, | ||
| + | "from_way": "USD", | ||
| + | "to_amount": 3378.39, | ||
| + | "to_way": "RUR" | ||
| + | } | ||
| } | } | ||
| - | </pre></code> | + | </code> |
| - | h3. Ответ мерчанта | + | Ответ мерчанта |
| | Название | Тип | Описание | | | Название | Тип | Описание | | ||
| Строка 100: | Строка 107: | ||
| | pay_for | string | Номер заказа | | | pay_for | string | Номер заказа | | ||
| | signature | string | Контрольная подпись, строка для построения "code;pay_for;api_key" | | | signature | string | Контрольная подпись, строка для построения "code;pay_for;api_key" | | ||
| + | | receipt | json | Содержит информацию о списке покупок в чеке | | ||
| + | | receipt.items | array | Список товаров в чеке | | ||
| + | | receipt.items.name | string | Название товара | | ||
| + | | receipt.items.price | float | Цена за единицу товара | | ||
| + | | receipt.items.quantity | float | Количество | | ||
| + | | receipt.sum | float | Сумма чека | | ||
| Пример: | Пример: | ||
| - | <pre><code class="json"> | + | <code class="json"> |
| { | { | ||
| - | "code":0, | + | "code": 0, |
| - | "type":"pay", | + | "type": "pay", |
| - | "pay_for":"55446", | + | "pay_for": "55446", |
| - | "signature":"172de16ada92791b3753b3121d471f5c" | + | "signature": "172de16ada92791b3753b3121d471f5c", |
| + | "receipt": { | ||
| + | "items": [ | ||
| + | { | ||
| + | "name": "product 1", | ||
| + | "price": 100.00, | ||
| + | "quantity": 2.8 | ||
| + | }, | ||
| + | { | ||
| + | "name": "product 2", | ||
| + | "price": 18.50, | ||
| + | "quantity": 4 | ||
| + | }, | ||
| + | { | ||
| + | "name": "product 3", | ||
| + | "price": 500.00, | ||
| + | "quantity": 1 | ||
| + | } | ||
| + | ], | ||
| + | "sum": 854.00 | ||
| + | } | ||
| } | } | ||
| - | </code></pre> | + | </code> |
| - | h1. Запросы от мерчанта к OnPay | + | ==== Запросы от мерчанта к OnPay ==== |
| - | h2. Получить данные платежа | + | ===== Получить данные платежа ===== |
| адрес - json_interfaces/payments/:id, где id - номер платежа в системе OnPay | адрес - json_interfaces/payments/:id, где id - номер платежа в системе OnPay | ||
| - | Используется для получения данных о прошедшем платеже. Используемые параметры: | + | Используется для получения данных о прошедшем платеже. HTTP метод - GET. Используемые параметры: |
| | Название | Тип | Описание | | | Название | Тип | Описание | | ||
| | login | string | Логин сайта | | | login | string | Логин сайта | | ||
| Строка 123: | Строка 156: | ||
| Пример запроса: | Пример запроса: | ||
| - | <pre><code class="json"> | + | <code class="json"> |
| { | { | ||
| - | "login":"onpay", | + | "login":"onpay", |
| - | "signature":"1d15f90df20da53d7206e9f7db7d2c9d" | + | "signature":"1d15f90df20da53d7206e9f7db7d2c9d" |
| } | } | ||
| - | </code></pre> | + | </code> |
| В ответ будет выдан JSON с данными: | В ответ будет выдан JSON с данными: | ||
| Строка 146: | Строка 179: | ||
| Пример ответа: | Пример ответа: | ||
| - | <pre><code class="json"> | + | <code class="json"> |
| { | { | ||
| - | "signature":"172de16ada92791b3753b3121d471f5c", | + | "signature": "172de16ada92791b3753b3121d471f5c", |
| - | "user":{ | + | "user": { |
| - | "email":"mail@mail.ru", | + | "email": "mail@mail.ru", |
| - | "phone":"9631478946", | + | "phone": "9631478946", |
| - | "note":"" | + | "note": "" |
| - | }, | + | }, |
| - | "payment":{ | + | "payment": { |
| - | "id":"7121064", | + | "id": "7121064", |
| - | "date_time":"2013-12-05T12:07:09+04:00", | + | "date_time": "2013-12-05T12:07:09+04:00", |
| - | "amount":10200, | + | "amount": 10200, |
| - | "way":"USD", | + | "way": "USD", |
| - | "rate":33121445, | + | "rate": 33121445, |
| - | "release_at":null | + | "release_at": null |
| - | }, | + | }, |
| - | "balance":{ | + | "balance": { |
| - | "amount":"3300", | + | "amount": "3300", |
| - | "way":"RUR" | + | "way": "RUR" |
| - | } | + | } |
| } | } | ||
| - | </pre></code> | + | </code> |
| - | h2. Получить курс обмена | + | ===== Получить курс обмена ===== |
| адрес - json_interfaces/rates/:from/to/:to, где from и to - валюта из и валюта назначения соответственно | адрес - json_interfaces/rates/:from/to/:to, где from и to - валюта из и валюта назначения соответственно | ||
| Строка 179: | Строка 212: | ||
| Пример запроса: | Пример запроса: | ||
| - | <pre><code class="json"> | + | <code class="json"> |
| { | { | ||
| - | "login":"onpay", | + | "login":"onpay", |
| - | "signature":"65ded5353c5ee48d0b7d48c591b8f430" | + | "signature":"65ded5353c5ee48d0b7d48c591b8f430" |
| - | }</code></pre> | + | } |
| + | </code> | ||
| В ответ будет выдан JSON с данными: | В ответ будет выдан JSON с данными: | ||
| Строка 193: | Строка 227: | ||
| Пример ответа: | Пример ответа: | ||
| - | <pre><code class="json"> | + | <code class="json"> |
| { | { | ||
| - | "from":"USD", | + | "from":"USD", |
| - | "to":"RUR", | + | "to":"RUR", |
| - | "rate":33121445 | + | "rate":33121445 |
| - | "signature":"4671aeaf49c792689533b00664a5c3ef" | + | "signature":"4671aeaf49c792689533b00664a5c3ef" |
| } | } | ||
| - | </code></pre> | + | </code> |
| - | + | ||
| - | h2. Купоны | + | |
| - | + | ||
| - | Общий адрес интерфейса - json_interfaces/coupons/ | + | |
| - | + | ||
| - | h3. Создание Купона | + | |
| - | + | ||
| - | метод - POST | + | |
| - | адрес - json_interfaces/coupons/ | + | |
| - | + | ||
| - | | Название | Тип | Описание | | + | |
| - | | login | string | Логин сайта | | + | |
| - | | type | string | Тип купона - для величины в процентах percent, для постоянной суммы const | | + | |
| - | | percent_off | bigint | Предоставляемая скидка, в процентах, используется только для типа percent (для const - 0) | | + | |
| - | | max_amount | bigint | Ограничение сверху по предоставляемой сумме скидки, используется только для типа percent, указывается в центах. 0 для купона без ограничения (для const - 0) | | + | |
| - | | value | bigint | Величина скидки, используется только для типа const, указывается в центах (для percent - 0) | | + | |
| - | | min_amount | bigint | Ограничение снизу, купон может использоваться только для платежей выше указанной суммы, указывается в центах, используется только для типа const (для percent - 0) | | + | |
| - | | max_redemptions | int | Ограничение сверху по количеству использований | | + | |
| - | | expired_at | string | Дата истечения скидочной акции в формате "CCYY-MM-DDThh:mm:ssTZD" где TZD смещение часового пояса в формате [+-]hh:mm | | + | |
| - | | signature | string | Контрольная подпись для "login;type;percent_off;max_amount;value;min_amount;max_redemptions;expired_at;api_key" | | + | |
| - | + | ||
| - | Пример запроса для процентной скидки: | + | |
| - | <pre><code class="json"> | + | |
| - | { | + | |
| - | "login":"onpay", | + | |
| - | "type":"percent", | + | |
| - | "percent_off":10, | + | |
| - | "max_amount":100000, | + | |
| - | "value":0, | + | |
| - | "min_amount":0, | + | |
| - | "max_redemptions":1, | + | |
| - | "expired_at":"2013-12-05T12:07:09+04:00", | + | |
| - | "signature":"1d15f90df20da53d7206e9f7db7d2c9d" | + | |
| - | } | + | |
| - | </code></pre> | + | |
| - | + | ||
| - | Пример запроса для постоянной скидки: | + | |
| - | <pre><code class="json"> | + | |
| - | { | + | |
| - | "login":"onpay", | + | |
| - | "type":"const", | + | |
| - | "percent_off":0, | + | |
| - | "max_amount":0, | + | |
| - | "value":10000, | + | |
| - | "min_amount":100000, | + | |
| - | "max_redemptions":1, | + | |
| - | "expired_at":"2013-12-05T12:07:09+04:00", | + | |
| - | "signature":"d41d8cd98f00b204e9800998ecf8427e" | + | |
| - | } | + | |
| - | </code></pre> | + | |
| - | + | ||
| - | В ответ будет выдан JSON с данными: | + | |
| - | | Название | Тип | Описание | | + | |
| - | | code | string | Уникальный код купона | | + | |
| - | | type | string | Тип купона - для величины в процентах percent, для постоянной суммы const | | + | |
| - | | percent_off | bigint | Предоставляемая скидка, в процентах, только для типа percent (для const - 0) | | + | |
| - | | max_amount | bigint | Ограничение сверху по предоставляемой сумме скидки, только для типа percent. 0 для купона без ограничения (для const - 0) | | + | |
| - | | value | bigint | Величина скидки, только для типа const, указывается в центах (для percent - 0) | | + | |
| - | | min_amount | bigint | Ограничение снизу, купон может использоваться только для платежей выше указанной суммы, только для типа const (для percent - 0) | | + | |
| - | | max_redemptions | int | Ограничение сверху по количеству использований | | + | |
| - | | expired_at | string | Дата истечения скидочной акции в формате "CCYY-MM-DDThh:mm:ssTZD" где TZD смещение часового пояса в формате [+-]hh:mm | | + | |
| - | | redemptions_count | int | Количество использований | | + | |
| - | | state | string | Текущее состояние, new для купона с не исчерпанным лимитом использований, complete для использованного максимально допустимое кол-во раз, expired для купона с истекшим временем действия и не исчерпанным лимитом использований, deleted для удаленного купона | | + | |
| - | | signature | string | Контрольная подпись "code;type;redemptions_count;state;api_key" | | + | |
| - | + | ||
| - | Пример ответа для процентной скидки: | + | |
| - | <pre><code class="json"> | + | |
| - | { | + | |
| - | "code":"3whhZ4U0J9B0tATiOb", | + | |
| - | "type":"const", | + | |
| - | "percent_off":10, | + | |
| - | "max_amount":100000, | + | |
| - | "value":0, | + | |
| - | "min_amount":0, | + | |
| - | "max_redemptions":1, | + | |
| - | "expired_at":"2013-12-05T12:07:09+04:00", | + | |
| - | "redemptions_count":0, | + | |
| - | "state":"new", | + | |
| - | "signature":"172de16ada92791b3753b3121d471f5c" | + | |
| - | } | + | |
| - | </code></pre> | + | |
| - | Пример ответа для постоянной скидки: | + | |
| - | <pre><code class="json"> | + | |
| - | { | + | |
| - | "code":"3whhZ4U0J9B0tATiOb", | + | |
| - | "type":"const", | + | |
| - | "percent_off":0, | + | |
| - | "max_amount":0, | + | |
| - | "value":10000, | + | |
| - | "min_amount":100000, | + | |
| - | "max_redemptions":1, | + | |
| - | "expired_at":"2013-12-05T12:07:09+04:00", | + | |
| - | "redemptions_count":0, | + | |
| - | "state":"new", | + | |
| - | "signature":"172de16ada92791b3753b3121d471f5c" | + | |
| - | } | + | |
| - | </code></pre> | + | |
| - | + | ||
| - | h3. Получение купона | + | |
| - | + | ||
| - | метод - GET | + | |
| - | адрес - json_interfaces/coupons/:code, где code - уникальный код купона | + | |
| - | + | ||
| - | Используется для просмотра текущего состояния купона. | + | |
| - | | Название | Тип | Описание | | + | |
| - | | login | string | Логин сайта | | + | |
| - | | signature | string | Контрольная подпись для "login;code;"get";api_key" | | + | |
| - | + | ||
| - | Пример запроса: | + | |
| - | <pre><code class="json"> | + | |
| - | { | + | |
| - | "login":"onpay", | + | |
| - | "signature":"1d15f90df20da53d7206e9f7db7d2c9d" | + | |
| - | } | + | |
| - | </code></pre> | + | |
| - | + | ||
| - | Ответ будет аналогичен как и у запроса для создания купона. | + | |
| - | + | ||
| - | h3. Удаление купона | + | |
| - | + | ||
| - | метод - DELETE | + | |
| - | адрес - json_interfaces/coupons/:code, где code - уникальный код купона | + | |
| - | + | ||
| - | Используется для отключения купона до истечения его срока годности или исчерпания количества использований. | + | |
| - | | Название | Тип | Описание | | + | |
| - | | login | string | Логин сайта | | + | |
| - | | signature | string | Контрольная подпись для "login;code;"delete";api_key" | | + | |
| - | + | ||
| - | Пример запроса: | + | |
| - | <pre><code class="json"> | + | |
| - | { | + | |
| - | "login":"onpay", | + | |
| - | "signature":"1d15f90df20da53d7206e9f7db7d2c9d" | + | |
| - | } | + | |
| - | </code></pre> | + | |
| - | + | ||
| - | Ответ будет аналогичен как и у запроса для создания купона. | + | |
| - | + | ||
| - | h1. Ошибки | + | |
| - | + | ||
| - | В любом ответе могут присутствовать данные об ошибке, они записываются в конец сообщения в следующем формате: | + | |
| - | | Название | Тип | Описание | | + | |
| - | | params | string | Перечисляются все ошибочные параметры | | + | |
| - | | params.code | string | Код ошибки | | + | |
| - | | params.message | string | Текст ошибки | | + | |
| - | | params.name | string | Название параметра | | + | |
| - | | type | string | Тип ошибки | | + | |
| - | | message | string | Текст сообщения | | + | |
| - | + | ||
| - | JSON вида: | + | |
| - | <pre><code class="json"> | + | |
| - | { | + | |
| - | "error":{ | + | |
| - | "params":[ | + | |
| - | { | + | |
| - | "code":"required", | + | |
| - | "message":"Description cannot be blank.", | + | |
| - | "name":"description" | + | |
| - | } | + | |
| - | ], | + | |
| - | "type":"invalid_param_error", | + | |
| - | "message":"Invalid data parameters" | + | |
| - | } | + | |
| - | }</code></pre> | + | |
| - | + | ||
| - | h1. Примечания | + | |
| - | + | ||
| - | 1) Для хеширования строки подписи используется алгоритм SHA1 | + | |
| - | 2) Методы запросов: | ||
| - | | Запрос | метод | | ||
| - | | check | POST | | ||
| - | | pay | POST | | ||
| - | | state | GET | | ||
| - | | rate | GET | | ||
| - | | Создание купона | POST | | ||
| - | | Получение купона | GET | | ||
| - | | Удаление купона | DELETE | | ||