FiKSDevelopers
Open platform

ICTility LLC / FiKS API

Connect your business to FiKS.

Everything your development team needs to send sales, track receipts and reconcile reports.

Open playground
Merchant receipt endpoints currently run in SIMULATION. API acceptance does not mean ATK acceptance, printing or fiscalization. Official ATK TEST integration is a separate platform-admin workflow.
BASE URLhttps://fiks.ictility.com

01 / START

Quick start

  1. Get a company API key

    Ask your platform administrator for your company ID and merchant API key. Store the key in your server environment as FIKS_API_KEY.

  2. Send one sale

    POST a sale to your merchant receipts endpoint. Use a unique external_id and Idempotency-Key for each sale. Retain both values and the exact request for retries.

  3. Track the receipt

    Save receipt.id from the response. Read the receipt or its events, and configure signed webhooks with the administrator.

Company typeReceipt output
BILLINGPrint queue + preview QR. Email is an optional manual copy.
DIRECTCatalog/POS sales with print queue + preview QR. Email is an optional manual copy.
ONLINEcustomer_contact.email is required. Automatic email follows ATK acknowledgement; no automatic print job.

The company type is configured by an administrator. Supplying an email on a BILLING or DIRECT sale does not switch it to automatic email delivery.

02 / ACCESS

Authentication

Authorization: Bearer <MERCHANT_API_KEY>
Content-Type: application/json
Idempotency-Key: <YOUR_STABLE_SALE_REFERENCE>

Merchant keys are scoped to one company. The merchant path uses the company ID, not its tax NUI. A key cannot access another company. Browser login, merchant keys, connector keys and ATK agent keys are separate credentials.

Keep keys on your backend, never in storefront JavaScript or URLs. The playground sends only to this FiKS origin, does not use your login cookie, and does not save the key.

Send decimal amounts as strings. unit_price allows 4 decimal places; quantity allows 3; monetary totals allow 2. Prices include VAT. Unknown fields, inconsistent totals and duplicate JSON keys are rejected. Maximum request body: 1 MiB.

03 / RECEIPTS

Receipt lifecycle

RECEIVED→SENT→ATK_RECEIVED→PRINTED→CLOSED

HTTP 202 means FiKS stored the receipt. A replay returns HTTP 200 and the existing ID. Neither response proves ATK acceptance. For print delivery, CLOSED requires ATK acknowledgement and print confirmation. For online delivery, CLOSED requires ATK acknowledgement and email-provider acceptance; PRINTED is skipped.

Current merchant lifecycle acknowledgements are SIMULATION only and fiscalized remains false. Email-provider acceptance does not prove inbox delivery or that the customer read it. QR links open the FiKS preview, not ATK fiscal verification.

04 / EVENTS

Webhooks

An administrator configures an HTTPS destination on an approved host. The signing secret is returned once. Verify the signature over the untouched raw request body, reject stale timestamps and deduplicate by event ID before processing.

X-FiKS-Event-ID: <event-id>
X-FiKS-Timestamp: <unix-seconds>
X-FiKS-Signature: sha256=<hex-digest>

HMAC-SHA256(secret, timestamp + "." + raw_body)

fiks.received · atk.sent · atk.received · receipt.printed · receipt.closed

Return a 2xx response after durably accepting an event. Delivery is retried up to 8 attempts with exponential delays capped at 1 hour, when the dispatcher runs. Duplicates and out-of-order delivery are possible. Use sequence and receipt lookup to reconcile.

Example webhook payload

05 / RELIABILITY

Errors and retries

HTTPMeaning / action

After a network timeout, keep the same idempotency key, external_id and payload. A changed payload returns 409. Do not create a new reference to bypass an uncertain outcome. List endpoints return at most 100 recent records; query-string pagination is not supported. Monthly reports use Europe/Belgrade calendar months; accepted means received by FiKS, not ATK accepted.

06 / BUILD & TEST

API playground

Start with a sample and validate it without creating a receipt. Switch to the company API when you are ready to send an authenticated request.

Company type applies to validation only. API requests use the company's saved settings.

POST
Request body
Response
Run a request to see its response.

These samples call the company API. Set FIKS_API_KEY in your server environment. Your pasted key is never included in copied or downloaded code.

07 / REFERENCE

Endpoint reference

Expand an endpoint for parameters, request fields and responses. Technical schema names and descriptions are shown in English. Administrator and agent operations require their own permissions.

Loading API reference…