Pređi na sadržaj
API dokumentacija

Create fiscal receipts in bulk

POST
/receipt/{invoiceType}/{transactionType}/bulk
Code sample: curl
curl -X POST https://api.fiscomm.rs/receipt/normal/sale/bulk \
-H "Authorization: Bearer $FISCOMM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"receipts": [
{ "orderNumber": "BULK-1", "items": [{ "name": "Item", "quantity": 1, "unitPrice": 6000, "totalAmount": 6000, "labels": ["A"] }], "payments": [{ "type": "cash", "amount": 6000 }], "metaFields": {} }
]
}'

Submits multiple fiscal receipts in a single request. Only one bulk request is processed at a time per shop — concurrent requests are rejected with 429. Body wraps the array: { receipts: [ … ] } (a bare array is rejected); max 30. Response: { receipts, failedReceipts, totalProcessed, successful, failed } (no top-level correlationId). Ideal for batch integrations or end-of-day processing. Requires shop-level access via Bearer token or API key.

invoiceType
required
string
Allowed values: normal training advance proforma copy
transactionType
required
string
Allowed values: sale refund finalize
Media typeapplication/json
object
receipts
required

Array of receipts to create in bulk (max 30)

Array<object>
object
orderNumber
required

Order number (REQUIRED, cannot be empty). Unique identifier for the transaction within your system. Maps to your internal POS transaction IDs.

string

Example

1234567890
buyerId
required

Buyer ID

string

Example

10:1234567890
referentDocumentNumber

Referent document number

string
nullable

Example

AAAAA-BBBBB-123
referentDocumentDt

Referent document date

string format: date-time
nullable

Example

2026-11-18T17:30:29.633Z
buyerCostCenterId

Buyer cost center ID

string
nullable

Example

10:123456789
cashier

Cashier name

string
nullable

Example

cashier
dateTimeOfIssue

Date time of issue

string format: date-time
nullable

Example

2026-11-18T17:30:29.633Z
items
required
Array<object>
object
name
required
string

Example

Producto 1
gtin
string

Example

1234567890
quantity
required
number

Example

1
unitPrice
required
number

Example

100
totalAmount
required
number

Example

100
labels
required
Array<string>

Example

[
"F"
]
metaFields

Optional. Your own key/values echoed onto the archived receipt (not required).

object

Example

{
"customer_name": "John Doe",
"order_id": "12345"
}
payments
Array<object>
object
type
required

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

cash
amount
required
number

Example

100
advanceAmount

Amount paid in advance (optional, mainly for finalize advance flows)

number

Example

100
settings

Settings for the receipt

object
skipOrderNumberValidation

Skip order number validation. Useful for systems that cannot enforce order number uniqueness. Default: false.

boolean
skipInvoiceNumberValidation

Skip invoice number validation. Useful for special scenarios where fiscal system needs manual invoice number handling. Default: false.

boolean
skipAmountValidation

Skip items totalAmount and payment amount validation. Allows for rounding differences or manual calculation handling. Default: false.

boolean
skipAdvanceChainDerivation

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.

boolean
sendToEmail

Email address to send the receipt PDF. If provided, receipt will be automatically emailed to this address.

string

Example

customer@example.com
orderNumberUnderReceipt

Display 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.

boolean
textHeader

Optional per-receipt header text rendered in PDF. Overrides shop default header for this receipt.

string
""
textFooter

Optional per-receipt footer text rendered in PDF. Overrides shop default footer for this receipt.

string
""
skipBuyerIdValidation

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.

boolean
isFinal

Marks a NORMAL/SALE receipt as finalization of an advance-payment chain. When true, referent document must be an ADVANCE/REFUND receipt.

boolean
returnIfOrderNumberExists

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.

boolean
Media typeapplication/json
object
receipts
required
Array<object>
object
invoiceNumber
required

Fiscal receipt number (PFR), unique per shop, e.g. “AZM5ZCCR-Dt1Ov2o0-507302”.

string
invoiceCounter
required

Receipt counter, e.g. “468497/507302ОП”.

string
invoiceCounterExtension
required

Counter suffix indicating the receipt kind (e.g. “ОП” sale, “ОР” refund).

string
businessName
required

Seller / business name as registered.

string
locationName
required

Point-of-sale (shop) name.

string
sdcDateTime
required

Fiscalization timestamp from PURS (ISO 8601 UTC, “Z”).

string
invoicePdfUrl
required

URL of the receipt PDF (hosted by Fiscomm).

string
verificationUrl
required

Tax Administration (PURS) verification URL for the customer.

string
totalAmount
required

Receipt total amount.

number
invoiceType
required

Invoice type (e.g. normal, training, advance, proforma, copy).

string
transactionType
required

Transaction type (sale or refund).

string
taxItems
required

Tax breakdown, one entry per tax label.

Array<object>
object
categoryType
required

PURS tax category type code (0 standard, 1/2 special).

number
label
required

Tax label as printed on the receipt (e.g. “Ђ”, “Е”, “F”). Pull valid labels from GET /receipt/tax-rates.

string
amount
required

Tax amount for this label.

number
rate
required

Tax rate in percent (e.g. 20 for Ђ, 10 for Е).

number
categoryName
required

Tax category name (e.g. “VAT”, “ECAL”).

string
orderNumber
required

Your order number, echoed back from the request.

string
metaFields

Custom key/value pairs echoed back exactly as sent on the request.

object
key
additional properties
string
emailSentTo

E-mail address the receipt was queued to (settings.sendToEmail). Absent when no e-mail was sent.

string
journal
required

Plain-text receipt journal (for printing). In training mode it contains the “ОВО НИЈЕ ФИСКАЛНИ РАЧУН” marker.

string
additional
required

Additional PURS data (signature, MRC, TIN, journal, …).

object
mrc
required

SDC MRC identifier (fiscal device code), e.g. “99-3414-Dt1Ov2o0”.

string
signedBy
required

Security element identifier that signed the receipt.

string
signature
required

Digital signature returned by the Tax Administration (PURS).

string
tin
required

Taxpayer TIN, e.g. “RS112410326”.

string
requestedBy
required

Security element identifier that requested fiscalization.

string
taxGroupRevision
required

Revision of the tax-rate group applied to this receipt.

number
messages
required

PURS status message, e.g. “Success”.

string
encryptedInternalData
required

Encrypted internal data block from the SDC (opaque).

string
journal
required

Plain-text receipt journal (for printing). In training mode it contains the “ОВО НИЈЕ ФИСКАЛНИ РАЧУН” marker.

string
failedReceipts
required
Array<string>
totalProcessed
required
number
successful
required
number
failed
required
number

Example generated

{
"receipts": [
{
"invoiceNumber": "example",
"invoiceCounter": "example",
"invoiceCounterExtension": "example",
"businessName": "example",
"locationName": "example",
"sdcDateTime": "example",
"invoicePdfUrl": "example",
"verificationUrl": "example",
"totalAmount": 1,
"invoiceType": "example",
"transactionType": "example",
"taxItems": [
{}
],
"orderNumber": "example",
"metaFields": {
"additionalProperty": "example"
},
"emailSentTo": "example",
"journal": "example",
"additional": {
"mrc": "example",
"signedBy": "example",
"signature": "example",
"tin": "example",
"requestedBy": "example",
"taxGroupRevision": 1,
"messages": "example",
"encryptedInternalData": "example",
"journal": "example"
}
}
],
"failedReceipts": [
"example"
],
"totalProcessed": 1,
"successful": 1,
"failed": 1
}

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).

Media typeapplication/json
object
status
required

HTTP status code.

number
code
required

Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).

string
message
required

Technical message describing the error.

string
userMessage

Human-friendly message safe to surface to an end user.

string
details

Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].

object
key
additional properties
any
path

Request path.

string
correlationId

Correlation id of the request, for support/log lookups.

string

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.

Media typeapplication/json
object
status
required

HTTP status code.

number
code
required

Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).

string
message
required

Technical message describing the error.

string
userMessage

Human-friendly message safe to surface to an end user.

string
details

Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].

object
key
additional properties
any
path

Request path.

string
correlationId

Correlation id of the request, for support/log lookups.

string

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.

Media typeapplication/json
object
status
required

HTTP status code.

number
code
required

Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).

string
message
required

Technical message describing the error.

string
userMessage

Human-friendly message safe to surface to an end user.

string
details

Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].

object
key
additional properties
any
path

Request path.

string
correlationId

Correlation id of the request, for support/log lookups.

string

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.

Media typeapplication/json
object
status
required

HTTP status code.

number
code
required

Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).

string
message
required

Technical message describing the error.

string
userMessage

Human-friendly message safe to surface to an end user.

string
details

Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].

object
key
additional properties
any
path

Request path.

string
correlationId

Correlation id of the request, for support/log lookups.

string

Example

{
"status": 404,
"code": "NOT_FOUND",
"message": "Resource not found",
"correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"
}

Another bulk request for this shop is already in progress — only one runs at a time. Retry after it finishes.

Media typeapplication/json
object
status
required

HTTP status code.

number
code
required

Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).

string
message
required

Technical message describing the error.

string
userMessage

Human-friendly message safe to surface to an end user.

string
details

Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].

object
key
additional properties
any
path

Request path.

string
correlationId

Correlation id of the request, for support/log lookups.

string

Example

{
"status": 429,
"message": "A bulk request for this shop is already in progress. Retry after it finishes.",
"correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"
}

Internal error. Safe to retry later.

Media typeapplication/json
object
status
required

HTTP status code.

number
code
required

Machine-readable Fiscomm error code. Examples: ERR_00202 (validation), ERR_00701 (item total does not match payment total), ERR_00002 (internal error).

string
message
required

Technical message describing the error.

string
userMessage

Human-friendly message safe to surface to an end user.

string
details

Additional structured detail. For validation errors this includes validationErrors: [{ field, message }].

object
key
additional properties
any
path

Request path.

string
correlationId

Correlation id of the request, for support/log lookups.

string

Example

{
"status": 500,
"code": "ERR_00002",
"userMessage": "Server error. Please try again later.",
"correlationId": "5cbf3d9f-bd38-4375-89ab-34ed6be68d97"
}