> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tungo.kz/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

Понадобятся три вещи. Ключ с правом `chat.use`: см. [Создать ключ API](https://docs.tungo.kz/platform/api-keys.md). Деньги на балансе платформы: см. [Баланс платформы и расход](https://docs.tungo.kz/platform/balance.md). И компания с подключённой 1С, потому что ИИ-бухгалтер отвечает по её данным. Как подключить 1С, описано в разделе [Подключение 1С](https://docs.tungo.kz/1c/overview.md).

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

```sh theme={null}
export TUNGO_API=https://api.tungo.kz
export TUNGO_KEY=tg_…
```

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

```sh theme={null}
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 подставляются в адреса остальных запросов.

```sh theme={null}
export WS=ws_…
export CO=co_…
```

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

```sh theme={null}
curl "$TUNGO_API/v1/companies/$CO/onec/status" -H "x-api-key: $TUNGO_KEY"
```

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

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

```sh theme={null}
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 тиын. Это оценка одного вызова модели. Чтобы ответить на вопрос, ИИ-бухгалтер обычно вызывает модель несколько раз, поэтому настоящая цена известна только по факту.

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

```sh theme={null}
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`. Остальные отказы разобраны на странице [Ошибки и ограничения](https://docs.tungo.kz/platform/errors-and-limits.md).

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

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

```sh theme={null}
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` из прошлого ответа.

```sh theme={null}
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`. Для нового действия нужно новое значение.

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

## Что дальше

* [Получать события (вебхуки)](https://docs.tungo.kz/platform/webhooks.md): узнавать о готовых документах и окончании ответов без опроса.
* [Ошибки и ограничения](https://docs.tungo.kz/platform/errors-and-limits.md): как разбирать отказы и не упираться в частоту запросов.
* [Баланс платформы и расход](https://docs.tungo.kz/platform/balance.md): сколько стоил запрос и где это видно.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.