Новые события ленты потоком SSE

Переподключение — с заголовком Last-Event-ID: события до него не повторяются. once=1 — догнать хвост и закрыть поток. Без курсора — только события новее самого свежего на момент подключения. Время события ставится до записи, поэтому событие может появиться в базе позже уже отданного более нового. Чтобы такие опоздавшие не терялись, подключение с курсором (каждый опрос once=1, переподключение после обрыва) заново отдаёт события последних 30 с до курсора, а открытый поток досылает опоздавшие в том же окне. Поэтому одно событие может прийти несколько раз: клиент обязан отсекать повторы по id в data — событие с уже виденным id заменяет прежнее, а не добавляется. id кадра — курсор для переподключения: самое новое из уже отданных, у опоздавшего и повтора он не меняется. Каждые 15 с — `event: ping` (пропускать). Сбой ленты — `event: error` с data { error: "feed_failed", message } и конец потока: переподключитесь. Доступ: company.read. Доступно по ключу API.

GET /v1/companies/{co}/feed/events

Новые события ленты потоком SSE

cURL

curl --request GET \
  --url https://api.tungo.kz/v1/companies/{co}/feed/events \
  --cookie tungo.session_token=

200

{
  "id": "<string>",
  "cursor": "<string>",
  "section": "auto",
  "section_title": "<string>",
  "at": "2023-11-07T05:31:56Z",
  "title": "Реализация товаров и услуг №0000-000123 записан и сверен",
  "actions": [
    {
      "action": "open",
      "label": "<string>",
      "method": "GET",
      "href": "<string>",
      "enabled": true,
      "hint": "<string>",
      "body": {
        "batch_id": "bat_01jz8x3m4n5p6q7r8s9t0v1w2x",
        "post": true
      }
    }
  ],
  "detail": "<string>",
  "proposal_id": "<string>",
  "dialog_id": "<string>",
  "batch_id": "<string>",
  "status": "previewed",
  "status_title": "<string>",
  "amount": {
    "amount": 1234.5,
    "amount_tiyn": 123450,
    "formatted": "1 234,50 ₸"
  },
  "actor": "<string>",
  "actor_name": "<string>"
}

Авторизации

sessionapiKeybearerKey

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

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

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

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

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

Параметры запроса

cursor · string

С какого события (cursor из FeedItem); заголовок Last-Event-ID важнее

section · enum<string>

Только этот раздел; без него — все Раздел ленты: auto — «Сделано автоматически» (записано в 1С, проверки учёта без серьёзных находок); decision — «Требует решения» (ждёт одобрения, выписка дня); question — «Вопросы от ИИ» (блокеры, вопросы, сбои автоматизаций)

Доступные опции: auto, decision, question

once · enum<string>

1 — отдать накопившееся и закрыть поток (для опроса без постоянного соединения)

Доступные опции: 1

Ответ

200

text/event-stream

События ленты: id — курсор для переподключения, event: feed, data — FeedItem

Карточка ленты: событие по предложению, вопрос ИИ, выписка дня, проверка учёта или запуск автоматизации

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

Устойчивый id события ленты (не номер предложения): ключ для списка в интерфейсе

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

Курсор этого события: передавать в ?cursor= и в Last-Event-ID

section · enum<string> · обязательно

Раздел ленты: auto — «Сделано автоматически» (записано в 1С, проверки учёта без серьёзных находок); decision — «Требует решения» (ждёт одобрения, выписка дня); question — «Вопросы от ИИ» (блокеры, вопросы, сбои автоматизаций)

Доступные опции: auto, decision, question

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

Название раздела по-русски

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

Когда случилось, ISO 8601 UTC

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

Заголовок карточки

Пример:

"Реализация товаров и услуг №0000-000123 записан и сверен"

actions · object[] · обязательно

Кнопки карточки в нужном порядке

Show child attributes

detail · string

Подробности: блокеры, расхождения, текст вопроса или отчёта

proposal_id · string

Номер предложения (P-…), если событие про него

dialog_id · string

Разговор чата, из которого предложение: «Открыть разговор» — GET …/chat/{dialog_id}. Нет — предложение не из чата

batch_id · string

Задание пачки (выписка дня): сводка — GET …/batch/{batch_id}/summary

status · enum<string>

Где предложение в жизненном цикле (подпись по-русски — в status_title рядом):

• previewed — ждёт решения бухгалтера: показать кнопки «Записать» и «Отклонить»;
• approved — одобрено, но запись в 1С не закончена (1С не ответила): «Записать» ещё раз безопасно — второй документ не создастся;
• rejected — отклонено, в 1С ничего не записано; конечное;
• committed — записано в 1С черновиком, без проведения (проводок нет);
• posted — записано и проведено, проводки ещё не сверены;
• verified — проведено, фактические проводки 1С совпали с ожидаемыми; конечное, всё хорошо;
• mismatch — проведено, но проводки расходятся с ожидаемыми: показать предупреждение, причины — в result.mismatches;
• failed — записать не удалось: причина — в последней записи history.

Доступные опции: previewed, approved, rejected, committed, posted, verified, mismatch, failed

status_title · string

Статус предложения по-русски

amount · object

Сумма документа, если есть

Show child attributes

actor · string

Кто сделал: usr_… — человек, key_… — ключ API, ai — ИИ, checks — проверки учёта, automation:… — автоматизация, system — сервис

actor_name · string

Имя того, кто сделал, для показа: имя человека, название ключа API, «ИИ-бухгалтер», «Проверки учёта», «Автоматизация»; нет — неизвестно, показать actor