FiKS — sales, receipts and reports in one place.
FiKS is ICTility LLC’s platform for managing transactions from billing / ERP systems, direct product sales and online stores. Each company has its own workspace, users and receipt archive.
Developed with the aim of meeting Kosovo’s fiscal legislation and ATK’s technical and functional requirements.
Official ATK documentationThese are test receipts. ATK and a real printer are not connected.
Transactions
The active company's records.
Account security
Change your initial password to continue.
Every account belongs to one company. Roles are enforced by the server.
Create access
Company users
Manage companies, access and daily activity from one place.
Company directory
Open a workspace or edit its settings.
Administration activity
Latest receipts 0
| REFERENCE | BRANCH / POS | AMOUNT | STATUS | RECEIVED AT |
|---|
No transactions
Transactions appear here after FiKS receives them.
Merchants
Choose how the company makes sales.
Connect your billing to FiKS
Keep making sales in your billing / ERP. Your server sends each completed sale to FiKS; your team uses this page for setup and monitoring. FiKS does not need to stay open in a browser.
- 01
Prepare the connection
The FiKS administrator supplies your company endpoint and merchant API key. Your billing provider maps the sale fields and stores the key on its server.
- 02
Send each completed sale
The billing server sends one HTTPS request per sale. FiKS validates and stores the receipt, creates its QR and queues it for printing after ATK confirmation.
- 03
Track the result in billing
Save receipt.id in billing. Read its status through the API or receive signed webhooks. For Billing companies, printing is required; email is an optional manual action.
Available now: API intake, receipt storage, QR and status tracking in SIMULATION. Real ATK submission and physical printing still need the certified adapter and printer agent; receiving a request is not fiscal confirmation.
Merchant endpoint
Each merchant has an endpoint and API key for ERP receipts. FiKS checks company ownership on the server. The ERP URL is informational until the appropriate adapter is built.
- Send the transaction with a unique reference.
- Save the identifier returned by the gateway.
- Read the status and reconcile the result.
Send the order through the merchant API with customer_contact.email. Use a unique reference to avoid duplicate receipts.
"customer_contact": {"email": "buyer@example.com"}Authorization: Bearer <MERCHANT_API_KEY>
Idempotency-Key: <UNIQUE_REFERENCE>
Content-Type: application/json
{
"external_id": "ERP-2026-00001",
"branch_id": "PR-01",
"pos_id": "POS-01",
"operator_id": "OP-01",
"type": "SALE",
"currency": "EUR",
"items": [{
"code": "SVC-01", "name": "Shërbim provues",
"unit": "cope", "quantity": "1",
"unit_price": "11.8000",
"tax_category": "STANDARD"
}],
"payments": [{"method": "BANK_TRANSFER",
"amount": "11.80"}],
"total": "11.80", "tax_total": "1.80"
}Set FIKS_API_KEY in your server environment and save the sample as fiks-receipt.json. Use a new external_id and Idempotency-Key for each new sale; keep them unchanged on retries.
Implementation guide for your IT team
1. Map your billing fields
Send decimal values as strings with a dot, for example "11.80". Use up to 3 decimal places for quantity, 4 for unit_price and 2 for totals. Do not send passwords or card details.
external_id | Unique sale reference from billing. Reuse it on retries. |
|---|---|
branch_id · pos_id · operator_id | Branch, terminal and operator codes agreed with the company. |
items[] | 1–200 lines: code, name, unit, quantity, unit_price and tax_category. Unit prices include VAT. |
tax_category | STANDARD (18%), REDUCED (8%), ZERO (0%) or EXEMPT. Use the category applicable to the item. |
payments[] · total · tax_total | Payment methods: CASH, CARD, BANK_TRANSFER. Payments and totals must match the items. |
type · currency | This version accepts SALE in EUR. Returns and cancellations are not implemented. |
2. Authenticate and handle retries
Use the merchant API key in Authorization: Bearer on the billing server. It is different from your login password and from the integration agent key. The merchant key is shown when the company is created; request it securely from the platform administrator. Never embed it in browser code.
Persist the request before sending. Use a unique Idempotency-Key for each sale and keep both the key and body unchanged after a timeout or retryable server error. HTTP 202 means accepted by FiKS; HTTP 200 with replayed=true means the existing receipt was returned. Save receipt.id and receipt.lifecycle_status.
Stop and investigate HTTP 409: the reference or key was reused with different data. Correct validation errors (400/422) before retrying; check the key or company access for 401/403. Never create a new sale reference just to work around a timeout.
3. Read statuses and receive webhooks
RECEIVEDfiks.received | FiKS validated and saved the receipt. |
|---|---|
SENTatk.sent | The agent reported submission toward ATK. |
ATK_RECEIVEDatk.received | The agent supplied an ATK acceptance reference. |
PRINTEDreceipt.printed | The agent confirmed printing and archived its evidence. |
CLOSEDreceipt.closed | For Billing: ATK confirmation and confirmed printing are both required. |
These downstream acknowledgements are simulated here. HTTP acceptance, a QR image or a visible receipt does not mean ATK has accepted it.
Your billing provider supplies an HTTPS webhook URL. The platform administrator approves its host and enables it below, then shares the signing secret securely. Events start after activation; use GET to reconcile earlier receipts.
X-FiKS-Event-ID: <event-id>
X-FiKS-Timestamp: <unix-seconds>
X-FiKS-Signature: sha256=<hex-hmac>
HMAC-SHA256(secret, timestamp + "." + raw_request_body)Verify the signature against the original request bytes, check timestamp freshness and deduplicate by event ID. Store the event durably, then return HTTP 2xx within 5 seconds. Retries stop after 8 attempts; monitor failed deliveries and reconcile with GET. A periodic agent dispatcher is needed for retries when there is no app traffic.
4. If billing exports files instead of calling an API
Target flow: billing exports a file → a local connector reads the folder / SFTP → maps it to the JSON request → sends it to the company endpoint → records the FiKS receipt ID and archives the file. The connector needs a persistent retry queue and must not import the same sale twice.
For this route, provide an anonymized TXT/XML/JSON sample, the field specification, folder or SFTP details, and printer model / SDK. The hosted app does not currently fetch FTP files; the parser and local connector must be implemented for that billing format.
5. Test with your billing provider
Send one test sale and save its receipt ID. Send the identical request again: it must return the same ID. Test invalid totals, a connection timeout, webhook signature verification and retry handling. Compare the billing totals with FiKS reports. Real ATK and printer acceptance tests are a separate prerequisite for production.
Acknowledgements and webhooks
FiKS → ATK accepted → print or email → closed. Agent acknowledgements are accepted only in SIMULATION here.
Integration agent
A separate key from the ERP key, used to report receipt statuses. Only its hash is stored.
This deactivates the previous agent key.
Webhook to ERP
Select a merchant.
No active configuration.
Webhook deliveries
HMAC-SHA256 signature · delayed retries · deduplicate using the event ID.
For retries without app traffic, the agent must periodically call the dispatcher endpoint. Configuring a new URL cancels previous pending deliveries.
Send ERP JSON for testing
Active profile only. Send monetary amounts as strings.
Choose products
Open a company and add products to the catalogue.
Products 0
Active company catalogue · prices include VAT.
| CODE | NAME | CATEGORY | PRICE | VAT |
|---|
SIMULATION · Operational report, not an X/Z tax report. Dates use Kosovo time.
Daily sales
Gross amount · EURPayment method
Receipt status
VAT breakdown
Top products
Sales by branch
Sales by company
Change workflow
Changes the company's workspace. Receipts, products and API keys are kept.
Company profile
Company details
POS branch and operator
Email receipts
Checking services…
Manual email does not replace printing for billing and direct sales.
Automatic printing
View print queue
Try sample data
These actions create test data in the active company.
ATK integration
Register each POS, connect its local agent and review official ATK test responses.
1. ATK registration
Save a draft now. Enter only the identifiers assigned by ATK when they are available. Each POS needs its own registration and local key.
2. Local POS agent and certificate
The private key is created and kept on the originating POS. FiKS stores only certificate metadata and test evidence. Never upload the private key here.
.venv/bin/python tools/atk_agent.py enroll --config fiks-atk.json --state-dir /secure/fiks-pos .venv/bin/python tools/atk_agent.py check --config fiks-atk.json --state-dir /secure/fiks-pos .venv/bin/python tools/atk_agent.py run-once --config fiks-atk.json --state-dir /secure/fiks-pos
Set the EDI fiscalization number and agent key locally as environment variables. The setup guide lists the exact steps and requirements.
3. ATK test submissions
Only explicitly queued test payloads are sent. Existing demo receipts are never submitted automatically. The local agent must be running.
Prepare a test coupon
| Reference | Coupon ID | Status | ATK ID | Updated | Evidence |
|---|
OUTCOME_UNKNOWN requires reconciliation with ATK. FiKS preserves the signed request and does not automatically resend after a timeout or interrupted submission.
