Pređi na sadržaj
API dokumentacija

List archived receipts

GET
/archive/receipts
Code sample: curl
curl -X GET https://api.fiscomm.rs/archive/receipts \
-H "Authorization: Bearer $FISCOMM_API_KEY"

Returns a paginated list of issued fiscal receipts for the authenticated shop or company. Supports filtering by date range, invoice number, invoice type, transaction type, payment type, cashier, and custom meta fields. When using API key authentication, the shop is resolved automatically from the key — no shopId is required. When using Bearer token with company-level access, pass shopId in the query to scope results to a specific shop; omit it for a company-wide list.

page
number

Example

1

Page

limit
number

Example

10

Limit

sortBy
string

Example

createdAt

Sort by field

sortOrder
string

Example

ASC

Sort order

startDate
string format: date-time
endDate
string format: date-time
invoiceNumber
string
buyerId
string
shopId
number

Filter by shop ID. For API key authentication this is resolved automatically from the key — only pass this when using Bearer token with company-level access to scope results to a specific shop.

invoiceType
string
Allowed values: normal training advance proforma copy
orderNumber
string
orderNumbers
Array<string>

Example

[
"MP-1001",
"MP-1002"
]

Filter by multiple exact order numbers.

orderNumberExact
boolean

When true, orderNumber is matched exactly (=) instead of partially (ILIKE).

transactionType
string
Allowed values: sale refund finalize
paymentType

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
cashier
string
userId
number
metaFields

Filter by meta field key-value pairs (JSONB containment, exact match)

object
metaFieldsSearch

Filter by meta field key-value pairs (partial ILIKE match per key)

object
sendToEmail
string

Example

john@example.com

Filter by email address the receipt was sent to (settings.sendToEmail, partial match)

include
Array<string>

Example

[
"company",
"shop"
]

Relations to include (e.g., company, shop, items, payments). Can be passed as comma-separated string or array.

Media typeapplication/json
object
page
required
number
limit
required
number
total
required
number
totalPages
required
number
isTotalCapped
required
boolean
data
required

List of receipts, each receipt is an object of type ReceiptDto

Array<object>
object
id
required
number
invoiceNumber
required
string
invoiceCounter
required
string
invoiceCounterExtension
required
string
buyerId
required
string
orderNumber
required
string
referentDocumentNumber
required
string
referentDocumentDt
required
string format: date-time
address
required
string
buyerCostCenterId
required
string
businessName
required
string
locationName
required
string
sdcDateTime
required
string format: date-time
dateTimeOfIssue
required
string format: date-time
qrCodeFileUrl
required
string
invoicePdfUrl
required
string
storagePath
required
string
filename
required
string
cashier
required
string
items
required
Array<object>
object
name
required
string
gtin
string
quantity
required
number
unitPrice
required
number
totalAmount
required
number
labels
required
Array<string>
metaFields
required
object
payments
required
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
amount
required
number
advanceAmount

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

number
taxItems
required
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
additional
required
object
encryptedInternalData
required
string
journal
required
string
signedBy
required
string
mrc
required
string
tin
required
string
requestedBy
required
string
taxGroupRevision
required
string
signature
required
string
messages
required
string
verificationUrl
required
string
invoiceType
required
string
transactionType
required
string
companyId
required
string
shopId
required
string
totalAmount
required
number
settings
required
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
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
pdfGeneratedAt
required
string format: date-time
advanceItems
required
Array<object>
object
name
required
string
gtin
string
quantity
required
number
unitPrice
required
number
totalAmount
required
number
labels
required
Array<string>
company
required
object
shop
required
object
apiKey
required
object
user
required
object
chain
required
Array<object>
object

Example

{
"data": [
{
"items": [
{
"name": "Producto 1",
"gtin": "1234567890",
"quantity": 1,
"unitPrice": 100,
"totalAmount": 100,
"labels": [
"F"
]
}
],
"metaFields": {
"customer_name": "John Doe",
"order_id": "12345"
},
"payments": [
{
"type": "cash",
"amount": 100,
"advanceAmount": 100
}
],
"settings": {
"skipOrderNumberValidation": false,
"skipInvoiceNumberValidation": false,
"skipAmountValidation": false,
"skipAdvanceChainDerivation": false,
"sendToEmail": "customer@example.com",
"orderNumberUnderReceipt": false,
"textHeader": "",
"textFooter": "",
"skipBuyerIdValidation": false,
"isFinal": false,
"returnIfOrderNumberExists": false
},
"advanceItems": [
{
"name": "Producto 1",
"gtin": "1234567890",
"quantity": 1,
"unitPrice": 100,
"totalAmount": 100,
"labels": [
"F"
]
}
]
}
]
}

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"
}

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"
}