ICTility LLC / FiKS API
Connect your business to FiKS.
Everything your development team needs to send sales, track receipts and reconcile reports.
https://fiks.ictility.com01 / START
Quick start
- 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.
- 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.
- Track the receipt
Save receipt.id from the response. Read the receipt or its events, and configure signed webhooks with the administrator.
| Company type | Receipt output |
|---|---|
BILLING | Print queue + preview QR. Email is an optional manual copy. |
DIRECT | Catalog/POS sales with print queue + preview QR. Email is an optional manual copy. |
ONLINE | customer_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→CLOSEDHTTP 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
| HTTP | Meaning / 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.
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…
