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_SECURITY_ELEMENT_UNAVAILABLE or PFR_SUBMISSION_CANCELLED_BEFORE_SEND). Wait a few seconds and send the same request with the same key: the same operation is sent again, and the attempt that issues the receipt answers 201 with the same id. The same goes for a 503 without a document (for example CURRENT_TAX_CONFIGURATION_UNAVAILABLE), where nothing was even reserved. 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

All seven payment types are available on every premise; a premise cannot restrict the choice. One receipt may carry several payments, and their sum must equal the total amount.

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 additionally returns the buyer's name and address from the NBS register in buyerDetails and uses them to prefill the operator's screen. The receipt itself prints only ИД купца and the buyer's optional field; the register data is not printed.

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.