Fiscomm Support
Overview
Fiscomm Public API 2.0
Odeljak „Fiscomm Public API 2.0“Fiscomm REST API for fiscalization in Serbia (Tax Administration, PURS/SUF). Send order data → get a fiscal receipt (PFR number, QR, PDF, verification link). No device, no manual entry.
Quick start
- Get an API key (bound to a single shop) from your Fiscomm account.
- Send
Authorization: Bearer <API_KEY>. You never send ashopId— the server resolves shop, company and certificate from the key. - Build against a demo account (test certificate) or use
invoiceType=trainingfor non-fiscal receipts. Issue real receipts withinvoiceType=normalon a production account.
Issue your first (training) receipt:
curl -X POST https://api.fiscomm.rs/receipt/training/sale \
-H "Authorization: Bearer $FISCOMM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"orderNumber": "ORDER-1001",
"items": [{ "name": "Item", "quantity": 1, "unitPrice": 6000, "totalAmount": 6000, "labels": ["Ђ"] }],
"payments": [{ "type": "cash", "amount": 6000 }],
"metaFields": {}
}'
// npm install github:Fiscomm/fiscomm-sdk-ts
import { FiscommClient } from 'fiscomm-sdk';
const client = new FiscommClient({ apiKey: process.env.FISCOMM_API_KEY });
const { receipt } = await client.receipts.sale('training', {
orderNumber: 'ORDER-1001',
items: [{ name: 'Item', quantity: 1, unitPrice: 6000, totalAmount: 6000, labels: ['Ђ'] }],
payments: [{ type: 'cash', amount: 6000 }],
metaFields: {},
});
console.log(receipt.invoiceNumber, receipt.verificationUrl);
// composer require fiscomm/sdk:dev-main
use Fiscomm\Sdk\FiscommClient;
$client = new FiscommClient(getenv('FISCOMM_API_KEY'));
$res = $client->receipts()->sale('training', [
'orderNumber' => 'ORDER-1001',
'items' => [['name' => 'Item', 'quantity' => 1, 'unitPrice' => 6000, 'totalAmount' => 6000, 'labels' => ['Ђ']]],
'payments' => [['type' => 'cash', 'amount' => 6000]],
'metaFields' => (object) [],
]);
echo $res->receipt->invoiceNumber;
Environments — the account decides, not the host
The host and API are identical for testing and production: https://api.fiscomm.rs. What differs is the account you authenticate as, via the certificate (security element) on its shop:
- Demo account — test certificate → routed to the Tax Administration sandbox, receipts are NOT legal documents, and a test set of tax labels is returned.
- Production account — your real certificate (from the ePorezi portal) → legal fiscal documents and the real tax labels. The certificate alone determines the Tax Administration environment, whether receipts are real, and which tax labels apply. Request shape and host never change between environments.
Training receipts
Separately from the account, invoiceType=training issues a non-fiscal training receipt (marked “ОВО НИЈЕ ФИСКАЛНИ РАЧУН”) on any account. Only the path changes: POST /receipt/training/sale for a test receipt, POST /receipt/normal/sale for a real one.
Tax labels — do not hardcode
Pull them from GET /receipt/tax-rates. They depend on the account’s tax group and differ between a demo account and a production account. Production: Ђ=20%, Е=10%, Г=0%, А=0%. Use currentTaxRates for new receipts.
Idempotency (important for retries)
orderNumber is unique per shop + company + invoiceType + transactionType (~14 days). On a lost response, resend the SAME request with settings.returnIfOrderNumberExists=true → the existing receipt is returned. Confirm what went through with POST /archive/receipts/fiscalization-lookup.
What the response returns
POST .../sale|refund → { correlationId, receipt }. correlationId is per request (absent in bulk). The QR image (qrCodeFileUrl) is NOT in this response — get it from GET /archive/receipts/{invoiceNumber}. Any metaFields you send is echoed back on receipt.metaFields exactly as sent.
Errors
Every error is { status, code, message, userMessage?, details?, correlationId }. code is stable (ERR_*). Always include correlationId when contacting support.
| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 400 | ERR_00202 | Input validation (details.validationErrors[]) |
Fix the fields and retry |
| 400 | ERR_00603 | orderNumber already used |
Use settings.returnIfOrderNumberExists to fetch the existing receipt |
| 400 | ERR_00701 | Items total ≠ payments total | Align items/payments (or settings.skipAmountValidation) |
| 400 | ERR_00201 | Referenced document missing | Provide referentDocumentNumber (e.g. on advance/finalize) |
| 409 | ERR_00302 | Advance-item tax label rule | On a demo account use label A, E or F for advance items |
| 400 | ERR_01010 | Rejected by the Tax Administration (details.pursRawResponse) |
Read the reason in pursRawResponse (e.g. invalid gtin) |
| 401 | ERR_00101 | Missing/invalid key | Check the Bearer token |
| 403 | — | Valid key without access to the shop | Key is not for that shop |
| 404 | — | Not found | Check the path / invoice number |
| 429 | — | Concurrent bulk for the same shop | Serialize bulk calls |
| 500 | ERR_00002 | Internal error | Retry later; report the correlationId |
Advance chain (two calls)
advance/finalize is not self-contained. First POST /receipt/advance/sale (items + payments; payments[].advanceAmount is added on top of amount), then POST /receipt/advance/finalize with referentDocumentNumber = the advance’s invoiceNumber. Finalize returns { correlationId, refundReceipt, finalReceipt }. On a demo account, advance items must use tax label A, E or F.
Bulk / async / webhook
No general rate limit. Bulk (/receipt/{type}/{tx}/bulk, up to 30, one per shop at a time → 429) takes a wrapped body { "receipts": [ … ] } and returns { receipts, failedReceipts, totalProcessed, successful, failed } (no top-level correlationId). The async flow delivers the raw fiscalReceipt to a webhook — but the async endpoints may be unavailable and can return 500 on some accounts, so prefer the synchronous endpoints unless async is confirmed enabled. For LLM agents: /llms.txt (index) and /llms-full.txt (full guide).
Authentication
Odeljak „Authentication“api-key
Odeljak „api-key“Pass your API key here. API keys use the same Bearer token format as user JWTs:
Authorization: Bearer <your-api-key>
Security scheme type: http
Bearer format: JWT