Registracija

Za developere

API dokumentacija

Uvod

Dokumentacija

Pristupne podatke (SOFTWARE-API-TOKEN) za slanje e-dokumenata iz vašeg sustava zatražite putem maila rh/ukod//ofni.

Adrese testnog, odnosno produkcijskog API-a su: https://api-test.doku.hr i https://api.doku.hr.

Adrese testnog, odnosno produkcijskog PORTAL-a su: https://portal-test.doku.hr i https://portal.doku.hr.

Provjera dostupnosti API-a

Ping
GET /
Primjer odgovora 200 OK 

{
  "message": "Hello TEST @ 28.11.2025. 19:15:22"
}

1. Zahtjev (HTTP request)

Svi zahtjevi u zaglavlju moraju imati:

Zaglavlje Vrijednost/Primjer Opis
Content-Type application/json -
Authorization API-TOKEN 6020b357-6a6d-491c-bcda-ef0d5ade6c55 API token korisnika u čije ime se obavljaju API operacije
SOFTWARE-API-TOKEN 191dc405-a779-4535-99df-94aa763369a3 Jedinstveni identifikator vašeg sustava

*API token - Token kojeg korisnik postavlja u vaš sustav kako bi mogao slati e-dokumente, a dostupan mu je u portalu po registraciji i verifikaciji pretinca.

2. Odgovor (HTTP response)

Navedeni su primjeri uspješnog odgovra, te neki od općenitih neuspješnih odgovora.

U zaglavlju (HTTP response header) svakog odgovora nalazi se Doku-Request-Id, jedinstveni identifikator zahtjeva/poziva prema API-u. Generiran je od strane sustava pri svakom zapirmanju zahtjeva, odnosno slanju odgovora.

HTTP STATUS CODE Opis
200 OK Uspješan odgovor u JSON formatu. Polje "data" je opcionalno i ne mora biti prisutno u odgovoru. 

{
  "message": "Opis rezultata akcije",
  "data": {}
}
400 BAD REQUEST Klijentska greška pri slanju zahtjeva. Odgovor u JSON formatu. Polje "details" je opcionalno i ne mora biti prisutno u odgovoru. 

{
  "code": "ERROR",
  "message": "Opis greške.",
  "details": []
}




{
  "code": "MODEL_VALIDATION_FAILED",
  "message": "Prisutne su validacijske greške (1)",
  "data": [
    {
      "property": "name",
      "message": "Property 'name' must not be null",
      "attemptedValue": ""
    }
  ]
}




{
  "code": "XSD_VALIDATION_FAILED",
  "message": "XSD validacija neuspješna (1)",
  "data": [
    {
      "severity": "Error",
      "message": "XML is invalid line 14, column 17 cvc-complex-type.2.4.a:
      Invalid content was found starting with element '{"urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2":IssueTime}'...
    }
  ]
}




{
  "code": "XSL_VALIDATION_FAILED",
  "message": "XSL validacija neuspješna (1)",
  "data": [
    {
      "severity": "Warning",
      "message": "[UBL-CR-681]-A UBL invoice should not include the PaymentMeans InstructionNote]"
    }
  ]
}
401 UNAUTHORIZED Greška u autentikaciji. Opis u odgovoru. 

{
  "code": "HTTP_401_001",
  "message": "Invalid Authorization HTTP header."
}
404 NOT FOUND Traženi resurs nije pronađen. Provjeriti ID resursa.
500 INTERNAL SERVER ERROR Iznimna i rijetka greška u obradi zahtjeva. Po pojavljivanju smo obavješteni o istoj i radimo na rješavanju problema.

3. Računi

Operacije nad ulaznim i izlaznim računima

3.1. Izlazni računi

Definirane su sljedeće operacije: uvoz izlaznog računa, lista izlaznih računa, detalji pojedinačnog izlaznog računa, preuzimanje izlaznog računa, fiskalizacija izlaznog računa, evidencija naplate izlaznog računa.

3.1.1. Upload izlaznog računa

POST /documents/invoices/upload
Parametar Pozicija Opis
xml body Base64 string XML dokumenta
Primjer zahtjeva 

{
  "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM..."
}
Primjer odgovora 200 OK 

{
  "id": int,
  "message": "string"
}

3.1.2. Lista izlaznih računa
GET /documents/invoices/outgoing
Parametar Tip podatka Pozicija Opis
page int QUERY STRING broj stranice
importedFrom datetime QUERY STRING od datuma importa, uključivo taj datum i vrijeme (npr: 2025-10-09T02:08:10). ISO 8601
importedTo datetime QUERY STRING do datuma importa, uključivo taj datum i vrijeme (npr: 2025-10-09T02:08:10). ISO 8601
issueDateFrom date QUERY STRING od datuma izdavanja, uključivo taj datum. ISO 8601
issueDateTo date QUERY STRING do datuma izdavanja, uključivo taj datum. ISO 8601
dueDateFrom date QUERY STRING od datuma dospijeća, uključivo taj datum. ISO 8601
dueDateTo date QUERY STRING do datuma dospijeća, uključivo taj datum. ISO 8601
Primjer odgovora 200 OK 

{
  "data": {
    "page": 1,
    "pageSize": 100,
    "pagesTotal": 1,
    "recordsFrom": 1,
    "recordsTo": 1,
    "recordsTotal": 1,
    "records": [
      {
        "id": 1,
        "status": "FISCALIZED",
        "name": "1/1/1",
        "receiver": {
          "name": "Tvrtka d.o.o.",
          "oib": "10472637205"
        },
        "issueDate": "2025-10-21",
        "dueDate": "2025-11-04",
        "payableAmount": 1238.5,
        "currency": "EUR"
      }
    ]
  }
}

3.1.3. Detalji izlaznog računa
GET /documents/invoices/outgoing/{id}
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
Primjer odgovora 200 OK 

{
  "data": {
    "id": 1,
    "name": "1/1/1",
    "status": "FISCALIZED",
    "receiver": {
      "name": "Tvrtka d.o.o.",
      "oib": "10472637205"
    },
    "issueDate": "2025-10-21",
    "dueDate": "2025-11-04",
    "payableAmount": 1238.5,
    "currency": "EUR",
    "history": [
      {                                            
        "status": "IMPORTED",                     
        "timestamp": "2025-11-08T12:50:25.36"
      },                                           
      {                                            
        "status": "FISCALIZED",                   
        "timestamp": "2025-11-08T12:54:50.86"
      },                                           
      {                                            
        "status": "SENT",                         
        "timestamp": "2025-11-08T12:55:44.58"
      },                                           
      {                                            
        "status": "DELIVERED",                    
        "timestamp": "2025-11-08T12:55:44.58"
      },
      {                                            
        "status": "MARKED_PAID",                    
        "timestamp": "2025-11-09T108:55:44.58"
      }
    ]             
  }
}

3.1.4. Preuzimanje izlaznog računa

GET /documents/invoices/outgoing/{id}/export
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
Primjer odgovora 200 OK 

{
  "data": {
    "xml": "BASE 64 UBL Invoice xml"
  }
}

3.1.5. Fiskalizacija izlaznog računa
POST /documents/invoices/outgoing/{id}/fiscalize
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
200 OK 

{
  "message": "Izlazni račun '1/1/1' je fiskaliziran."
}
400 BAD REQUEST 

{
  "code": "OUT_INV_FISC_001",
  "message": "Izlazni račun '1/1/1' je u nedozvoljenom statusu - 'FISCALIZED'. Fiskalizacija nije moguća."
}




{
  "code": "OUT_INV_FISC_002",
  "message": "Izlazni račun '1/1/1' nije fiskaliziran. Molimo pokušajte kasnije."
}




{
  "code": "OUT_INV_FISC_003",
  "message": "Ulazni račun '1/1/1' nije fiskaliziran. (greška od servisa za fiskalizaciju)"
}

3.1.6. Slanje izlaznog računa
POST /documents/invoices/outgoing/{id}/send
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
200 OK 

{
  "message": "Izlazni račun '1/1/1' je predan na slanje."
}
400 BAD REQUEST 

{
  "code": "SEND_ERROR",
  "message": "Opis greške"
}

3.1.7. Evidencija naplate izlaznog računa
POST /documents/invoices/outgoing/{id}/mark-paid
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
datumNaplate date BODY ISO 8601 date
naplaceniIznos decimal BODY
nacinPlacanja enum BODY Moguće vrijednosti: T (transakcijski račun), O (obračunsko plaćanje), Z (ostalo)
Primjer zahtjeva 

{
  "datumNaplate": "2025-10-28",
  "naplaceniIznos": 808.00,
  "nacinPlacanja": "T"
}
200 OK 

{
  "message": "Izlazni račun '1/1/1' je označen plaćen."
}
400 BAD REQUEST 

{
  "code": "OUT_INV_MARK_PAID_001",
  "message": "Izlazni račun '1/1/1' je u nedozvoljenom statusu - 'IMPORTED'. Označavanje naplate računa nije moguće."
}




{
  "code": "OUT_INV_MARK_PAID_002",
  "message": "Izlazni račun '1/1/1' nije označen plaćen. Molimo pokušajte kasnije."
}




{
  "code": "OUT_INV_MARK_PAID_003",
  "message": "Izlazni račun '1/1/1' nije označen plaćen. (greška od servisa za fiskalizaciju)"
}

3.2. Ulazni računi

Definirane su sljedeće operacije: lista ulaznih računa, detalji pojedinačnog ulaznog računa, preuzimanje ulaznog računa, fiskalizacija ulaznog računa, te odbijanje ulaznog računa.

3.2.1. Lista ulaznih računa

GET /documents/invoices/incoming
Parametar Tip podatka Pozicija Opis
page int QUERY STRING broj stranice
importedFrom datetime QUERY STRING od datuma importa, uključivo taj datum i vrijeme (npr: 2025-10-09T02:08:10). ISO 8601
importedTo datetime QUERY STRING do datuma importa, uključivo taj datum i vrijeme (npr: 2025-10-09T02:08:10). ISO 8601
issueDateFrom date QUERY STRING od datuma izdavanja, uključivo taj datum. ISO 8601
issueDateTo date QUERY STRING do datuma izdavanja, uključivo taj datum. ISO 8601
dueDateFrom date QUERY STRING od datuma dospijeća, uključivo taj datum. ISO 8601
dueDateTo date QUERY STRING do datuma dospijeća, uključivo taj datum. ISO 8601
Primjer odgovora 200 OK 

{
  "data": {
    "page": 1,
    "pageSize": 100,
    "pagesTotal": 1,
    "recordsFrom": 1,
    "recordsTo": 1,
    "recordsTotal": 1,
    "records": [
      {
        "id": 1,
        "status": "FISCALIZED",
        "name": "1/1/1",
        "sender": {
          "name": "Tvrtka d.o.o.",
          "oib": "10472637205"
        },
        "issueDate": "2025-10-21",
        "dueDate": "2025-11-04",
        "payableAmount": 1238.5,
        "currency": "EUR"
      }
    ]
  }
}

3.2.2. Detalji ulaznog računa

GET /documents/invoices/incoming/{id}
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
Primjer odgovora 200 OK 

{
  "data": {
    "id": 1,
    "name": "1/1/1",
    "status": "FISCALIZED",
    "sender": {
      "name": "Tvrtka d.o.o.",
      "oib": "10472637205"
    },
    "issueDate": "2025-10-21",
    "dueDate": "2025-11-04",
    "payableAmount": 1238.5,
    "currency": "EUR",
    "history": [
      {                                            
        "status": "IMPORTED",                     
        "timestamp": "2025-11-24T09:18:25.36"
      },                                           
      {                                            
        "status": "RECEIVED",                   
        "timestamp": "2025-11-24T09:18:50.85"
      },                                           
      {                                            
        "status": "FISCALIZED",                         
        "timestamp": "2025-11-24T09:18:44.12"
      },                                           
      {                                            
        "status": "REJECTED",                    
        "timestamp": "2025-11-24T09:19:11.78"
      }
    ]
  }
}

3.3.3. Preuzimanje ulaznog računa

GET /documents/invoices/incoming/{id}/export
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
Primjer odgovora 200 OK 

{
  "data": {
    "xml": "BASE 64 UBL Invoice xml"
  }
}

3.2.4. Fiskalizacija ulaznog računa

POST /documents/invoices/incoming/{id}/fiscalize
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
200 OK 

{
  "message": "Ulazni račun '1/1/1' je fiskaliziran."
}
400 BAD REQUEST 

{
  "code": "IN_INV_FISC_001",
  "message": "Ulazni račun '1/1/1' je u nedozvoljenom statusu - 'FISCALIZED'. Fiskalizacija nije moguća."
}




{
  "code": "IN_INV_FISC_002",
  "message": "Ulazni račun '1/1/1' nije fiskaliziran. Molimo pokušajte kasnije."
}




{
  "code": "IN_INV_FISC_003",
  "message": "Ulazni račun '1/1/1' nije fiskaliziran. (greška od servisa za fiskalizaciju)"
}

3.2.5. Odbijanje ulaznog računa

POST /documents/invoices/incoming/{id}/reject
Parametar Tip podatka Pozicija Opis
id int PATH ID dokumenta
datumOdbijanja date BODY ISO 8601 date
vrstaRazlogaOdbijanja enum BODY Moguće vrijednosti: N (neusklađenost podataka koji ne utječu na obračun poreza), U (neusklađenost podataka koji utječu na obračun poreza), O (ostalo)
razlogOdbijanja string BODY Razlog zbog kojeg se eRačun odbija. (1 - 1000 znakova)
Primjer zahtjeva 

{
  "datumOdbijanja": "2025-10-28",
  "vrstaRazlogaOdbijanja": "N",
  "razlogOdbijanja": "Krivi primatelj eRačuna"
}
200 OK 

{
  "message": "Ulazni račun '1/1/1' je označen odbijen."
}
400 BAD REQUEST 

{
  "code": "IN_INV_REJECT_001",
  "message": "Ulazni račun '1/1/1' je u nedozvoljenom statusu - 'REJECTED'. Odbijanje nije moguće."
}




{
  "code": "IN_INV_REJECT_002",
  "message": "Ulazni račun '1/1/1' nije odbijen. Molimo pokušajte kasnije."
}




{
  "code": "IN_INV_REJECT_003",
  "message": "Ulazni račun '1/1/1' nije odbijen. (greška od servisa za fiskalizaciju)"
}

4. Izvještavanje

Koristi se samo jedna metoda za evidenciju isporuke za koju nije moguće izdati eRačun

4.1. Evidencija isporuke za koju nije moguće izdati eRačun

POST /report/non-einvoice-delivery
Parametar Pozicija Opis
xml BODY Base64 string XML dokumenta
Primjer zahtjeva 

{
  "xml": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPEludm9pY2UgeG1sbnM..."
}
Primjer odgovora 200 OK 

{
  "message": "Evidencija isporuke/računa '1/1/1' za koju nije izdan eRačun je uspješna."
}

5. KPD

Pretraga KPD-a po kodu ili nazivu.

5.1. Pretraga

POST /kpd/search
Parametar Pozicija Opis
type BODY "CODE" ili "NAME"
Primjer zahtjeva 

{
  "type": "NAME",
  "value": "papir"
}
Primjer odgovora 200 OK 

{
  "data": [
    {
      "code": "13.10.72",
      "name": "Pređa od jute ili ostalih tekstilnih likovih vlakana; pređa od ostalih biljnih tekstilnih vlakana; papirna pređa"
    },
    {
      "code": "13.20.15",
      "name": "Tkanine od ostalih biljnih tekstilnih vlakana; tkanine od papirne pređe"
    }
  ]
}

6. Korisnički pretinac/račun

Upravljanje podatcima korisničkog pretinca

6.1. Registracija novog korisničkog računa/pretinca

POST /accounts
Primjer zahtjeva 

{
  "company": {
    "name": "Tvrtka d.o.o.",
    "oib": "01234567890",
    "mb": null,
    "street": "Ulica 5",
    "postCode": "21403",
    "city": "Sutivan",
    "country": "HRV",
    "email": "mailtvrtke@example.com",
    "phoneNumber": "+385777000"
  },
  "user": {
    "firstName": "Ime",
    "lastName": "Prezime",
    "email": "mailkorisnika@example.com"
  }
}
Primjer odgovora 200 OK 

{
  "message": "Registracija pretinca '01234567890' je uspješna"
  "data":
  {
    "activationNotificationEmail": "mailtvrtke@example.com",
    "password": "11223344",
    "apiToken": "23199e53-acb0-4ea4-a39a-00c765101f22"
  }
}