Conventions

Identifiers in every request

Idempotency-Key

Every fiscal mutation (POST to /v1/fiscal-documents, /copies, /v1/refund-workflows, /v1/advance-cases*, /v1/proforma-training-workflows, /v1/receipt-deliveries) requires an Idempotency-Key header of 16 to 200 characters. The key is unique within your organization and is bound to the canonical content of the request:

• same key, same content: the API returns the original operation (200 instead of 201) and never issues a second receipt, however many times you repeat;
• same key, different content: 409 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST with the original's operationId;
• new key: a new operation, and potentially a new receipt.

{
  "code": "IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST",
  "operationId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761"
}

Document statuses

Every fiscal request becomes a durable operation with a status. The status is the truth; the HTTP code is only its summary.

Reading the response

1. 01

   201 and fiscalized: true

   The receipt exists. Store id, pfr.invoiceNumber, pfr.sdcTime, pfr.verificationUrl and, if needed, the PDF. The order is fiscalized.

2. 02

   503 and retryable: true

   Nothing was sent (NOT_FISCALIZED, for example PFR_SUBMISSION_FAULT or CURRENT_TAX_CONFIGURATION_UNAVAILABLE). Wait a few seconds and send the same request with the same key. Cap the number of attempts, then hand over to an operator.

3. 03

   503 and status OUTCOME_UNKNOWN

   Do not send a new request for the same sale. Remember the id and poll GET /v1/operations/{id} (every 30 seconds, then less often). BokaPOS resolves the outcome in the background purely by reading from the V-PFR; once found, the status becomes FISCALIZED. If it stays unknown, an operator decides in the portal.

4. 04

   422

   The request breaks a rule (ours or the V-PFR's). Nothing was issued. Fix the request and send it with a new key, because the old key is bound to the wrong content.

5. 05

   403

   Environment or licence. Nothing was issued. Sandbox never gets a 403 for licensing.

6. 06

   409

   A conflict: the key reused with different content, or an action not allowed in the current workflow state (advance, proforma). Read the state and continue from it.

Amounts, quantities and rounding

• All prices and amounts are gross, in dinars, with at most two decimals (8990.00). More decimals are rejected by the V-PFR (code 2804).
• unitPrice is the final unit price after discount. You do not send tax: BokaPOS computes it from the tax label by the official rules and the V-PFR signs it.
• unitPriceBeforeDiscount is an optional pre-discount price, displayed only outside the fiscal part of the receipt; it must be greater than unitPrice.
• quantity has up to three decimals (1.5), minimum 0.001.
• The sum of quantity × unitPrice over the items, rounded to two decimals, must equal the sum of payments. Otherwise 422 with an error on totals.
• Several payment types on one receipt are allowed (payments is a list).

Time

• All times are ISO 8601. createdAt and updatedAt are UTC (Z). pfr.sdcTime is the V-PFR signing time with the offset the V-PFR sent (+02:00 or +01:00); it is the official receipt time.
• The pfrFrom/pfrTo filters in the journal and reports refer to sdcTime; createdFrom/createdTo to the moment BokaPOS received the request. The lower bound is inclusive, the upper exclusive.
• You do not send the receipt time. The only exception is an advance payment by wire transfer received earlier (paymentOccurredAt), per the official rule; see Advance.

Invoice and transaction types

POST /v1/fiscal-documents accepts only NORMAL SALE; everything else has its own workflow that BokaPOS runs on the server, with the correct references and order.

References between documents

A refund, a copy and the final receipt after an advance must reference the source document (PFR number and time). When the source is a document BokaPOS issued, you send only its fiscalDocumentId ({ "source": "BOKA", "fiscalDocumentId": "..." }) and BokaPOS fills in the exact PFR facts; it must be on the same taxpayer and premise. A reference to another ESIR's document (source: EXTERNAL) requires the exact PFR number, time and type and is supported only for a copy through POST /v1/fiscal-documents; refunds and advances do not accept external documents.

Payment types

A premise may run in the restricted payment mode (only OTHER, CASH, WIRE_TRANSFER, VOUCHER); other types then return 422 PAYMENT_TYPE_NOT_ALLOWED_ON_PREMISE. The mode is the premise's paymentMode field.

Buyer identification

buyer.id is the official prefix:value. It is mandatory on every refund, on sales to companies that need the PIB on the receipt, and in the other cases the regulations list. For a domestic company (10:, 12: or 14: with a valid PIB) BokaPOS automatically prints the buyer's name and address from the NBS register under the identification, on every representation; it also returns them in buyerDetails.

buyer.optionalField is the buyer's optional field, also prefix:value: 20: SNPDV, 21: LNPDV, 30: to 33: PPO-PDV forms, 50: corporate card number (payment is VOUCHER), 60: corporate-card refund period ddMMyyyy_ddMMyyyy. The same prefix means different things in the two fields.

Pagination

Journal lists use a stable keyset: the response carries nextCursor, which you send as cursor for the next page; null is the end. pageSize goes up to 200 (default 50). The product list uses the same pattern with a UUID cursor. Ordering is by createdAt then id, descending, so a new page never skips or repeats an entry.

Error shapes

The full catalogue of codes with what to do is on the Errors page.