Qoʻllanma

Tasnivo API

Mahsulot nomini tekshirish, katalogni yuklash va hisobotni olish uchun ochiq API.

Shu sahifada

Uzun qatorlarni koʻrish uchun kodni yon tomonga suring yoki «Qatorlarni oʻrash»ni yoqing.

Tez boshlash

Misollarda ikki oʻzgaruvchi ishlatiladi: $BASE — ilova manzili, $KEY — API kaliti. Kalitni administrator Sozlamalar → Integratsiyalar boʻlimida yaratadi; u faqat bir marta koʻrsatiladi.

shell

export BASE="https://tasnivo.uz"
export KEY="mxk_..."   # Sozlamalar → Integratsiyalar → API kalitlari

Kirish

Har bir soʻrovda kalit Authorization sarlavhasida yuboriladi. Kalitsiz, oʻchirib qoʻyilgan kalit yoki yopilgan hisob bilan soʻrov 401 oladi.

HTTP

Authorization: Bearer $KEY

Chegaralar

Chegara	Qiymat
Soʻrovlar, bitta kalitga	daqiqasiga 60 ta
Bitta /check soʻrovidagi mahsulotlar	20 tagacha
Oyiga tekshiruvlar, «Koʻrik»	500 tagacha
Oyiga tekshiruvlar, «Korxona»	1 000 tagacha
Oyiga tekshiruvlar, «Buxgalter»	10 000 tagacha
Oyiga tekshiruvlar, «Byuro»	50 000 tagacha
Oyiga yuklanadigan qatorlar, «Koʻrik»	5 000 tagacha
Oyiga yuklanadigan qatorlar, «Korxona»	20 000 tagacha
Oyiga yuklanadigan qatorlar, «Buxgalter»	50 000 tagacha
Oyiga yuklanadigan qatorlar, «Byuro»	200 000 tagacha
Yuklanadigan fayl hajmi	20 MB gacha
Kataloglar roʻyxatining bir sahifasi	100 tagacha
Hisobotning bir sahifasi	1 000 tagacha

Kalit tanilgandan keyingi har bir javobda (xato javoblarda ham) ikki sarlavha bor: X-RateLimit-Limit — daqiqadagi chegara, X-RateLimit-Remaining — shu daqiqada qolgan soʻrovlar. Chegaradan oshsa 429 qaytadi, Retry-After esa necha soniyadan keyin urinish mumkinligini aytadi.

HTTP

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

Tekshiruvlar /check orqali yuborilgan mahsulotlar soni boʻyicha hisoblanadi. API orqali yuklangan qatorlar ilovadagi yuklashlar bilan bir xil oylik chegaraga kiradi.

Sahifalash

Roʻyxatlar sahifalab qaytadi. limit — sahifa hajmi (kattarogʻi maksimumgacha qisqartiriladi). Javobdagi nextCursor qiymatini keyingi soʻrovda cursor parametri sifatida yuboring; nextCursor null boʻlsa, bu oxirgi sahifa.

Takroriy soʻrovlar

POST /api/v1/check va POST /api/v1/catalogs Idempotency-Key sarlavhasini qabul qiladi. Tarmoq uzilganda soʻrovni xavfsiz takrorlash uchun har bir amalga yangi qiymat (masalan, UUID) bering.

Qiymat 1 dan 255 tagacha koʻrinadigan ASCII belgidan iborat boʻladi; boshqacha boʻlsa 400 invalid_request qaytadi.
Xuddi shu qiymat bilan 24 soat ichida qayta yuborilgan soʻrov qayta bajarilmaydi: birinchi muvaffaqiyatli javob qaytadi va Idempotent-Replayed: true sarlavhasi qoʻshiladi.
Muvaffaqiyatsiz soʻrovlar saqlanmaydi: ularni shu qiymat bilan qayta yuborish mumkin.
Shu qiymat boshqa mazmundagi soʻrov bilan kelsa, 422 idempotency_key_reused qaytadi.
Birinchi soʻrov hali bajarilayotgan boʻlsa, 409 idempotency_in_progress qaytadi.
Qiymatlar har bir API kaliti uchun alohida: ikki kalit bir xil qiymatni ishlatsa, toʻqnashmaydi.

Mahsulotni tekshirish

POST/api/v1/check

Bitta yoki bir nechta mahsulotni tekshiradi: topilgan muammolar, taklif etilgan kod va muqobillar qaytadi. Hech narsa saqlanmaydi.

API kaliti bilanJavob: 200Idempotency-Key qabul qiladi

Soʻrov

curl -X POST "$BASE/api/v1/check" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"items": [{"name": "Sut 3.2% 1 L", "barcode": "4780000000000", "unit": "dona"}]}'

Javob (namuna)

{
  "results": [
    {
      "name": "Sut 3.2% 1 L",
      "markingRequired": false,
      "findings": [
        {
          "type": "MISSING",
          "severity": "high",
          "suggestedMxik": "00000000000000000",
          "confidence": 0.91,
          "reason": "…",
          "alternatives": [
            {
              "code": "00000000000000000",
              "name": "…",
              "confidence": 0.84
            }
          ]
        }
      ]
    }
  ]
}

confidence — 0 dan 1 gacha moslik bahosi: u nomzodlarni tartiblaydi, kod toʻgʻri boʻlish ehtimolligi emas. Taklif faqat inson uni ilovada qabul qilganda kuchga kiradi.

Kataloglar roʻyxati

GET/api/v1/catalogs

Tashkilotingiz kataloglari, eng yangisi birinchi. clientId bilan bitta mijozning kataloglari.

API kaliti bilanJavob: 200Sahifalab beradi

Parametrlar

Nomi	Joyi
limit	query	ixtiyoriy
cursor	query	ixtiyoriy
clientId	query	ixtiyoriy

Mumkin boʻlgan xatolar

401unauthorized
429rate_limited
500server_error
400invalid_request
404not_found

Soʻrov

curl "$BASE/api/v1/catalogs?limit=50" \
  -H "Authorization: Bearer $KEY"

# next page
curl "$BASE/api/v1/catalogs?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $KEY"

Javob (namuna)

{
  "catalogs": [
    {
      "id": "cm1a2b3c4d5e6f7g8h9i0j",
      "filename": "katalog.xlsx",
      "clientId": "cm0z9y8x7w6v5u4t3s2r1q",
      "createdAt": "2026-10-01T09:30:00.000Z",
      "status": "ready",
      "rows": 1200,
      "progress": {
        "done": 1200,
        "total": 1200
      }
    }
  ],
  "nextCursor": "cm1a2b3c4d5e6f7g8h9i0j"
}

Katalog yuklash

POST/api/v1/catalogs

Excel yoki CSV faylni yuklaydi; audit fonda ishlaydi. Javobda katalog identifikatori qaytadi, natijani hisobotdan oling.

API kaliti bilanJavob: 202Idempotency-Key qabul qiladi

Parametrlar

Nomi	Joyi
file	file	majburiy
clientId	form	ixtiyoriy

Mumkin boʻlgan xatolar

401unauthorized
429rate_limited
500server_error
400invalid_request
409idempotency_in_progress
422idempotency_key_reused
404not_found
402plan_expired
402plan_limit
413too_large
422unreadable_file

Soʻrov

curl -X POST "$BASE/api/v1/catalogs" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@katalog.xlsx" \
  -F "clientId=cm0z9y8x7w6v5u4t3s2r1q"

Javob (namuna)

{
  "id": "cm1a2b3c4d5e6f7g8h9i0j",
  "status": "analyzing",
  "rows": 1200,
  "clientId": "cm0z9y8x7w6v5u4t3s2r1q"
}

Katalog hisoboti

GET/api/v1/catalogs/{id}/report

Audit holati, muammo turlari boʻyicha xulosa va muammolar roʻyxati. status ready boʻlguncha summary null, findings boʻsh.

API kaliti bilanJavob: 200Sahifalab beradi

Parametrlar

Nomi	Joyi
id	path	majburiy
limit	query	ixtiyoriy
cursor	query	ixtiyoriy

Mumkin boʻlgan xatolar

401unauthorized
429rate_limited
500server_error
400invalid_request
404not_found

Soʻrov

curl "$BASE/api/v1/catalogs/cm1a2b3c4d5e6f7g8h9i0j/report?limit=200" \
  -H "Authorization: Bearer $KEY"

Javob (namuna)

{
  "id": "cm1a2b3c4d5e6f7g8h9i0j",
  "filename": "katalog.xlsx",
  "clientId": "cm0z9y8x7w6v5u4t3s2r1q",
  "createdAt": "2026-10-01T09:30:00.000Z",
  "status": "ready",
  "rows": 1200,
  "progress": {
    "done": 1200,
    "total": 1200
  },
  "error": null,
  "summary": {
    "MISSING": 12,
    "MISMATCH": 4
  },
  "findings": [
    {
      "id": "cm9f8e7d6c5b4a3z2y1x0w",
      "row": 7,
      "name": "Sut 3.2% 1 L",
      "barcode": "4780000000000",
      "unit": "dona",
      "currentMxik": null,
      "type": "MISSING",
      "severity": "high",
      "suggestedMxik": "00000000000000000",
      "confidence": 0.91,
      "reason": "…",
      "decision": "pending",
      "decisionSource": null,
      "chosenMxik": null
    }
  ],
  "nextCursor": null
}

Javoblardagi qiymatlar namuna: identifikatorlar, kodlar va sonlar sizning maʼlumotlaringizda boshqacha boʻladi.

Xatolar

Xato javobi har doim bir xil shaklda: kod va inglizcha xabar. Dasturda kodga tayaning, xabar matni oʻzgarishi mumkin.

JSON

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests: at most 60 per minute for this key. Try again in 12 s."
  }
}

Kod	HTTP	Maʼnosi
invalid_request	400	Soʻrov notoʻgʻri: maydon, parametr, `cursor` yoki `Idempotency-Key` xato.
unauthorized	401	Kalit yoʻq, notoʻgʻri yoki oʻchirib qoʻyilgan, yoxud hisob yopilgan.
plan_expired	402	Sinov muddati tugagan: tarifni faollashtiring.
plan_limit	402	Tarifning oylik chegarasi (tekshiruvlar yoki qatorlar) tugagan.
not_found	404	Katalog yoki mijoz topilmadi (boshqa tashkilotniki ham topilmaydi) yoki mijoz arxivda: unga yuklab boʻlmaydi.
idempotency_in_progress	409	Shu `Idempotency-Key` bilan birinchi soʻrov hali bajarilmoqda.
too_large	413	Fayl ruxsat etilgan hajmdan katta.
unreadable_file	422	Faylni oʻqib boʻlmadi: unda qator yoki tovar nomi ustuni yoʻq.
idempotency_key_reused	422	Bu `Idempotency-Key` boshqa soʻrov uchun ishlatilgan.
rate_limited	429	Daqiqalik chegara tugadi: `Retry-After` soniyadan keyin qayta urinib koʻring.
server_error	500	Kutilmagan xato: birozdan soʻng qayta urinib koʻring.

OpenAPI

Mashina oʻqiydigan tavsif (OpenAPI 3.0): /api/v1/openapi.json