АСНА REST API может уведомлять заинтересованных подписчиков о событиях, происходящих в сервисе. Например, вы можете получать уведомление о поступлении новых заказов или об успешной загрузке ваших остатков в облако. Для это API использует технологию Webhooks, т.е. осуществляет HTTP запросы на ваши адреса, зарегистрированные в API. Использование уведомлений возможно, если ваши сервисы находятся в открытом доступе и имеют либо постоянный IP адрес, либо постоянное доменное имя. В случае отсутствия постоянного доменного имени или адреса можно воспользоваться службами Dynamic DNS или утилитами, типа ngrok1 . За консультацией вы можете обратиться в Отдел веб-сервисов компании АСНА.
При получении запроса на ваш URL, вы можете вычислить хэш тела запроса по алгоритму SHA256 и сравнить его значение с содержимым заголовка X-Signature. В случае если вычисленное вами значение совпадает с тем, что находится в заголовке, вы обрабатываете запрос, иначе отклоняете его.
Алгоритм формирования значения заголовка X-Signature⚓︎
Содержимое тела запроса в виде массива байт хэшируется по алгоритму SHA256 с использованием секретного ключа.
Полученный массив байт переводим в строку с шестнадцатиричным кодированием (hex-encoded string)
Спереди к полученной строке добавляем строку sha256=
Проверка подписи не обязательна, но если вы хотите быть уверены что запрос пришел именно от АСНА API, а не от постороннего, возможно вредоносного, ПО, то наличие этой проверки в вашем сервисе сделает его более защищенным.
Клиенты, которые желают защитить от несанкционированного доступа свои URL, используемые для получения уведомлений от АСНА REST API, должны получить ключ, который будет использоваться для формирования подписи запроса.
Уникальный идентификатор клиента по справочнику АСНА (например, если нужно получить уведомление о событии приема полных остатков по определенной аптеке, то в качестве clientId подставляется уникальный идентификатор этой аптеки )
url
string
URL, на который API должен делать запрос при возникновении события
Уникальный идентификатор клиента по справочнику АСНА (например, если нужно получить уведомление о событии приема полных остатков по определенной аптеке, то в качестве clientId подставляется уникальный идентификатор этой аптеки )
url
string
URL, на который API должен делать запрос при возникновении события
Уникальный идентификатор клиента по справочнику АСНА (например, если нужно удалить уведомление о событии приема полных остатков по определенной аптеке, то в качестве clientId подставляется уникальный идентификатор этой аптеки )
Если вы, при вызове API, получили в ответ HTTP-статус 202 Accepted, то это значит что переданные данные требуют отложенной обработки и были поставлены в очередь на обработку. В этом случае HTTP-заголовок Location содержит URL, запросив который вы получите статус обработки.
Проверить статус отложенной обработки можно несколькими способами.
Через вызов API, описанный в этом разделе, можно получить информацию о статусе отложенной обработки.
Получить статус отложенной обработки можно, кроме вышеописанного, способом, описанным в Информирование о событиях API (Webhooks).
Иногда может возникнуть необходимость проверить отправляемые данные на соответствие формату JSON. Как правило, это происходит если API отклоняет запрос со статусом 400, но вы не можете обнаружить причину. Для проверки ваших данных, вы можете использовать следующий вызов API:
HTTP/1.1400Bad RequestContent-Type:application/json{"statusCode":400,"isError":true,"isTransient":false,"exceptionMessage":"Please correct the specified validation errors and try again","validationErrors":[{"field":"stocks[0].prtId","message":"Line: 1 Position: 88 Value: 111445 Error: Invalid type. Expected String but got Integer."},{"field":"stocks[0].supDate","message":"Line: 1 Position: 166 Value: Error: String '' does not validate against format 'date-time'."},{"field":"stocks[0].gnvls","message":"Line: 1 Position: 188 Value: 1 Error: Invalid type. Expected Boolean, Null but got Integer."},{"field":"stocks[0].dp","message":"Line: 1 Position: 197 Value: 0 Error: Invalid type. Expected Boolean, Null but got Integer."},{"field":"stocks[0].exp","message":"Line: 1 Position: 246 Value: 0 Error: Invalid type. Expected String, Null but got Integer."},{"field":"stocks[1].prtId","message":"Line: 1 Position: 436 Value: 8608872 Error: Invalid type. Expected String but got Integer."},{"field":"stocks[1].supDate","message":"Line: 1 Position: 516 Value: Error: String '' does not validate against format 'date-time'."},{"field":"stocks[1].gnvls","message":"Line: 1 Position: 538 Value: 1 Error: Invalid type. Expected Boolean, Null but got Integer."},{"field":"stocks[1].dp","message":"Line: 1 Position: 547 Value: 0 Error: Invalid type. Expected Boolean, Null but got Integer."},{"field":"stocks[1].exp","message":"Line: 1 Position: 596 Value: 0 Error: Invalid type. Expected String, Null but got Integer."}]}
Имя
Тип
Описание
field
string
Поле, в котором обнаружена ошибка
message
string
Описание ошибки
Возможна ситуация когда пакет не удается распарсить, в этом случае мы не можем понять в каких полях ошибка. Ниже пример такого ответа.
123456
{"statusCode":400,"isError":true,"isTransient":false,"exceptionMessage":"Invalid character after parsing property name. Expected ':' but got: 1. Path 'stocks[0]', line 5, position 20."}
Bad Request. Полученные службой данные содержат ошибки. Информация об ошибке возвращается в теле ответа.
401
Unauthorized. Токен авторизации неверный или истек срок его действия
403
Forbidden. У вас нет прав на выполнение данной операции
429
Too Many Requests. Слишком много запросов с одного IP адреса за промежуток времени
500
Internal Server Error. Ошибка сервиса. Если ошибка повторяется, сообщите, пожалуйста, разработчикам сервиса
Ngrok - утилита, обеспечивающая безопасные туннели для инструментов разработки и отладки вебхуков с локального хоста. Имеется бесплатная и платная версии. Ссылка↩
Последнее обновление: 17 августа 2021 г. 11:14:40 Созданный: 5 августа 2021 г. 12:36:05
