Вебхуки

Вебхуки предоставляют возможность получать обновления по интересующим темам, как только они произошли в системе 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: enum

[cargoes.on_boards, auctions.on_boards]

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

• cargoes.on_boards — Грузы на площадках
• auctions.on_boards — Торги на площадках

auctions.on_boardscargoes.on_boards

boards: [string]

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

boards: [string]

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

}

Пример

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

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

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

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

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

post /webhooks/v1/create

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

Запрос

Модель

{...}

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

subscription_type: enum (nullable)

[normal, complex]

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

• normal — Обычная
• complex — С возможностью настройки фильтров

complexnormal

topic: string

Тема

callback: string

URL

subscription: {missing-type-info}

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

topic: string

Тема

callback: string

URL

}

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

CURL

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

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", "{""topic"":""cargoes.on_boards"",""callback"":""https://example.com/webhook?userId=000000"",""subscription_type"":""complex"",""subscription"":{""channel"":""cargoes.on_boards"",""boards"":[""644bdc87dbd6fc3747887c7b""]}}");

Ответ

202

Модель

null

Пример

null

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

Модель

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Пример

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

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

{ "topic": "cargoes.on_boards", "callback": "https://example.com/webhook?userId=000000", "subscription_type": "complex", "subscription": { "channel": "cargoes.on_boards", "boards": [ "644bdc87dbd6fc3747887c7b" ] } }

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

post /gw/oauth2/webhooks/v1/create

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

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

Запрос

Модель

{...}

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

subscription_type: enum (nullable)

[normal, complex]

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

• normal — Обычная
• complex — С возможностью настройки фильтров

complexnormal

topic: string

Тема

callback: string

URL

subscription: {missing-type-info}

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

topic: string

Тема

callback: string

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 '{"topic":"cargoes.on_boards","callback":"https://example.com/webhook?userId=000000","subscription_type":"complex","subscription":{"channel":"cargoes.on_boards","boards":["644bdc87dbd6fc3747887c7b"]}}'

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", "{""topic"":""cargoes.on_boards"",""callback"":""https://example.com/webhook?userId=000000"",""subscription_type"":""complex"",""subscription"":{""channel"":""cargoes.on_boards"",""boards"":[""644bdc87dbd6fc3747887c7b""]}}");

Ответ

202

Модель

null

Пример

null

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

Модель

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Пример

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

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

{ "topic": "cargoes.on_boards", "callback": "https://example.com/webhook?userId=000000", "subscription_type": "complex", "subscription": { "channel": "cargoes.on_boards", "boards": [ "644bdc87dbd6fc3747887c7b" ] } }

В ответе содержится заголовок 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}

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

Запрос

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

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

Модель

{...}

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

status: enum

[created, verification, active, removed, deactivated]

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

• created — Создан

• verification — Проверяется

• active — Активен

• removed — Удален

• deactivated — Деактивирован

  Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

deactivatedactivecreatedverification

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

first_failure_date: date-time

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

suspended_until: date-time (nullable)

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

}

verification:{...}

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

status: enum

[progress, failed]

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

• progress — Выполнение
• failed — Провалена

failedprogress

fail_reason: enum

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

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

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

  Ошибка на стороне ATI.SU

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

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

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

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

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

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

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

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

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

}

}

Пример

{...}

"status":"deactivated",

"hook":{...}

"id":"string",

"callback":"string",

"topic":"string",

"application_id":"string",

"contact_id":0,

"key":"string",

"first_failure_date":"1970-01-01T00:00:00.000Z"

}

}

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

Модель

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Пример

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

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

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

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

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

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

Запрос

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

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

Модель

{...}

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

status: enum

[created, verification, active, removed, deactivated]

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

• created — Создан

• verification — Проверяется

• active — Активен

• removed — Удален

• deactivated — Деактивирован

  Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

deactivatedactivecreatedverification

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

first_failure_date: date-time

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

suspended_until: date-time (nullable)

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

}

verification:{...}

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

status: enum

[progress, failed]

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

• progress — Выполнение
• failed — Провалена

failedprogress

fail_reason: enum

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

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

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

  Ошибка на стороне ATI.SU

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

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

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

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

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

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

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

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

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

}

}

Пример

{...}

"status":"deactivated",

"hook":{...}

"id":"string",

"callback":"string",

"topic":"string",

"application_id":"string",

"contact_id":0,

"key":"string",

"first_failure_date":"1970-01-01T00:00:00.000Z"

}

}

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

Модель

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Пример

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

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

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

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

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

get /webhooks/v1/subscriptions/{id}

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

Запрос

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

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: enum

[cargoes.on_boards, auctions.on_boards]

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

• cargoes.on_boards — Грузы на площадках
• auctions.on_boards — Торги на площадках

auctions.on_boardscargoes.on_boards

boards: [string]

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

boards: [string]

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

}

Пример

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

Консоль

Отправить

Параметры

id Id вебхука

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

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

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

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

Запрос

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

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: enum

[cargoes.on_boards, auctions.on_boards]

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

• cargoes.on_boards — Грузы на площадках
• auctions.on_boards — Торги на площадках

auctions.on_boardscargoes.on_boards

boards: [string]

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

boards: [string]

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

}

Пример

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

Консоль

Отправить

Параметры

id Id вебхука

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

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

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

get /webhooks/v1/status

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

Запрос

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

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

Модель

[{...}]

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

status: enum

[created, verification, active, removed, deactivated]

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

• created — Создан

• verification — Проверяется

• active — Активен

• removed — Удален

• deactivated — Деактивирован

  Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

deactivatedactivecreatedverification

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

first_failure_date: date-time

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

suspended_until: date-time (nullable)

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

}

verification:{...}

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

status: enum

[progress, failed]

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

• progress — Выполнение
• failed — Провалена

failedprogress

fail_reason: enum

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

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

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

  Ошибка на стороне ATI.SU

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

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

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

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

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

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

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

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

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

}

}]

Пример

[...]

{...}

"status":"deactivated",

"hook":{...}

"id":"string",

"callback":"string",

"topic":"string",

"application_id":"string",

"contact_id":0,

"key":"string",

"first_failure_date":"1970-01-01T00:00:00.000Z"

}

}

]

Консоль

Отправить

Параметры

statuses Идентификатор состояния вебхука - `created` — Создан - `verification` — Проверяется - `active` — Активен - `removed` — Удален - `deactivated` — Деактивирован > Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

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

get /gw/oauth2/webhooks/v1/status

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

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

Запрос

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

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

Модель

[{...}]

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

status: enum

[created, verification, active, removed, deactivated]

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

• created — Создан

• verification — Проверяется

• active — Активен

• removed — Удален

• deactivated — Деактивирован

  Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

deactivatedactivecreatedverification

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

first_failure_date: date-time

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

suspended_until: date-time (nullable)

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

}

verification:{...}

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

status: enum

[progress, failed]

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

• progress — Выполнение
• failed — Провалена

failedprogress

fail_reason: enum

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

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

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

  Ошибка на стороне ATI.SU

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

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

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

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

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

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

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

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

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

}

hook:{...}

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

id: string

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

callback: string

URL

topic: string

Тема

application_id: string (nullable)

Идентификатор приложения

contact_id: integer

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

key: string (nullable)

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

}

}]

Пример

[...]

{...}

"status":"deactivated",

"hook":{...}

"id":"string",

"callback":"string",

"topic":"string",

"application_id":"string",

"contact_id":0,

"key":"string",

"first_failure_date":"1970-01-01T00:00:00.000Z"

}

}

]

Консоль

Отправить

Параметры

statuses Идентификатор состояния вебхука - `created` — Создан - `verification` — Проверяется - `active` — Активен - `removed` — Удален - `deactivated` — Деактивирован > Хук деактивируется, если на протяжении нескольких дней ни одна отправка в него не удалась

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

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

Тема

entities:[{...}]

Сообщения

entity_id: string

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

action_date: date-time

Дата события

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

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

}]

is_retry: boolean

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

}

Пример

{...}

"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

}

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

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}

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

Запрос

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

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

Модель

[{...}]

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

entity_id: string

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

action_date: date-time

Дата события

status: enum

[failed]

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

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

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

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

}]

Пример

[...]

{...}

"entity_id":"string",

"action_date":"1970-01-01T00:00:00.000Z",

"status":"failed",

"entity":null

}

]

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

Модель

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Пример

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

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

since Начальная дата фильтра в формате ISO

Получить проваленные отправки

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

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

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

Запрос

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

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

Модель

[{...}]

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

entity_id: string

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

action_date: date-time

Дата события

status: enum

[failed]

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

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

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

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

}]

Пример

[...]

{...}

"entity_id":"string",

"action_date":"1970-01-01T00:00:00.000Z",

"status":"failed",

"entity":null

}

]

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

Модель

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Пример

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

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

since Начальная дата фильтра в формате ISO

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

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

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

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

put /webhooks/v1/subscriptions/{id}

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

Запрос

Модель

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

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

• cargoes.on_boards — Грузы на площадках
• auctions.on_boards — Торги на площадках

auctions.on_boardscargoes.on_boards

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.on_boards","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.on_boards"",""boards"":[""string""]}");

Ответ

200

Модель

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

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

• cargoes.on_boards — Грузы на площадках
• auctions.on_boards — Торги на площадках

auctions.on_boardscargoes.on_boards

boards: [string]

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

boards: [string]

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

}

Пример

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

Консоль

Отправить

Параметры

id Id вебхука

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

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

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

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

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

Запрос

Модель

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

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

• cargoes.on_boards — Грузы на площадках
• auctions.on_boards — Торги на площадках

auctions.on_boardscargoes.on_boards

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.on_boards","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.on_boards"",""boards"":[""string""]}");

Ответ

200

Модель

{...}

channel: enum

[cargoes.on_boards, auctions.on_boards]

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

• cargoes.on_boards — Грузы на площадках
• auctions.on_boards — Торги на площадках

auctions.on_boardscargoes.on_boards

boards: [string]

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

boards: [string]

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

}

Пример

{...}

"channel":"cargoes.on_boards",

"boards":[...]

"string"

]

}

Консоль

Отправить

Параметры

id Id вебхука

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

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

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

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

Удалить вебхук

delete /webhooks/v1/delete/{id}

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

Запрос

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

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

Модель

null

Пример

null

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

Модель

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Пример

{...}

"error_code":"string",

"reason":"string",

"details":"?",

"error_list":[...]

{}

]

}

Консоль

Отправить

Параметры

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

Удалить вебхук

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

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

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

Запрос

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

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

Модель

null

Пример

null

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

Модель

{...}

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

error_code: string

Код ошибки

reason: string

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

details: {missing-type-info}

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

error_list:[{}]

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

}

Пример

{...}

"error_code":"string",

"reason":"string",

"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 ↩