Skip to content

Magento · through the API

Magento fiscalization in Serbia: fiscal receipts through the BokaPOS API

Magento has everything a clean integration needs: order events, a module that listens to them and configuration for tax-class mapping. BokaPOS does not ship a Magento module; your developer builds one around the BokaPOS API, usually in a day or two.

Request sandbox accessAPI documentation

Magento stores in Serbia often sell to business buyers too. There the buyer's PIB goes on the fiscal receipt as buyer identification; BokaPOS supports that in the same call.

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.

Where the integration hooks in

A custom module registers an observer on the event Magento emits when an order is saved or its status changes. When the order reaches the status you chose (for example paid or shipped), the observer builds the request from items, discounts, shipping and payment, calls BokaPOS and stores the PFR number, verification link and status as order attributes. A credit memo triggers a fiscal refund.

Integration steps

Effort
Typically two days for a developer who knows Magento modules, including the credit memo and sandbox testing.

  1. Account and sandbox

    Request BokaPOS access and receive sandbox credentials and a test security element, free.

  2. Module configuration

    Keep the client id and secret, the taxpayer and premise selection, the triggering status and the mapping of tax classes to labels from GET /v1/tax-rates in the admin configuration.

  3. Observer on the status

    At the chosen status send POST /v1/fiscal-documents with an idempotency key from the order increment id. Store the response with the order and show it in the admin.

  4. Receipt to the customer

    Attach the PDF from /representations/ to the Magento order e-mail or switch on the BokaPOS E-mail module.

  5. Credit memo and production

    A credit memo sends a fiscal refund with the reference and buyer identification. After the tests the taxpayer activates the security element and you switch to production credentials.

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 BokaPOS have a ready-made Magento module?

Not today. There is a documented API, PHP examples and a free sandbox, so a developer builds the module in a day or two.

How is a sale to a company fiscalized in Magento?

Like a sale to a private person, plus buyer identification: the company's PIB is sent in the buyer field and printed on the receipt as the buyer ID.

What about partial shipments?

The fiscal receipt follows the supply. If you ship in parts, agree with your accountant whether to issue a receipt per shipment or an advance receipt at payment; BokaPOS supports both flows.

Can I test without the taxpayer's certificate?

Yes. The sandbox uses a test security element that BokaPOS assigns, so you test the integration before the taxpayer receives its own element from the Tax Administration.

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