API keys, the public API and webhooks: how to connect your own system to Zaksio

What it is for

An API key lets your shop, wholesaler or your own program read and write data in Zaksio without a person logging in. The public API v1 runs at an address starting with /v1 and covers products, stock levels, counterparties and sales invoices (reading, PDF and issuing). Webhooks work the other way round: Zaksio itself sends a request to your system when something happens, e.g. an invoice is issued.

You will find a full description of every endpoint, examples in curl, JavaScript, Python and PHP, and a description of webhook signature verification in the API documentation (the "API documentation" page). This article describes the page in the app.

Where to find it and who can use it

Settings, "API and integrations" (the "How it works" button opens short instructions). The screen is visible to the Owner and the company Administrator. The module is available regardless of the company's business profile. The platform administrator can disable the public API for an organisation, in which case the screen shows a message that the feature is disabled.

Creating a key

1. In the "API keys" tab, click "New key".
2. Enter a "Key name" (e.g. the name of the integration) and choose a "Company". The key sees data of that one company only.
3. Select the "Scopes", i.e. what the key is allowed to do (list below).
4. Optionally enter "Allowed IP addresses" (single addresses or CIDR ranges), choose "Expiry" and set "Request limit per minute" (120 by default).
5. Enter your password (and your 2FA code, if you have it enabled) and click "Create key".
6. Copy the key from the "Copy your API key now" window and store it somewhere safe.

Scopes

• Products: read and write (list, details, add, change).
• Stock levels: read (total and breakdown by warehouse).
• Counterparties: read and write (add, change, delete, as long as the counterparty does not appear on any documents).
• Invoices: reading (list, details, PDF) and issuing (gapless numbering and posting as in the app).

A key can never do more than its scopes, or more than the permissions of the person who created it. Permissions are checked on every request: if that person's role is lowered, the key loses the corresponding capabilities, and when the person leaves the organisation, their keys stop working.

Key safeguards

• IP address restriction: requests from other addresses are rejected (code 403), and the attempt is recorded in the audit log.
• Expiry: after the chosen date the key stops working (code 401).
• Request limit per minute: once exceeded, the API responds with code 429 and a Retry-After header.
• Revocation: "Revoke" takes effect immediately and cannot be undone. It requires your password.
• Rotation: "Rotate" creates a new key with the same scopes and restrictions, while the old one keeps working for a chosen transition period (from zero to 7 days) so you have time to replace it in your integration.
• Creating, revoking and rotating keys and adding webhooks require you to re-enter your password and 2FA code. All of these actions, as well as writes made with a key, are recorded in the audit log.

First call

You send the key in the Authorization header: Bearer zk_live_... The "/v1/whoami" endpoint returns the company and the key's scopes, so it is handy for checking that the key works. Amounts are in grosze, quantities are decimal strings, and lists are paginated with a cursor (limit and cursor parameters). Errors use the RFC 9457 format (application/problem+json) with a stable code field.

Writes (POST, PATCH, DELETE) support the Idempotency-Key header: a repeated request with the same key returns the stored response instead of performing the write a second time, e.g. issuing a second invoice. Always include it when issuing invoices.

Webhooks

1. In the "Webhooks" tab, click "New webhook".
2. Enter the "Recipient address (URL)": https only, and a public address. Local and internal addresses are blocked.
3. Choose the events (invoice issued, invoice paid, counterparty added or changed, product added or changed, product stock level changed) and, if you wish, a single company.
4. Confirm with your password. Copy the "Signing secret": you only see it once.
5. Use the "Test" button to send a test event and see the recipient's response straight away.

Every request is signed (HMAC-SHA256 from the secret, the Zaksio-Signature header with a timestamp), so the recipient can verify that it comes from Zaksio and is not a replay from a few minutes ago. Ready-made verification code in four languages is in the API documentation. You can replace the secret at any time with the "New secret" button; the previous one then stops working.

• A delivery is considered successful after a 2xx response. Redirects are not supported.
• Failed deliveries are retried after 1 minute, 5 minutes, 30 minutes, 2, 6 and 12 hours. After the seventh failed attempt the delivery is marked "Failed" and you can retry it manually in the "Log".
• After 25 failed attempts in a row, the subscription is disabled automatically (with the reason given). You re-enable it with the "Enable" button.
• "Log" shows every delivery: status, number of attempts, response code, the recipient's response and the content sent.

Usage

The "Usage" tab shows the number of requests per day (with the share that ended in an error shown separately) for all keys or a selected one, over 7, 30 or 90 days. In the keys table you can also see the date and address of each key's last use.

API invoices and KSeF

Issuing an invoice through the API does not send it to KSeF: you do that in the app.