Уведомление по умолчанию

Если в настройках Магазина была активирована опция отправки автоматических уведомлений о смене статуса Заказа, то при поступлении оплаты в пользу Заказа, система «Инвойсбокс» осуществит запрос на специальный URL, который указан в настройках Магазина.

На указанный URL будет осуществлен POST запрос с Content-Type: application/json в теле которого будет находиться объект OrderNotification.

OrderNotification

Повторяет структуру OrderResponse, основные поля:

Заказ считается оплаченным, если его статус равен completed. В этом случае Магазин должен сверить сумму Заказа в запросе с суммой Заказа в своей системе учёта. Если не совпадает, в обработке запроса нужно отказать и вернуть ошибку.

Формат ответа

В случае успешности обработки запроса веб-сервис Магазина должен вернуть объект NotificationSuccess, а в случае ошибки - NotificationError. HTTP код в обоих случаях должен быть равен 200. Запросы с кодом отличные от 200 считаются ошибочными. Так же ошибочными считаются ответы, не содержащий валидный json.

NotificationSuccess

Пример объекта NotificationSuccess:

{
  "status" : "success"
}

NotificationError

Пример объекта NotificationError:

{
  "status" : "error",
  "code" : "order_wrong_amount",
  "message" : "Сумма заказа не соответствует сумме оплаты"
}

NotificationErrorCode

Код ошибки	Описание
out_of_service	Техническая ошибка обработки запроса веб сервером Магазина, при получении этого кода ошибки система «Инвойсбокс» будет пытаться повторить этот запрос еще 10 раз в течение последующих суток.
order_wrong_amount	Сумма заказа в Магазине не соответствует сумме заказа в уведомлении
order_already_paid	Заказ уже оплачен другим инструментом оплаты
order_not_found	Заказ не найден в учётной системе Магазина
shipping_unavailable	Услуга не может быть оказана или товар не может быть доставлен
signature_error	Ошибка проверки подписи запроса

Обратите внимание, в случае, если аналогичный запрос с тем же идентификатором (id) уже был обработан ранее успешно в вашей системе, то в этом случае следует вернуть статус успешной обработки уведомления status = success.

В случае, если заказ в вашей системе был оплачен ранее уведомлением с другим идентификатором (id) или иным платёжным инструментом, то следует вернуть ошибку status = error, code = order_already_paid.

Время выполнения запроса

Существует лимит ожидания ответа от веб-сервера Магазина на запросы уведомления, который составляет 20 секунд. Запросы отрабатывающие дольше этого значения считаются ошибочными.

Подпись запроса

При обработке запроса уведомления Магазину необходимо проверить его целостность. Для этого необходимо сформировать подпись тела входящего запроса и сравнить со значением из заголовка X-Signature. Если эти значения не совпадают, необходимо сформировать ответ NotificationError с NotificationErrorCode signature_error. Электронная подпись формируется путем криптографического преобразования содержимого тела запроса с использованием ключа и алгоритма выбранных в настройках уведомлений. По умолчанию используется алгоритм sha1 и метод hmac. Ключ можно получить в настройках интеграции магазина в ЛК Инвойсбокс.

<?php

$xSignature = false;
foreach (getallheaders() as $header => $value)
    if (strtolower($header) == "x-signature") {
        $xSignature = $value;
        break;
    }
}

if (!$xSignature) {
    // Ошибка, подпись запроса не получена
    header("Content-Type: application/json");
    die('{"status":"error","code":"out_of_service"}');
}

$payload = file_get_contents("php://input");
$apiKey = ""; // Согласованный ключ для подписи
$calcSignature = hash_hmac("sha1", $payload, $apiKey);

if ($xSignature != $calcSignature) {
    // Ошибка, подпись запроса неверная
    header("Content-Type: application/json");
    die('{"status":"error","code":"signature_error"}');
}

import hashlib
import hmac
import json

# Проверьте правильность пути и метода в декораторе @app.route()
# - его нужно подстроить под ваше веб-приложение.
@app.route("/invoicebox_callback", methods=['POST'])

async def invoicebox_callback():
    x_signature = request.headers.get('x-signature')
    if not x_signature:
        # Ошибка, подпись запроса не получена
        response = jsonify({'status': 'error', 'code': 'out_of_service'})
        response.headers["Content-Type"] = "application/json"
        return response, 400
    
    # Согласованный ключ для подписи
    api_key = ""
    payload = request.data
    calc_signature = hmac.new(api_key.encode(), payload, hashlib.sha1).hexdigest()
    
    if x_signature != calc_signature:
        # Ошибка, подпись запроса неверная
        response = jsonify({'status': 'error', 'code': 'signature_error'})
        response.headers["Content-Type"] = "application/json"
        return response, 400

Для удобства, смотрите также PHP SDK

Система мониторинга и автоматическое тестирование интеграции

В системе мониторинга «Инвойсбокс» реализовано автоматическое тестирование работоспособности интеграции.

Для проверки корректности интеграции, система может направлять тестовое уведомление, в котором в качестве идентификатора заказа в учётной системе магазина будет передано пустое значение, в качестве идентификатора заказа в системе «Инвойсбокс» будет передано значение ffffffff-ffff-ffff-ffff-ffffffffffff.

При получении такого запроса, система учёта магазина должна проверить корректность подписи запроса, сверить идентификатор магазина с настройками и вернуть ответ по резултатам проверки.

Читать далее »