Od registracije do
prvog testnog eRačuna.

Jedno povezivanje, zaseban ključ za svaku firmu.

Proizvođač blagajne jednom ugradi podršku za KontAI API. Svaka firma koja koristi tu blagajnu otvara svoj račun i izdaje vlastiti ključ. API iz ključa prepoznaje firmu, povezani program i dopuštene radnje.

Ako vaša blagajna još nema opciju „KontAI”: pošaljite proizvođaču poveznicu na ove upute. Sam unos ključa ne dodaje podršku programu koji još nema implementiranu integraciju.

Otvorite zaseban demo račun.

1. Otvorite registraciju u demo portalu.
2. Unesite naziv tvrtke ili obrta, svoj OIB, e-mail adresu i lozinku od najmanje 12 znakova.
3. Potvrdite da u testnim dokumentima koristite samo testne podatke i kliknite Otvori sandbox račun.
4. Otvorit će se Pregled integracija. Provjerite OIB prikazan uz vašu organizaciju. Taj OIB mora biti i OIB izdavatelja u XML-u.

Demo i produkcija imaju zasebne registracije, prijave, ključeve i dokumente. Postojeća produkcijska prijava ne otvara demo račun. Ako je demo račun već registriran, koristite Prijavi se.

Dodajte program i izdajte API ključ.

1. U izborniku otvorite Integracije → Nova integracija. Unesite prepoznatljiv naziv, primjerice „Moja blagajna – razvoj”, i kliknite Kreiraj integraciju.
2. Uz integraciju kliknite Izdaj API ključ. Odaberite integraciju, naziv ključa i rok valjanosti.
3. Odaberite dopuštenja iz tablice. Za sve primjere u ovom vodiču trebaju vam svih pet demo dopuštenja; u stvarnoj integraciji dodijelite samo ona koja koristite.
4. Kliknite Izdaj API ključ i odmah spremite tajni ključ. Počinje s kt_test_ i prikazuje se samo jednom.

Ključ spremite na poslužitelju koji povezuje blagajnu s KontAI-jem. Ne ugrađujte ga u javni web-kod, zajedničku instalaciju aplikacije ili repozitorij. Lozinka za portal ne šalje se uz API pozive.

Ako ključ izgubite, izdajte novi. Ako je otkriven, odmah kliknite Opozovi. Radnja Zamijeni izdaje novi ključ i odmah opoziva stari; novi ključ zatim postavite u svom programu.

Najprije isprobajte slanje u portalu.

1. Otvorite Testno slanje i odaberite svoju integraciju.
2. Kliknite Učitaj ogledni XML. Portal priprema testni račun s vašim OIB-om izdavatelja i KontAI OIB-om primatelja 99062919827.
3. Kliknite Provjeri XML. Ako postoje pogreške, ispravite ih prema prikazanoj poruci.
4. Potvrdite da račun sadrži samo testne podatke i kliknite Pošalji u sandbox.
5. Otvorite Poslani dokumenti i provjerite status. Interno dostavljeno potvrđuje dostavu unutar demoa.

Kako poslati samome sebi?

U svom XML-u postavite vlastiti OIB kao primatelja. U odjeljku AccountingCustomerParty uskladite EndpointID sa shemom 9934, identifikatore primatelja i ostale podatke o primatelju. Ako je naveden PDV identifikator, njegov format u oglednom dokumentu je HR + OIB. Takav račun vidjet ćete i u Ulaznim dokumentima.

Račun poslan KontAI testnom primatelju ostaje u vašem pregledu poslanih dokumenata; ne pojavljuje se u vašoj ulaznoj pošti. Slanje bilo kojem drugom OIB-u odbija se porukom RECIPIENT_NOT_ALLOWED.

Preuzmite XML za testiranje iz svog programa

U API dokumentaciji, dok ste prijavljeni, kliknite Preuzmi ogledni XML. Spremite ga kao racun.xml. Ogledni račun koristi vaš OIB i testne podatke. Za svaki novi testni račun koristite novi broj dokumenta.

Prvi pozivi iz vašeg programa.

Osnovna demo API adresa je https://demo-eracuni.kontai.hr/api/v1. Pozive šalje vaš poslužitelj. Registracija i upravljanje ključevima rade se u portalu; za poslovne pozive koristite samo rute /api/v1/.

Authorization: Bearer VAS_DEMO_API_KLJUC
Content-Type: application/json

Ne šaljite dodatna polja username, password, software_id, environment ili adresu primateljevog servisa. Ključ određuje firmu i integraciju, a adresa API-ja okolinu.

A. Preuzmite gotov primjer za prvi test

Primjer radi uz Node.js 18 ili noviji i ne treba dodatne pakete. Radi na Windowsu, macOS-u i Linuxu. Koristi isključivo demo adresu i odbija produkcijski ključ.

Spremite kontai-demo.mjs i svoj racun.xml u istu mapu. Otvorite terminal u toj mapi. Naredbom node --version provjerite da je Node.js dostupan. Primjer je pomoć za testiranje; u vlastitom sustavu obradite statuse, ponavljanja i pohranu dokumenata.

B. Postavite ključ u trenutačnoj sesiji terminala

Odaberite primjer za svoj terminal. Ključ se pri unosu ne ispisuje na ekran i ne upisujete ga u datoteku programa.

printf 'Zalijepite demo API ključ: '
read -r -s KONTAI_DEMO_API_KEY
printf '\n'
export KONTAI_DEMO_API_KEY

$kontaiSecret = Read-Host 'Zalijepite demo API ključ' -AsSecureString
$env:KONTAI_DEMO_API_KEY = [System.Net.NetworkCredential]::new('', $kontaiSecret).Password
Remove-Variable kontaiSecret

C. Provjerite vezu i primatelja

node kontai-demo.mjs info
node kontai-demo.mjs recipient 99062919827

Prvi poziv mora vratiti environment: "sandbox" i organization_oib vaše firme. Provjera primatelja mora potvrditi internu testnu dostavu. Za provjeru vlastitog primatelja zamijenite broj svojim OIB-om.

D. Provjerite XML pa pošaljite račun

node kontai-demo.mjs validate racun.xml

Nastavite kada odgovor ima valid: true. Provjera obuhvaća UBL XSD, HR pravila i EN16931. Kod pogreške pogledajte issues i ispravite XML.

node kontai-demo.mjs send racun.xml demo-proba-0001

demo-proba-0001 je vaš ključ zahtjeva, odnosno Idempotency-Key. Zapišite ga uz dokument prije prvog slanja. Za svaki novi dokument odaberite novi ključ; kod ponavljanja koristite isti ključ i potpuno isti XML.

Primjer šalje POST /invoices sa sljedećim tijelom. Vrijednost XML-a u stvarnom zahtjevu mora biti JSON string s pravilno kodiranim navodnicima i prijelomima redaka; koristite JSON serializer svojeg jezika.

{
  "xml": "CIJELI_UBL_XML_KAO_STRING",
  "synthetic_data": true
}

E. Provjerite status i preuzmite dokumente

Iz odgovora slanja spremite id. U sljedećoj naredbi zamijenite ID_DOKUMENTA tim identifikatorom.

node kontai-demo.mjs status ID_DOKUMENTA
node kontai-demo.mjs outbox
node kontai-demo.mjs inbox

Detalj računa sadrži i xml. Ako je status još accepted, provjerite ga ponovno nakon kratke stanke, primjerice dvije sekunde. Nemojte zbog čekanja ponovno kreirati račun. Testni XML čuva se 30 dana; nakon isteka expired je true, a sadržaj XML-a više nije dostupan.

Pregled API poziva

Putanje u tablici dodaju se na osnovnu adresu /api/v1. Trenutačno nema webhook obavijesti ni filtriranja popisa upitnim parametrima; status dohvaćate GET pozivom. Potpuni ugovor API-ja nalazi se u OpenAPI specifikaciji.

Razlikujte primitak zahtjeva od dostave.

Najčešće pogreške

Za podršku sačuvajte vrijeme, putanju poziva, HTTP status, error.code i request_id odnosno zaglavlje X-Request-ID. API ključ i lozinku nemojte slati.

Provjerite cijeli tijek.

• Identitet: GET /info prikazuje očekivani OIB i sandbox okolinu.
• Ispravan račun: XML prolazi validaciju i dobiva ID.
• KontAI primatelj: račun završava kao internal_delivered.
• Vlastiti primatelj: račun se vidi i u ulaznim dokumentima.
• Zabranjeni primatelj: drugi OIB dobiva RECIPIENT_NOT_ALLOWED, bez slanja.
• Neispravan XML ili iznos: pogreška je vidljiva korisniku, a slanje se zaustavlja.
• Ponovljeni zahtjev: isti ključ i sadržaj vraćaju isti ID bez drugog računa.
• Izmijenjeni zahtjev: isti ključ s drugim XML-om vraća 409.
• Opozvani ključ: novi zahtjev vraća 401.
• Odvojene firme: korisnik druge firme ne vidi vaše račune.

U svom programu vodite zasebno status slanja, dostave i, kada bude podržano u produkciji, fiskalizacije i eIzvještavanja. Demo uspjeh potvrđuje samo opisani testni tijek.

Produkciju pripremite zasebno.

1. Otvorite Produkcijske integracije i registrirajte zaseban račun ili se prijavite postojećim produkcijskim računom.
2. Potvrdite e-mail, provjerite OIB i podatke firme te dovršite prihvat ugovora u portalu.
3. Dodajte program i izdajte zaseban produkcijski ključ kt_live_. Trenutačno dostupne ovlasti su validation:write, invoices:read i inbox:read.
4. Kad portal ispuni preduvjete, kliknite Zatraži produkcijsku aktivaciju. Zahtjev odlazi KontAI timu.
5. Potvrda adrese zaprimanja i ovlaštenja u FiskAplikaciji, provjera firme te otvaranje produkcijske razmjene dovršavaju se zasebno. Sam zahtjev KontAI timu ne šalje ovlaštenje Poreznoj i ne uključuje slanje.

Produkcijska osnovna adresa je https://eracuni.kontai.hr/api/v1. Vaš program mora imati jasno odvojenu konfiguraciju, ključeve i evidenciju za svaku okolinu. Ogledni klijent iz ovog vodiča namjerno radi samo na demo adresi.

Kratki odgovori prije povezivanja.