KWNDevelopersالعربيةOpen KWN

Guides

Connect a third-party system

For software companies — ERP, POS, e-commerce, accounting — connecting their customers’ KWN accounts.

A KWN company connects your product the same way it connects its own systems: with a key it creates and hands to you. You need no partner account: one key per customer company, used from your servers.

Connecting a customer

  1. In your product, ask the customer for a KWN API key, and tell them the scopes you need — the fewest that do the job (Scopes).
  2. The customer creates it in Settings → Integrations → API keys, named after your product, and pastes it into your product.
  3. Store it encrypted, against that customer, on your server only.
  4. Call GET /me at once: check the company’s TRN and name against your records, and that the key holds the capabilities you need (and eInvoicing.available if you send invoices).

Running the connection

  • Carry your ids as externalId on every record you create, and look records up by it — never by name.
  • Send an Idempotency-Key on every create and reuse it on retries (Idempotency).
  • Sync by updatedSince on a schedule (Pagination and sync); stay within each company’s rate limit, which every key of that company shares.
  • Branch on code in a refusal, never on the sentence (Errors).

When a key stops working

The company owns the key and may revoke it at any time — and every key stops while its KWN account is inactive. A 401 API_KEY_INVALID or MERCHANT_INACTIVE means stop calling with it and ask the customer to reconnect; do not retry in a loop. A 403 means the key lacks a scope or the company’s plan lacks an app: tell the customer which.

What a connection can never do

  • Reach another company. A key is bound to one; another company’s record answers 404.
  • Manage users, keys, billing or settings, or see bank details and internal notes.
  • Do more than the person who created the key may do.

Every change a key makes is recorded against it in the company’s audit trail, and the company sees when each key was last used. Name your product clearly so they can recognise it.