Уведомление по умолчанию
Если в настройках Магазина была активирована опция отправки автоматических уведомлений о смене статуса Заказа, то при поступлении оплаты в пользу Заказа, система «Инвойсбокс» осуществит запрос на специальный URL, который указан в настройках Магазина.
На указанный URL будет осуществлен POST запрос с Content-Type: application/json в теле которого будет находиться объект OrderNotification.
OrderNotification
Повторяет структуру OrderResponse, основные поля:
| Свойство | Обязательное | Тип | Описание |
|---|---|---|---|
| id | да | string(36) | Идентификатор заказа в системе «Инвойсбокс», например: 01771534-1a57-f184-dee3-ebeb91dded75
|
| status | да | string(50) enum | Статус заказа, например: completed, canceled
|
| merchantId | да | string(36) | Идентификатор магазина, например: 01771534-1a57-f184-dee3-ebeb91dded76
|
| merchantOrderId | да | string(36) | Идентификатор заказа в учётной системе магазина, например: O-12345
|
| merchantOrderIdVisible | нет | string(100) | Номер заказа, отображаемый на платежной странице. Если не заполнено, показывается значение из merchantOrderId например 111TN22-33
|
| amount | да | float | Сумма заказа, например: 19658.45
|
| currencyId | да | string(3) enum | Валюта заказа, например: RUB, USD,EUR, GBP
|
| createdAt | да | datetime | Дата создания заказа, например: 2020-12-22T00:00:00+00:00
|
Заказ считается оплаченным, если его статус равен completed. В этом случае Магазин должен сверить сумму Заказа в запросе с суммой Заказа в своей системе учёта. Если не совпадает, в обработке запроса нужно отказать и вернуть ошибку.
Формат ответа
В случае успешности обработки запроса веб-сервис Магазина должен вернуть объект NotificationSuccess, а в случае ошибки - NotificationError. HTTP код в обоих случаях должен быть равен 200. Запросы с кодом отличные от 200 считаются ошибочными. Так же ошибочными считаются ответы, не содержащий валидный json.
NotificationSuccess
| Свойство | Обязательное | Тип | Описание |
|---|---|---|---|
| status | да | string(50) | В случе успешной обработки допустимо только одно значение - success
|
Пример объекта NotificationSuccess:
{
"status" : "success"
}
NotificationError
| Свойство | Обязательное | Тип | Описание |
|---|---|---|---|
| status | да | string(50) enum | В случае ошибки обработки запроса допустимо только одно значение - error
|
| code | нет | string(100) enum | Код ошибки - значение из справочника NotificationErrorCode, по умолчанию out_of_service
|
| message | нет | string(500) | Детальное описание ошибки в текстовом формате |
Пример объекта NotificationError:
{
"status" : "error",
"code" : "order_wrong_amount",
"message" : "Сумма заказа не соответствует сумме оплаты"
}
NotificationErrorCode
| Код ошибки | Описание |
|---|---|
out_of_service |
Техническая ошибка обработки запроса веб сервером Магазина, при получении этого кода ошибки система «Инвойсбокс» будет пытаться повторить этот запрос еще 10 раз в течение последующих суток. |
order_wrong_amount |
Сумма заказа в Магазине не соответствует сумме заказа в уведомлении |
order_already_paid |
Заказ уже оплачен другим инструментом оплаты 
|
order_not_found |
Заказ не найден в учётной системе Магазина |
signature_error |
Ошибка проверки подписи запроса |
Обратите внимание, в случае, если аналогичный запрос от системы «Инвойсбокс» на оплату уже был обработан ранее успешно и заказ был отмечен как оплаченный, то в этом случае следует вернуть статус успешной обработки success. В случае, если заказ был оплачен ранее под другим идентификатором системы «Инвойсбокс» или иным платёжным инструментом, то следует вернуть ошибку order_already_paid.
Время выполнения запроса
Существует лимит ожидания ответа от веб-сервера Магазина на запросы уведомления, который составляет 20 секунд. Запросы отрабатывающие дольше этого значения считаются ошибочными.
Подпись запроса
При обработке запроса уведомления Магазину необходимо проверить его целостность. Для этого необходимо сформировать подпись тела входящего запроса и сравнить со значением из заголовка X-Signature. Если эти значения не совпадают, необходимо сформировать ответ NotificationError с NotificationErrorCode signature_error. Электронная подпись формируется путем криптографического преобразования содержимого тела запроса с использованием ключа и алгоритма выбранных в настройках уведомлений. По умолчанию используется алгоритм sha1 и метод hmac. Ключ можно получить в настройках интеграции магазина в ЛК Инвойсбокс.
Система мониторинга и автоматическое тестирование интеграции
В системе мониторинга «Инвойсбокс» реализовано автоматическое тестирование работоспособности интеграции.
Для проверки корректности интеграции, система может направлять тестовое уведомление, в котором в качестве идентификатора заказа в учётной системе магазина будет передано пустое значение, в качестве идентификатора заказа в системе «Инвойсбокс» будет передано значение ffffffff-ffff-ffff-ffff-ffffffffffff.
При получении такого запроса, система учёта магазина должна проверить корректность подписи запроса, сверить идентификатор магазина с настройками и вернуть ответ по резултатам проверки.