Поиск по сайту

API
Главная / API - Уведомления о событиях по заказам

Уведомления о событиях по заказам

Обновлено 25.08.2023
Содержание:

Общие сведения

Сервис позволяет управлять подписками на получение уведомлений о событиях, происходящих с заказами (список доступных событий содержится в справочнике "Типы событий").

Пользователь может создать до 10 подписок. В каждую подписку можно добавить требуемый набор заказов и настроить для неё перечень событий, инициирующих отправку уведомлений, а также перечень ролей пользователей, которым должны отправляться уведомления.  

Сервис доступен только авторизованным пользователям.

Создание/изменение подписки

Запрос метода

Структура запроса

Адрес метода: https://api.dellin.ru/v1/webhooks/update

{
   "appkey":"00000000-0000-0000-0000-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000",
   "id": "2",
   "url": "https://webhook.site",
   "eventTypes": [
      "order.state.pickup"
   ],
   "orderRoles": [
      "sender"
   ],
   "state": "enabled"
}
{
}

Описание параметров

Request
Request
ПараметрОбязательныйТипОписание
appkeyДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию
sessionIDДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
idНет*integer

Идентификатор подписки.

*Параметр обязателен в случае передачи запроса на изменение существующей подписки

urlДаstringАдрес, на который должны отправляться уведомления (схема https)
eventTypesНет*array of strings

Массив типов событий, о которых необходимо отправлять уведомления.

Формат типа события: "<сущность>.<группа событий>.<событие>".

Примеры:

  • "order.state.processing",
  • "order.state.declined",
  • "order.change.pickup_info"

Перечень доступных типов (комбинаций сущности, группы и события) с их описанием можно получить с помощью справочника "Типы событий".

*Если параметр не передан, то подписка будет оформлена на все типы событий

orderRolesДаarray of strings

Список ролей пользователей, которым необходимо отправлять уведомления.

Доступные значения:

  • customer - заказчик,
  • sender - отправитель,
  • receiver - получатель,
  • payer - плательщик
stateНетstring

Параметр для управления статусом подписки.

Доступные значения:

  • enabled - активировать,
  • disabled - отключить

Значение по умолчанию: "enabled"

Ответ метода

Структура ответа

{
   "metadata": {
      "status": 200,
      "generated_at": "2023-06-02 14:13:40"
   },
   "data": {
      "id": 2,
      "eventTypes": [
         "order.state.pickup"
      ],
      "orderRoles": [
         "sender"
      ],
      "state": "enabled",
      "url": "https://webhook.site"
   }
}
{
}

Описание параметров

Response
Response
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusinteger

Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)

metadata.generated_atstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

dataobjectИнформация о подписке
data.idintegerИдентификатор подписки
data.eventTypesarray of stringsСписок событий, о которых будут отправляться уведомления (см. справочник "Типы событий")
data.orderRolesarray of stringsСписок ролей пользователей, которым будут отправляться уведомления
data.statestring

Статус подписки.

Возможные значения:

  • enabled - активна,
  • disabled - отключена,
  • error - остановлена (ошибка отправки уведомления)
Статус "error" устанавливается для подписки, если возникла ошибка доставки уведомления на стороне получателя. В этом случае производится попытка повторной доставки этого уведомления через 1 минуту, 20 минут и 3 часа.Если 4 попытки доставки уведомлений (подряд) в рамках одной подписки оказались неудачными, то эта подписка автоматически отключается (ее статус меняется на "disabled")
data.urlstringАдрес, на который будут отправляться уведомления

Обработка ошибок

В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".

Добавление заказов в подписку

Сервис позволяет добавить заказы в подписку.

В адрес метода вместо {id} следует подставить идентификатор подписки.

Запрос метода

Структура запроса

Адрес метода: https://api.dellin.ru/v1/webhooks/{id}/orders/add

{
   "appkey":"00000000-0000-0000-0000-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000",
   "orderNumbers":[
      "8216702228554",
      "8217711111041"
   ]
}
{
}

Описание параметров

Request
Request
ПараметрОбязательныйТипОписание
appkeyДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию

sessionID

ДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
orderNumbersДаarray of strings

Массив номеров заказов для добавления в подписку.

Максимальное количество номеров в массиве - 5.

Номер заказа по одному из следующих параметров можно получить с помощью метода "Журнал заказов":
  • номер накладной,
  • номер заявки экспедитора,
  • внешний номер заказа

Ответ метода

Структура ответа

{
   "metadata":{
      "status":200,
      "generated_at":"2023-05-25 10:49:48"
   }
}
{
}

Описание параметров

Response
Response
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusintegerЭмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)
metadata.generated_atstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

Обработка ошибок

В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".

Удаление подписок

Запрос метода

Структура запроса

Адрес метода: https://api.dellin.ru/v1/webhooks/delete

{
   "appkey":"00000000-0000-0000-0000-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000",
   "ids":[
      1,
      2
   ]
}
{
}

Описание параметров

Request
Request
ПараметрОбязательныйТипОписание
appkeyДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию

sessionID

ДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
idsДаarray of integers

Массив идентификаторов удаляемых подписок

Ответ метода

Структура ответа

{
   "metadata":{
      "status":200,
      "generated_at":"2023-05-25 10:49:48"
   }
}
{
}

Описание параметров

Response
Response
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusintegerЭмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)
metadata.generated_atstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

Обработка ошибок

В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".

Удаление заказов из подписки

Запрос метода

Структура запроса

Адрес метода: https://api.dellin.ru/v1/webhooks/{id}/orders/delete

{
   "appkey":"00000000-0000-0000-0000-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000",
   "orderNumbers":[
      "8216702228554",
      "8217711111041"
   ]
}
{
}

Описание параметров

Request
Request
ПараметрОбязательныйТипОписание
appkeyДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию

sessionID

ДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
orderNumbersДаarray of strings

Массив номеров заказов для удаления из подписки.

Максимальное количество номеров в массиве - 5.

Номер заказа по одному из следующих параметров можно получить с помощью метода "Журнал заказов":
  • номер накладной,
  • номер заявки экспедитора,
  • внешний номер заказа

Ответ метода

Структура ответа

{
   "metadata":{
      "status":200,
      "generated_at":"2023-05-25 10:49:48"
   }
}
{
}

Описание параметров

Response
Response
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusintegerЭмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)
metadata.generated_atstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

Обработка ошибок

В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".

Информация о подписках

Сервис позволяет получать информацию о подписках.

Для получения информации о конкретной подписке следует в адрес метода вместо {id} подставить идентификатор подписки.

Для получения информации обо всех подписках используется адрес без идентификатора подписки.

Запрос метода

Структура запроса

Адрес метода: https://api.dellin.ru/v1/webhooks/{id} или https://api.dellin.ru/v1/webhooks

{
   "appkey":"00000000-0000-0000-0000-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000"
}
{
}

Описание параметров

Request
Request
ПараметрОбязательныйТипОписание
appkeyДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию

sessionID

ДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"

Ответ метода

Структура ответа

{
   "metadata": {
      "status": 200,
      "generated_at": "2023-05-25 11:09:32"
   },
   "data": [
      {
         "id": 3,
         "eventTypes": [
            "order.state.completed"
         ],
         "orderRoles": [
            "customer",
            "payer",
            "receiver",
            "sender"
          ],
          "state": "enabled",
          "url": "https://webhook.site"
      }
   ]
}
{
}

Описание параметров

Response
Response
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusintegerЭмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)
metadata.generated_atstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

dataobjectИнформация о подписке
data.idintegerИдентификатор подписки
data.eventTypesarray of stringsСписок событий, о которых отправляются уведомления (см. справочник "Типы событий")
data.orderRolesarray of stringsСписок ролей пользователей, которым отправляются уведомления
data.statestring

Статус подписки.

Возможные значения:

  • enabled - активна,
  • disabled - отключена,
  • error - остановлена (ошибка отправки уведомления)
Статус "error" устанавливается для подписки, если возникла ошибка доставки уведомления на стороне получателя. В этом случае производится попытка повторной доставки этого уведомления через 1 минуту, 20 минут и 3 часа.Если 4 попытки доставки уведомлений (подряд) в рамках одной подписки оказались неудачными, то эта подписка автоматически отключается (ее статус меняется на "disabled")
data.urlstringАдрес, на который отправляются уведомления

Обработка ошибок

В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".

Список заказов из подписки

Сервис позволяет по идентификатору подписки получить список номеров добавленных в нее заказов либо узнать, добавлен ли в нее заказ с определенным номером.

Запрос метода

Структура запроса

Адрес метода: https://api.dellin.ru/v1/webhooks/{id}/orders

{
   "appkey":"00000000-0000-0000-0000-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000",
   "orderNumber":"8216702228554",
   "page":2,
   "perPage":10
}
{
}

Описание параметров

Request
Request
ПараметрОбязательныйТипОписание
appkeyДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию

sessionID

ДаstringID сессии. Для получения сессии необходимо воспользоваться методом "Авторизация пользователя"
orderNumberНетstring

Номер заказа.

Используется для проверки того, добавлен ли заказ с определенным номером в подписку. В случае передачи этого параметра информация о других заказах в ответ не выводится.

Если параметр не передан, то в ответ выводится массив номеров заказов, добавленных в данную подписку.

Номер заказа по одному из следующих параметров можно получить с помощью метода "Журнал заказов":
  • номер накладной,
  • номер заявки экспедитора,
  • внешний номер заказа
pageНетintegerНомер страницы
perPageНетinteger

Количество элементов на страницу.

Минимальное значение: 1,

Максимальное значение: 100,

Значение по умолчанию: 100

Ответ метода

Структура ответа

{
   "metadata": {
      "status": 200,
      "generated_at": "2023-05-25 11:09:32",
      "currentPage": 2,
      "nextPage": 3,
      "prevPage": 1,
      "totalPages": 30
   },
   "orders": [
      "8216702228554",
      "8217711111041"
   ]
}
{
}

Описание параметров

Response
Response
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusintegerЭмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)
metadata.generated_atstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

metadata.currentPageintegerНомер текущей страницы
metadata.nextPageintegerНомер следующей страницы
metadata.prevPage integerНомер предыдущей страницы
metadata.totalPagesintegerОбщее количество страниц
ordersarray of strings

Если в запросе не был передан номер заказа в параметре "orderNumber", то в этом параметре выводится массив номеров заказов, добавленных в данную подписку.

Если был передан, то выводится:

  • переданный номер заказа, если он добавлен в данную подписку;
  • пустой массив, если не добавлен

Обработка ошибок

В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".