Evaluating a Fiscal Invoice API Provider
When comparing proposals from different fiscalization vendors, the same six terms keep showing up in email threads. This article explains each clearly.
1. Headless
Meaning: the vendor exposes only an API — no mandatory web or desktop UI for issuing invoices.
Why it matters: e-commerce expects the customer to receive an invoice within seconds of checkout. If the solution isn't headless, someone has to manually click a button in the vendor's UI — not workable online. Headless means your system calls the API directly, receives the PDF and QR code, and hands them to the customer without human intervention.
Signal words in proposals: headless, API-first, server-to-server.
2. Per-račun billing
Meaning: in addition to the monthly subscription, the vendor charges a small amount per issued invoice.
Two common models:
- Tiered — monthly subscription includes the first N invoices; above the threshold, each invoice is billed. Good fit for merchants with predictable volume.
- Flat — fixed monthly subscription, unlimited invoices. Good fit for high-volume or fast-growing merchants.
Practical note: for ≤ 500 invoices/month, tiered is usually cheaper; for planned growth, flat gives stability.
3. Sandbox and self-service registration
Sandbox is a test environment where transactions don't produce real invoices at PU. Self-service sandbox means you can register on your own and get a test API key immediately, without contacting sales or signing NDAs.
Why it matters: you get to validate the integration before any financial commitment. Try before you buy.
Red flag: if the vendor requires an NDA and manual approval for sandbox access, a few lost days means a shifted integration plan.
4. Avans support
Avans is Serbian for advance payment. When a buyer pays before delivery, strict interpretation of the law requires an Avans-Prodaja invoice at payment time and a Promet-Prodaja invoice at delivery — two invoices per order.
E-commerce scenario: the customer pays by card immediately, and the package ships within 3-5 business days. Technically that's an Avans situation.
Practice: market approaches vary; the compliant path is to support Avans. Whether the vendor has an Avans module or Avans built in is critical for compliant operation.
5. Idempotency
Meaning: if the same request is retried (due to a network timeout), the vendor recognizes the duplicate and returns the already-issued invoice instead of issuing a new one.
Why it matters: without idempotency, a retry produces a duplicate invoice for the same order → tax-reporting mismatch and potential double-charge for the customer.
How vendors implement it: the client sends a unique ID in the request (commonly orderNumber, RequestId, or Idempotency-Key); the vendor uses that ID to detect retries.
Questions to ask the vendor: exact field name, max length, and "lifetime" (how long the same ID is treated as a duplicate).
6. SLA (Service Level Agreement)
Meaning: the contractually guaranteed uptime, for example "99.9% per year".
Reference table:
| SLA | Max annual downtime | Max monthly downtime |
|---|---|---|
| 99.0% | about 3 days 16 hours | about 7 hours 12 minutes |
| 99.9% | 8 hours 45 minutes | 43 minutes |
| 99.95% | 4 hours 22 minutes | 21 minutes |
| 99.99% | 52 minutes | 4 minutes |
Why it matters: fiscalization is a real-time blocking step — while the vendor is down, every checkout stalls. 99.0% is not enough for e-commerce; the recommended minimum is 99.9%.
Detail to watch: whether the SLA covers just the vendor's API or the end-to-end path to PU. The latter is the meaningful number, but most vendors only commit to the former.
Short evaluation checklist
Technical: - Is the solution headless? - Is the sandbox available through self-service registration? - How is idempotency implemented (field and lifetime)? - Are all invoice types supported (Promet / Avans / Refundacija / Poništavanje)? - What SLA is committed (API only or end-to-end to PU)? - Is the API documentation publicly available?
Commercial: - Monthly subscription and per-račun billing rules? - Length of the trial period and whether it covers production? - Additional cost per extra point of sale? - Monthly billing option available? - Data ownership when migrating to another vendor?
About AdriaMart
This article is a by-product of the AdriaMart team's technical preparation for a planned future entry into the Serbian e-commerce market. We're currently in the pre-launch preparation phase and we're publishing what we've learned as open notes. Suggestions and corrections: [email protected].