← Povratak na validator

API Dokumentacija

Programski pristup HR e-Racun validaciji

Endpoint za validaciju

POST /api/validate

Validira XML racun kroz tri sloja validacije i vraca rezultate u JSON formatu:

Zahtjev

Posaljite multipart/form-data POST zahtjev s XML datotekom u polju file.

Primjeri koda

curl -X POST \
  -F "file=@invoice.xml" \
  https://validator.servisiram.hr/api/validate
import requests

url = "https://validator.servisiram.hr/api/validate"

with open("invoice.xml", "rb") as f:
    files = {"file": ("invoice.xml", f, "application/xml")}
    response = requests.post(url, files=files)

result = response.json()

if result["valid"]:
    print("Invoice is valid!")
else:
    print(f"Found {result['error_count']} errors:")
    for error in result["errors"]:
        print(f"  [{error['rule_id']}] {error['message']}")
const formData = new FormData();
formData.append("file", fileInput.files[0]);

fetch("/api/validate", {
    method: "POST",
    body: formData
})
.then(response => response.json())
.then(result => {
    if (result.valid) {
        console.log("Invoice is valid!");
    } else {
        console.log(`Found ${result.error_count} errors:`);
        result.errors.forEach(error => {
            console.log(`  [${error.rule_id}] ${error.message}`);
        });
    }
});

Format odgovora

Uspjesan odgovor (HTTP 200)

Vraca se kada je validacija zavrsena. Provjerite polje valid da odredite je li racun prosao validaciju.

{
  "valid": false,
  "filename": "invoice.xml",
  "profile_detected": "HR",
  "layers_used": ["PEPPOL", "XSD", "HR-CIUS"],
  "error_count": 4,
  "fatal_count": 2,
  "warning_count": 2,
  "errors_by_layer": {
    "PEPPOL": 1,
    "XSD": 1,
    "HR-CIUS": 2
  },
  "errors": [
    {
      "rule_id": "PEPPOL-EN16931-R003",
      "flag": "warning",
      "message": "[PEPPOL-EN16931-R003] - A buyer reference or purchase order reference MUST be provided.",
      "location": "/ubl-invoice:Invoice",
      "source": "PEPPOL"
    },
    {
      "rule_id": "XSD",
      "flag": "warning",
      "message": "Element 'cbc:InvalidElement' is not allowed...",
      "location": "",
      "source": "XSD"
    },
    {
      "rule_id": "HR-BR-2",
      "flag": "fatal",
      "message": "[HR-BR-2] - Racun mora imati vrijeme izdavanja...",
      "location": "/ubl-invoice:Invoice",
      "source": "HR-CIUS"
    },
    {
      "rule_id": "HR-BR-9",
      "flag": "fatal",
      "message": "[HR-BR-9] - OIB operatera mora biti naveden...",
      "location": "/ubl-invoice:Invoice/cac:AccountingSupplierParty/cac:Party",
      "source": "HR-CIUS"
    }
  ]
}

Odgovor za validan racun

{
  "valid": true,
  "filename": "invoice.xml",
  "profile_detected": "HR",
  "layers_used": ["PEPPOL", "XSD", "HR-CIUS"],
  "error_count": 0,
  "fatal_count": 0,
  "warning_count": 0,
  "errors_by_layer": {},
  "errors": []
}

Polja odgovora

Polje Tip Opis
valid boolean Je li racun prosao sva pravila validacije
filename string Originalno ime ucitane datoteke
profile_detected string Detektirani profil racuna (trenutno uvijek "HR")
layers_used array Koristeni slojevi validacije: "PEPPOL", "XSD", "HR-CIUS"
error_count integer Ukupan broj gresaka validacije
fatal_count integer Broj fatalnih gresaka (racun je nevalidan)
warning_count integer Broj upozorenja (informativno)
errors_by_layer object Broj gresaka po sloju validacije
errors array Lista gresaka validacije s detaljima

Polja objekta greske

Polje Tip Opis
rule_id string Identifikator pravila (npr. "XSD", "PEPPOL-EN16931-R003", "HR-BR-2")
flag string Ozbiljnost: "fatal", "error" ili "warning"
message string Opis greske razumljiv covjeku
location string XPath lokacija greske u XML dokumentu
source string Sloj validacije koji je proizveo gresku: "PEPPOL", "XSD" ili "HR-CIUS"

Odgovori s greskama

Status Uvjet Odgovor
400 Datoteka nije poslana {"error": "No file provided", "message": "..."}
400 Prazno polje datoteke {"error": "No file selected", "message": "..."}
400 Datoteka nije XML {"error": "Invalid file type", "message": "..."}
429 Prekoraceno ogranicenje zahtjeva Too Many Requests
500 Greska servera {"error": "Server error", "message": "..."}

Ogranicenja zahtjeva

Radi zastite od zlouporabe, API primjenjuje sljedeca ogranicenja po IP adresi:

Endpoint Ogranicenje
/api/validate 30 zahtjeva/minuta, 200 zahtjeva/sat
/upload 10 zahtjeva/minuta
Globalno (svi endpointi) 1000 zahtjeva/sat

Kada se prekoraci ogranicenje, API vraca HTTP status 429 Too Many Requests.

Dodatne informacije

Podrzani formati

Slojevi validacije

Validator provodi tri sloja validacije redom:

PEPPOL i XSD greske se prijavljuju kao upozorenja jer HR-CIUS pravila imaju prioritet za hrvatske racune.

Razrjesavanje konflikata

Dva PEPPOL pravila su automatski iskljucena za HR racune jer su u konfliktu s HR-CIUS zahtjevima:

Ogranicenje velicine datoteke

Maksimalna velicina datoteke: 16 MB