Predbežná validácia

Pred odoslaním dokumentu si ho môžete dať overiť. Endpoint prejde rovnakým päťúrovňovým validačným reťazcom, aký beží po odoslaní — takže čo prejde tu, prejde aj tam. Nevytvára faktúru, nič neukladá a nespotrebúva kredit.

Overenie dokumentu

POST /api/v1/documents/validate
X-Api-Key: …
Content-Type: application/json
Accept-Language: sk

{
  "xml_content": "<Invoice xmlns=…>…</Invoice>",
  "receiver_peppol_id": "0245:2120984085"
}

Povinné je jediné pole — xml_content. Prítomnosť receiver_peppol_id zapína aj overenie príjemcu cez Peppol SMP; bez neho sa overuje len samotný dokument.

Odpoveď má vždy stav 200, aj keď je dokument neplatný. Neplatná faktúra nie je chyba volania — verdikt je súčasťou dát.

{
  "valid": false,
  "network_ready": false,
  "overall_severity": "FATAL",
  "validation_levels": {
    "L1_xml": "OK", "L2_xsd": "OK", "L3_en16931": "OK",
    "L4_peppol": "FATAL", "L5_sk": "WARNING"
  },
  "errors": [{
    "rule_id": "PEPPOL-EN16931-R001",
    "rule_set": "PEPPOL",
    "level": 4,
    "severity": "FATAL",
    "raw_message": "Business process MUST be provided.",
    "raw_location": "/Invoice[1]/cbc:ProfileID",
    "title": "Chýba identifikátor obchodného procesu",
    "explanation": "Peppol vyžaduje, aby faktúra deklarovala…",
    "fix": "Doplňte element cbc:ProfileID s hodnotou…",
    "location": "Hlavička faktúry → Profil",
    "localized": true
  }],
  "warnings": [],
  "truncated": false,
  "total_findings": 1,
  "document": { "document_type": "INVOICE", "invoice_number": "FA-2026-001", "…": "…" },
  "receiver": {
    "peppol_id": "0245:2120984085",
    "registered": true,
    "supports_document_type": false,
    "reason": "NOT_SERVICED",
    "checked_at": "2026-08-05T10:00:00Z"
  },
  "duration_ms": 1840
}

Nálezy sú lokalizované, originál zostáva

title, explanation, fix a location sa prekladajú podľa hlavičky Accept-Language (podporujeme sk a en; bez hlavičky sa použije en). Použitý jazyk vraciame v Content-Language.

Rovnaký tvar nálezu vracia aj GET /api/v1/invoices/{id}/validation — viď Validácia.

raw_message a raw_location sa neprekladajú nikdy — sú to originálny text Schematronu a XPath. Práve ich potrebujete, keď riešite problém s dodávateľom svojho ERP.

Ak pravidlo v katalógu ešte nemáme, localized je false a title obsahuje originálnu anglickú správu. Nález sa nikdy nestratí.

Päť úrovní validácie

Úroveň	Čo overuje
`L1_xml`	správnosť XML
`L2_xsd`	schéma UBL 2.1
`L3_en16931`	pravidlá EN 16931
`L4_peppol`	pravidlá Peppol BIS 3.0
`L5_sk`	slovenské národné pravidlá

Hodnoty sú OK, WARNING, FATAL alebo SKIPPED. SKIPPED znamená, že úroveň nebežala — typicky preto, že skončila skôr: zlyhanie na L1 zastaví všetko ostatné.

Pravidlá EN 16931 a Peppol BIS bežia v jednom reťazci, takže sa nikdy nespúšťajú dvakrát; každá úroveň napriek tomu hlási vlastný výsledok.

Úroveň L5_sk môže navyše vrátiť ERROR — slovenskú sadu pravidiel sa nepodarilo spustiť. Dokument to nezhodí, ale medzi upozorneniami nájdete nález s rule_id SK_ENGINE, aby bolo zrejmé, že slovenské pravidlá overené neboli.

Overenie príjemcu

network_ready je true, len keď je dokument platný a príjemca je v sieti a podporuje daný typ dokumentu. Obe polia — network_ready aj receiver — sú v odpovedi len vtedy, keď ste o overenie požiadali.

Pole reason rozlišuje tri situácie, ktoré sa nesmú zamieňať:

`reason`	Význam	Čo s tým
`NOT_REGISTERED`	príjemca nie je v Peppol sieti	overte jeho Peppol ID
`NOT_SERVICED`	príjemca je v sieti, ale nepodporuje tento typ dokumentu	overte typ dokumentu
`LOOKUP_UNAVAILABLE`	verdikt sa nezistil — SMP neodpovedalo	skúste o chvíľu znova

Pri LOOKUP_UNAVAILABLE sú registered aj supports_document_type null, nie false — neoverili sme, že príjemca neexistuje, len sme sa to nedozvedeli.

Overenie príjemcu bez dokumentu

Ak potrebujete len zistiť, či je zákazník dosiahnuteľný, dokument posielať nemusíte:

GET /api/v1/participants/0245:2120984085/reachability?document_type=INVOICE

Odpoveď má rovnaký tvar ako blok receiver vyššie.

Limity

dokument najviac 10 MB, rovnako ako pri odoslaní; väčší vráti 413
najviac 500 nálezov v odpovedi; pri skrátení je truncated: true a total_findings nesie skutočný počet
ak je validačná služba dočasne nedostupná, vrátime 503 a hlavičku Retry-After; odosielanie faktúr to neovplyvňuje
počet validácií a dopytov na dostupnosť za minútu závisí od balíka — od 10 validácií a 30 dopytov pri MINI po 300 validácií a 120 dopytov pri ENTERPRISE (Limity a kvóty). Obe cesty majú vlastné počítadlo — validovanie v cykle vám nevyčerpá kvótu na odosielanie faktúr. Váš limit a zostatok nesú hlavičky RateLimit-Policy a RateLimit, pri prekročení príde 429 s Retry-After