Skip to content

API documentation

Going to production

The code does not change. The certificate, the licence and the credential do, and a few things that were relaxed in the sandbox become strict. This is the order and the checklist.

Updated: 29 August 2026 · Contract version 1.0.0

Order

  1. 01

    The Owner obtains the security element

    The taxpayer's authorized person requests a file-based security element for the distance-commerce premise in the Tax Administration portal and downloads the original ZIP (PFX, password, PAK). BokaPOS never accesses the Tax Administration portal on your behalf.

  2. 02

    The Owner uploads it to the BokaPOS portal

    In cloud.bokapos.rs, Security elements: the original ZIP plus the password and PAK, through an encrypted one-time browser session. The element is bound to the exact taxpayer and premise.

  3. 03

    BokaPOS verifies and activates

    BokaPOS Administration verifies the chain, JID and PIB and activates the element with one Training document (Обука), which has no tax effect. From then on the element can sign.

  4. 04

    Licence

    BokaPOS issues the organization's licence (base subscription per production element, plus the Advance and E-mail modules as needed). GET /v1/license returns productionFiscalizationAllowed: true.

  5. 05

    Production credential

    BokaPOS issues a boka-prod-... client id and secret. Your system receives them as a configuration secret.

  6. 06

    Swap and verify

    Replace the client id and secret, call GET /v1/runtime, then GET /v1/tax-rates. Verify the first production receipt at suf.purs.gov.rs through pfr.verificationUrl.

  7. 07

    Sandbox stays available

    The sandbox credential and element keep working for further testing. From the moment the production credential is active, the portal hides the organization's sandbox data (the BOKA GROUP DOO test taxpayer, its premise, the test element and every sandbox document) so nobody confuses it with real receipts; the Owner can show it again in Settings. The API is unaffected: each key sees only its own environment.

What differs in production

TopicSandboxProduction
URL and codeapi.bokapos.rsthe same
Credentialboka-sbx-...boka-prod-...; an object of the other environment is 404 for you, and crossing an element returns 403 CREDENTIAL_ENVIRONMENT_MISMATCH
Datasandbox taxpayers, premises, elements and documents onlyproduction ones only; the same PIB may exist once in each environment
Security elementBokaPOS's from the pool, BOKA GROUP DOO's PIB on the receiptyour certificate, your PIB and name on the receipt
Verificationsandbox.suf.purs.gov.rssuf.purs.gov.rs
Tax labelstest set (F, A, Ж...)official Serbian labels (Ђ, Е, Г, А...), from GET /v1/tax-rates
Advance items10: Аванс (X) for any labelonly 10: Аванс (Ђ), 11: Аванс (Е), 12: Аванс (Г), 13: Аванс (А)
Licencenever blockssale, copy, proforma, training and advance need a valid licence; refund and cancellation never
Moduleseverything worksAdvance and E-mail need the module enabled
E-mail deliveryworks when enabled in the portalthe same, plus the E-mail module
Pricefreeper the price list; 600 documents a month included

Checklist before the first production receipt

  • Tax labels are read from GET /v1/tax-rates, not from configuration; the mapping of your tax groups to labels is verifiable and covers every rate you sell.
  • The Idempotency-Key is persisted before sending and replayed with the same key after an interruption.
  • OUTCOME_UNKNOWN handling exists and is tested: no new request, polling GET /v1/operations/{id}, escalation to an operator.
  • Amounts have two decimals, quantities three; item and payment totals match.
  • The customer receives the verification link (and a PDF or image) for every receipt, and the fiscal part is not altered.
  • Refunds go through /v1/refund-workflows with buyer identification; for cash you print the copy for signature.
  • If you use advances: advance item names are composed from the label, commercialFooter is filled, closing sends only the top-up.
  • Monitoring: GET /v1/security-elements (certificate expiry) and GET /v1/license (state) are checked periodically; 401/403/503 raise alerts.
  • The credential secret lives only on the server, in environment secrets; logs contain no token.
  • The sandbox test passed: one sale, one partial refund, one journal search, one PDF.

Support

BokaPOS Administration: office@bokagroup.rs, +381 69 558 55 88. Send the operation id and clientReference with a request; never the token, the secret or the certificate. Contract changes are announced in the OpenAPI file (info.version) and on this page.