Do everything the app does — under the same rules — from your own software.

1. Verify your key

Every request carries Authorization: Bearer. Your first call tells you which business and which company the key is bound to, and what it may do:

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

{
  "data": {
    "tenant":    { "id": "…", "name": "Örnek Ticaret A.Ş.", "plan": "Pro" },
    "company":   { "id": "…", "legalName": "Örnek Ticaret A.Ş.", "baseCurrency": "TRY" },
    "apiClient": { "prefix": "kp_live_a1b2c3d4", "environment": "live",
                   "scopes": ["me:read", "contacts:write", "sales:write", "sales:approve"] }
  },
  "meta": { "requestId": "0HN…" }
}

GET /v1/capabilities then tells you whether e-documents are connected for this company, how many credits are left and what the base currency is — you shape your flow around that.

2. Match the contact by your own key

You do not have to search for a customer every time: upsert by tax number or by contact code. An existing record is updated, a missing one is created.

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",
        "preferredCurrency": "TRY",
        "paymentTermDays": 30
      }'

The response is { "data": { "id": "…", "name": "…", "created": true } }. The created flag tells you whether a record was opened or an existing one updated. matchBy accepts only taxNumber or code.

3. Issue and approve the invoice

An invoice line has no amount field. You send quantity, unit price, discount and VAT rate; the line total, the withheld VAT, the base amount and the document number are produced on the server.

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 },
          { "description": "Shipping", "quantity": 1, "unitPrice": 150, "vatRate": 20 }
        ]
      }'

{
  "data": { "id": "c41b…", "number": "SF-2026-000412", "status": "approved", "approved": true },
  "meta": { "requestId": "0HN…" }
}

approve: true does creation and approval in one transaction: the document number, the customer's debt and the stock issue appear together. That is a money mutation, so the key needs sales:approve alongside sales:write — otherwise you get 403 insufficient_scope.

4. Record the payment and close the invoice

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

The cash ledger, the customer ledger and the allocation are written in the same transaction. Use allocations[] to split across several invoices, or POST /v1/payments/{id}/actions/allocate to settle later.

5. Pull the changes

To keep the other system current you poll the feed. It gives you the type and id of what changed; you read the detail from its own endpoint.

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

{
  "data": [
    { "type": "sales_invoice", "id": "c41b…", "action": "created", "occurredAt": "2026-09-23T07:12:44Z" },
    { "type": "payment",       "id": "77af…", "action": "created", "occurredAt": "2026-09-23T07:13:02Z" }
  ],
  "meta": { "checkpoint": "2026-09-23T07:13:02Z", "nextCursor": null, "hasMore": false }
}

On the next call you pass meta.checkpoint as since — the bound is exclusive, so the same record does not come twice. We recommend a five-minute overlap against the gap between commit order and timestamp order; reads are idempotent, so a repeated record is harmless.

Identity and permissions

The key is sent as Authorization: Bearer kp_live_… (or X-Api-Key). The plain value is never stored — Kumpara keeps only the SHA-256 hash and the display prefix. Every key is locked to one company; another company's data cannot come back, architecturally. A key's scopes can never exceed the role of the user who created it.

Scopes are {resource}:{action} and there are twenty-eight of them:

An endpoint you are not allowed to call returns 403 insufficient_scope and names the missing scope.

Idempotency

Every write requires an Idempotency-Key. The key is stored inside the same transaction that writes the record — there is no dual write. A second call with the same key does not repeat the work. The response takes one of two shapes: 409 idempotency_replayed (you read the created record with GET), or 200 carrying the body of the first response plus a replayed: true flag. Both mean "already applied"; your client should treat either one as success. The key's scope is the quadruple (business, API key, endpoint, key), so two integrators cannot collide on the same value.

Money, exchange rates and numeric types

Amounts are stored as numeric(19,4) and returned as decimal strings in JSON, so no floating-point rounding happens. An amount is never separated from its currency.

Every financial line carries its own rate snapshot: originalAmount, originalCurrency, exchangeRate, baseAmount, baseCurrency. Even if the rate list is updated later, a past document does not move. You may supply the rate yourself in exchangeRate; if you omit it, 1 is used — fill it in when you issue a cross-currency document.

Pagination and filters

Lists are paginated by cursor; there is no offset. The response carries meta.nextCursor and meta.hasMore. Page size is given by pageSize: default 50, maximum 200. For deltas use the updatedAfter query parameter or the /v1/changes feed.

Errors

Errors use RFC 9457 application/problem+json and carry a stable code. The dictionary is frozen: a documented code does not change.

{
  "type": "https://docs.kumpara.net/errors/insufficient_scope",
  "title": "Yetki yok",
  "status": 403,
  "detail": "Bu uç `sales:approve` yetkisi ister; anahtarınızda yok.",
  "code": "insufficient_scope",
  "requestId": "0HN…"
}

Field-level failures add an errors[] array; each entry carries pointer, code and detail.

Rate limits

Reads and writes use separate buckets — pulling a report does not block invoicing. The defaults are 600 reads and 120 writes per minute per key; every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Over the limit you get 429 plus Retry-After.

Request id

Every response carries X-Request-Id, and the same value appears as requestId in an error body. Share it in a support request. To supply your own, send an X-Request-Id header (up to 64 characters) and the response echoes it.

Discovery

The whole contract is published as OpenAPI 3: https://api.kumpara.net/v1/openapi.json for machines, https://api.kumpara.net/v1/docs to browse. The spec needs no authentication — it is the contract, not data.

The table below is the whole surface that is live today. Full parameters, bodies and response schemas live in OpenAPI: https://api.kumpara.net/v1/docs.

How the document chain links up. A delivery note body takes orderId; an invoice body takes orderId and deliveryNoteIds[], and lines match through orderLineId and deliveryNoteLineId. The remaining quantity is not a stored counter — it is derived from non-cancelled invoices, so a cancelled invoice frees the order up to be invoiced again.

Stock leaves in one place only. Shipping and invoice approval never deduct the same goods twice: total sales-side issue is max(Σ shipped, Σ approved invoices) and each document writes only its own delta. If the invoice was approved first, shipping may produce no movement at all — that is correct behaviour.

Isolation lives in the database. What separates one business from another is not a filter in the application but PostgreSQL's own row-level security. An API request connects with a least-privilege role and the context is written to the database as the connection opens, so even a badly written query cannot return another business's row. Company separation sits on top of that: a key is locked to one company.

The key is not stored. Only the SHA-256 hash and the display prefix (kp_live_a1b2c3d4) are kept. The plain value appears once, in the creation response; if you lose it, it cannot be recovered — you issue a new one. Keys are never written to logs; only the prefix is. Revocation takes effect immediately.

There is no privilege escalation. A key's scopes can never exceed the role of the user who created it. Creating an invoice with approve: true needs sales:approve as well as sales:write; if it is missing the request is refused, not quietly saved as a draft.

Everything leaves a trail. Every write through the API is recorded in the audit log with the key prefix as the actor (api:kp_live_a1b2c3d4). Who did what and when can always be asked afterwards; the app, mobile and the API all land in the same trail.

Personal data is scoped narrowly. Fields such as national ID numbers, IBANs, names and addresses come back masked to keys without the pii:read scope — the last four characters stay visible and the endpoint still works. If your integration does not need personal data, never grant it; the best protection is data that never leaves.

How to store the key. Keep it server-side, in an environment variable or a secret manager; never embed it in source code, a browser or a mobile app. Issue a separate key per integration so revoking one does not affect the others. When you open a support request, share the requestId and the Idempotency-Key — never your key.