Prijeđite na glavni sadržaj

Primjeri najbolje prakse, najčešće greške i rješenja

Sigurnosne preporuke za API ključeve

API ključ nikada nije pohranjen u bazi u čistom tekstu - pohranjuje se samo SHA256 hash. U korisničkom sučelju vidljivo je samo zadnjih 8 znakova ključa (referenca). Savjetujemo da:

  • Rotirajte ključeve periodično - kreirajte novi ključ, ažurirajte integraciju, obrišite stari.

  • Postavite datum isteka za ključeve koji se koriste privremeno.

  • Pratite lastUsedAt - deaktivirajte nekorištene ključeve.

  • Ne dijelite ključeve između različitih sustava - kreirajte zasebne ključeve za svaku integraciju.

  • Pohranite ključ sigurno - koristite environment varijable ili secret manager, nikad hardkodirajte.

  • Ako sumnjate da je ključ kompromitiran, odmah ga deaktivirajte i kreirajte novi.

Postoji li Parra Sandbox (testno) okruženje za API integraciju?

Parra Sandbox okruženje je dostupno za testiranje API integracije putem linka koji ste zaprimili u emailu nakon generiranja API ključa. Preporučamo da ga koristite.
Kako konfigurirati ovo okruženje pročitajte na ovom linku.

Preporuka za upravljanje rate limitom

  1. Pratite response headere

    Implementirajte praćenje X-RateLimit-Remaining headera u vašoj integraciji. Kada se približite limitu, usporite zahtjeve.

  2. Implementirajte exponential backoff

    Kada dobijete 429 odgovor:

    1. pokušaj: čekaj 1 sekundu

    2. pokušaj: čekaj 2 sekunde

    3. pokušaj: čekaj 4 sekunde

    4. pokušaj: čekaj 8 sekundi

    ...

  3. Koristite Retry-After header

    Retry-After header govori koliko sekundi trebate čekati prije sljedećeg zahtjeva.

  4. Batchajte zahtjeve

    Umjesto da šaljete puno pojedinačnih zahtjeva, grupirajte operacije gdje je moguće.

  5. Cache-irajte podatke

    Šifrarnike (valute, zemlje, jedinice mjere) dohvaćajte jednom i cache-irajte lokalno.

Verzioniranje - specifikacija verzije

API koristi zadanu verziju 1.0. Preporučujemo uvijek eksplicitno navesti verziju da izbjegnete neočekivano ponašanje. Uvijek koristite v1.1 za nove integracije. Verzija 1.0 je deprecated i bit će uklonjena u budućnosti.

Kako specificirati verziju:

Preporučeno: URL putanja (path versioning)

GET /v1.1/123/customers GET /v1/123/invoices

Ako koristite v1 bez minor verzije, sustav koristi zadanu verziju 1.0.

Alternativa 1: Query string

GET /123/customers?api-version=1.1

Alternativa 2: HTTP header

X-API-Version: 1.1

Checklist za migraciju v1.0 > v1.1.

[ ] Promijenite verziju u URL-u na /v1.1/

[ ] Zamijenite currencyId s currencyMark

[ ] Zamijenite countryId s countryCode

[ ] Zamijenite unitOfMeasureId s unitOfMeasureCode

[ ] Zamijenite operatorId s operatorOib

[ ] Zamijenite taxExcludeBasisId s taxExcludeBasisMark

[ ] Ažurirajte parsiranje enum vrijednosti (objekt umjesto int)

[ ] Ažurirajte parsiranje lista kupaca/artikala (paginacija)

[ ] Ažurirajte obradu odgovora pri kreiranju računa (objekt umjesto int)

[ ] Za B2C: uklonite documentDate iz zahtjeva

[ ] Dodajte logiranje X-Correlation-ID headera za debugging

[ ] Testirajte sve endpointe s /v1.1/ verzijom

Preporuke za korištenje šifrarnika

  1. Cache-irajte šifrarnike - podaci se rijetko mijenjaju, dovoljno ih je dohvaćati jednom dnevno.

  2. Koristite enum endpointe za prikaz opcija korisniku ili za validaciju prije slanja zahtjeva.

Preporuke za error handling

  1. Uvijek provjerite HTTP status kod - ne oslanjajte se samo na body odgovora

  2. Parsirajte errorCode polje - koristite ga za programsku obradu grešaka

  3. Logirajte cijeli odgovor - uključujući headere, za debugging

  4. Implementirajte retry logiku za 429 i 500 greške s exponential backoff

  5. NE ponavljajte zahtjeve za 400 i 401 greške - one zahtijevaju ispravku ulaznih podataka

API ne radi, što da provjerim?

Redom provjerite sve sljedeće:

  1. Je li API ključ aktivan i nije istekao?

  2. Koristite li ispravan businessSubjectId?

  3. Je li Authorization: Bearer {ključ} header ispravno formatiran?

  4. Je li vaša IP adresa na whitelisti (ako je konfigurirano)?

  5. Jeste li prekoračili rate limit?

  6. Provjerite /diagnostics/ping za dijagnostiku.

Prikazuje se: 500 Internal Server Error. Što da radim?

Pokušajte ponovo s exponential backoff. Ako se ponavlja, kontaktirajte Parra podršku na [email protected] sa sljedećim informacijama:

  • Točnim vremenom greške

  • Endpoint koji pozivate

  • Request body (bez API ključa!)

  • Response body - CorrelationId

Zašto dobivam InvoiceNumberMismatchWithFormatSettings?

Broj računa mora točno odgovarati formatu iz postavki. Uvijek koristite /next-invoice-number endpoint.

Što znači draftInvoiceId query parameter?

Ako ste prethodno kreirali skicu (draft) računa, možete je finalizirati slanjem na isti endpoint s draftInvoiceId parametrom.

Mogu li koristiti API iz browsera (JavaScript)?

Ne preporučujemo jer bi API ključ bi bio vidljiv u kodu. Koristite server-side integraciju.

Ostali česti scenariji i primjeri najbolje prakse

Scenarij 1: Prva integracija - test poziv

Cilj: Provjeriti da API ključ radi i da je konfiguracija ispravna.

GET /v1.1/diagnostics/ping Authorization: Bearer {vaš_api_ključ}

Ako dobijete:

  • 200 OK → sve je ispravno, u odgovoru vidite businessSubjectId

  • 401 → ključ je neispravan, istekao ili deaktiviran

  • 403 → IP adresa nije dozvoljena - 429 → rate limit prekoračen

Scenarij 2: Automatsko kreiranje B2B računa iz ERP sustava

Tijek rada

1. Cache-iraj šifrarnike (jednom dnevno):    
GET /codebooks/currencies    
GET /codebooks/countries    
GET /codebooks/units-of-measure    
GET /settings/workspaces    
GET /settings/payment-devices?workspaceId=...    
GET /settings/operators    
GET /settings/bank-accounts  

2. Za svaki račun:    .
a) GET /invoices/next-invoice-number?invoiceDateTime=...&workSpaceMark=PP1&paymentDeviceMark=NU1    
b) POST /invoices/b2b (s podacima iz koraka a)    
c) Provjeri odgovor - spremi invoice ID  

3. Opcionalno:    
GET /invoices/{id}/download/xml  (za B2B eRačune)    
GET /invoices/{id}/download/pdf  (obični PDF račun)

Ključne napomene

  • Uvijek koristite /next-invoice-number - na taj način se Parra brine o slijednosti računa

  • Šaljite račune sekvencijalno (ne paralelno) za isti poslovni prostor/naplatni uređaj. U suprotnom je moguće da dođe do pogreške zbog neispravne slijednosti.

  • Provjerite odgovor - v1.1 vraća puni InvoiceDetailsDto pa možete odmah vidjeti status fiskalizacije

Scenarij 3: Automatska obrada dolaznih eRačuna

Tijek rada

1. Periodično (npr. svakih 15 minuta):    
GET /incoming-einvoices/unprocessed?page=1&pageSize=100  

2. Za svaku neobrađeni eRačun:    
a) GET /incoming-einvoices/{id}  (dohvati detalje)    
b) Procesiraj prema poslovnim pravilima    
c1) PATCH /incoming-einvoices/{id}/send-to-accounting       
ILI       
c2) POST /incoming-einvoices/{id}/reject  

3. Nastavi s paginacijom dok ima neobrađenih

Ključne napomene

  • Koristite /unprocessed endpoint umjesto /incoming-einvoices za efikasniji polling

  • Implementirajte idempotentnost - ako je eRačun već obrađen, API vraća grešku (ne duplikat)

  • Logirajte sve akcije za revizijski trag

Scenarij 4: Sinkronizacija kupaca

1. GET /customers - dohvati sve kupce 
2. Usporedi s lokalnom bazom 
3. Ažuriraj lokalne zapise

Kupci se mogu samo čitati putem API-ja. Kreiranje/uređivanje je moguće samo kroz Parra aplikaciju.

Scenarij 5: Dohvat i preuzimanje računa

1. GET /invoices?page=1&pageSize=100  (dohvati listu) 
2. Za svaki račun koji trebate:    GET /invoices/{id}  (detalji) 
3. Za preuzimanje datoteka:    
GET /invoices/{id}/download/xml  (eRačun)    
GET /invoices/{id}/download/pdf  (obični PDF račun) 
4. Preuzmi datoteku s SAS URI-ja

SAS URI je privremeni! Koristite ga odmah nakon dohvata. Ako istekne, pozovite endpoint ponovo.

Primjeri najbolje prakse

1. Error handling

try:     
response = api.call(endpoint)
if response.status == 200:         
           process(response.data)     
elif response.status == 429:         
           wait(response.headers['Retry-After'])
           retry()     
elif response.status == 400:
           log_error(response.body.errorCode, response.body.detail)
           # NE pokušavaj ponovo - ispravi zahtjev     
elif response.status == 401:         
           alert("API ključ je neispravan!")     
elif response.status >= 500:         
           retry_with_backoff()

2. Rate limit management

  • Pratite X-RateLimit-Remaining header

  • Kad padne ispod 10%, usporite zahtjeve

  • Implementirajte red čekanja za zahtjeve

3. Retry logika

HTTP status

Pokušaj ponovo?

Strategija

200

Ne

Uspjeh

400

Ne

Ispravi zahtjev

401

Ne

Provjeri API ključ

403

Ne

Provjeri businessSubjectId / IP

404

Ne

Resurs ne postoji

429

Da

Čekaj Retry-After sekundi

500

Da

Exponential backoff (1s, 2s, 4s, 8s)

502/503

Da

Exponential backoff

4. Caching strategija

Resurs

Koliko često osvježiti

Razlog

Valute

1x dnevno

Rijetko se mijenjaju

Države

1x dnevno

Statični podatak

Jedinice mjere

1x dnevno

Rijetko se mijenjaju

KPD

1x tjedno

Gotovo nikad se ne mijenja

Operateri

1x po sesiji

Mogu se dodavati

Bankovni računi

1x po sesiji

Rijetko se mijenjaju

Poslovni prostori

1x po sesiji

Rijetko se mijenjaju

Naplatni uređaji

1x po sesiji

Rijetko se mijenjaju

5. Sigurnost integracije

  • Pohranite API ključ u environment varijable ili secret manager

  • Nikad ne logirajte API ključ u logove

  • Implementirajte circuit breaker za zaštitu od kaskadnih grešaka

  • Postavite timeout na zahtjeve (preporučeno: 30 sekundi)

6. Monitoring

Pratite sljedeće metrike u vašoj integraciji:

  • Broj uspješnih vs neuspješnih zahtjeva

  • Prosječno vrijeme odgovora

  • Rate limit iskorištenost

  • Broj 429 i 500 grešaka

  • Vrijeme zadnjeg uspješnog poziva

Jesmo li odgovorili na vaše pitanje?