Pređi na sadržaj
API dokumentacija

Overview

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

  1. Get an API key (bound to a single shop) from your Fiscomm account.
  2. Send Authorization: Bearer <API_KEY>. You never send a shopId — the server resolves shop, company and certificate from the key.
  3. Build against a demo account (test certificate) or use invoiceType=training for non-fiscal receipts. Issue real receipts with invoiceType=normal on 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).

LLM agent guide (llms.txt)

Information

  • OpenAPI version: 3.0.0

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