Завести хук

Только тому, у кого есть chat.use (ИИ-бухгалтер): хук может питать сценарий с ИИ, а токен видит только заводящий; без права — 403 permission_error, code missing_permission, permission chat.use. Токен приёма — только в этом ответе; потерянный меняется через rotate. Повтор с тем же Idempotency-Key отдаёт тот же хук без токена (token: null). Сколько хуков у компании — предел настройки automations (hooks_per_company), сверх — 429.

Idempotency-Key: повтор с тем же ключом и тем же телом отдаёт прежний ответ (статус и тело) с заголовком Idempotent-Replayed: true и ничего не делает второй раз; тот же ключ с другим адресом или телом — 422 (error.code = idempotency_key_reused); первый запрос с этим ключом ещё идёт — 409 (error.code = idempotency_in_progress). Запоминается только удачный ответ (2xx): после отказа повтор с тем же ключом выполнится заново. Ключ живёт сутки (настройка idempotency.keys), область — организация и тот, кто прислал (ключ API или человек).

Доступ: automations.manage | company.manage.

Доступно по ключу API.

POST /v1/companies/{co}/automations/hooks

Завести хук

cURL

curl --request POST \
  --url https://api.tungo.kz/v1/companies/{co}/automations/hooks \
  --header 'Content-Type: application/json' \
  --cookie tungo.session_token= \
  --data '
{
  "name": "Оплаты интернет-магазина",
  "signature_secret": "<string>",
  "signature_header": "x-signature",
  "id_path": "data.payment_id"
}
'

201

{
  "id": "hk_01jz8x3m4n5p6q7r8s9t0v1w2x",
  "name": "Оплаты интернет-магазина",
  "enabled": true,
  "token_hint": "…x7Qk",
  "signed": true,
  "signature_header": "x-signature",
  "id_path": "data.payment_id",
  "scenarios_url": "/v1/companies/co_01h455vb4pex5vsknk084sn02q/automations/scenarios",
  "created_at": "2026-10-05T09:30:00.000Z",
  "updated_at": "2026-10-05T09:30:00.000Z",
  "token": "th_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "url": "https://api.tungo.kz/hooks/th_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "token_note": "<string>"
}

Авторизации

sessionapiKeybearerKey

tungo.session_token · string · cookie · обязательно

Сессия кабинета: cookie ставит вход через /v1/auth/* (Better Auth), браузер шлёт её сам — фронтенду кабинета ничего добавлять не нужно (fetch с credentials: 'include'). За HTTPS имя cookie — __Secure-tungo.session_token. Сессия кончилась — 401 authentication_error: отправить на вход.

Заголовки

Idempotency-Key · string

Ключ повтора (например, UUID): повтор с тем же ключом и тем же телом не выполняет действие второй раз, а отдаёт прежний ответ

Maximum string length: 255

Параметры пути

co · string · обязательно

id компании, co_… — из GET /v1/companies

Тело

application/json

Новый хук.

name · string · обязательно

Название хука для людей (1–200 знаков): откуда приходят события.

Required string length: 1 - 200

Пример:

"Оплаты интернет-магазина"

signature_secret · string | null

Секрет подписи (16–500 знаков), общий с отправителем. Задан — каждое событие обязано нести в заголовке signature_header HMAC-SHA256(секрет, сырое тело) в hex (можно с приставкой sha256=), иначе приём отвечает 401. Хранится зашифрованным и обратно не отдаётся — в ответах видно только signed. null или не передан — без подписи (при изменении null снимает подпись). По событиям хука без подписи автоодобрение ничего в 1С не пишет.

Required string length: 16 - 500

signature_header · string

Имя заголовка с подписью: латиница, цифры, дефис, до 64 знаков; приводится к нижнему регистру. Не передан при заведении — x-signature.

Pattern: ^[a-z0-9-]{1,64}$

Пример:

"x-signature"

id_path · string | null

Путь через точку к id события в JSON тела — номер платежа или чека у отправителя. Задан и поле есть — повтор с тем же id считается тем же событием, даже с новым Idempotency-Key. null или нет — id берётся из заголовка Idempotency-Key, затем X-Event-Id, иначе — хеш тела; вдобавок то же тело в окне automations.queue.hook_dedupe_minutes (по умолчанию сутки) считается повтором. Хук, питающий сценарий с автоодобрением, обязан иметь id_path: снять его нельзя (400), а сменить может только тот, у кого есть proposals.approve (иначе 403). В 1С само пишется только событие, номер которого взят из тела по id_path; нет id_path у хука или поля в теле (номер из заголовка) — предложения ждут человека.

Pattern: ^[A-Za-z0-9_.-]{1,200}$

Пример:

"data.payment_id"

Ответ

201

application/json

Хук заведён

Хук с токеном — ответ на заведение и смену токена; токен больше нигде не показывается.

id · string · обязательно

id хука — для адресов …/automations/hooks/{id} и для trigger.hook_id сценария (hk_…)

Пример:

"hk_01jz8x3m4n5p6q7r8s9t0v1w2x"

name · string · обязательно

Название хука для людей

Пример:

"Оплаты интернет-магазина"

enabled · boolean · обязательно

false — хук выключен: события на его адрес получают 404, как на неизвестный

token_hint · string · обязательно

Последние 4 знака токена после многоточия — узнать, какой адрес настроен у отправителя. Сам токен не хранится: потерян — POST …/hooks/{id}/rotate

Пример:

"…x7Qk"

signed · boolean · обязательно

Задан ли секрет подписи: true — события без верной подписи отвергаются (401). Сам секрет не показывается никогда. По событиям хука без подписи автоодобрение ничего в 1С не пишет

signature_header · string · обязательно

Заголовок, в котором отправитель присылает подпись (нижним регистром)

Пример:

"x-signature"

id_path · string | null · обязательно

Путь через точку к id события в JSON тела (номер платежа у отправителя) — по нему отсеиваются повторы. null — id из заголовков Idempotency-Key / X-Event-Id или хеш тела

Пример:

"data.payment_id"

scenarios_url · string · обязательно

Путь API к сценариям компании: сценарии этого хука — те, у которых trigger.hook_id равен id хука

Пример:

"/v1/companies/co_01h455vb4pex5vsknk084sn02q/automations/scenarios"

created_at · string<date-time> · обязательно

Когда заведён, ISO 8601 UTC

Пример:

"2026-10-05T09:30:00.000Z"

updated_at · string<date-time> · обязательно

Когда менялся последний раз, ISO 8601 UTC

Пример:

"2026-10-05T09:30:00.000Z"

token · string | null · обязательно

Токен хука (th_…, 46 знаков) — только в этом ответе: сохраните у отправителя. Кто знает токен, может слать события этой компании. null — повтор запроса с тем же Idempotency-Key: токен уже выдан первым ответом (token_note)

Пример:

"th_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

url · string | null · обязательно

Полный адрес приёма событий (адрес API + /hooks/{token}) — его и дают отправителю. null — повтор с тем же Idempotency-Key

Пример:

"https://api.tungo.kz/hooks/th_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"

token_note · string

Только в повторе с тем же Idempotency-Key: почему token и url — null и что делать (rotate)