> ## 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/kk/platform/api-keys.md) бетін қараңыз. Платформа балансындағы ақша: [Платформа балансы және шығын](https://docs.tungo.kz/kk/platform/balance.md) бетін қараңыз. Және 1С қосылған компания, өйткені ЖИ-бухгалтер соның деректері бойынша жауап береді. 1С-ті қалай қосу керегі [1С қосу](https://docs.tungo.kz/kk/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 қайтарады. Платформа балансы бос болса, `platform_balance_exhausted` кодымен 402 келеді. Қалған бас тартулар [Қателер мен шектеулер](https://docs.tungo.kz/kk/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":"Какой НДС у последней реализации?"}'
```

Әр оқиғаның атауы және `type` өрісі бар JSON денесі болады. Бастау үшін үш түрі жеткілікті. `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}'
```

Бір чатта бір мезгілде бір ғана жауап жүреді. Уақытынан бұрын жіберілген екінші сұрақ `turn_in_progress` кодымен 409 алады. Чат жабық болса немесе ол енді жоқ болса, `dialog_closed` кодымен 409 немесе 410 келеді. Екі жағдайда да жаңа чат бастаңыз: сұрақты `dialog_id` өрісінсіз жіберіңіз.

## Сұрауды ақша екі рет алынбайтындай қайталау

Желі сұрау кеткеннен кейін, бірақ жауап келгенге дейін үзіліп кетуі мүмкін. Қайталау екінші ақылы сұраққа айналмауы үшін `Idempotency-Key` тақырыбын кез келген өз бірегей мәніңізбен беріңіз, мысалы UUID.

Сол қайталау кілтімен және сол денемен жасалған қайталау ештеңені екінші рет орындамайды. Ол бұрынғы жауапты `Idempotent-Replayed: true` тақырыбымен қайтарады. Бірінші сұрау әлі орындалып жатса, `idempotency_in_progress` кодымен 409 келеді: күте тұрып, қайталаңыз. Сол қайталау кілті басқа денемен жіберілсе, `idempotency_key_reused` кодымен 422 келеді. Жаңа әрекетке жаңа мән керек.

Тек сәтті жауап есте сақталады, бас тартудан кейін қайталау жаңадан орындалады. Мән бір тәулік сақталады.

## Әрі қарай

* [Оқиғаларды алу (вебхуктар)](https://docs.tungo.kz/kk/platform/webhooks.md): дайын құжаттар мен жауаптардың аяқталғаны туралы сауалсыз біліп отыру.
* [Қателер мен шектеулер](https://docs.tungo.kz/kk/platform/errors-and-limits.md): бас тартуларды қалай талдау керек және сұраулар жиілігіне қалай тірелмеу керек.
* [Платформа балансы және шығын](https://docs.tungo.kz/kk/platform/balance.md): сұрау қанша тұрды және оны қайдан көруге болады.


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