Developer API · Beta

Panel qiladigan hamma ishni oʻsha qoidalar bilan oʻz dasturingizdan bajaring.

Q: Soʻrovni ikki marta yuborsam, takroriy yozuv boʻladimi?

Yoʻq. Har bir yozuv `Idempotency-Key` talab qiladi; kalit yozuvni yozgan tranzaksiya ichida saqlanadi. Ayni kalit ikkinchi marta kelsa ish qayta bajarilmaydi: yo `409 idempotency_replayed` olasiz va yozuvni `GET` bilan oʻqiysiz, yo `200` bilan birinchi javob gavdasi va `replayed: true` bayrogʻi keladi. Ikkalasi ham muvaffaqiyat sanaladi.

Q: Paneldagi oʻzgarishlarni ham koʻra olamanmi?

Ha. `GET /v1/changes` oqimi oʻzgarish qayerdan kelganiga qaramaydi: panel, mobil ilova va API bir oqimga tushadi. Oqim faqat tip va identifikatorni beradi.

Q: Alohida sandbox muhiti bormi?

Hozircha yoʻq — buni ochiq aytamiz. `kp_test_` kaliti bugun faqat yorliq va haqiqiy maʼlumotingizga yozadi. Sinash uchun alohida kompaniya oching.

Q: Webhook bormi?

Hozircha yoʻq. Bugungi ishlaydigan yoʻl — `GET /v1/changes` ni muntazam soʻrash: oxirgi `meta.checkpoint` ni keyingi chaqiruvda `since` sifatida berasiz.

Kumpara Developer API onlayn doʻkonlar, ERP, buxgalteriya dasturlari va marketpleys integratorlarini ulaydi. /v1 yuzasi panel bilan bir xil yadroni chaqiradi: bir xil tekshiruv, bir xil daftar yozuvi, bir xil soliq hisobi.

Daftar-xavfsiz: har bir pul harakati bitta tranzaksiya, tuzatish esa teskari yozuv
e-Hujjat ham shu yerda: chiqarish, bekor qilish, kiruvchi quti, soliq toʻlovchi soʻrovi va kontor
Turkiya uchun: satr boʻyicha ushlab qolish, QQS istisno kodi, koʻp valyuta va kurs snapshot'i

Beta dasturiga qoʻshiling Uchlarni OpenAPI'da koʻring

Developer API hozir yopiq beta bosqichida; umumiy kirish hali ochiq emas va sana aytilmaydi. Beta ishtirokchilari oʻz manzili va kalitlarini bizdan oladi.

Nima qura olasiz?

Quyidagilar bugun ishlayotgan uchlar bilan qilinadi — reja emas.

Buyurtma zanjirini toʻliq quring

Buyurtma oching, yuk xatini joʻnating, hisob-fakturani yozib tasdiqlang va toʻlovni shu chaqiruvda yoping. Qisman joʻnatish va qisman hisob-faktura qoʻllab-quvvatlanadi.

Buxgalteriya va ERP sinxroni

GET /v1/changes oqimi oʻzgargan yozuvning tipi va identifikatorini beradi; tafsilotni oʻz uchidan oʻqiysiz. Oqim panel, mobil va API'ni ajratmaydi.

Ombor qoldigʻini mutlaq qiymatda yozing

POST /v1/stock-levels/actions/set inventarizatsiya natijasini yozadi; farq tuzatish harakatiga aylanadi.

e-Faktura va e-Arxiv yuboring

Bitta chaqiruv tasdiqlangan hisob-fakturani e-hujjatga aylantiradi; ssenariy serverda tanlanadi. Kiruvchi qutini sinxronlaysiz, XML/PDF yuklaysiz.

Kontragent holatini bitta manbadan oʻqing

Bitta balans yetmaydi: daftar satrlari, ochiq moddalar va muddat tahlili alohida uchlardir. Toʻlovni ochiq hisob-fakturalarga yopasiz.

Boshlangʻich qoldiqlarni koʻchiring

Kontragent va mahsulot uchun boshlangʻich qoldiqlar alohida uchlarda; har birining teskari yozuv jufti bor.

Besh qadamda birinchi hisob-fakturangiz

Har bir yozuv uchta sarlavha bilan keladi: Authorization, Idempotency-Key, Content-Type.

1

Kalit yarating

Ilovada: Sozlamalar → API kalitlari. Nom, kompaniya va scope tanlang. Ochiq kalit bir marta koʻrinadi.
2

Kimligingizni tasdiqlang

GET /v1/me kalit bogʻlangan biznes, kompaniya, muhit va scope'larni qaytaradi.
3

Kontragentni upsert qiling

VKN yoki kontragent kodi boʻyicha moslang: bor yozuv yangilanadi, yoʻqi ochiladi.
4

Hisob-fakturani yozib tasdiqlang

approve: true bilan yaratish va tasdiqlash bitta tranzaksiyada: raqam, qarz va ombor chiqimi birga.
5

Toʻlovni yoping

Toʻlovni yaratayotganda hisob-fakturani ham berasiz: kassa, kontragent va yopish bitta tranzaksiyada.

Tez boshlash

1. Kalitni tekshiring

Har bir soʻrov Authorization: Bearer sarlavhasi bilan keladi. Birinchi chaqiruv kalit qaysi biznes va kompaniyaga bogʻlanganini hamda qanday huquqlarga egaligini aytadi:

curl -s "https://api.kumpara.net/v1/me" \
  -H "Authorization: Bearer kp_live_a1b2c3d4_…"

GET /v1/capabilities esa bu kompaniyada e-hujjat ulanganmi, kontor qancha qolgan va baza valyuta nima ekanini aytadi.

2. Kontragentni oʻz kalitingiz bilan moslang

curl -s -X POST "https://api.kumpara.net/v1/contacts/actions/upsert?matchBy=taxNumber" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: contact-4711-2026-09-23" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Örnek Gıda Ltd. Şti.", "type": "customer", "taxNumber": "1234567890" }'

Javobdagi created maydoni yozuv yangi ochilganini yoki mavjudi yangilanganini bildiradi. matchBy faqat taxNumber yoki code boʻladi.

3. Hisob-fakturani yozing va tasdiqlang

Hisob-faktura satrida summa maydoni yoʻq. Siz miqdor, narx, chegirma va QQS stavkasini yuborasiz; qolganini server hisoblaydi.

curl -s -X POST "https://api.kumpara.net/v1/sales-invoices" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: order-88213-invoice" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "6f1c…", "currency": "TRY", "approve": true,
        "lines": [ { "productId": "9a3e…", "quantity": 10, "unitPrice": 250, "vatRate": 20 } ] }'

approve: true yaratish va tasdiqlashni bitta tranzaksiyada bajaradi. Bu pul mutatsiyasi, shuning uchun kalitda sales:write yonida sales:approve ham boʻlishi kerak.

4. Toʻlovni yozing va hisob-fakturani yoping

curl -s -X POST "https://api.kumpara.net/v1/payments" \
  -H "Authorization: Bearer kp_live_…" \
  -H "Idempotency-Key: payment-88213" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "6f1c…", "cashAccountId": "2b77…", "direction": "incoming",
        "amount": 3060, "invoiceType": "sales_invoice", "invoiceId": "c41b…" }'

5. Oʻzgarishlarni oling

curl -s "https://api.kumpara.net/v1/changes?since=2026-09-23T06:00:00Z&types=sales_invoice,payment" \
  -H "Authorization: Bearer kp_live_…"

Keyingi chaqiruvda meta.checkpoint ni since sifatida berasiz — chegara qatʼiy, ayni yozuv ikki marta kelmaydi. Besh daqiqalik ustma-ustlik qoldirishni tavsiya qilamiz.

Asosiy shartnoma

Kimlik va huquqlar

Kalit Authorization: Bearer kp_live_… (yoki X-Api-Key) bilan yuboriladi. Ochiq qiymat saqlanmaydi — Kumpara faqat SHA-256 xesh va prefiksni tutadi. Har bir kalit bitta kompaniyaga bogʻlangan; boshqa kompaniya maʼlumoti qaytmaydi. Kalit huquqi uni yaratgan foydalanuvchi rolidan oshmaydi.

Huquqlar {resurs}:{amal} koʻrinishida, yigirma sakkizta: read, write, approve hamda e-hujjat uchun issue/cancel/incoming. Huquqsiz uch 403 insufficient_scope qaytaradi va yetishmayotgan huquqni nomi bilan aytadi.

Idempotentlik

Har bir yozuv Idempotency-Key talab qiladi. Kalit yozuvni yozgan tranzaksiya ichida saqlanadi. Ayni kalit ikkinchi marta kelsa ish qayta bajarilmaydi. Javob ikki koʻrinishdan biri boʻladi: 409 idempotency_replayed (yaratilgan yozuvni GET bilan oʻqiysiz) yoki 200 bilan birinchi javob gavdasi va replayed: true bayrogʻi. Ikkalasi ham "amal allaqachon bajarilgan" degani; mijozingiz ikkalasini ham muvaffaqiyat deb qabul qilishi kerak.

Pul, kurs va sonli tiplar

Summalar numeric(19,4) sifatida saqlanadi va JSON'da satr boʻlib qaytadi — yaxlitlash xatosi yoʻq. Summa hech qachon valyutadan ajratilmaydi.

Har bir moliyaviy satr oʻz kurs snapshot'ini olib yuradi: originalAmount, originalCurrency, exchangeRate, baseAmount, baseCurrency. Kurs keyin oʻzgarsa ham oʻtgan hujjat oʻzgarmaydi. Kursni exchangeRate bilan berishingiz mumkin; bermasangiz 1 ishlatiladi.

Sahifalash

Roʻyxatlar cursor bilan sahifalanadi; offset yoʻq. Javobda meta.nextCursor va meta.hasMore bor. pageSize standart 50, eng koʻpi 200. Delta uchun updatedAfter soʻrov parametri yoki /v1/changes.

Xatolar

Xatolar RFC 9457 application/problem+json va barqaror code maydoni bilan qaytadi: 400 — soʻrov oʻqilmadi, 401 — kalit yaroqsiz (unauthorized), 403 — huquq yoʻq, 404 — yozuv yoʻq, 409 — toʻqnashuv, 422 — biznes qoida buzildi, 429 — limit oshdi.

Limitlar va soʻrov identifikatori

Oʻqish va yozish alohida kovada: standart daqiqasiga 600 oʻqish va 120 yozish. Har javobda RateLimit-* sarlavhalari bor. Har javob X-Request-Id olib yuradi; xato gavdasida requestId sifatida koʻrinadi. Toʻliq shartnoma OpenAPI 3 sifatida: https://api.kumpara.net/v1/openapi.json.

Resurslar

Quyidagi jadval bugun ishlayotgan yuzaning barchasi. Toʻliq parametrlar va javob sxemalari OpenAPI'da: https://api.kumpara.net/v1/docs.

Soha	Asosiy uchlar	Huquqlar
Kontekst	`GET /v1/me`, `GET /v1/capabilities`	`me:read`
Kontragent	`GET · POST /v1/contacts`, `POST /v1/contacts/actions/upsert`	`contacts:read` · `contacts:write`
Kontragent holati	`GET /v1/contacts/{id}/balance`, `…/ledger-entries`, `…/open-items`, `GET /v1/aging`	`contacts:read`
Mahsulot va variant	`GET · POST /v1/products`, `POST /v1/products/{id}/variants`	`products:read` · `products:write`
Ombor	`GET /v1/stock-levels`, `POST /v1/stock-levels/actions/set`, `GET /v1/stock-movements`	`stock:read` · `stock:write`
Buyurtma	`GET · POST /v1/orders`, `POST /v1/orders/{id}/actions/cancel`	`sales:read` · `sales:write`
Yuk xati	`GET · POST /v1/delivery-notes`, `…/actions/ship`	`sales:read` · `sales:write`
Sotuv hisob-fakturasi	`GET · POST /v1/sales-invoices`, `…/{id}/actions/approve`, `…/{id}/actions/cancel`	`sales:read` · `sales:write` · `sales:approve`
Xarid hisob-fakturasi	`GET · POST /v1/purchase-invoices`, `…/{id}/actions/approve`	`purchase:*`
Toʻlovlar	`GET · POST /v1/payments`, `POST /v1/payments/{id}/actions/allocate`	`payments:read` · `payments:write`
Kassa va bank	`GET /v1/cash-accounts`, `…/{id}/ledger-entries`	`cash:read`
Chek va veksel	`GET /v1/cheques`	`cheques:read`
e-Hujjat	`POST /v1/sales-invoices/{id}/actions/issue-e-document`, `GET /v1/e-documents`, `GET /v1/incoming-e-documents`	`edocuments:*`
Maʼlumotnoma	`GET /v1/warehouses`, `GET /v1/categories`, `GET /v1/reference/{type}`	`catalog:read`
Oʻzgarish oqimi	`GET /v1/changes`	`changes:read`

Hujjat zanjiri qanday bogʻlanadi? Yuk xatida orderId, hisob-fakturada orderId va deliveryNoteIds[] bor; satrlar orderLineId va deliveryNoteLineId bilan moslanadi. Qolgan miqdor saqlangan hisoblagichdan emas, bekor qilinmagan hisob-fakturalardan keltirib chiqariladi.

Ombor chiqimi bitta joyda tugʻiladi. Joʻnatish va hisob-faktura tasdigʻi bir molni ikki marta kamaytirmaydi: umumiy chiqim max(Σ joʻnatish, Σ tasdiqlangan hisob-faktura).

Hozircha yoʻq — rejada

Notoʻgʻri taxminga qurmasligingiz uchun yoʻq narsalarni ham yozamiz.

Webhook Tez orada

Bugun ishlaydigan yoʻl — GET /v1/changes ni soʻrash; webhooks:manage katalogda bor, lekin uch yoʻq.

Izolyatsiyalangan sandbox Tez orada

kp_test_ bugun faqat yorliq va haqiqiy maʼlumotga yozadi. Sinash uchun alohida kompaniya oching.

ETag / If-Match Tez orada

Bir vaqtlilik nazorati tayanch ustunsiz yarim qoʻshilmaydi: himoya bor degan taassurot yoʻqligidan yomonroq.

OAuth 2.1 va ilovalar katalogi Tez orada

Beta davrida mijozingiz oʻz panelidan tor kalit yaratadi; rozilik ekranli oqim rejada.

Kiruvchi e-hujjatni xarid hisob-fakturasiga aylantirish Tez orada

Kiruvchi qutini oʻqish, javob berish va eʼtiborsiz qoldirish ishlaydi; satr-mahsulot moslash hozircha panelda.

Hisobot va eksport uchlari Tez orada

Muddat tahlili (GET /v1/aging) ishlaydi; P&L, QQS va asinxron eksport hali yoʻq.

Xavfsizlik, izolyatsiya va shaxsiy maʼlumot

Izolyatsiya maʼlumotlar bazasi darajasida. Bizneslarni ajratadigan narsa ilovadagi filtr emas, PostgreSQL'ning satr darajasidagi xavfsizlik qatlami. API soʻrovi eng kam huquqli rol bilan ulanadi va kontekst ulanish ochilishida bazaga yoziladi; soʻrov notoʻgʻri yozilsa ham boshqa biznes satri qaytmaydi. Kalit bitta kompaniyaga bogʻlangan.

Kalit saqlanmaydi. Faqat SHA-256 xesh va prefiks (kp_live_a1b2c3d4) saqlanadi. Ochiq qiymat yaratish javobida bir marta koʻrinadi; yoʻqotsangiz tiklanmaydi, yangisini yaratasiz. Kalit loglarga yozilmaydi. Bekor qilish darhol kuchga kiradi.

Huquq koʻtarilishi yoʻq. Kalit scope'i uni yaratgan foydalanuvchi rolidan oshmaydi. approve: true bilan hisob-faktura yaratish sales:write yonida sales:approve talab qiladi.

Har bir amal iz qoldiradi. API orqali har bir yozuv audit jurnaliga kalit prefiksi bilan tushadi (api:kp_live_a1b2c3d4). Panel, mobil va API bir jurnalga yozadi.

Shaxsiy maʼlumot tor doirada. JShShIR, IBAN, ism va manzil kabi maydonlar pii:read huquqi yoʻq kalitlarga niqoblangan holda qaytadi — oxirgi toʻrt belgi koʻrinadi, uch esa ishlashda davom etadi. Integratsiyangizga kerak boʻlmasa, bu huquqni bermang.

Kalitni qanday saqlash kerak? Server tomonda, muhit oʻzgaruvchisida yoki sir menejerida; manba kodga, brauzerga yoki mobil ilovaga joylamang. Har bir integratsiyaga alohida kalit yarating. Yordam soʻraganda requestId va Idempotency-Key ni ulashing, kalitni hech qachon emas.

Dasturchilar soʻraydigan savollar

API qaysi tarifga kiradi?

Kirish tarifga qarab yopilmaydi. Farq soʻrov limitlari va kvotalarda; ular sozlanadi. Beta davrida kirish ariza bilan ochiladi.

Summalarni oʻzim hisoblab yubora olamanmi?

Yoʻq — yagona vakolat serverda. Siz miqdor, narx, chegirma, QQS stavkasi, ushlab qolish kodi va valyutani yuborasiz. Satr jamlanmasi, ushlangan QQS, baza summa va hujjat raqami serverda hosil boʻladi.

Soʻrovni ikki marta yuborsam, takroriy yozuv boʻladimi?

Yoʻq. Har bir yozuv Idempotency-Key talab qiladi; kalit yozuvni yozgan tranzaksiya ichida saqlanadi. Ayni kalit ikkinchi marta kelsa ish qayta bajarilmaydi: yo 409 idempotency_replayed olasiz va yozuvni GET bilan oʻqiysiz, yo 200 bilan birinchi javob gavdasi va replayed: true bayrogʻi keladi. Ikkalasi ham muvaffaqiyat sanaladi.

Tasdiqlangan hisob-fakturani tahrirlab boʻladimi?

Yoʻq, tasdiqlangan hujjat oʻzgarmaydi. Tuzatish yoʻli — bekor qilish va yangi hujjat; bekor qilish teskari yozuv yozadi. Daftarlaralarda UPDATE/DELETE yoʻq.

Paneldagi oʻzgarishlarni ham koʻra olamanmi?

Ha. GET /v1/changes oqimi oʻzgarish qayerdan kelganiga qaramaydi: panel, mobil ilova va API bir oqimga tushadi. Oqim faqat tip va identifikatorni beradi.

Alohida sandbox muhiti bormi?

Hozircha yoʻq — buni ochiq aytamiz. kp_test_ kaliti bugun faqat yorliq va haqiqiy maʼlumotingizga yozadi. Sinash uchun alohida kompaniya oching.

Webhook bormi?

Hozircha yoʻq. Bugungi ishlaydigan yoʻl — GET /v1/changes ni muntazam soʻrash: oxirgi meta.checkpoint ni keyingi chaqiruvda since sifatida berasiz.

Koʻp kompaniyali biznesda nima qilaman?

Har bir kalit bitta kompaniyaga bogʻlangan va faqat oʻsha kompaniya maʼlumotini koʻradi. Koʻp kompaniyali integratsiyada kompaniya boshiga bitta kalit yaratasiz.

Hisob-faktura yaratish kontor sarflaydimi?

Yoʻq. Kontor faqat e-hujjat trafigida ishlatiladi: har bir chiquvchi va kiruvchi e-hujjat 1 kontor. Tizimda yaratgan hujjatlaringiz kontor sarflamaydi.

Kalitni yoʻqotsam nima boʻladi?

Tiklab boʻlmaydi. Kumpara faqat SHA-256 xesh va prefiksni saqlaydi; ochiq qiymat yaratish javobida bir marta koʻrsatiladi. Yoʻqotsangiz eskisini bekor qilib yangisini yaratasiz.