Davomat — Integratsiya API (v1)

Yuz tanish davomat tizimidan ma'lumotni o'z dasturingizga (ERP, 1C, buxgalteriya, HR) olib berish uchun REST interfeys. Faqat o'qiydi. Barqaror — versiya manzilda (/api/v1), keyingi yangilanishlarda buzilmaydi.

Uch qadamda boshlash:
1. Admin panel → 🔌 Integratsiya → kalit yarating (bir marta ko'rsatiladi, nusxalab oling).
2. GET /api/v1/ping bilan kalitni tekshiring.
3. Har kuni (yoki har 15 daqiqada) /api/v1/attendance/daily yoki /api/v1/attendance/events ni so'rang.

Asos

Bazaviy manzil	`https://davomat.softizim.uz/api/v1`
Format	JSON (UTF-8). Faqat `GET`.
Vaqt	ISO 8601, O'zbekiston vaqti: `2026-07-19T09:03:00+05:00`
Sana	`YYYY-MM-DD`
Xodim identifikatori	`erp_id` — sizning dasturingizdagi tabel raqami. Firma ichida takrorlanmaydi.

Avtorizatsiya

Har so'rovda kalit yuboriladi (ikkalasidan biri):

Authorization: Bearer ftk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-Key: ftk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Kalit faqat yaratilganda bir marta ko'rsatiladi — bazada uning qaytarib bo'lmaydigan xeshi saqlanadi. Yo'qotsangiz yangisini yaratib, eskisini bekor qiling. Kalit terminal tokenidan alohida va hech narsa yoza olmaydi.

Xatolar

{ "error": { "code": "unauthorized", "message": "API kalit noto'g'ri yoki bekor qilingan" } }

Kod	HTTP	Ma'nosi
`unauthorized`	401	Kalit yo'q, noto'g'ri yoki bekor qilingan
`tenant_inactive`	403	Firma obunasi to'xtatilgan
`bad_request`	400	Parametr xato (sana formati, davr juda uzun va h.k.)

Cheklovlar

limit — defolt 500, maksimum 1000.
Bir so'rovdagi davr (from…to) ko'pi bilan 366 kun.
from/to berilmasa: to = bugun, from = 30 kun oldin.

1. Kalitni tekshirish

GET /api/v1/ping

curl -H "Authorization: Bearer ftk_…" \
     https://davomat.softizim.uz/api/v1/ping

{
  "ok": true,
  "api_version": "v1",
  "tenant": "Alfa MChJ",
  "key_name": "1C buxgalteriya",
  "server_time": "2026-07-19T04:03:11.482Z",
  "timezone": "+05:00"
}

2. Xodimlar

GET /api/v1/employees?updated_since=&include_inactive=&limit=&offset=

Parametr	Tavsif
`updated_since`	ISO vaqt — faqat shundan keyin o'zgarganlar (inkremental sinxronizatsiya). Oldingi javobdagi `server_time` ni saqlab, keyingi safar shuni yuboring.
`include_inactive`	`1` — ishdan bo'shatilganlar ham kiradi. Defolt: faqat faollar.
`limit`, `offset`	Sahifalash. `has_more` rost bo'lsa `next_offset` bilan davom eting.

{
  "employees": [
    { "erp_id": "1001", "full_name": "Ahmedov Alisher", "is_active": true,
      "department": "Ishlab chiqarish", "position": "Operator",
      "phone": "+998901234567", "has_photo": true,
      "updated_at": "2026-07-14T06:12:00Z" }
  ],
  "count": 1, "has_more": false, "next_offset": 1,
  "server_time": "2026-07-19T04:03:11Z"
}

3. Bo'limlar (smena vaqtlari)

GET /api/v1/departments

Kechikish shu vaqtlarga nisbatan hisoblanadi.

{
  "departments": [
    { "name": "Ishlab chiqarish", "shift_start": "08:00",
      "shift_start_minutes": 480, "grace_minutes": 5 },
    { "name": "Ofis", "shift_start": "09:00",
      "shift_start_minutes": 540, "grace_minutes": 5 }
  ]
}

4. Kunlik tabel — eng ko'p ishlatiladigan

GET /api/v1/attendance/daily?from=2026-07-01&to=2026-07-19&erp_id=&limit=&offset=

Har bir xodim × kun uchun bitta qator. erp_id berilsa — faqat o'sha xodim.

{
  "days": [
    { "date": "2026-07-19", "erp_id": "1001", "full_name": "Ahmedov Alisher",
      "department": "Ishlab chiqarish",
      "first_in":  "2026-07-19T08:03:00+05:00",
      "last_out":  "2026-07-19T18:12:00+05:00",
      "worked_minutes": 549, "worked_hours": 9.15,
      "sessions": 2, "late_minutes": 0, "status": "complete" }
  ],
  "count": 1, "total": 1, "has_more": false, "next_offset": 1,
  "from": "2026-07-01", "to": "2026-07-19"
}

Maydon	Ma'nosi
`first_in` / `last_out`	Kunning birinchi kirishi va oxirgi chiqishi (to'liq ISO vaqt).
`worked_minutes` `worked_hours`	NET ishlangan vaqt: har `in`→`out` juftligi qo'shiladi, tushlik va oraliq chiqishlar hisobga kirmaydi. (Ya'ni `last_out − first_in` emas.)
`sessions`	Kun ichidagi kirish-chiqish juftliklari soni (1 = tushlikka chiqmagan).
`late_minutes`	Kechikish daqiqasi — xodim bo'limining smena boshlanishi + imtiyoz (grace) ga nisbatan. Kechikmasa 0.
`status`	`complete` — to'liq kun. `no_out` — kirdi, chiqishni belgilamadi (`worked_minutes` to'liq emas). `no_in` — kirish qaydi yo'q, faqat chiqish bor. `unbalanced` — tartibsiz/ortiqcha qaydlar.

status ≠ complete bo'lgan kunlarni ish haqiga to'g'ridan-to'g'ri kiritmang — admin panelning 🩹 Tuzatish bo'limida to'g'irlanadi, keyin qayta so'rang.

5. Xom qaydlar (inkremental oqim)

GET /api/v1/attendance/events?since_seq=0&limit=1000

Har bir kirish/chiqish alohida qator — o'z hisobingizni o'zingiz qurmoqchi bo'lsangiz.

Kursor: javobdagi next_since_seq ni saqlang va keyingi so'rovda since_seq qilib yuboring — takrorsiz va yo'qotishsiz faqat yangilari keladi. has_more rost bo'lsa darhol yana so'rang.

{
  "events": [
    { "seq": 148213, "id": "b1f0…", "erp_id": "1001", "type": "in",
      "timestamp": "2026-07-19T08:03:00+05:00", "confidence": 0.94,
      "manual": false, "note": null, "terminal": "Sex kirish" }
  ],
  "count": 1, "has_more": false, "next_since_seq": 148213,
  "server_time": "2026-07-19T04:03:11Z"
}

Maydon	Ma'nosi
`seq`	Kursor raqami. O'sib boradi, takrorlanmaydi.
`type`	`in` (keldi) yoki `out` (ketdi).
`confidence`	Yuz tanish ishonchliligi 0…1.
`manual`	`true` — terminal emas, admin qo'lda kiritgan (`note` da sababi).
`terminal`	Qaysi qurilmada qayd etilgan (`MANUAL` — qo'lda).

since_seq bilan sana filtri shart emas — butun tarix bo'ylab oqim beradi. Birinchi marta since_seq=0 dan boshlab has_more=false bo'lguncha aylantiring.

6. Davr jamlanmasi — ish haqi uchun

GET /api/v1/attendance/summary?from=2026-07-01&to=2026-07-31

Oy bo'yicha har xodimga bitta qator — bitta so'rovda.

{
  "employees": [
    { "erp_id": "1001", "full_name": "Ahmedov Alisher",
      "department": "Ishlab chiqarish",
      "days_present": 22, "days_late": 3, "days_incomplete": 1,
      "worked_minutes": 10560, "worked_hours": 176.0,
      "avg_hours_per_day": 8.0, "late_minutes": 47 }
  ],
  "count": 1, "from": "2026-07-01", "to": "2026-07-31"
}

days_incomplete — status ≠ complete bo'lgan kunlar soni. Katta bo'lsa oldin tuzating.

Tavsiya etilgan sxema

Kuniga bir marta (kechqurun) — /attendance/daily?from=…&to=… bilan tabel oling.
Real vaqtga yaqin kerak bo'lsa — har 5–15 daqiqada /attendance/events?since_seq=….
Oy yopilganda — /attendance/summary bilan solishtiring.
Xodim ro'yxatini /employees?updated_since=… bilan sinxron ushlang.

Ma'lumot keyin ham o'zgarishi mumkin (admin kunni tuzatsa). Shuning uchun oy yopilishida oxirgi 7–30 kunni qayta so'rab, o'zingizdagini yangilang.

Savol bo'lsa — admin panel egasiga murojaat qiling. Foydalanuvchi qo'llanmasi: /qollanma.html