Autentifikacija i okruženja

Adrese

Nema odvojenog sandbox hosta. Isti kod, iste adrese i isti pozivi rade u oba okruženja; menja se samo client id i tajna.

Pristupni podaci

API kredencijal (client id i tajnu) izdaje BokaPOS administracija na zahtev vlasnika organizacije, posebno za sandbox (boka-sbx-...) i za produkciju (boka-prod-...). Tajna se prikazuje jednom, pri izdavanju, i ne može se ponovo pročitati; ako se izgubi, kredencijal se opoziva i izdaje nov. Kredencijal je vezan za jednu organizaciju i jedno okruženje i nosi fiksan paket scope-ova opisan ispod.

Preuzimanje tokena

Standardni client_credentials zahtev, application/x-www-form-urlencoded. Nije potrebno slati scope; token dobija sve scope-ove kredencijala.

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"

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "tenant:read operations:read catalogue:read catalogue:write fiscal:read fiscal:write refund:write proforma-training:write advance:write advance:close configuration:read security-elements:read"
}

• Token važi 300 sekundi. Keširajte ga u memoriji procesa i obnovite kada mu ostane manje od, na primer, 30 sekundi. Ne tražite nov token za svaki poziv.
• Odgovor 401 na bilo kom pozivu znači istekao ili nevažeći token: uzmite nov i ponovite isti zahtev (sa istim Idempotency-Key).
• Token je JWT sa tvrdnjama org_id (vaša organizacija) i boka_env (sandbox ili production). Ne morate ih čitati; API ih primenjuje sam.
• Pogrešan client id ili tajna vraćaju 401 sa error: invalid_client od servera za identitet.

Zaglavlje svakog poziva

Authorization: Bearer <access_token>
Content-Type: application/json
Idempotency-Key: order-4127-sale-1      (samo na fiskalnim izmenama)
Accept: application/json

Scope-ovi kredencijala

Svaki API kredencijal dobija isti paket od dvanaest scope-ova. Oni određuju koje operacije sme da pozove; sve ostale operacije iz ugovora pripadaju portalu i BokaPOS konzoli.

Sandbox i produkcija

• Kredencijal nosi okruženje. Sandbox kredencijal može da radi samo sa sandbox bezbednosnim elementom, produkcioni samo sa produkcionim. Ukrštanje vraća 403 CREDENTIAL_ENVIRONMENT_MISMATCH pre bilo kakve rezervacije.
• Sandbox element dodeljuje BokaPOS iz sopstvenog fonda; sandbox računi zato izlaze pod PIB-om BOKA GROUP DOO i verifikuju se na sandbox.suf.purs.gov.rs. Produkcioni element je sertifikat vaše firme koji vlasnik otprema u portalu.
• Sandbox je besplatan i nikad blokiran licencom. Produkcija traži važeću licencu; GET /v1/license kaže unapred da li je fiskalizacija dozvoljena.
• Poreske oznake se razlikuju. Sandbox Poreske uprave nosi generički test skup; produkcija zvanične srpske oznake. Zato se oznake uvek čitaju iz GET /v1/tax-rates.
• Kredencijal vidi samo svoje okruženje. Svako čitanje je ograničeno: sandbox ključ lista samo sandbox obveznike, prodajna mesta, bezbednosne elemente i dokumente, produkcioni samo produkcione. Objekat drugog okruženja za vas ne postoji, pa čitanje po id-u vraća 404, a podešavanje koje registrujete (POST /v1/taxpayers) pripada okruženju vašeg ključa. PIB je jedinstven po okruženju, pa vaša firma može da postoji jednom u sandboxu i jednom u produkciji.
• Idempotency ključevi su jedinstveni po organizaciji u oba okruženja. Ponovna upotreba ključa iz sandbox testiranja u produkciji vraća 409 IDEMPOTENCY_KEY_REUSED_IN_OTHER_ENVIRONMENT; izaberite nov ključ umesto ponavljanja.
• Ista organizacija, oba okruženja. Vlasnik u portalu vidi sandbox i produkcione dokumente jedno pored drugog dok organizacija ne pređe u produkciju; od tada portal podrazumevano sakriva sandbox podatke (vlasnik ih može ponovo prikazati u Podešavanjima). Vaš sistem ih razlikuje po kredencijalu kojim je zvao.

Prelazak u produkciju je opisan na stranici Prelazak u produkciju: sertifikat, aktivacija, licenca, produkcioni kredencijal, zamena u konfiguraciji. Kod se ne menja.

Provera posle prijave

curl -X GET "https://api.bokapos.rs/v1/runtime" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

{
  "manufacturer": "BOKA GROUP DOO",
  "productName": "BokaPOS",
  "esirNumber": "",
  "softwareVersion": "1.0.0",
  "buildCommit": "1f0d454e8b2c9a7d6f5e4c3b2a1908f7e6d5c4b3",
  "instanceId": "api-bokapos-rs",
  "organizationId": "7c1e9a4b-2d3f-4e5a-b6c7-8d9e0f1a2b3c",
  "clientId": "boka-sbx-k7m2p9x4q1wz",
  "fiscalEndpointsEnabled": true,
  "pfrAdapter": "configured"
}

pfrAdapter: configured i fiscalEndpointsEnabled: true znače da je fiskalizacija moguća za vaše okruženje. esirNumber je prazan dok Poreska uprava ne dodeli broj odobrenja; kada ga dodeli, štampa se na svakom računu.