chat.use: см. Создать ключ API. Деньги на балансе платформы: см. Баланс платформы и расход. И компания с подключённой 1С, потому что ИИ-бухгалтер отвечает по её данным. Как подключить 1С, описано в разделе Подключение 1С.
Все примеры ниже используют две переменные окружения. Ключ передаётся в заголовке x-api-key. Вместо него можно прислать Authorization: Bearer tg_….
Проверить ключ и узнать id
workspace.id и начинается с ws_. Поле blocked_reason показывает, почему запросы к ИИ-бухгалтеру сейчас не пройдут, например из-за пустого баланса. Если в нём null, всё в порядке.
Второй запрос возвращает компании ключа. Id компании лежит в data[].id и начинается с co_. Эти id подставляются в адреса остальных запросов.
connected и итог последней проверки подключения.
Прикинуть цену вопроса
Этот запрос бесплатный: модель не отвечает, с баланса ничего не списывается.input_tokens, max_output_tokens, input_cost_tiyn и max_cost_tiyn. Суммы указаны в тиынах, 1 ₸ = 100 тиын. Это оценка одного вызова модели. Чтобы ответить на вопрос, ИИ-бухгалтер обычно вызывает модель несколько раз, поэтому настоящая цена известна только по факту.
Задать вопрос
"stream": false ответ приходит одним JSON, когда ИИ-бухгалтер закончит. Это может занять время, поэтому поставьте в своём клиенте запас по времени ожидания. Главные поля ответа:
answer— текст ответа в Markdown.dialog_id— id чата, он нужен для следующего вопроса.proposals— документы, которые ИИ-бухгалтер подготовил для 1С по ходу ответа.usage— токены и цена ответа,cost_tiynв тиынах.stop_reason— чем закончился ответ,end_turnзначит «ответ готов».
mode это ограничивает: ask означает только ответ, document означает подготовить документ.
Если компания не подключена к 1С, запрос вернёт 409. Пустой баланс платформы даёт 402 с кодом platform_balance_exhausted. Остальные отказы разобраны на странице Ошибки и ограничения.
Получить ответ потоком
Если не передавать"stream": false, ответ приходит потоком событий в формате Server-Sent Events. Так можно показывать текст по мере появления.
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 из прошлого ответа.
turn_in_progress. Если чат закрыт или его больше нет, придёт 409 с кодом dialog_closed или 410. В обоих случаях начните новый чат: отправьте вопрос без dialog_id.
Повторять запрос без двойного списания
Сеть может оборваться после того, как запрос ушёл, но до того, как пришёл ответ. Чтобы повтор не стал вторым платным вопросом, передавайте заголовокIdempotency-Key с любым своим уникальным значением, например UUID.
Повтор с тем же ключом повтора и тем же телом ничего не делает второй раз. Он возвращает прежний ответ с заголовком Idempotent-Replayed: true. Если первый запрос ещё выполняется, придёт 409 с кодом idempotency_in_progress: подождите и повторите. Тот же ключ повтора с другим телом даёт 422 с кодом idempotency_key_reused. Для нового действия нужно новое значение.
Запоминается только удачный ответ, после отказа повтор выполнится заново. Значение помнится сутки.
Что дальше
- Получать события (вебхуки): узнавать о готовых документах и окончании ответов без опроса.
- Ошибки и ограничения: как разбирать отказы и не упираться в частоту запросов.
- Баланс платформы и расход: сколько стоил запрос и где это видно.