Create a fiscal sale receipt
curl -X POST https://api.fiscomm.rs/receipt/normal/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": ["A"] }], "payments": [{ "type": "cash", "amount": 6000 }], "metaFields": {} }'// npm install github:Fiscomm/fiscomm-sdk-tsimport { FiscommClient } from 'fiscomm-sdk';
const client = new FiscommClient({ apiKey: process.env.FISCOMM_API_KEY });const { receipt } = await client.receipts.sale('normal', { orderNumber: 'ORDER-1001', items: [{ name: 'Item', quantity: 1, unitPrice: 6000, totalAmount: 6000, labels: ['A'] }], payments: [{ type: 'cash', amount: 6000 }], metaFields: {},});console.log(receipt.invoiceNumber, receipt.verificationUrl);// composer require fiscomm/sdk:dev-mainuse Fiscomm\Sdk\FiscommClient;
$client = new FiscommClient(getenv('FISCOMM_API_KEY'));$res = $client->receipts()->sale('normal', [ 'orderNumber' => 'ORDER-1001', 'items' => [['name' => 'Item', 'quantity' => 1, 'unitPrice' => 6000, 'totalAmount' => 6000, 'labels' => ['A']]], 'payments' => [['type' => 'cash', 'amount' => 6000]], 'metaFields' => (object) [],]);echo $res->receipt->invoiceNumber;Issues a fiscal sale receipt for the given invoice type. Supported invoice types: NORMAL, TRAINING, PROFORMA, COPY, ADVANCE. TRAINING issues a non-fiscal test receipt (same flow, not registered with Poreska uprava) — use it to develop and test. referentDocumentNumber is optional for sale receipts. buyerId is optional for sale receipts (commonly used in B2B scenarios). To skip buyerId validation, set settings.skipBuyerIdValidation to true. Requires shop-level access via Bearer token or API key.
Returns { correlationId, receipt }. The QR image is NOT in this response — fetch it from GET /archive/receipts/{invoiceNumber}. For safe retries on a lost response, set settings.returnIfOrderNumberExists=true (returns the existing receipt instead of a duplicate). Common errors: ERR_00202 (validation), ERR_00701 (items vs payments mismatch), ERR_01010 (Poreska uprava rejected) — see the introduction for the full error table.
Authorizations
Odeljak „Authorizations“Parameters
Odeljak „Parameters“Path Parameters
Odeljak „Path Parameters“Request Bodyrequired
Odeljak „Request Bodyrequired“object
Order number (REQUIRED, cannot be empty). Unique identifier for the transaction within your system. Maps to your internal POS transaction IDs.
Example
1234567890Buyer ID (OPTIONAL for sale receipts; Required for refunds unless skipBuyerIdValidation is true). Format: “type:identifier” (e.g., “10:123456789”)
Example
10:1234567890Referent document number (optional for sale receipts; required for refunds)
Example
AAAAA-BBBBB-123Referent document date
Example
2026-11-18T17:30:29.633ZBuyer cost center ID
Example
10:123456789Cashier name
Example
cashierDate time of issue
Example
2026-11-18T17:30:29.633Zobject
Example
Producto 1Example
1234567890Example
1Example
100Example
100Example
[ "F"]Optional. Your own key/values echoed onto the archived receipt (not required).
object
Example
{ "customer_name": "John Doe", "order_id": "12345"}object
Payment type. Accepts both original enum values (Cash, WireTransfer, Card, Check, Voucher, MobileMoney, Virman, Mobile, Factoring, Account, Other) and lowercase alternatives (cash, card, wire_transfer, wiretransfer, check, voucher, mobile_money, mobilemoney, virman, mobile, factoring, account, other)
object
Example
cashExample
100Amount paid in advance (optional, mainly for finalize advance flows)
Example
100Settings for the receipt
object
Skip order number validation. Useful for systems that cannot enforce order number uniqueness. Default: false.
Skip invoice number validation. Useful for special scenarios where fiscal system needs manual invoice number handling. Default: false.
Skip items totalAmount and payment amount validation. Allows for rounding differences or manual calculation handling. Default: false.
Advance finalize only: issue the Avans-Refundacija and the final receipt EXACTLY as provided in the payload, without deriving or adjusting amounts from the advance chain. This also bypasses the chain snapshot (“No advance items … in the chain” guard), so finalization can proceed on historically over-refunded advance chains (Σrefund ≥ Σsale). The caller is fully responsible for the issued amounts. Default: false.
Email address to send the receipt PDF. If provided, receipt will be automatically emailed to this address.
Example
customer@example.comDisplay order number as a barcode block under the receipt. Overrides the shop-level setting for this receipt only. If not provided, falls back to shop receiptSettings.
Optional per-receipt header text rendered in PDF. Overrides shop default header for this receipt.
Optional per-receipt footer text rendered in PDF. Overrides shop default footer for this receipt.
Skip buyer ID validation for refunds. Use this flag only if you cannot provide buyerId for refund transactions (rarely recommended, may violate local regulations). Default: false.
Marks a NORMAL/SALE receipt as finalization of an advance-payment chain. When true, referent document must be an ADVANCE/REFUND receipt.
When true and a receipt with the same orderNumber already exists, the existing receipt is returned (idempotent) instead of throwing ReceiptOrderExistsException. Useful for integrations that retry after a lost response. Default: false.
Responses
Odeljak „Responses“object
object
object
object
object
Payment type. Accepts both original enum values (Cash, WireTransfer, Card, Check, Voucher, MobileMoney, Virman, Mobile, Factoring, Account, Other) and lowercase alternatives (cash, card, wire_transfer, wiretransfer, check, voucher, mobile_money, mobilemoney, virman, mobile, factoring, account, other)
object
Amount paid in advance (optional, mainly for finalize advance flows)
object
PURS tax category type code (0 standard, 1/2 special).
Tax label as printed on the receipt (e.g. “Ђ”, “Е”, “F”). Pull valid labels from GET /receipt/tax-rates.
Tax amount for this label.
Tax rate in percent (e.g. 20 for Ђ, 10 for Е).
Tax category name (e.g. “VAT”, “ECAL”).
object
Example
{ "correlationId": "54e041b7-1d28-4e09-a604-90cbdff587bf", "receipt": { "invoiceNumber": "AZM5ZCCR-Dt1Ov2o0-507308", "invoiceCounter": "468497/507302ОП", "invoiceCounterExtension": "ОП", "businessName": "PRIMER DOO", "locationName": "PRIMER DOO", "sdcDateTime": "2026-09-15T16:48:18.972Z", "invoicePdfUrl": "https://api.fiscomm.rs/receipt/e4f2…", "verificationUrl": "https://suf.purs.gov.rs/v/?vl=A0FaTTVaQ0NS…", "totalAmount": 6000, "invoiceType": "normal", "transactionType": "sale", "taxItems": [ { "categoryType": 0, "label": "A", "amount": 1000, "rate": 20, "categoryName": "VAT" } ], "additional": { "mrc": "99-3414-Dt1Ov2o0", "tin": "RS112410326", "signature": "…", "messages": "Success" }, "orderNumber": "ORDER-1001", "metaFields": { "source": "webshop", "orderId": "48213" }, "journal": "======== ФИСКАЛНИ РАЧУН ========\r\n…" }}Validation or business-rule error. Branch on code: ERR_00202 (input validation), ERR_00701 (items total ≠ payments total), ERR_01010 (rejected by the Tax Administration).
object
HTTP status code.
Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).
Technical message describing the error.
Human-friendly message safe to surface to an end user.
Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].
object
Request path.
Correlation id of the request, for support/log lookups.
Example
{ "status": 400, "code": "ERR_00202", "message": "Validation failed", "details": { "validationErrors": [ { "field": "orderNumber", "message": "should not be empty" } ] }, "path": "/receipt/normal/sale", "correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"}Missing or invalid API key.
object
HTTP status code.
Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).
Technical message describing the error.
Human-friendly message safe to surface to an end user.
Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].
object
Request path.
Correlation id of the request, for support/log lookups.
Example
{ "status": 401, "code": "ERR_00101", "message": "Failed to validate API token", "correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"}The API key is valid but has no access to this shop or resource.
object
HTTP status code.
Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).
Technical message describing the error.
Human-friendly message safe to surface to an end user.
Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].
object
Request path.
Correlation id of the request, for support/log lookups.
Example
{ "status": 403, "message": "Forbidden — API key has no access to this shop", "correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"}The requested resource does not exist.
object
HTTP status code.
Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).
Technical message describing the error.
Human-friendly message safe to surface to an end user.
Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].
object
Request path.
Correlation id of the request, for support/log lookups.
Example
{ "status": 404, "code": "NOT_FOUND", "message": "Resource not found", "correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"}Business-rule conflict. ERR_00302 = advance-item tax-label rule (on a demo account, advance items must use label A, E or F). Note this is HTTP 409, not 400.
object
HTTP status code.
Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).
Technical message describing the error.
Human-friendly message safe to surface to an end user.
Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].
object
Request path.
Correlation id of the request, for support/log lookups.
Example
{ "status": 409, "code": "ERR_00302", "message": "In sandbox mode, use A, E or F labels for advance items", "correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"}Internal error. Safe to retry later.
object
HTTP status code.
Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).
Technical message describing the error.
Human-friendly message safe to surface to an end user.
Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].
object
Request path.
Correlation id of the request, for support/log lookups.
Example
{ "status": 500, "code": "ERR_00002", "userMessage": "Server error. Please try again later.", "correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"}