Вебхуки

Вебхуки предоставляют возможность получать обновления по интересующим темам, как только они произошли в системе ATI.SU.

Требования к вебхукам

Для того чтобы обеспечить безопасность и стабильную работу, есть несколько требований, которым должен удовлетворять вебхук:

• не является открытым и угадываемым, то есть третьи лица не должны иметь возможности узнать о его существовании;
• если используется DNS-имя, оно должно разрешаться в публичный¹ IPv4 адрес;
• если используется IP-адрес, он должен быть публичным¹ IPv4 адресом;
• доступен по протоколу HTTPS;
• уникален на каждую подписку;
• реализует механизм аутентификации.

Рекомендации по реализации

1. Время ответа

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

2. Уникальность

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

3. TLS

Сообщения могут содержать закрытую информацию, поэтому отправка их в незашифрованном виде недопустима. Если у вас нет возможности использовать доверенный сертификат, напишите на почту api@ati.su.

Использование API

Для существования вебхука необходимы два метода по одному URL. Первый (GET) отвечает за управление состоянием, а второй (POST) — за передачу сообщений.

Создание вебхука

Создание вебхука происходит в два этапа: отправка запроса на создание и верификация.

Отправка запроса на создание

Чтобы подписаться на события через вебхуки, необходимо выбрать тему и указать её в параметре topic. Для тем подписки, которые позволяют подписаться на события по чужим сущностям, необходимо задать тип подписки complex в параметре subscription_type, а также заполнить параметры фильтра в соответствии с темой и указать их в параметре subscription запроса на создание вебхука.

Параметр subscription

Модель

{...}

Параметры подписки.

channel: xxx-of

Канал подписки.

cargoesauctions

boards*: [string]

Идентификаторы площадок для подписки.

boards*: [string]

Идентификаторы площадок для подписки.

}

Пример

{...}

"channel":"cargoes",

"boards":[...]

"string"

]

}

Параметр callback должен содержать URL вебхука. В URL допустимы параметры запроса, которые будут переданы при вызове вебхука. Параметры запроса можно использовать, например, для привязки вебхука к пользователю:

https://example.org/webhook?userId=00000000

Версия OAuth2.0 v1 OAuth2.0 v2

Создаёт вебхук.

post /webhooks/v1/create

Модель и примеры

Параметры

Параметров нет

Запрос

Модель

{...}

Запрос создания вебхука

subscription_type: xxx-of (nullable)

Тип подписки вебхука.

complexnormal

topic*: string

Минимальное количество символов: 1

Тема подписки. Допустимые значения — идентификаторы тем из документации вебхуков: https://ati.su/developers/api/webhooks/topics/. Подставляйте имя темы (cargoes.on_boards, catalogs.drivers, …). Для тем с фильтром дополнительно нужен subscription_type=complex

callback*: string

Минимальное количество символов: 1

URL

subscription*: {missing-type-info}

Параметры подписки с возможностью настройки фильтров

topic*: string

Минимальное количество символов: 1

Тема подписки. Допустимые значения — идентификаторы тем из документации вебхуков: https://ati.su/developers/api/webhooks/topics/. Подставляйте имя темы (cargoes.on_boards, catalogs.drivers, …). Для тем с фильтром дополнительно нужен subscription_type=complex

callback*: string

Минимальное количество символов: 1

URL

}

Пример запроса

CURL

curl 'https://api.ati.su/webhooks/v1/create' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{"subscription_type":"normal","topic":"cargoes.on_boards","callback":"https://example.com/webhook?userId=000000"}'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("POST", "https://api.ati.su", "/webhooks/v1/create", "{""subscription_type"":""normal"",""topic"":""cargoes.on_boards"",""callback"":""https://example.com/webhook?userId=000000""}");

Ответ

202 HTTP 202, если создание принято; 4XX при ошибке запроса.

Модель

{}

Пустой ответ: операция принята к асинхронному выполнению.

Пример

{}

4XX Ошибка запроса. [Подробнее про ошибки API](/documentation/errors/)

Модель

ONE-OF

(nullable)

1:{...}

Описание ошибки

error_code: string

Код ошибки.

reason: string

Причина ошибки.

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки.

}

Пример

{...}

"error_code":"not_found",

"reason":"Вебхук с Id '644bdc87dbd6fc3747887c7b' не найден",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

Нет параметров

{ "subscription_type": "normal", "topic": "cargoes.on_boards", "callback": "https://example.com/webhook?userId=000000" }

Создаёт вебхук.

post /gw/oauth2/webhooks/v1/create

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

Модель и примеры

Параметры

Параметров нет

Запрос

Модель

{...}

Запрос создания вебхука

subscription_type: xxx-of (nullable)

Тип подписки вебхука.

complexnormal

topic*: string

Минимальное количество символов: 1

Тема подписки. Допустимые значения — идентификаторы тем из документации вебхуков: https://ati.su/developers/api/webhooks/topics/. Подставляйте имя темы (cargoes.on_boards, catalogs.drivers, …). Для тем с фильтром дополнительно нужен subscription_type=complex

callback*: string

Минимальное количество символов: 1

URL

subscription*: {missing-type-info}

Параметры подписки с возможностью настройки фильтров

topic*: string

Минимальное количество символов: 1

Тема подписки. Допустимые значения — идентификаторы тем из документации вебхуков: https://ati.su/developers/api/webhooks/topics/. Подставляйте имя темы (cargoes.on_boards, catalogs.drivers, …). Для тем с фильтром дополнительно нужен subscription_type=complex

callback*: string

Минимальное количество символов: 1

URL

}

Пример запроса

CURL

curl 'https://api.ati.su/gw/oauth2/webhooks/v1/create' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{"subscription_type":"normal","topic":"cargoes.on_boards","callback":"https://example.com/webhook?userId=000000"}'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("POST", "https://api.ati.su", "/gw/oauth2/webhooks/v1/create", "{""subscription_type"":""normal"",""topic"":""cargoes.on_boards"",""callback"":""https://example.com/webhook?userId=000000""}");

Ответ

202 HTTP 202, если создание принято; 4XX при ошибке запроса.

Модель

{}

Пустой ответ: операция принята к асинхронному выполнению.

Пример

{}

4XX Ошибка запроса. [Подробнее про ошибки API](/documentation/errors/)

Модель

ONE-OF

(nullable)

1:{...}

Описание ошибки

error_code: string

Код ошибки.

reason: string

Причина ошибки.

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки.

}

Пример

{...}

"error_code":"not_found",

"reason":"Вебхук с Id '644bdc87dbd6fc3747887c7b' не найден",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

Нет параметров

{ "subscription_type": "normal", "topic": "cargoes.on_boards", "callback": "https://example.com/webhook?userId=000000" }

В ответе содержится заголовок Location с URL GET-метода проверки состояния созданного вебхука.

Верификация

После отправки запроса на создание, вебхук проходит верификацию. Вызывается GET метод по URL вебхука с параметрами challenge и topic, а также параметрами указанными при создании.

Пример верификационного запроса

GET /webhook?status=verification&verification_status=progress&topic=orders&challenge=608b672ed0a5aaecc2d42488 HTTP/1.1
Host: example.org:443
Date: Thu, 01 Jan 1970 00:00:00 GMT
Digest: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Accept: application/json
Authorization: HMAC-SHA-256 Credential=6447f577905114d5b9b2c618&SignedHeaders=Date;Digest;Host&Signature=IFfS27QZuXLTNV9idpwnUNDSiayHYAJO0IcoJy2pHy8=

Вебхук должен ответить в течение 20 секунд на верификационный запрос JSON-строкой с содержимым параметра challenge.

Верификационный запрос, так же как и все остальные, имеет заголовок Authorization, поэтому возможна его аутентификация. При его поступлении следует получить сгенерированный ключ с помощью метода проверки состояния вебхука (поле hook.key).

Пример ответа на верификационный запрос

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 26

"608b672ed0a5aaecc2d42488"

Как только ответ будет получен, отправится оповещение о смене состояния. После успешной верификации, отключите логику обработки параметра challenge для данного вебхука, чтобы избежать ошибок.

Если верификация провалилась, узнать причину можно с помощью метода проверки состояния вебхука. Вебхук будет находиться в состоянии verification.

Проверка состояния вебхука

Проверка состояния одного вебхука

Версия OAuth2.0 v1 OAuth2.0 v2

Возвращает состояние вебхука.

get /webhooks/v1/status/{id}

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор вебхука. Пример: 644bdc87dbd6fc3747887c7b

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/webhooks/v1/status/{id}' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("GET", "https://api.ati.su", "/webhooks/v1/status/{id}");

Ответ

200 HTTP 200 с состоянием вебхука при успехе; 4XX при ошибке запроса.

Модель

{...}

Состояние вебхука

status: xxx-of

Идентификатор состояния вебхука.

deactivatedactivecreatedverification

hook:

Деактивированный вебхук.

ONE-OF

1:{...}

Деактивированный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

first_failure_date: date-time

Дата первой проваленной отправки

}

hook:

Активный вебхук.

ONE-OF

1:{...}

Активный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

suspended_until: date-time (nullable)

Дата окончания приостановки подписки

}

hook:

Созданный вебхук.

ONE-OF

1:{...}

Созданный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

}

verification:

Проверка вебхука

ONE-OF

1:{...}

Проверка вебхука

status: xxx-of

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

failedprogress

fail_reason*:

Причина провала проверки.

ONE-OF

enum

[unknown_error, tls_error, socket_error, request_error, challenge_mismatch, wrong_response_format]

Причины провала проверки вебхука

• unknown_error — Неизвестная ошибка

  Ошибка на стороне АТИ

• tls_error — Ошибка установки защищенного соединения

  Возможно используется недоверенный сертификат, или сервер не поддерживает протокол HTTPS

• socket_error — Ошибка создания TCP соединения

  Возможно указан недоступный IP адрес, DNS-имя, разрешающееся в недоступный IP адрес, или сервер не принимает запросы

• request_error — Ошибка запроса

  Получен HTTP-код, отличный от 200, или превышено время ожидания ответа

• challenge_mismatch — Challenge не совпадает

• wrong_response_format — Неправильный формат ответа

  Формат ответа отличается от JSON-строки

}

hook:

Проверяемый вебхук.

ONE-OF

1:{...}

Проверяемый вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

}

}

Пример

{...}

"status":"created",

"verification":{...},

"status":"progress"

},

"hook":{...}

"id":"644bdc87dbd6fc3747887c7b",

"callback":"https://hooks.example.com/webhook",

"topic":"cargoes.on_boards",

"application_id":"cargo-integrator",

"contact_id":14612,

"key":"a3f1c8e92b7d4e6a"

}

}

4XX Ошибка запроса. [Подробнее про ошибки API](/documentation/errors/)

Модель

ONE-OF

(nullable)

1:{...}

Описание ошибки

error_code: string

Код ошибки.

reason: string

Причина ошибки.

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки.

}

Пример

{...}

"error_code":"not_found",

"reason":"Вебхук с Id '644bdc87dbd6fc3747887c7b' не найден",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

id Идентификатор вебхука.

Возвращает состояние вебхука.

get /gw/oauth2/webhooks/v1/status/{id}

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор вебхука. Пример: 644bdc87dbd6fc3747887c7b

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/gw/oauth2/webhooks/v1/status/{id}' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("GET", "https://api.ati.su", "/gw/oauth2/webhooks/v1/status/{id}");

Ответ

200 HTTP 200 с состоянием вебхука при успехе; 4XX при ошибке запроса.

Модель

{...}

Состояние вебхука

status: xxx-of

Идентификатор состояния вебхука.

deactivatedactivecreatedverification

hook:

Деактивированный вебхук.

ONE-OF

1:{...}

Деактивированный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

first_failure_date: date-time

Дата первой проваленной отправки

}

hook:

Активный вебхук.

ONE-OF

1:{...}

Активный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

suspended_until: date-time (nullable)

Дата окончания приостановки подписки

}

hook:

Созданный вебхук.

ONE-OF

1:{...}

Созданный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

}

verification:

Проверка вебхука

ONE-OF

1:{...}

Проверка вебхука

status: xxx-of

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

failedprogress

fail_reason*:

Причина провала проверки.

ONE-OF

enum

[unknown_error, tls_error, socket_error, request_error, challenge_mismatch, wrong_response_format]

Причины провала проверки вебхука

• unknown_error — Неизвестная ошибка

  Ошибка на стороне АТИ

• tls_error — Ошибка установки защищенного соединения

  Возможно используется недоверенный сертификат, или сервер не поддерживает протокол HTTPS

• socket_error — Ошибка создания TCP соединения

  Возможно указан недоступный IP адрес, DNS-имя, разрешающееся в недоступный IP адрес, или сервер не принимает запросы

• request_error — Ошибка запроса

  Получен HTTP-код, отличный от 200, или превышено время ожидания ответа

• challenge_mismatch — Challenge не совпадает

• wrong_response_format — Неправильный формат ответа

  Формат ответа отличается от JSON-строки

}

hook:

Проверяемый вебхук.

ONE-OF

1:{...}

Проверяемый вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

}

}

Пример

{...}

"status":"created",

"verification":{...},

"status":"progress"

},

"hook":{...}

"id":"644bdc87dbd6fc3747887c7b",

"callback":"https://hooks.example.com/webhook",

"topic":"cargoes.on_boards",

"application_id":"cargo-integrator",

"contact_id":14612,

"key":"a3f1c8e92b7d4e6a"

}

}

4XX Ошибка запроса. [Подробнее про ошибки API](/documentation/errors/)

Модель

ONE-OF

(nullable)

1:{...}

Описание ошибки

error_code: string

Код ошибки.

reason: string

Причина ошибки.

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки.

}

Пример

{...}

"error_code":"not_found",

"reason":"Вебхук с Id '644bdc87dbd6fc3747887c7b' не найден",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

id Идентификатор вебхука.

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

Версия OAuth2.0 v1 OAuth2.0 v2

Получить параметры фильтра

get /webhooks/v1/subscriptions/{id}

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор подписки. Пример: 644bdc87dbd6fc3747887c7b

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/webhooks/v1/subscriptions/{id}' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("GET", "https://api.ati.su", "/webhooks/v1/subscriptions/{id}");

Ответ

200

Модель

{...}

Параметры подписки.

channel: xxx-of

Канал подписки.

cargoesauctions

boards*: [string]

Идентификаторы площадок для подписки.

boards*: [string]

Идентификаторы площадок для подписки.

}

Пример

{...}

"channel":"cargoes",

"boards":[...]

"string"

]

}

Консоль

Отправить

Параметры

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

Получить параметры фильтра

get /gw/oauth2/webhooks/v1/subscriptions/{id}

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор подписки. Пример: 644bdc87dbd6fc3747887c7b

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/gw/oauth2/webhooks/v1/subscriptions/{id}' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("GET", "https://api.ati.su", "/gw/oauth2/webhooks/v1/subscriptions/{id}");

Ответ

200

Модель

{...}

Параметры подписки.

channel: xxx-of

Канал подписки.

cargoesauctions

boards*: [string]

Идентификаторы площадок для подписки.

boards*: [string]

Идентификаторы площадок для подписки.

}

Пример

{...}

"channel":"cargoes",

"boards":[...]

"string"

]

}

Консоль

Отправить

Параметры

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

Проверка состояния нескольких вебхуков

Версия OAuth2.0 v1 OAuth2.0 v2

Возвращает состояния нескольких вебхуков.

get /webhooks/v1/status

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
statuses	string[]	query	Фильтр по состояниям вебхуков. Пример: active

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/webhooks/v1/status' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("GET", "https://api.ati.su", "/webhooks/v1/status");

Ответ

200 HTTP 200 со списком состояний вебхуков.

Модель

[{...}]

Состояние вебхука

status: xxx-of

Идентификатор состояния вебхука.

deactivatedactivecreatedverification

hook:

Деактивированный вебхук.

ONE-OF

1:{...}

Деактивированный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

first_failure_date: date-time

Дата первой проваленной отправки

}

hook:

Активный вебхук.

ONE-OF

1:{...}

Активный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

suspended_until: date-time (nullable)

Дата окончания приостановки подписки

}

hook:

Созданный вебхук.

ONE-OF

1:{...}

Созданный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

}

verification:

Проверка вебхука

ONE-OF

1:{...}

Проверка вебхука

status: xxx-of

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

failedprogress

fail_reason*:

Причина провала проверки.

ONE-OF

enum

[unknown_error, tls_error, socket_error, request_error, challenge_mismatch, wrong_response_format]

Причины провала проверки вебхука

• unknown_error — Неизвестная ошибка

  Ошибка на стороне АТИ

• tls_error — Ошибка установки защищенного соединения

  Возможно используется недоверенный сертификат, или сервер не поддерживает протокол HTTPS

• socket_error — Ошибка создания TCP соединения

  Возможно указан недоступный IP адрес, DNS-имя, разрешающееся в недоступный IP адрес, или сервер не принимает запросы

• request_error — Ошибка запроса

  Получен HTTP-код, отличный от 200, или превышено время ожидания ответа

• challenge_mismatch — Challenge не совпадает

• wrong_response_format — Неправильный формат ответа

  Формат ответа отличается от JSON-строки

}

hook:

Проверяемый вебхук.

ONE-OF

1:{...}

Проверяемый вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

}

}]

Пример

[...]

{...}

"status":"created",

"verification":{...},

"status":"progress"

},

"hook":{...}

"id":"644bdc87dbd6fc3747887c7b",

"callback":"https://hooks.example.com/webhook",

"topic":"cargoes.on_boards",

"application_id":"cargo-integrator",

"contact_id":14612,

"key":"a3f1c8e92b7d4e6a"

}

}

]

Консоль

Отправить

Параметры

statuses Фильтр по состояниям вебхуков.

Возвращает состояния нескольких вебхуков.

get /gw/oauth2/webhooks/v1/status

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
statuses	string[]	query	Фильтр по состояниям вебхуков. Пример: active

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/gw/oauth2/webhooks/v1/status' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("GET", "https://api.ati.su", "/gw/oauth2/webhooks/v1/status");

Ответ

200 HTTP 200 со списком состояний вебхуков.

Модель

[{...}]

Состояние вебхука

status: xxx-of

Идентификатор состояния вебхука.

deactivatedactivecreatedverification

hook:

Деактивированный вебхук.

ONE-OF

1:{...}

Деактивированный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

first_failure_date: date-time

Дата первой проваленной отправки

}

hook:

Активный вебхук.

ONE-OF

1:{...}

Активный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

suspended_until: date-time (nullable)

Дата окончания приостановки подписки

}

hook:

Созданный вебхук.

ONE-OF

1:{...}

Созданный вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

}

verification:

Проверка вебхука

ONE-OF

1:{...}

Проверка вебхука

status: xxx-of

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

failedprogress

fail_reason*:

Причина провала проверки.

ONE-OF

enum

[unknown_error, tls_error, socket_error, request_error, challenge_mismatch, wrong_response_format]

Причины провала проверки вебхука

• unknown_error — Неизвестная ошибка

  Ошибка на стороне АТИ

• tls_error — Ошибка установки защищенного соединения

  Возможно используется недоверенный сертификат, или сервер не поддерживает протокол HTTPS

• socket_error — Ошибка создания TCP соединения

  Возможно указан недоступный IP адрес, DNS-имя, разрешающееся в недоступный IP адрес, или сервер не принимает запросы

• request_error — Ошибка запроса

  Получен HTTP-код, отличный от 200, или превышено время ожидания ответа

• challenge_mismatch — Challenge не совпадает

• wrong_response_format — Неправильный формат ответа

  Формат ответа отличается от JSON-строки

}

hook:

Проверяемый вебхук.

ONE-OF

1:{...}

Проверяемый вебхук.

id*: string

Минимальное количество символов: 1

Идентификатор вебхука.

callback*: string

Минимальное количество символов: 1

URL, на который отправляются уведомления.

topic*: string

Минимальное количество символов: 1

Тема подписки.

application_id: string (nullable)

Идентификатор приложения. null, если вебхук создан без приложения.

contact_id*: integer

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

key*: string

Минимальное количество символов: 1

Ключ, используемый для подписывания запросов.

}

}]

Пример

[...]

{...}

"status":"created",

"verification":{...},

"status":"progress"

},

"hook":{...}

"id":"644bdc87dbd6fc3747887c7b",

"callback":"https://hooks.example.com/webhook",

"topic":"cargoes.on_boards",

"application_id":"cargo-integrator",

"contact_id":14612,

"key":"a3f1c8e92b7d4e6a"

}

}

]

Консоль

Отправить

Параметры

statuses Фильтр по состояниям вебхуков.

Оповещения о смене состояния вебхука

GET-метод по URL вебхука используется также для оповещений о смене его (вебхука) состояния. Во все вызовы передается параметр topic, обозначающий тему подписки.

Событие	Параметры	Описание
Провал верификации	status: verification verification_status: failed	Проблемы с верификацией.
Провал отправки	distribution_status: failed since: YYYY-MM-DDThh:mm:ss	Проблемы с отправкой сообщения. В параметре since указана дата первой проваленной отправки.
Провал повторной отправки	distribution_status: failed_retry failed_count: число	Проблемы с повторной отправкой сообщений. В параметре failed_count указано количество повторно отправляемых сообщений.
Остальные изменения состояния вебхука	status: одно из значений поля status

Оповещение о смене статуса не ожидает ответа.

Получение сообщений

При возникновении события, вызывается POST метод вебхука с параметром topic. В теле запроса передается одна или несколько обновленных сущностей (параметр entities[].entity) и другие параметры события.

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

Тело запроса

Модель

{...}

Запрос с отправляемыми сообщениями

topic: string

Тема

is_retry: boolean

Является ли отправка повторной

}

Пример

{...}

"topic":"orders",

"is_retry":false

}

Пример отправки сообщения

POST /webhook?topic=orders HTTP/1.1
Host: example.org:443
Date: Thu, 01 Jan 1970 00:00:00 GMT
Digest: SypZnuCTiysyLuUz9DOYckaU/vf0zrzdxKL1j/sHemg=
Content-Type: application/json
Content-Length: 208
Authorization: HMAC-SHA-256 Credential=6447f577905114d5b9b2c618&SignedHeaders=Date;Digest;Host&Signature=V8CpKji2ysF5h5VVerhcq/GMQGxoHwf0EcGiDIL41e0=

{"topic": "orders", "entities": [{"entity_id": "4ea8c372-9510-4880-a80d-fb9ac19129cf", "action_date": "2021-04-30T05:12:41.687Z", "entity": {"id": "4ea8c372-9510-4880-a80d-fb9ac19129cf"}}], "is_retry": false}

Ожидается ответ с кодом 2xx (Successful)² на протяжении 20 секунд. В ином случае отправка помечается проваленной, и отправляется оповещение об изменении состояния вебхука.

Для временной приостановки получения сообщений, можно использовать ответ 429 (Too Many Requests)³ с заголовком Retry-After⁴. Приостановка возможна не более чем на 1 день.

Если был получен ответ 410 (Gone)⁵, вебхук удаляется без возможности восстановления.

Повторные отправки

Как только вебхук успешно примет сообщение, будет предпринята попытка повторно отправить сообщения, отправка которых провалилась ранее. Отличить повторную отправку от первоначальной можно по значению true в заголовке ATI-Is-Retry запроса. В случае провала повторной отправки, она будет отложена до успешного получения вебхуком нового сообщения.

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

До тех пор, пока вебхук не удален, можно получить его проваленные отправки.

Версия OAuth2.0 v1 OAuth2.0 v2

Возвращает проваленные отправки вебхука.

get /webhooks/v1/distributions/failed/{id}

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор вебхука. Пример: 644bdc87dbd6fc3747887c7b
since	string (date-time)	query	Начальная дата фильтра (UTC). Пример: 2024-01-15T10:30:00Z

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/webhooks/v1/distributions/failed/{id}' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("GET", "https://api.ati.su", "/webhooks/v1/distributions/failed/{id}");

Ответ

200 HTTP 200 со списком проваленных отправок; 4XX при ошибке запроса.

Модель

[{...}]

Проваленная отправка сообщения.

entity_id: string

Идентификатор отправляемой сущности.

action_date: date-time

Дата события (UTC).

status:

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

ONE-OF

enum

[failed]

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

• failed — Провалена

entity: {missing-type-info} (nullable)

Отправляемая сущность

}]

Пример

[...]

{...}

"entity_id":"5710d7a6de0c8b0ee83565b9",

"action_date":"2024-01-15T10:30:00Z",

"status":"failed",

"entity":null

}

]

4XX Ошибка запроса. [Подробнее про ошибки API](/documentation/errors/)

Модель

ONE-OF

(nullable)

1:{...}

Описание ошибки

error_code: string

Код ошибки.

reason: string

Причина ошибки.

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки.

}

Пример

{...}

"error_code":"not_found",

"reason":"Вебхук с Id '644bdc87dbd6fc3747887c7b' не найден",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

id Идентификатор вебхука.

since Начальная дата фильтра (UTC).

Возвращает проваленные отправки вебхука.

get /gw/oauth2/webhooks/v1/distributions/failed/{id}

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор вебхука. Пример: 644bdc87dbd6fc3747887c7b
since	string (date-time)	query	Начальная дата фильтра (UTC). Пример: 2024-01-15T10:30:00Z

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/gw/oauth2/webhooks/v1/distributions/failed/{id}' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("GET", "https://api.ati.su", "/gw/oauth2/webhooks/v1/distributions/failed/{id}");

Ответ

200 HTTP 200 со списком проваленных отправок; 4XX при ошибке запроса.

Модель

[{...}]

Проваленная отправка сообщения.

entity_id: string

Идентификатор отправляемой сущности.

action_date: date-time

Дата события (UTC).

status:

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

ONE-OF

enum

[failed]

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

• failed — Провалена

entity: {missing-type-info} (nullable)

Отправляемая сущность

}]

Пример

[...]

{...}

"entity_id":"5710d7a6de0c8b0ee83565b9",

"action_date":"2024-01-15T10:30:00Z",

"status":"failed",

"entity":null

}

]

4XX Ошибка запроса. [Подробнее про ошибки API](/documentation/errors/)

Модель

ONE-OF

(nullable)

1:{...}

Описание ошибки

error_code: string

Код ошибки.

reason: string

Причина ошибки.

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки.

}

Пример

{...}

"error_code":"not_found",

"reason":"Вебхук с Id '644bdc87dbd6fc3747887c7b' не найден",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

id Идентификатор вебхука.

since Начальная дата фильтра (UTC).

Редактирование вебхука

Изменение параметров вебхука не предусмотрено, но для тем подписки с фильтром возможно редактирование фильтра с помощью соответствующего метода. Изменение канала подписки невозможно.

Версия OAuth2.0 v1 OAuth2.0 v2

Отредактировать параметры фильтра

put /webhooks/v1/subscriptions/{id}

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор подписки. Пример: 644bdc87dbd6fc3747887c7b

Запрос

Модель

{...}

Параметры подписки.

channel: xxx-of

Канал подписки.

cargoesauctions

boards*: [string]

Идентификаторы площадок для подписки.

boards*: [string]

Идентификаторы площадок для подписки.

}

Пример запроса

CURL

curl 'https://api.ati.su/webhooks/v1/subscriptions/{id}' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{"channel":"cargoes","boards":["string"]}'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("PUT", "https://api.ati.su", "/webhooks/v1/subscriptions/{id}", "{""channel"":""cargoes"",""boards"":[""string""]}");

Ответ

200

Модель

{...}

Параметры подписки.

channel: xxx-of

Канал подписки.

cargoesauctions

boards*: [string]

Идентификаторы площадок для подписки.

boards*: [string]

Идентификаторы площадок для подписки.

}

Пример

{...}

"channel":"cargoes",

"boards":[...]

"string"

]

}

Консоль

Отправить

Параметры

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

{ "channel": "cargoes", "boards": [ "string" ] }

Отредактировать параметры фильтра

put /gw/oauth2/webhooks/v1/subscriptions/{id}

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор подписки. Пример: 644bdc87dbd6fc3747887c7b

Запрос

Модель

{...}

Параметры подписки.

channel: xxx-of

Канал подписки.

cargoesauctions

boards*: [string]

Идентификаторы площадок для подписки.

boards*: [string]

Идентификаторы площадок для подписки.

}

Пример запроса

CURL

curl 'https://api.ati.su/gw/oauth2/webhooks/v1/subscriptions/{id}' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{"channel":"cargoes","boards":["string"]}'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("PUT", "https://api.ati.su", "/gw/oauth2/webhooks/v1/subscriptions/{id}", "{""channel"":""cargoes"",""boards"":[""string""]}");

Ответ

200

Модель

{...}

Параметры подписки.

channel: xxx-of

Канал подписки.

cargoesauctions

boards*: [string]

Идентификаторы площадок для подписки.

boards*: [string]

Идентификаторы площадок для подписки.

}

Пример

{...}

"channel":"cargoes",

"boards":[...]

"string"

]

}

Консоль

Отправить

Параметры

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

{ "channel": "cargoes", "boards": [ "string" ] }

Удаление вебхука

При удалении вебхука, прекращается отправка сообщений в него, а также удаляются его проваленные отправки.

Версия OAuth2.0 v1 OAuth2.0 v2

Удаляет вебхук.

delete /webhooks/v1/delete/{id}

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор вебхука. Пример: 644bdc87dbd6fc3747887c7b

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/webhooks/v1/delete/{id}' \
  -X 'DELETE' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("DELETE", "https://api.ati.su", "/webhooks/v1/delete/{id}");

Ответ

202 HTTP 202, если удаление принято; 4XX при ошибке запроса.

Модель

{}

Пустой ответ: операция принята к асинхронному выполнению.

Пример

{}

4XX Ошибка запроса. [Подробнее про ошибки API](/documentation/errors/)

Модель

ONE-OF

(nullable)

1:{...}

Описание ошибки

error_code: string

Код ошибки.

reason: string

Причина ошибки.

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки.

}

Пример

{...}

"error_code":"not_found",

"reason":"Вебхук с Id '644bdc87dbd6fc3747887c7b' не найден",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

id Идентификатор вебхука.

Удаляет вебхук.

delete /gw/oauth2/webhooks/v1/delete/{id}

Отправка запросов с авторизацией OAuth2.0 v2 временно недоступна

Модель и примеры

Параметры

Параметр	Тип	Расположение	Описание
id обязательный	string	path	Идентификатор вебхука. Пример: 644bdc87dbd6fc3747887c7b

Запрос

Пример запроса

CURL

curl 'https://api.ati.su/gw/oauth2/webhooks/v1/delete/{id}' \
  -X 'DELETE' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'

1C

Процедура ВыполнитьHTTPЗапрос(МетодЗапроса, АдресХоста, АдресРесурса, ТекстЗапроса) Экспорт
  ЗаголовкиHTTP = Новый Соответствие();
  ЗаголовкиHTTP.Вставить("Accept", "application/json");
  ЗаголовкиHTTP.Вставить("Content-Type", "application/json");
  ЗаголовкиHTTP.Вставить("Authorization", "Bearer {authorizationToken}");
  HTTPЗапрос = Новый HTTPЗапрос(АдресРесурса, ЗаголовкиHTTP);
  HTTPЗапрос.УстановитьТелоИзСтроки(ТекстЗапроса, КодировкаТекста.UTF8, ИспользованиеByteOrderMark.НеИспользовать);
  ЗащищенноеСоединениеSSL = Новый ЗащищенноеСоединениеOpenSSL(Новый СертификатКлиентаWindows, Новый СертификатыУдостоверяющихЦентровWindows);

  Соединение = Новый HTTPСоединение(АдресХоста,,,,,, ЗащищенноеСоединениеSSL);

  Попытка
    Ответ = Соединение.ВызватьHTTPМетод(МетодЗапроса, HTTPЗапрос);
    Сообщить("Код ответа: " + Ответ.КодСостояния);
    Сообщить("Ответ: " + Ответ.ПолучитьТелоКакСтроку("UTF-8"));
  Исключение
    Сообщить("Ошибка выполнения запроса!" + Символы.ПС + ОписаниеОшибки());
  КонецПопытки;
КонецПроцедуры

ВыполнитьHTTPЗапрос("DELETE", "https://api.ati.su", "/gw/oauth2/webhooks/v1/delete/{id}");

Ответ

202 HTTP 202, если удаление принято; 4XX при ошибке запроса.

Модель

{}

Пустой ответ: операция принята к асинхронному выполнению.

Пример

{}

4XX Ошибка запроса. [Подробнее про ошибки API](/documentation/errors/)

Модель

ONE-OF

(nullable)

1:{...}

Описание ошибки

error_code: string

Код ошибки.

reason: string

Причина ошибки.

details: {missing-type-info}

Дополнительные параметры

error_list:[{}]

Вложенные ошибки.

}

Пример

{...}

"error_code":"not_found",

"reason":"Вебхук с Id '644bdc87dbd6fc3747887c7b' не найден",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

id Идентификатор вебхука.

Footnotes

1. RFC 1918 | Private Address Space ↩ ↩²

2. RFC 7231 | Successful 2xx ↩

3. RFC 6585 | 429 Too Many Requests ↩

4. RFC 7231 | Retry-After ↩

5. RFC 7231 | 410 Gone ↩