# 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.

Izvor: https://bokapos.rs/integracije/sopstveni-sistem

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](https://bokapos.rs/api), OpenAPI opis: [api.bokapos.rs/openapi.yaml](https://api.bokapos.rs/openapi.yaml), paket za AI asistente: [llms.txt](https://bokapos.rs/api/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](https://bokapos.rs/api).

**Ukratko**

- Autentifikacija: OAuth 2.0 client credentials (client id i tajna), token na auth.bokapos.rs.
- Jedan poziv izdaje račun, drugi ga preuzima u željenom formatu (PDF A4, 80 mm, 58 mm, slika, JSON).
- Idempotentni ključ: isti zahtev dva puta vraća isti račun; izmenjen sadržaj sa istim ključem dobija 409.
- Poreske oznake se čitaju sa `GET /v1/tax-rates` pre izdavanja; ukodirane oznake se odbijaju.
- Sandbox i produkcija dele adresu; razlikuju se po pristupnim podacima i bezbednosnom elementu.

## 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

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.

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

## Isti poziv za svaku platformu

```bash
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"
  }
}'
```

## Č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.