Сделать первый запрос

Проверьте ключ, узнайте id организации и компании, прикиньте цену вопроса и задайте его ИИ-бухгалтеру по API.

Первый запрос занимает несколько минут: вы проверяете ключ, узнаёте id компании и отправляете вопрос ИИ-бухгалтеру. Ответ приходит одним JSON или потоком событий, на ваш выбор.

Понадобятся три вещи. Ключ с правом chat.use: см. Создать ключ API. Деньги на балансе платформы: см. Баланс платформы и расход. И компания с подключённой 1С, потому что ИИ-бухгалтер отвечает по её данным. Как подключить 1С, описано в разделе Подключение 1С.

Все примеры ниже используют две переменные окружения. Ключ передаётся в заголовке x-api-key. Вместо него можно прислать Authorization: Bearer tg_….

export TUNGO_API=https://api.tungo.kz
export TUNGO_KEY=tg_…

​

Проверить ключ и узнать id

curl "$TUNGO_API/v1/api-key" -H "x-api-key: $TUNGO_KEY"
curl "$TUNGO_API/v1/companies" -H "x-api-key: $TUNGO_KEY"

Первый запрос рассказывает о самом ключе: права, компании, срок, расход за месяц. Id организации лежит в поле workspace.id и начинается с ws_. Поле blocked_reason показывает, почему запросы к ИИ-бухгалтеру сейчас не пройдут, например из-за пустого баланса. Если в нём null, всё в порядке.

Второй запрос возвращает компании ключа. Id компании лежит в data[].id и начинается с co_. Эти id подставляются в адреса остальных запросов.

export WS=ws_…
export CO=co_…

Подключена ли 1С у компании, показывает отдельный запрос. В ответе поле connected и итог последней проверки подключения.

curl "$TUNGO_API/v1/companies/$CO/onec/status" -H "x-api-key: $TUNGO_KEY"

​

Прикинуть цену вопроса

Этот запрос бесплатный: модель не отвечает, с баланса ничего не списывается.

curl -X POST "$TUNGO_API/v1/companies/$CO/chat/count-tokens" \
  -H "x-api-key: $TUNGO_KEY" -H "Content-Type: application/json" \
  -d '{"message":"Какой НДС у последней реализации?"}'

В ответе четыре числа: input_tokens, max_output_tokens, input_cost_tiyn и max_cost_tiyn. Суммы указаны в тиынах, 1 ₸ = 100 тиын. Это оценка одного вызова модели. Чтобы ответить на вопрос, ИИ-бухгалтер обычно вызывает модель несколько раз, поэтому настоящая цена известна только по факту.

​

Задать вопрос

curl -X POST "$TUNGO_API/v1/companies/$CO/chat" \
  -H "x-api-key: $TUNGO_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-question-1" \
  -d '{"message":"Какой НДС у последней реализации?","stream":false}'

С "stream": false ответ приходит одним JSON, когда ИИ-бухгалтер закончит. Это может занять время, поэтому поставьте в своём клиенте запас по времени ожидания. Главные поля ответа:

• answer — текст ответа в Markdown.
• dialog_id — id чата, он нужен для следующего вопроса.
• proposals — документы, которые ИИ-бухгалтер подготовил для 1С по ходу ответа.
• usage — токены и цена ответа, cost_tiyn в тиынах.
• stop_reason — чем закончился ответ, end_turn значит «ответ готов».

Сам вопрос в 1С ничего не записывает. Подготовленные документы попадают в очередь и ждут одобрения, как в кабинете. По умолчанию ИИ-бухгалтер сам решает, ответить или подготовить документ. Поле mode это ограничивает: ask означает только ответ, document означает подготовить документ.

Если компания не подключена к 1С, запрос вернёт 409. Пустой баланс платформы даёт 402 с кодом platform_balance_exhausted. Остальные отказы разобраны на странице Ошибки и ограничения.

​

Получить ответ потоком

Если не передавать "stream": false, ответ приходит потоком событий в формате Server-Sent Events. Так можно показывать текст по мере появления.

curl -N -X POST "$TUNGO_API/v1/companies/$CO/chat" \
  -H "x-api-key: $TUNGO_KEY" -H "Content-Type: application/json" \
  -d '{"message":"Какой НДС у последней реализации?"}'

У каждого события есть имя и тело в JSON с полем type. Для начала достаточно трёх видов. Событие text несёт очередной кусок ответа в поле delta. Событие error сообщает об ошибке, поток после него не рвётся. Событие done приходит последним: в нём итоговый ответ целиком в поле answer, цена в cost_tiyn и stop_reason. Остальные виды событий описаны в справочнике API.

Id чата и номер ответа приходят в заголовках X-Dialog-Id и X-Turn-No. Обрыв соединения ответ не останавливает: ИИ-бухгалтер доработает до конца. Чтобы дочитать события, откройте GET /v1/companies/{co}/chat/{id}/events с заголовком Last-Event-ID, и уже полученные события не повторятся.

​

Продолжить чат

Чтобы следующий вопрос учитывал предыдущие, пришлите dialog_id из прошлого ответа.

curl -X POST "$TUNGO_API/v1/companies/$CO/chat" \
  -H "x-api-key: $TUNGO_KEY" -H "Content-Type: application/json" \
  -d '{"message":"А за прошлый квартал?","dialog_id":"…","stream":false}'

В одном чате одновременно идёт один ответ. Второй вопрос, присланный раньше времени, получит 409 с кодом turn_in_progress. Если чат закрыт или его больше нет, придёт 409 с кодом dialog_closed или 410. В обоих случаях начните новый чат: отправьте вопрос без dialog_id.

​

Повторять запрос без двойного списания

Сеть может оборваться после того, как запрос ушёл, но до того, как пришёл ответ. Чтобы повтор не стал вторым платным вопросом, передавайте заголовок Idempotency-Key с любым своим уникальным значением, например UUID.

Повтор с тем же ключом повтора и тем же телом ничего не делает второй раз. Он возвращает прежний ответ с заголовком Idempotent-Replayed: true. Если первый запрос ещё выполняется, придёт 409 с кодом idempotency_in_progress: подождите и повторите. Тот же ключ повтора с другим телом даёт 422 с кодом idempotency_key_reused. Для нового действия нужно новое значение.

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

​

Что дальше

• Получать события (вебхуки): узнавать о готовых документах и окончании ответов без опроса.
• Ошибки и ограничения: как разбирать отказы и не упираться в частоту запросов.
• Баланс платформы и расход: сколько стоил запрос и где это видно.