API documentation

Advance

The customer pays before delivery, sometimes in instalments. The regulations require an Аванс Продаја for every payment, an Аванс Рефундација of the whole advance at delivery and a final Промет Продаја receipt with a reference. BokaPOS runs the entire chain as one case; you send the payments and, at the end, the delivery.

Updated: 29 August 2026 · Contract version 1.0.0

Flow

01
Open a case
POST /v1/advance-cases with the order's clientReference. The case issues no receipt; it holds the chain.
02
Fiscalize every payment
POST /v1/advance-cases/{id}/payments for every payment received. The first Аванс Продаја has no reference; every next one automatically references the previous.
03
Cancel a wrong payment (if needed)
POST /v1/advance-cases/{id}/cancellations issues an Аванс Рефундација that voids the latest advance sale in full; the case stays open.
04
Close at delivery
POST /v1/advance-cases/{id}/close with the delivered items and the top-up. BokaPOS issues the Аванс Рефундација of the whole advance, then the final Промет Продаја receipt referencing it.

Opening a case

POST /v1/advance-cases

curl -X POST "https://api.bokapos.rs/v1/advance-cases" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-5001-advance-case" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-5001"
}'

201 Created

{
  "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-5001",
  "externalAdvance": null,
  "state": "OPEN",
  "advanceSales": [],
  "cancellations": [],
  "cancelledAdvanceSaleIds": [],
  "advanceRefund": null,
  "finalSale": null,
  "failureCode": null,
  "createdAt": "2026-09-03T09:00:00.000Z",
  "updatedAt": "2026-09-03T09:00:00.000Z"
}

A case can also take over advances collected before eFiscalization (externalAdvance: total amount, label, payment type, number of the last pre-fiscal document, digits only, and its date). The first advance sale then references that document, and the closure refunds the old and new advances together.

Advance payment

The items of an advance sale are not goods but the prescribed advance literals: name 10: Аванс (Ђ) for label Ђ, 11: Аванс (Е), 12: Аванс (Г), 13: Аванс (А), exactly so, without a unit of measure, with taxLabels of the same label and unitPrice equal to the amount paid for that rate. If the order has items at two rates, the advance splits into two advance items. commercialFooter is mandatory: describe what is being paid.

POST /v1/advance-cases/{advanceCaseId}/payments

curl -X POST "https://api.bokapos.rs/v1/advance-cases/c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f/payments" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-5001-advance-1" \
  -H "Content-Type: application/json" \
  -d '{
  "cashier": {
    "id": "web-shop"
  },
  "items": [
    {
      "name": "10: Аванс (F)",
      "quantity": 1,
      "unitPrice": 3000,
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "WIRE_TRANSFER",
      "amount": 3000
    }
  ],
  "paymentOccurredAt": "2026-09-02T11:30:00+02:00",
  "commercialFooter": "Avans za porudžbinu ORDER-5001. Isporuka po uplati ostatka."
}'

201 Created

{
  "id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "idempotencyKey": "order-5001-advance-1",
  "clientReference": "ORDER-5001",
  "invoiceType": "ADVANCE",
  "transactionType": "SALE",
  "cashierId": "web-shop",
  "buyerId": null,
  "buyerDetails": null,
  "status": "FISCALIZED",
  "fiscalized": true,
  "failureCode": null,
  "retryable": false,
  "pfr": {
    "invoiceNumber": "JWX4K9PL-JWX4K9PL-1049",
    "sdcTime": "2026-09-01T10:15:32.483+02:00",
    "requestedBy": "JWX4K9PL",
    "signedBy": "JWX4K9PL",
    "transactionTypeCounter": 904,
    "totalCounter": 1049,
    "invoiceCounterExtension": "АП",
    "totalAmount": 3000,
    "totalTax": 297.2973,
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
    "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1049\nБројач рачуна:                904/1049АП\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
  },
  "receipt": {
    "textUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/official-text",
    "jsonUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/canonical-json",
    "pdfA4Url": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/pdf-a4",
    "pdf80mmUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/pdf-80mm",
    "pdf58mmUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/pdf-58mm",
    "previewImageUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/preview-png",
    "qrImageUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/qr-svg",
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
    "preferredPaperFormat": "a4"
  },
  "createdAt": "2026-09-03T09:01:00.000Z",
  "updatedAt": "2026-09-01T08:15:32.611Z"
}

In production the item name is the prescribed `10: Аванс (Ђ)` (or 11/12/13 for Е, Г, А) with the same label. The sandbox lacks those labels, so it accepts `10: Аванс (X)` for any label in the fresh configuration.

Cancelling a wrong payment

The official procedure for a wrongly issued advance is an Аванс Рефундација that repeats that whole advance receipt, references it and carries the seller's own PIB as the buyer (10:<PIB>). BokaPOS does that itself: you send the id of the latest advance sale. The chain continues from the previous payment; cancelled sales stay visible in advanceSales, and cancelledAdvanceSaleIds says which were voided.

POST /v1/advance-cases/{advanceCaseId}/cancellations

curl -X POST "https://api.bokapos.rs/v1/advance-cases/c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f/cancellations" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-5001-advance-1-cancel" \
  -H "Content-Type: application/json" \
  -d '{
  "cashier": {
    "id": "web-shop"
  },
  "advanceSaleFiscalDocumentId": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80"
}'

201 Created

{
  "id": "a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "idempotencyKey": "order-5001-advance-1-cancel",
  "clientReference": "ORDER-5001",
  "invoiceType": "ADVANCE",
  "transactionType": "REFUND",
  "cashierId": "web-shop",
  "buyerId": "10:115711881",
  "buyerDetails": null,
  "status": "FISCALIZED",
  "fiscalized": true,
  "failureCode": null,
  "retryable": false,
  "pfr": {
    "invoiceNumber": "JWX4K9PL-JWX4K9PL-1050",
    "sdcTime": "2026-09-01T10:15:32.483+02:00",
    "requestedBy": "JWX4K9PL",
    "signedBy": "JWX4K9PL",
    "transactionTypeCounter": 905,
    "totalCounter": 1050,
    "invoiceCounterExtension": "АР",
    "totalAmount": 3000,
    "totalTax": 297.2973,
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
    "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1050\nБројач рачуна:                905/1050АР\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
  },
  "receipt": {
    "textUrl": "/v1/fiscal-documents/a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d/representations/official-text",
    "jsonUrl": "/v1/fiscal-documents/a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d/representations/canonical-json",
    "pdfA4Url": "/v1/fiscal-documents/a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d/representations/pdf-a4",
    "pdf80mmUrl": "/v1/fiscal-documents/a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d/representations/pdf-80mm",
    "pdf58mmUrl": "/v1/fiscal-documents/a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d/representations/pdf-58mm",
    "previewImageUrl": "/v1/fiscal-documents/a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d/representations/preview-png",
    "qrImageUrl": "/v1/fiscal-documents/a9b8c7d6-e5f4-4a3b-8c2d-1e0f9a8b7c6d/representations/qr-svg",
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
    "preferredPaperFormat": "a4"
  },
  "reference": {
    "fiscalDocumentId": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
    "pfrNumber": "JWX4K9PL-JWX4K9PL-1049",
    "pfrTime": "2026-09-03T11:01:00.500+02:00"
  },
  "createdAt": "2026-09-01T08:15:31.902Z",
  "updatedAt": "2026-09-01T08:15:32.611Z"
}

Closing

finalItems are the delivered items at full value (as if issuing an ordinary receipt). remainingPayments is only the top-up: the final amount less the total fiscalized advance. When there is no top-up, send one payment with amount 0 (the V-PFR requires at least one element). BokaPOS issues two documents in order: the Аванс Рефундација of the whole advance, then Промет Продаја referencing it. Partial delivery from an advance is not supported in this workflow.

POST /v1/advance-cases/{advanceCaseId}/close

curl -X POST "https://api.bokapos.rs/v1/advance-cases/c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f/close" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-5001-close" \
  -H "Content-Type: application/json" \
  -d '{
  "cashier": {
    "id": "web-shop"
  },
  "finalItems": [
    {
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "remainingPayments": [
    {
      "type": "CARD",
      "amount": 5990
    }
  ],
  "commercialFooter": "Hvala na kupovini."
}'

201 Created

{
  "case": {
    "id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "clientReference": "ORDER-5001",
    "externalAdvance": null,
    "state": "CLOSED",
    "advanceSales": [
      {
        "id": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
        "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
        "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
        "idempotencyKey": "order-5001-advance-1",
        "clientReference": "ORDER-5001",
        "invoiceType": "ADVANCE",
        "transactionType": "SALE",
        "cashierId": "web-shop",
        "buyerId": null,
        "buyerDetails": null,
        "status": "FISCALIZED",
        "fiscalized": true,
        "failureCode": null,
        "retryable": false,
        "pfr": {
          "invoiceNumber": "JWX4K9PL-JWX4K9PL-1049",
          "sdcTime": "2026-09-01T10:15:32.483+02:00",
          "requestedBy": "JWX4K9PL",
          "signedBy": "JWX4K9PL",
          "transactionTypeCounter": 904,
          "totalCounter": 1049,
          "invoiceCounterExtension": "АП",
          "totalAmount": 3000,
          "totalTax": 297.2973,
          "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
          "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1049\nБројач рачуна:                904/1049АП\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
        },
        "receipt": {
          "textUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/official-text",
          "jsonUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/canonical-json",
          "pdfA4Url": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/pdf-a4",
          "pdf80mmUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/pdf-80mm",
          "pdf58mmUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/pdf-58mm",
          "previewImageUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/preview-png",
          "qrImageUrl": "/v1/fiscal-documents/d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80/representations/qr-svg",
          "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
          "preferredPaperFormat": "a4"
        },
        "createdAt": "2026-09-01T08:15:31.902Z",
        "updatedAt": "2026-09-01T08:15:32.611Z"
      }
    ],
    "cancellations": [],
    "cancelledAdvanceSaleIds": [],
    "advanceRefund": {
      "id": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091",
      "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
      "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
      "idempotencyKey": "order-5001-close:refund",
      "clientReference": "ORDER-5001",
      "invoiceType": "ADVANCE",
      "transactionType": "REFUND",
      "cashierId": "web-shop",
      "buyerId": "10:115711881",
      "buyerDetails": null,
      "status": "FISCALIZED",
      "fiscalized": true,
      "failureCode": null,
      "retryable": false,
      "pfr": {
        "invoiceNumber": "JWX4K9PL-JWX4K9PL-1051",
        "sdcTime": "2026-09-01T10:15:32.483+02:00",
        "requestedBy": "JWX4K9PL",
        "signedBy": "JWX4K9PL",
        "transactionTypeCounter": 906,
        "totalCounter": 1051,
        "invoiceCounterExtension": "АР",
        "totalAmount": 3000,
        "totalTax": 297.2973,
        "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
        "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1051\nБројач рачуна:                906/1051АР\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
      },
      "receipt": {
        "textUrl": "/v1/fiscal-documents/e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091/representations/official-text",
        "jsonUrl": "/v1/fiscal-documents/e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091/representations/canonical-json",
        "pdfA4Url": "/v1/fiscal-documents/e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091/representations/pdf-a4",
        "pdf80mmUrl": "/v1/fiscal-documents/e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091/representations/pdf-80mm",
        "pdf58mmUrl": "/v1/fiscal-documents/e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091/representations/pdf-58mm",
        "previewImageUrl": "/v1/fiscal-documents/e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091/representations/preview-png",
        "qrImageUrl": "/v1/fiscal-documents/e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091/representations/qr-svg",
        "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
        "preferredPaperFormat": "a4"
      },
      "reference": {
        "fiscalDocumentId": "d5e6f7a8-b9c0-4d1e-8f2a-3b4c5d6e7f80",
        "pfrNumber": "JWX4K9PL-JWX4K9PL-1049",
        "pfrTime": "2026-09-03T11:01:00.500+02:00"
      },
      "createdAt": "2026-09-01T08:15:31.902Z",
      "updatedAt": "2026-09-01T08:15:32.611Z"
    },
    "finalSale": {
      "id": "f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8091a2",
      "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
      "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
      "idempotencyKey": "order-5001-close:sale",
      "clientReference": "ORDER-5001",
      "invoiceType": "NORMAL",
      "transactionType": "SALE",
      "cashierId": "web-shop",
      "buyerId": null,
      "buyerDetails": null,
      "status": "FISCALIZED",
      "fiscalized": true,
      "failureCode": null,
      "retryable": false,
      "pfr": {
        "invoiceNumber": "JWX4K9PL-JWX4K9PL-1052",
        "sdcTime": "2026-09-01T10:15:32.483+02:00",
        "requestedBy": "JWX4K9PL",
        "signedBy": "JWX4K9PL",
        "transactionTypeCounter": 907,
        "totalCounter": 1052,
        "invoiceCounterExtension": "ПП",
        "totalAmount": 8990,
        "totalTax": 890.9009,
        "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
        "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1052\nБројач рачуна:                907/1052ПП\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
      },
      "receipt": {
        "textUrl": "/v1/fiscal-documents/f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8091a2/representations/official-text",
        "jsonUrl": "/v1/fiscal-documents/f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8091a2/representations/canonical-json",
        "pdfA4Url": "/v1/fiscal-documents/f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8091a2/representations/pdf-a4",
        "pdf80mmUrl": "/v1/fiscal-documents/f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8091a2/representations/pdf-80mm",
        "pdf58mmUrl": "/v1/fiscal-documents/f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8091a2/representations/pdf-58mm",
        "previewImageUrl": "/v1/fiscal-documents/f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8091a2/representations/preview-png",
        "qrImageUrl": "/v1/fiscal-documents/f7a8b9c0-d1e2-4f3a-8b4c-5d6e7f8091a2/representations/qr-svg",
        "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
        "preferredPaperFormat": "a4"
      },
      "reference": {
        "fiscalDocumentId": "e6f7a8b9-c0d1-4e2f-9a3b-4c5d6e7f8091",
        "pfrNumber": "JWX4K9PL-JWX4K9PL-1051",
        "pfrTime": "2026-09-05T13:20:44.010+02:00"
      },
      "createdAt": "2026-09-01T08:15:31.902Z",
      "updatedAt": "2026-09-01T08:15:32.611Z"
    },
    "failureCode": null,
    "createdAt": "2026-09-03T09:00:00.000Z",
    "updatedAt": "2026-09-05T11:20:45.300Z"
  }
}

The final Sale carries the whole delivered value (8,990) and references the Advance Refund; `remainingPayments` is only the top-up (5,990).

Case states

`state`	Meaning	Allowed
`OPEN`	chain in progress	payment, cancellation, closing
`ADVANCE_SALE_OUTCOME_UNKNOWN`	the latest payment has an unknown outcome	wait; `GET` the case until resolved
`CLOSING`	closing in progress	replay with the same key
`ADVANCE_REFUND_OUTCOME_UNKNOWN`	the closing advance refund has an unknown outcome	wait
`ADVANCE_REFUND_FISCALIZED_SALE_PENDING`	refund done, final receipt not sent	replay the closure with the same key
`FINAL_SALE_OUTCOME_UNKNOWN`	the final receipt has an unknown outcome	wait
`CLOSED`	everything fiscalized	nothing; read
`FAILED`	the V-PFR rejected a step; `failureCode`	a new case with corrected data

GET /v1/advance-cases/{advanceCaseId}

curl -X GET "https://api.bokapos.rs/v1/advance-cases/c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

GET /v1/advance-cases

curl -X GET "https://api.bokapos.rs/v1/advance-cases?businessPremiseId=b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22&state=OPEN&search=ORDER-5001" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

Sandbox and production

The Tax Administration sandbox lacks the labels Ђ, Е, Г, А, so in the sandbox BokaPOS accepts the name 10: Аванс (X) for any label in the fresh configuration (F in the examples). In production only the four prescribed names are valid; any other name is rejected. The code does not change: compose the name from the label you read from GET /v1/tax-rates.

Advance errors

HTTP	Code	Meaning	What to do	Retry
403	`MODULE_NOT_LICENSED`	The base licence is valid but the module in `module` (advance or email) is not enabled.	Enable the module through BokaPOS Administration or do not use that feature in production.	later
409	`ADVANCE_CASE_NOT_OPEN`	The case is closed, failed or waiting for an outcome to be resolved.	Read `GET /v1/advance-cases/{id}` and the `state` field.	never
422	`ADVANCE_CANCELLATION_TARGET_NOT_LATEST`	Only the latest fiscalized Advance Sale can be cancelled.	Send the `id` of the last `advanceSales` entry not listed in `cancelledAdvanceSaleIds`.	fix the request
422	`ADVANCE_CLOSE_TOTAL_MISMATCH`	`remainingPayments` does not equal the final amount less the stored advance.	Compute the difference from `advanceSales` and send it; when zero, one element with amount 0.	fix the request
422	`ADVANCE_CASE_HAS_NO_FISCALIZED_SALE`	A case without any fiscalized Advance Sale cannot be closed (unless it carries `externalAdvance`).	Fiscalize a payment first.	never
409	`ADVANCE_PAYMENT_SUPERSEDED`	A replayed request targets a payment that is no longer the latest in the chain.	Read the case and continue from the current state.	never
409	`ADVANCE_CASE_CLOSE_ALREADY_RESERVED`	A closure was already reserved with a different key.	Replay the closure with the same `Idempotency-Key` it started with.	same key
503	`ADVANCE_REFUND_NOT_FISCALIZED`	The Tax Administration rejected the closing Advance Refund: the case is `FAILED` with the rejection code, and the reserved final receipt was never sent; it carries this `failureCode`, `NOT_FISCALIZED`, `retryable: false`.	Read the case `failureCode` and `advanceRefund.pfrRejection`, fix the data and open a new case. Replaying the same closure sends nothing.	never

Flow

Open a case

Fiscalize every payment

Cancel a wrong payment (if needed)

Close at delivery

Opening a case

Advance payment

Cancelling a wrong payment

Closing

Case states

Sandbox and production

Advance errors