# Быстрый старт

Пять запросов: от «есть ключ» до картинки, которую можно послать клиенту.
Подставьте свой адрес сервиса и свой ключ.

```bash
BASE=https://teril.example.ru
KEY=pk_ваш_ключ
AUTH="Authorization: Bearer $KEY"
JSON="Content-Type: application/json"
```

## 1. Связь и остаток

```bash
curl -s "$BASE/v1/health"
# {"ok":true,"version":1,"model":"deepseek-v4-pro"}

curl -s -H "$AUTH" "$BASE/v1/usage"
# {"ok":true,"usage":{"coins_left":940,"coins_included":1000,"period_end":"…"}}
```

`/v1/health` отвечает без ключа — его и ставьте в мониторинг.

## 2. Завести разговор

`external_id` — ваш id лида. По нему разговор и находится потом: наш `id`
хранить не обязательно.

```bash
curl -s -X POST -H "$AUTH" -H "$JSON" "$BASE/v1/conversations" -d '{
  "external_id": "lead-7781",
  "webhook_url": "https://ваш-сервис/hooks/teril"
}'
```

```json
{ "ok": true, "conversation": {
  "id": "3f2b…", "external_id": "lead-7781", "order_id": "lead-lead-7781",
  "turn": 0, "running_turn": null, "has_project": false,
  "expires_at": "2026-10-18T…" } }
```

Тот же `external_id` второй раз вернёт **200** и тот же разговор — это
не ошибка, а вернувшийся лид. Заводить разговор при каждом сообщении
клиента безопасно.

## 3. Отправить просьбу клиента

```bash
CONV=3f2b…
curl -s -X POST -H "$AUTH" -H "$JSON" \
  -H "Idempotency-Key: msg-991" \
  "$BASE/v1/conversations/$CONV/turns" -d '{
    "text": "Кухня вдоль одной стены 3 метра. Мойка, посудомойка 60, варочная, духовка. Сверху навесные шкафы."
  }'
```

```json
{ "ok": true, "turn": { "id": "b41c…", "state": "queued" } }
```

**202, а не 200.** Ход идёт минуты. `Idempotency-Key` — id сообщения у вас:
повтор запроса с тем же ключом вернёт тот же ход и не потратит денег второй раз.

## 4. Дождаться исхода

Правильный путь — вебхук (см. [webhooks.md](webhooks.md)). Запасной — опрос:

```bash
TURN=b41c…
curl -s -H "$AUTH" "$BASE/v1/turns/$TURN"
```

```json
{ "ok": true, "turn": { "id": "b41c…", "state": "done", "status": "built",
  "result": {
    "status": "built",
    "note": "Собрал кухню 3 метра: тумба под мойку 800, посудомойка 600, ящики, духовка в пенале. Сверху четыре навесных шкафа.",
    "applied": 9, "turn": 1, "order_id": "lead-lead-7781",
    "usage": { "model": "…", "attempts": 1, "cost_usd": 0.0231, "ms": 41200, "coins": 1 }
  } } }
```

Клиенту показывайте `note`. Всё остальное — вам.

Если `status` — `question`, ассистент чего-то не знает про комнату и спросил:
в `note` лежит вопрос, его и перешлите клиенту. Полная таблица статусов —
в [turns.md](turns.md).

## 5. Показать картинку

```bash
curl -s -H "$AUTH" "$BASE/v1/conversations/$CONV/render?format=html&link=1"
# {"ok":true,"url":"https://teril.example.ru/r/eyJ…","expires_at":"…"}
```

Эту ссылку можно слать клиенту прямо в чат: она живёт сутки и ключа не требует.
Страница самодостаточна — чертёж крутится, наружу не ходит ничего.

Просить её можно после ЛЮБОГО хода, а не только после `built`: вид принадлежит
разговору, и `question` его не отменяет — картинка после вопроса та же, что
была. Условие «если статус built» в вашем коде означает, что клиент, ответивший
на вопрос ассистента, остался без картинки вовсе.

Нужна картинка внутрь своей вёрстки — возьмите `format=svg` без `link`:

```bash
curl -s -H "$AUTH" "$BASE/v1/conversations/$CONV/render?format=svg" > kitchen.svg

# Сплошными панелями: корпус и фасад красятся порознь (`clear` — как было).
curl -s -H "$AUTH" "$BASE/v1/conversations/$CONV/render?carcass=oak&facade=white" > kitchen.svg
```

## 6. Отдать в производство

```bash
curl -s -X POST -H "$AUTH" -H "$JSON" \
  "$BASE/v1/conversations/$CONV/handoff" -d '{"seat": "Цех на Ленина"}'
# {"ok":true,"handoff":{"seat_id":5,"seat_title":"Цех на Ленина","order_id":"lead-lead-7781","turn":3}}
```

Заказ появится карточкой в кабинете рабочего места. Что именно это значит
и чего НЕ значит — [handoff.md](handoff.md).

## Дальше

- весь набор ручек — [reference.md](reference.md);
- готовый клиент на Node — [examples/client.mjs](examples/client.mjs);
- проверка подписи вебхука — [examples/verify.mjs](examples/verify.mjs).