Developer API · Бета

Панель істейтін барлық істі сол ережелермен өз бағдарламаңыздан жасаңыз.

Q: Сұрауды екі рет жіберсем, қайталанған жазба бола ма?

Жоқ. Әр жазу `Idempotency-Key` талап етеді; кілт жазбаны жазған транзакция ішінде сақталады. Сол кілт екінші рет келсе жұмыс қайта жасалмайды: не `409 idempotency_replayed` аласыз да жазбаны `GET` арқылы оқисыз, не `200` және бірінші жауаптың денесі мен `replayed: true` жалаушасы келеді. Екеуі де сәтті саналады.

Q: Панельдегі өзгерістерді де көре аламын ба?

Иә. `GET /v1/changes` ағыны өзгерістің қайдан келгеніне қарамайды: панель, мобильді қосымша және API бір ағынға түседі. Ағын тек тип пен идентификаторды береді.

Q: Бөлек sandbox ортасы бар ма?

Әзірге жоқ — мұны ашық айтамыз. `kp_test_` кілті бүгін тек белгі және нақты деректеріңізге жазады. Сынау үшін бөлек компания ашыңыз.

Q: Webhook бар ма?

Әзірге жоқ. Бүгінгі жұмыс істейтін жол — `GET /v1/changes` тұрақты сұрау: соңғы `meta.checkpoint` мәнін келесі шақыруда `since` ретінде бересіз.

Kumpara Developer API онлайн дүкендерді, ERP, бухгалтерлік бағдарламаларды және маркетплейс интеграторларын жалғайды. /v1 беті панельмен бірдей ядроны шақырады: бірдей тексеру, бірдей кітап жазбасы, бірдей салық есебі.

Кітапқа қауіпсіз: әр ақша қозғалысы бір транзакция, түзету — кері жазба
e-Құжат та осында: шығару, болдырмау, кіріс жәшігі, салық төлеуші сұрауы және контор
Түркияға арналған: жол бойынша ұстау, ҚҚС ерекшелік коды, көп валюта және бағам снапшоты

Бета бағдарламасына қосылыңыз Ұштарды OpenAPI-де көріңіз

Developer API қазір жабық бета кезеңінде; жалпы қолжетімділік әлі ашық емес және күні айтылмайды. Бета қатысушылары өз мекенжайы мен кілттерін бізден алады.

74: жұмыс істейтін ұш Контрагенттен e-құжатқа дейін, бәрі қорғалған.
28: бөлек scope Кілтке тек керегін бересіз.
3: тек қосылатын кітап Контрагент, касса және қойма: UPDATE/DELETE жоқ.
1: кілт = 1 компания Компаниялар арасында ағып кету мүмкін емес.

Не құра аласыз?

Төмендегілердің бәрі бүгін жұмыс істейтін ұштармен жасалады — жоспар емес.

Тапсырыс тізбегін толық құрыңыз

Тапсырыс ашыңыз, жүкқұжатты жөнелтіңіз, шотты жазып бекітіңіз және төлемді сол шақыруда жабыңыз. Ішінара жөнелту мен ішінара шот қолдауда.

Бухгалтерия және ERP синхроны

GET /v1/changes ағыны өзгерген жазбаның типі мен идентификаторын береді; егжей-тегжейін өз ұшынан оқисыз. Ағын панель, мобиль және API-ды ажыратпайды.

Қойма қалдығын абсолют мәнмен жазыңыз

POST /v1/stock-levels/actions/set түгендеу нәтижесін жазады; айырма түзету қозғалысына айналады.

e-Шот және e-Мұрағат жіберіңіз

Бір шақыру бекітілген шотты e-құжатқа айналдырады; сценарий серверде таңдалады. Кіріс жәшігін синхрондайсыз, XML/PDF жүктейсіз.

Контрагент жағдайын бір көзден оқыңыз

Бір баланс жеткіліксіз: кітап жолдары, ашық баптар және мерзім талдауы бөлек ұштар. Төлемді ашық шоттарға жабасыз.

Бастапқы қалдықтарды көшіріңіз

Контрагент пен өнім үшін бастапқы қалдықтар бөлек ұштарда; әрқайсысының кері жазба жұбы бар.

Бес қадамда алғашқы шотыңыз

Әр жазу үш тақырып алып жүреді: Authorization, Idempotency-Key, Content-Type.

1

Кілт жасаңыз

Қосымшада: Параметрлер → API кілттері. Атау, компания және scope таңдаңыз. Ашық кілт бір рет көрінеді.
2

Кім екеніңізді растаңыз

GET /v1/me кілт байланған бизнес, компания, орта және scope қайтарады.
3

Контрагентті upsert жасаңыз

ЖСН не контрагент коды бойынша сәйкестендіріңіз: бар жазба жаңарады, жоғы ашылады.
4

Шотты жазып бекітіңіз

approve: true арқылы жасау мен бекіту бір транзакцияда: нөмір, қарыз және қойма шығысы бірге.
5

Төлемді жабыңыз

Төлемді жасағанда шотты да бересіз: касса, контрагент және жабу бір транзакцияда.

Жылдам бастау

1. Кілтті тексеріңіз

Әр сұрау Authorization: Bearer тақырыбымен келеді. Алғашқы шақыру кілт қай бизнеске және компанияға байланғанын, қандай құқықтары барын айтады:

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

GET /v1/capabilities бұл компанияда e-құжат қосулы ма, контор қанша қалды және база валюта не екенін айтады.

2. Контрагентті өз кілтіңізбен сәйкестендіріңіз

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" }'

Жауаптағы created өрісі жазба жаңадан ашылғанын әлде бары жаңарғанын білдіреді.

3. Шотты жазып бекітіңіз

Шот жолында сома өрісі жоқ. Сіз мөлшер, баға, жеңілдік және ҚҚС мөлшерлемесін жібересіз; қалғанын сервер есептейді.

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 жасау мен бекітуді бір транзакцияда орындайды. Бұл ақша мутациясы, сондықтан кілтте sales:write қасында sales:approve да болуы керек.

4. Төлемді жазып, шотты жабыңыз

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. Өзгерістерді алыңыз

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

Келесі шақыруда meta.checkpoint мәнін since ретінде бересіз — шекара қатаң, сол жазба екі рет келмейді. Бес минуттық қабаттасу қалдыруды ұсынамыз.

Негізгі келісім

Кімдік және құқықтар

Кілт Authorization: Bearer kp_live_… (немесе X-Api-Key) арқылы жіберіледі. Ашық мән сақталмайды — Kumpara тек SHA-256 хэш пен префиксті ұстайды. Әр кілт бір компанияға байланған; басқа компания деректері қайтпайды. Кілт құқығы оны жасаған пайдаланушы рөлінен аспайды.

Құқықтар {ресурс}:{әрекет} түрінде, жиырма сегіз дана: read, write, approve және e-құжат үшін issue/cancel/incoming. Құқығы жоқ ұш 403 insufficient_scope қайтарады.

Идемпотенттік

Әр жазу Idempotency-Key талап етеді. Кілт жазбаны жазған транзакция ішінде сақталады. Сол кілт екінші рет келсе жұмыс қайта жасалмайды. Жауап екі пішіннің бірі болады: 409 idempotency_replayed (жасалған жазбаны GET арқылы оқисыз) не 200 және бірінші жауаптың денесі мен replayed: true жалаушасы. Екеуі де «әрекет әлдеқашан қолданылды» дегенді білдіреді; клиентіңіз екеуін де сәтті деп санауы керек.

Ақша, бағам және сандық типтер

Сомалар numeric(19,4) ретінде сақталады және JSON-да жол болып қайтады — дөңгелектеу қатесі жоқ. Сома валютадан ешқашан ажыратылмайды.

Әр қаржылық жол өз бағам снапшотын алып жүреді: originalAmount, originalCurrency, exchangeRate, baseAmount, baseCurrency. Бағам кейін өзгерсе де өткен құжат өзгермейді. Бағамды exchangeRate арқылы бере аласыз; бермесеңіз 1 қолданылады.

Беттеу

Тізімдер cursor арқылы беттеледі; offset жоқ. Жауапта meta.nextCursor және meta.hasMore бар. pageSize әдепкі 50, ең көбі 200. Дельта үшін updatedAfter сұрау параметрі не /v1/changes.

Қателер

Қателер RFC 9457 application/problem+json және тұрақты code өрісімен қайтады: 400 — сұрау оқылмады, 401 — кілт жарамсыз (unauthorized), 403 — құқық жоқ, 404 — жазба жоқ, 409 — қайшылық, 422 — бизнес ереже бұзылды, 429 — лимит асты.

Лимиттер және сұрау идентификаторы

Оқу мен жазу бөлек шелекте: әдепкі минутына 600 оқу және 120 жазу. Әр жауапта RateLimit-* тақырыптары бар. Әр жауап X-Request-Id алып жүреді. Толық келісім OpenAPI 3 ретінде: https://api.kumpara.net/v1/openapi.json.

Ресурстар

Төмендегі кесте — бүгін жұмыс істейтін беттің бәрі. Толық параметрлер мен жауап схемалары OpenAPI-де: https://api.kumpara.net/v1/docs.

Сала	Негізгі ұштар	Құқықтар
Контекст	`GET /v1/me`, `GET /v1/capabilities`	`me:read`
Контрагент	`GET · POST /v1/contacts`, `POST /v1/contacts/actions/upsert`	`contacts:read` · `contacts:write`
Контрагент жағдайы	`GET /v1/contacts/{id}/balance`, `…/ledger-entries`, `…/open-items`, `GET /v1/aging`	`contacts:read`
Өнім және нұсқа	`GET · POST /v1/products`, `POST /v1/products/{id}/variants`	`products:read` · `products:write`
Қойма	`GET /v1/stock-levels`, `POST /v1/stock-levels/actions/set`, `GET /v1/stock-movements`	`stock:read` · `stock:write`
Тапсырыс	`GET · POST /v1/orders`, `POST /v1/orders/{id}/actions/cancel`	`sales:read` · `sales:write`
Жүкқұжат	`GET · POST /v1/delivery-notes`, `…/actions/ship`	`sales:read` · `sales:write`
Сатылым шоты	`GET · POST /v1/sales-invoices`, `…/{id}/actions/approve`, `…/{id}/actions/cancel`	`sales:read` · `sales:write` · `sales:approve`
Сатып алу шоты	`GET · POST /v1/purchase-invoices`, `…/{id}/actions/approve`	`purchase:*`
Төлемдер	`GET · POST /v1/payments`, `POST /v1/payments/{id}/actions/allocate`	`payments:read` · `payments:write`
Касса және банк	`GET /v1/cash-accounts`, `…/{id}/ledger-entries`	`cash:read`
Чек және вексель	`GET /v1/cheques`	`cheques:read`
e-Құжат	`POST /v1/sales-invoices/{id}/actions/issue-e-document`, `GET /v1/e-documents`, `GET /v1/incoming-e-documents`	`edocuments:*`
Анықтамалық	`GET /v1/warehouses`, `GET /v1/categories`, `GET /v1/reference/{type}`	`catalog:read`
Өзгеріс ағыны	`GET /v1/changes`	`changes:read`

Құжат тізбегі қалай жалғанады? Жүкқұжатта orderId, шотта orderId және deliveryNoteIds[] бар; жолдар orderLineId мен deliveryNoteLineId арқылы сәйкестендіріледі. Қалған мөлшер сақталған есептегіштен емес, болдырылмаған шоттардан шығарылады.

Қойма шығысы бір жерде туады. Жөнелту мен шот бекітуі бір тауарды екі рет азайтпайды: жалпы шығыс max(Σ жөнелту, Σ бекітілген шот).

Әзірге жоқ — жоспарда

Қате болжамға құрмауыңыз үшін жоқ нәрселерді де жазамыз.

Webhook Жақында

Бүгін жұмыс істейтін жол — GET /v1/changes сұрау; webhooks:manage каталогта бар, бірақ ұш жоқ.

Оқшауланған sandbox Жақында

kp_test_ бүгін тек белгі және нақты деректерге жазады. Сынау үшін бөлек компания ашыңыз.

ETag / If-Match Жақында

Қатарластық бақылауы тірек бағанасыз жартылай қосылмайды: қорғаныс бар деген әсер жоғынан жаман.

OAuth 2.1 және қосымшалар каталогы Жақында

Бета кезінде клиентіңіз өз панелінен тар кілт жасайды; келісім экранды ағын жоспарда.

Кіріс e-құжатты сатып алу шотына айналдыру Жақында

Кіріс жәшікті оқу, жауап беру және елемеу жұмыс істейді; жол-өнім сәйкестендіру әзірге панельде.

Есеп және экспорт ұштары Жақында

Мерзім талдауы (GET /v1/aging) жұмыс істейді; P&L, ҚҚС және асинхронды экспорт әлі жоқ.

Қауіпсіздік, оқшаулау және дербес дерек

Оқшаулау дерекқор деңгейінде. Бизнестерді ажырататын нәрсе қосымшадағы сүзгі емес, PostgreSQL-дің жол деңгейіндегі қауіпсіздік қабаты. API сұрауы ең аз құқықты рөлмен қосылады және контекст қосылым ашылғанда дерекқорға жазылады; сұрау қате жазылса да басқа бизнес жолы қайтпайды. Кілт бір компанияға байланған.

Кілт сақталмайды. Тек SHA-256 хэш пен префикс (kp_live_a1b2c3d4) сақталады. Ашық мән жасау жауабында бір рет көрінеді; жоғалтсаңыз қалпына келмейді, жаңасын жасайсыз. Кілт логтарға жазылмайды. Тоқтату бірден күшіне енеді.

Құқық көтерілуі жоқ. Кілт scope-ы оны жасаған пайдаланушы рөлінен аспайды. approve: true арқылы шот жасау sales:write қасында sales:approve талап етеді.

Әр әрекет із қалдырады. API арқылы әр жазу аудит журналына кілт префиксімен түседі (api:kp_live_a1b2c3d4). Панель, мобиль және API бір журналға жазады.

Дербес дерек тар аяда. ЖСН, IBAN, есім және мекенжай сияқты өрістер pii:read құқығы жоқ кілттерге бүркемеленіп қайтады — соңғы төрт таңба көрінеді, ұш жұмысын жалғастырады. Интеграцияңызға қажет болмаса, бұл құқықты бермеңіз.

Кілтті қалай сақтау керек? Сервер жағында, орта айнымалысында не құпия менеджерінде; бастапқы кодқа, браузерге не мобильді қосымшаға енгізбеңіз. Әр интеграцияға бөлек кілт жасаңыз. Қолдауға жазғанда requestId және Idempotency-Key бөлісіңіз, кілтті ешқашан емес.

Әзірлеушілер қоятын сұрақтар

API қай тарифке кіреді?

Қолжетімділік тарифке қарай жабылмайды. Айырмашылық сұрау лимиттері мен квоталарда; олар реттеледі. Бета кезеңінде қолжетімділік өтініммен ашылады.

Сомаларды өзім есептеп жібере аламын ба?

Жоқ — жалғыз билік серверде. Сіз мөлшер, баға, жеңілдік, ҚҚС мөлшерлемесі, ұстау коды және валюта жібересіз. Жол жиыны, ұсталған ҚҚС, база сома және құжат нөмірі серверде жасалады.

Сұрауды екі рет жіберсем, қайталанған жазба бола ма?

Жоқ. Әр жазу Idempotency-Key талап етеді; кілт жазбаны жазған транзакция ішінде сақталады. Сол кілт екінші рет келсе жұмыс қайта жасалмайды: не 409 idempotency_replayed аласыз да жазбаны GET арқылы оқисыз, не 200 және бірінші жауаптың денесі мен replayed: true жалаушасы келеді. Екеуі де сәтті саналады.

Бекітілген шотты түзете аламын ба?

Жоқ, бекітілген құжат өзгермейді. Түзету жолы — болдырмау және жаңа құжат; болдырмау кері жазба жазады. Кітаптарда UPDATE/DELETE жоқ.

Панельдегі өзгерістерді де көре аламын ба?

Иә. GET /v1/changes ағыны өзгерістің қайдан келгеніне қарамайды: панель, мобильді қосымша және API бір ағынға түседі. Ағын тек тип пен идентификаторды береді.

Бөлек sandbox ортасы бар ма?

Әзірге жоқ — мұны ашық айтамыз. kp_test_ кілті бүгін тек белгі және нақты деректеріңізге жазады. Сынау үшін бөлек компания ашыңыз.

Webhook бар ма?

Әзірге жоқ. Бүгінгі жұмыс істейтін жол — GET /v1/changes тұрақты сұрау: соңғы meta.checkpoint мәнін келесі шақыруда since ретінде бересіз.

Көп компаниялы бизнесте не істеймін?

Әр кілт бір компанияға байланған және тек сол компания деректерін көреді. Көп компаниялы интеграцияда компанияға бір кілт жасайсыз.

Шот жасау контор жұмсай ма?

Жоқ. Контор тек e-құжат трафигінде жұмсалады: әр шығыс және кіріс e-құжат 1 контор. Жүйеде жасаған құжаттарыңыз контор жұмсамайды.

Кілтті жоғалтсам не болады?

Қалпына келтіру мүмкін емес. Kumpara тек SHA-256 хэш пен префиксті сақтайды; ашық мән жасау жауабында бір рет көрсетіледі. Жоғалтсаңыз ескісін тоқтатып, жаңасын жасайсыз.

Бета бағдарламасына қосылыңыз

Бетаға онлайн дүкен платформалары, ERP және бухгалтерлік бағдарламалар, бухгалтерлік кеңселер мен маркетплейс интеграторлары қабылданады. Қатысушылар қолжетімділік және алдын ала хабарлама алады.

Өтініш беріңіз OpenAPI спецификациясы