Skip to content

Your own system · REST API

Fiscalization from your own system, ERP or SaaS through the BokaPOS API

If your system already knows when an order is paid, fiscalization is one HTTP call. The BokaPOS API is built for that: OAuth 2.0 client credentials, one `POST` per document, an idempotency key, clear statuses and the PDF, QR and verification link in the response.

Request sandbox accessAPI documentation

The free WooCommerce plugin uses the same API, so everything the plugin does is available to your system: sales, refunds, advance chains, proforma, training, copies, e-mail delivery, journal and reports. Documentation: API, OpenAPI contract: api.bokapos.rs/openapi.yaml, AI bundle: llms.txt.

The example below is the same call for every platform: a token, then one POST /v1/fiscal-documents with the order's idempotency key. The complete documentation with examples in five languages is on the API page.

What a minimal integration looks like

Four calls: token, tax rates, fiscal document and receipt representation. The rest is your business logic: when the supply happened, how you store the PFR number and how you send the receipt to the customer. For an unknown outcome (a network failure after sending) the API returns a clear status that is checked, never resent blindly.

Integration steps

Effort
A typical web-shop integration takes a day or two, including refund testing in the sandbox.

  1. Token

    POST to auth.bokapos.rs with the client id and secret. The token is short-lived; refresh it as needed and never send it to a browser.

  2. Tax rates

    GET /v1/tax-rates returns the labels the V-PFR currently accepts for your premise. Map your rates to them at every issue.

  3. Fiscal document

    POST /v1/fiscal-documents with items, payments, the document kind and the order's idempotency key. A 201 with fiscalized: true is the only proof of a receipt.

  4. Receipt representation

    GET /v1/fiscal-documents/{id}/representations/pdf-a4 (or 80 mm, 58 mm, image, JSON) and send it to the customer, or switch on the E-mail module.

  5. Refunds, advances, production

    A refund with the reference and buyer identification, an advance chain where needed, then production credentials once the taxpayer activates the security element.

The same call for every platform

curl -X POST "https://auth.bokapos.rs/realms/boka/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$BOKAPOS_CLIENT_ID" \
  -d "client_secret=$BOKAPOS_CLIENT_SECRET"

curl -X POST "https://api.bokapos.rs/v1/fiscal-documents" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-4127-sale-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127",
  "invoiceType": "NORMAL",
  "transactionType": "SALE",
  "cashier": {
    "id": "web-shop",
    "displayName": "Web shop"
  },
  "items": [
    {
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CARD",
      "amount": 8990
    }
  ],
  "metadata": {
    "orderId": "4127",
    "channel": "web"
  }
}'

API documentation

Frequently asked questions

Does the API work from any language?

Yes. It is plain HTTPS and JSON. The documentation has examples in curl, Node, PHP, C# and Python, and the OpenAPI contract lets you generate a client.

How do I prevent a duplicate receipt?

With an idempotency key derived from the order. The same key and content return the original receipt; an unknown outcome is checked, not resent.

Can I use ChatGPT or Claude for the integration?

Yes. The API page has a prompt and the documentation as text (llms.txt) with the OpenAPI contract, so an AI assistant can write a client for your language.

What about a marketplace selling on behalf of several taxpayers?

Each taxpayer has its own organization, security element and credentials; the platform calls the API on behalf of the exact taxpayer. Get in touch to agree the model.

Platforms

Pick the platform your shop runs on.

Ready to fiscalizefrom your own system?

The sandbox is free, and you issue your first receipt the same day.

Request a demoSee the documentation