# Dowo ochiq API va webhooklar

Dowo ma'lumotini o'z tizimingizdan (1C, sayt, CRM) o'qing, lid va qayta qo'ng'iroq yozing, hodisalarni webhook orqali oling.
Kalit admin paneldagi kompaniya sahifasi, "API va webhooklar" kartasida yaratiladi.

## Autentifikatsiya
Har so'rovda sarlavha: `Authorization: Bearer dwk_xxxxxxxx_...`. Kalit faqat bir kompaniya ma'lumotiga ruxsat beradi.
Ruxsat turlari: **read** (faqat o'qish) va **write** (o'qish va yozish). Kalit yaratilganda bir marta ko'rsatiladi, yo'qotsangiz yangisini yarating. Bekor qilingan kalit darrov ishlamaydi.

```
curl https://<manzil>/api/v1/me -H "Authorization: Bearer dwk_xxxxxxxx_..."
```

## Umumiy qoidalar
- Manzil: `/api/v1/...`, javoblar JSON, vaqtlar ISO 8601 (Toshkent, +05:00).
- Tezlik: kalitga daqiqasiga 120 so'rov. Oshsa `429` va `Retry-After`.
- Xato: `{"error": {"code": "invalid_phone", "message": "..."}}`. Kodlar: `unauthorized`, `invalid_key`, `forbidden`, `bad_request`, `invalid_phone`, `not_found`, `rate_limited`.
- Sahifalash: `?limit=50` (1 dan 100 gacha). Javobdagi `next` qiymatini keyingi so'rovga `?before=<next>` deb bering. `next` bo'sh bo'lsa ro'yxat tugagan.
- Takrorlanmaslik: POST so'rovga `Idempotency-Key: <noyob qiymat>` sarlavhasini qo'shing. Tarmoq uzilib qayta yuborsangiz, 24 soat ichida bir xil javob qaytadi va ikkinchi yozuv ochilmaydi (`Idempotent-Replay: true`).

## Manbalar
| Usul | Manzil | Ruxsat | Tavsif |
|---|---|---|---|
| GET | `/api/v1/me` | read | Kompaniya, tarif, ishlatilgan daqiqa |
| GET | `/api/v1/calls` | read | Qo'ng'iroqlar. Filtr: `since` (unix yoki ISO), `direction` (in/out), `outcome` (ai, operator, no_operator, abandoned, ...) |
| GET | `/api/v1/calls/{id}` | read | Bitta qo'ng'iroq, suhbat matni bilan |
| GET | `/api/v1/leads` | read | Lidlar (`since`) |
| POST | `/api/v1/leads` | write | Lid yozish: `{"name": "Ali", "phone": "+998901234567", "note": "..."}` |
| GET | `/api/v1/callbacks?status=open` | read | Qayta qo'ng'iroq ro'yxati (`open` yoki `done`) |
| POST | `/api/v1/callbacks` | write | Qayta qo'ng'iroq yozish: `{"phone": "...", "name": "...", "note": "..."}` |
| POST | `/api/v1/callbacks/{id}/done` | write | Bajarildi deb belgilash: `{"result": "Gaplashdik"}` |
| GET | `/api/v1/customers?q=` | read | Mijozlar (ism yoki telefon bo'yicha qidirish) |
| GET | `/api/v1/appointments` | read | Band qilishlar |
| GET | `/api/v1/agent` | read | AI agent sozlamalari: ismi, lavozimi, ohangi, modeli, gapirish tezligi, javob uzunligi |
| PUT | `/api/v1/agent` | write | Agentni o'zgartirish: `{"name": "Madina", "tone": "formal", "speech_rate": 0.92, "max_sentences": 3}` |
| GET | `/api/v1/knowledge/documents` | read | Bilimlar bazasi hujjatlari (nomi, turi, kategoriya, til, faol/nofaol) |
| GET | `/api/v1/knowledge/documents/{id}` | read | Hujjat matni bilan |
| POST | `/api/v1/knowledge/upload` | write | Hujjat yuklash: multipart `file` (PDF, DOCX, XLSX, CSV, TXT, JSON, rasm; 10 MB) yoki JSON `{"name", "text", "category", "language"}` |
| POST | `/api/v1/knowledge/documents/{id}` | write | Tahrirlash yoki `{"active": false}` bilan AI dan olib qo'yish |
| DELETE | `/api/v1/knowledge/documents/{id}` | write | Hujjatni o'chirish |
| GET | `/api/v1/analytics?from=2026-11-01&to=2026-11-30` | read | Statistika: jami va kunlar bo'yicha (qo'ng'iroqlar, AI hal qilgan, operatorga o'tgan, AI muvaffaqiyati %, o'rtacha baho) |
| POST | `/api/v1/feedback` | write | Suhbatga baho: `{"call_id": "...", "rating": 5, "comment": "..."}` |
| POST | `/api/v1/calls/{id}/transfer` | write | Hozir AI bilan davom etayotgan telefon qo'ng'irog'ini operatorga o'tkazish |

To'liq ta'rif (OpenAPI 3.1, Swagger va Postman uchun): `/api/v1/openapi.json`, o'qish uchun sahifa: `/api/docs`.
Qo'ng'iroq obyektida `extracted` maydoni bor: kompaniya panelda sozlagan tuzilgan ma'lumot (masalan `{"product": "Burchak divan", "budget": 8000000, "delivery_city": null}`).
Maydonlar sxemasi: panel, Kompaniya sahifasi, "Qo'ng'iroqdan keyin ma'lumot yig'ish" (ko'pi bilan 12 ta; tur: matn, son, ha/yo'q, tanlov). Aytilmagan qiymat `null`. Xuddi shu `extracted` `call.completed` webhookida ham keladi.
`/api/v1/calls/{id}` javobida `messages` (mijoz va AI xabarlari, qo'ng'iroq boshidan soniya va AI javob tezligi) va `kb_sources` (AI tayangan baza bo'limlari) bor.

Lid yaratilganda u ulangan CRM (Bitrix24, amoCRM, Odoo) ga ham tushadi va `lead.created` webhooki yuboriladi.

## Webhooklar
Webhook manzilingizga hodisa yuboriladi (`POST`, JSON). Manzil `https://` bilan boshlanishi va internetdan ochiq bo'lishi kerak.
Hodisalar: `call.started` (qo'ng'iroq boshlandi), `call.answered` (ko'tarildi: `by` = `ai` yoki `operator`), `call.transferred` (operatorga yo'naltirildi),
`call.ended` (tugadi, darhol), `call.failed` (AI ulanmadi, mijoz operatorga o'tdi), `call.completed` (tugadi, xulosa bilan, tahlildan keyin), `lead.created`, `callback.created`, `appointment.created`.
Har qo'ng'iroqda har hodisa bir marta yuboriladi; tanadagi `id` (masalan `call.ended:<qo'ng'iroq>`) bo'yicha takrorni tashlab yuboring.

```json
{"id": "evt_ab12...", "type": "lead.created", "created": "2026-11-11T16:30:00+05:00", "tenant": "kompaniya",
 "data": {"id": 17, "name": "Ali", "phone": "+998901234567", "note": "Divan narxi", "source": "ai", "call_id": "d3da6976fe5142c9"}}
```

Sarlavhalar: `X-Dowo-Event` (hodisa turi), `X-Dowo-Delivery` (yetkazish id), `X-Dowo-Signature: t=<unix>,v1=<imzo>`.

**Imzoni albatta tekshiring.** Imzo = `HMAC-SHA256(webhook maxfiy kaliti, "<t>.<xom tana>")` (hex). Vaqt (`t`) 5 daqiqadan eski bo'lsa rad eting (takrorlashdan himoya).

```python
import hmac, hashlib, time
def verify(secret: str, header: str, body: bytes) -> bool:
    p = dict(x.split("=", 1) for x in header.split(","))
    if abs(time.time() - int(p["t"])) > 300: return False
    expected = hmac.new(secret.encode(), p["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, p["v1"])
```

```js
const crypto = require("crypto");
function verify(secret, header, rawBody) {
  const p = Object.fromEntries(header.split(",").map(x => x.split(/=(.*)/s).slice(0, 2)));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) return false;
  const exp = crypto.createHmac("sha256", secret).update(p.t + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(exp), Buffer.from(p.v1));
}
```

**Javob va qayta urinish:** `2xx` javob qaytaring (8 soniya ichida). Aks holda Dowo 1 daqiqa, 5 daqiqa, 30 daqiqa, 2 soat, 6 soatdan keyin qayta uradi (jami 6 urinish). Ketma-ket 20 ta xatodan keyin webhook o'chiriladi (panelda ko'rinadi, qo'lda yoqiladi). Bir hodisa takror kelishi mumkin: `id` bo'yicha takrorlanishni o'zingiz tekshiring.
Maxfiy kalit yaratilganda bir marta ko'rsatiladi; yo'qotsangiz "Kalitni almashtirish" tugmasidan foydalaning (eskisi darrov ishlamaydi).
