Pređi na sadržaj

Sopstveni sistem · REST API

Fiskalizacija iz sopstvenog sistema, ERP-a ili SaaS-a preko BokaPOS API-ja

Ako vaš sistem već zna kada je porudžbina plaćena, fiskalizacija je jedan HTTP poziv. BokaPOS API je projektovan za to: OAuth 2.0 client credentials, jedan `POST` po dokumentu, idempotentni ključ, jasni statusi i PDF, QR i verifikacioni link u odgovoru.

Zatražite probni pristupAPI dokumentacija

Isti API koristi i besplatan WooCommerce dodatak, pa je sve što dodatak radi dostupno i vašem sistemu: prodaja, refundacija, avansni lanac, predračun, obuka, kopija, dostava e-poštom, dnevnik i izveštaji. Dokumentacija: API, OpenAPI opis: api.bokapos.rs/openapi.yaml, paket za AI asistente: llms.txt.

Primer ispod je isti poziv koji radi za svaku platformu: token, pa jedan POST /v1/fiscal-documents sa idempotentnim ključem porudžbine. Kompletna dokumentacija sa primerima u pet jezika je na stranici API.

Kako izgleda minimalna integracija

Četiri poziva: token, poreske oznake, fiskalni dokument i prikaz računa. Ostalo je vaša poslovna logika: kada je promet izvršen, kako čuvate PFR broj i kako šaljete račun kupcu. Za nepoznat ishod (mrežni prekid posle slanja) API vraća jasan status koji se proverava, nikad ne ponavlja naslepo.

Koraci integracije

Obim posla
Tipična integracija web shopa traje dan ili dva, uključujući testiranje refundacije u sandboxu.

  1. Token

    POST na auth.bokapos.rs sa client id i tajnom. Token važi kratko; osvežavajte ga po potrebi i nikad ga ne šaljite u pregledač.

  2. Poreske oznake

    GET /v1/tax-rates vraća oznake koje V-PFR trenutno priznaje za vaš poslovni prostor. Mapirajte svoje stope na njih pri svakom izdavanju.

  3. Fiskalni dokument

    POST /v1/fiscal-documents sa stavkama, plaćanjima, vrstom računa i idempotentnim ključem porudžbine. Odgovor 201 sa fiscalized: true je jedini dokaz računa.

  4. Prikaz računa

    GET /v1/fiscal-documents/{id}/representations/pdf-a4 (ili 80 mm, 58 mm, slika, JSON) i pošaljite kupcu, ili uključite modul E-mail.

  5. Refundacija, avans, produkcija

    Refundacija sa referencom i identifikacijom kupca, avansni lanac po potrebi, pa prelazak na produkcione pristupne podatke kada obveznik aktivira bezbednosni element.

Isti poziv za svaku platformu

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 dokumentacija

Česta pitanja

Da li API radi iz bilo kog jezika?

Da. To je običan HTTPS i JSON. Dokumentacija ima primere u curl, Node, PHP, C# i Python, a OpenAPI opis omogućava generisanje klijenta.

Kako sprečavam dupli račun?

Idempotentnim ključem izvedenim iz porudžbine. Isti ključ i isti sadržaj vraćaju originalni račun; nepoznat ishod se proverava, ne ponavlja.

Mogu li da koristim ChatGPT ili Claude za integraciju?

Da. Na stranici API postoji prompt i paket dokumentacije kao tekst (llms.txt) sa OpenAPI opisom, pa AI asistent može da napiše klijent za vaš jezik.

Šta se dešava sa marketplace platformom koja prodaje za više obveznika?

Svaki obveznik ima svoju organizaciju, bezbednosni element i pristupne podatke; platforma poziva API u ime tačnog obveznika. Javite se da dogovorimo model.

Platforme

Izaberite platformu na kojoj radi vaša prodavnica.

Spremni da fiskalizujeteiz sopstvenog sistema?

Probno okruženje je besplatno, a prvi račun izdajete isti dan.

Zatražite demoPogledajte dokumentaciju