CEZIH API dokumentacija — Tehnički pregled za developere (2026)

Tehnički vodič za developere i IT voditelje koji rade na integraciji s CEZIH-om. Pokriva: SOAP web servise, autentikaciju s AKD karticom, osnovne endpoints (eRecept, eUputnica, izvještaj), XML primjere i proces HZZO certifikacije. Namijenjeno ljudima koji razmatraju vlastitu integraciju ili evaluiraju gotove softvere.

1. Arhitektura CEZIH-a

CEZIH je SOA (Service-Oriented Architecture) sustav koji povezuje:

• Klinički sustavi — ordinacije, bolnice, poliklinike (vaš softver)
• Ljekarne — dohvat eRecepta po OIB-u
• Laboratoriji — primanje eUputnica, slanje nalaza
• HZZO backend — centralna baza osiguranja, fakturiranje, izvještaji
• FINA — izdavanje AKD kartica, verifikacija certifikata

Komunikacija primarno ide preko HTTPS/SOAP, s novijom FHIR specifikacijom za dio podataka.

2. Protokoli i standardi

3. Autentikacija — Get Work Permission

Svaki CEZIH request treba work session token. Token se dobiva pozivom "Get Work Permission" servisa, uz AKD digitalni potpis.

Primjer SOAP request-a (pojednostavljen)

POST /cezih/wsdl/authentication HTTP/1.1
Host: cezih.hzzo.hr
Content-Type: text/xml; charset=utf-8
SOAPAction: "GetWorkPermission"

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <wsse:Security>
      <wsse:BinarySecurityToken
        EncodingType="...#Base64Binary"
        ValueType="...#X509v3">
        [AKD X.509 certifikat u base64]
      </wsse:BinarySecurityToken>
      <ds:Signature>
        [XML digitalni potpis]
      </ds:Signature>
    </wsse:Security>
  </soap:Header>
  <soap:Body>
    <GetWorkPermission xmlns="...">
      <EmployeeID>123456789</EmployeeID>
      <InstitutionOIB>12345678901</InstitutionOIB>
      <Role>PHYSICIAN</Role>
    </GetWorkPermission>
  </soap:Body>
</soap:Envelope>

Response

<soap:Body>
  <GetWorkPermissionResponse>
    <WorkSessionToken>
      eyJhbGciOiJSUzI1NiIs...
    </WorkSessionToken>
    <ValidUntil>2026-04-20T17:00:00Z</ValidUntil>
    <EmployeeRoles>
      <Role>PHYSICIAN</Role>
      <Role>PRESCRIPTION_WRITER</Role>
    </EmployeeRoles>
  </GetWorkPermissionResponse>
</soap:Body>

Token vrijedi tipično 8 sati (kraj radnog dana). Svaki sljedeći API call u istoj sesiji koristi ovaj token umjesto ponovne AKD autentikacije.

4. Glavni servisi

4.1 Eligibility Query (provjera osiguranja)

Provjera HZZO statusa pacijenta po OIB-u. Rezultat: aktivan/neaktivan, kategorija, dopunsko osiguranje, datum isteka.

<EligibilityQuery>
  <PatientOIB>98765432109</PatientOIB>
  <QueryDate>2026-04-20</QueryDate>
</EligibilityQuery>

4.2 eRecept (elektroničko propisivanje)

Kreiranje elektroničkog recepta koji ljekarna dohvati po OIB-u pacijenta. Lijekovi referenciraju ATC kod.

<CreatePrescription>
  <PatientOIB>98765432109</PatientOIB>
  <PrescriberID>123456789</PrescriberID>
  <Medications>
    <Medication>
      <ATCCode>J01CR02</ATCCode>
      <Name>Amoksiclav 1g</Name>
      <Dose>1 tbl 3x dnevno</Dose>
      <Duration>7 dana</Duration>
      <Quantity>21</Quantity>
    </Medication>
  </Medications>
  <DiagnosisCode>J20.9</DiagnosisCode>
  <IssueDate>2026-04-20T14:30:00</IssueDate>
</CreatePrescription>

4.3 eUputnica (elektronička uputnica)

Upućivanje pacijenta na specijalista, laboratorij ili dijagnostiku. Sadrži HZZO šifre usluga.

<CreateReferral>
  <PatientOIB>98765432109</PatientOIB>
  <ReferringPhysicianID>123456789</ReferringPhysicianID>
  <TargetServiceCode>22031</TargetServiceCode>
  <!-- 22031 = RTG pluća -->
  <Urgency>STANDARD</Urgency>
  <ClinicalInfo>Sumnja na bronhitis, 7 dana kašljanja</ClinicalInfo>
  <DiagnosisCode>J20.9</DiagnosisCode>
</CreateReferral>

4.4 Izvješće poslije pregleda

Strukturirani medicinski nalaz po CDA R2 specifikaciji. Različiti template-i za različite grane (fizioterapija ima "eFizikalna terapija" template).

<ExaminationReport>
  <PatientOIB>98765432109</PatientOIB>
  <ExaminationDate>2026-04-20T14:30:00</ExaminationDate>
  <ExaminerID>123456789</ExaminerID>
  <DiagnosisList>
    <Diagnosis>
      <Code>J20.9</Code>
      <Description>Akutni bronhitis, nespecificirano</Description>
    </Diagnosis>
  </DiagnosisList>
  <Findings>Auskultatorno: disanje čujno, bez pjevušenja...</Findings>
  <Recommendations>Mirovanje, tekućina, kontrolni za 7 dana</Recommendations>
</ExaminationReport>

5. FHIR integracija (novija specifikacija)

CEZIH 2025+ podržava FHIR R4 za dio podataka. FHIR resources su dostupni REST-ful:

• GET /fhir/Patient/{oib} — demografski podaci
• GET /fhir/MedicationRequest?patient={oib} — povijest recepta
• POST /fhir/Observation — dodavanje mjerenja (VAS, krvni tlak)
• GET /fhir/DiagnosticReport?patient={oib} — dohvat laboratorijskih nalaza

FHIR je još uvijek komplement, ne zamjena za SOAP. Za eRecept i eUputnicu obavezno SOAP.

6. Testno okruženje

HZZO pruža testno CEZIH okruženje na zasebnom endpoint-u (cezih-test.hzzo.hr). Testne AKD kartice se dobijaju kroz FINA posebnim zahtjevom.

Testiranje mora pokriti:

• Autentikacija različitih tipova korisnika (liječnik, sestra, stomatolog)
• Happy path: eRecept, eUputnica, izvještaj
• Edge cases: isteken certifikat, mrežni timeout, nevažeći OIB
• Storno operacije (pogrešno poslane poruke)

7. Certifikacija softvera

Za produkcijsku integraciju vaš softver mora biti certificiran od strane HZZO-a. Proces:

1. Prijava HZZO-u — zahtjev za pristup testnom okruženju
2. NDA i ugovor — potpisivanje ugovora o pristupu CEZIH-u
3. Testno testiranje — 6-12 tjedana development + testiranje
4. Certifikacijski test — HZZO provodi formalno testiranje
5. Produkcijski pristup — odobrenje i credentials za produkciju

Cijeli proces traje 3-6 mjeseci minimum. Trošak: HZZO ne naplaćuje, ali interni development je značajan (2-4 osobe, full-time).

8. KLINIKAhub implementacija

Naš stack za CEZIH integraciju:

• Node.js (Express) za SOAP klijent (soap paket)
• node-forge za X.509 certifikat parsing i digitalno potpisivanje
• xmldom + xmlbuilder2 za XML generiranje
• better-sqlite3 za lokalnu cache session tokena
• pcsclite za komunikaciju sa smart card readerom preko USB

Frontend radi preko REST API-ja prema našem backend-u, nikada direktno prema CEZIH-u. Ovo omogućava keširanje, rate limiting, i bolju UX.

Česta pitanja