ValidáciaValidation

Päť validačných vrstiev od XML po slovenské pravidlá.Five validation layers from XML to Slovak rules.

2 min čítania2 min read

#l1
#l4
#l5
#schematron
#peppol bis billing 3.0
#en 16931
#validation

#l1
#l4
#l5
#schematron
#peppol bis billing 3.0
#en 16931
#validation

Päť vrstiev. Prvá fatálna chyba zastaví ďalšie a dokument sa neodošle.

Vrstva	Čo kontroluje	Pri chybe
`L1`	Správne utvorené XML	FATAL
`L2`	Schéma UBL 2.1 (XSD)	FATAL
`L3`	EN 16931 (CEN Schematron)	FATAL alebo WARNING
`L4`	Peppol BIS Billing 3.0 (Schematron)	FATAL
`L5`	Slovenské pravidlá podľa transpozície BIS	FATAL alebo WARNING

Každá vrstva hlási vlastný výsledok

Vrstvy L2, L3 a L4 bežia ako jeden reťazec, takže sa pravidlá nespúšťajú dvakrát. Napriek tomu má každá vlastný výsledok — nález sa priradí podľa toho, ktorá sada pravidiel ho vyrobila.

Hodnota vrstvy je OK, WARNING, FATAL alebo SKIPPED.

SKIPPED neznamená „prešlo”. Znamená, že vrstva vôbec nebežala, lebo reťazec sa zastavil skôr: chyba XSD zastaví L3 aj L4, fatálna chyba na L1 zastaví všetko ostatné. „Neoverené” a „v poriadku” sa nikdy nezlejú do jednej hodnoty.

Vrstva L5 môže navyše vrátiť ERROR — slovenskú sadu pravidiel sa nepodarilo spustiť. Dokument to nezastaví, ale do upozornení pribudne nález s ruleId SK_ENGINE, aby bolo z odpovede zrejmé, že slovenské pravidlá overené neboli.

Čo kontroluje slovenská vrstva

Vrstva L5 sa spúšťa, keď je dodávateľ slovenský subjekt. Rozlišuje dve závažnosti — fatálna chyba dokument zastaví, upozornenie ho len označí a pošle ďalej.

Fatálne: chýbajúca schéma 0245 pri identifikátoroch, neúplná adresa dodávateľa alebo odberateľa.
Upozornenie: podozrivý formát DIČ alebo IČO, chýbajúca právna forma, nezrovnalosti pri daňovom zástupcovi.

Výsledok validácie cez API

GET /api/v1/invoices/{id}/validation
X-Api-Key: …

Vracia posledný verdikt uložený k faktúre. Výsledky sú append-only — opakovaná validácia po oprave pridá nový záznam a starý zostáva v histórii.

Stav	Kedy
`200`	verdikt existuje
`202`	faktúra je ešte `PENDING` alebo `VALIDATING`; `retry_after` aj hlavička `Retry-After` hovoria, o koľko sekúnd skúsiť znova
`404`	faktúra neexistuje — alebo je z čias pred zavedením zápisu výsledkov a verdikt už nedostane

{
  "valid": false,
  "overallSeverity": "FATAL",
  "validationLevels": {
    "L1_xml": "OK",
    "L2_xsd": "OK",
    "L3_en16931": "OK",
    "L4_peppol": "FATAL",
    "L5_sk": "SKIPPED"
  },
  "errors": [{
    "ruleId": "PEPPOL-EN16931-R001",
    "level": 4,
    "ruleSet": "PEPPOL",
    "severity": "FATAL",
    "message": "Business process MUST be provided.",
    "location": "/Invoice[1]/cbc:ProfileID"
  }],
  "warnings": [],
  "durationMs": 1840
}

Príklad je skrátený — odpoveď nesie aj id, invoiceId, organizationId a createdAt, takže sa dá rozlíšiť, ktorý beh validácie verdikt vyrobil.

Nálezy sú tu v origináli: message je anglický text Schematronu a location je XPath. Práve tie potrebujete, keď problém riešite s dodávateľom svojho ERP. ruleId je stabilný identifikátor pravidla, takže sa naň dá naviazať vlastný preklad alebo mapovanie na polia vo vašom systéme.

Ak chcete hotové slovenské texty priamo z API, použite predbežnú validáciu — tá vracia title, explanation a fix podľa hlavičky Accept-Language, a to ešte pred odoslaním dokumentu.

Odpoveď tohto endpointu používa camelCase (overallSeverity, validationLevels), na rozdiel od zvyšku v1 API aj predbežnej validácie, ktoré používajú snake_case.

Five layers. The first fatal error stops the rest and the document is not sent.

Layer	What it checks	On failure
`L1`	Well-formed XML	FATAL
`L2`	UBL 2.1 schema (XSD)	FATAL
`L3`	EN 16931 (CEN Schematron)	FATAL or WARNING
`L4`	Peppol BIS Billing 3.0 (Schematron)	FATAL
`L5`	Slovak rules per the BIS transposition	FATAL or WARNING

Every layer reports its own result

Layers L2, L3 and L4 run as a single chain, so the rules are never executed twice. Each layer still reports its own result — a finding is attributed to the rule set that produced it.

A layer is OK, WARNING, FATAL or SKIPPED.

SKIPPED does not mean “passed”. It means the layer never ran because the chain stopped earlier: an XSD error stops both L3 and L4, a fatal error at L1 stops everything else. “Not checked” and “fine” never collapse into the same value.

Layer L5 can additionally return ERROR — the Slovak rule set failed to execute. This does not stop the document, but a finding with ruleId SK_ENGINE is added to the warnings so the response makes it obvious that the Slovak rules were not verified.

What the Slovak layer checks

Layer L5 runs when the supplier is a Slovak entity. It has two severities — a fatal error stops the document, a warning only flags it and lets it through.

Fatal: a missing 0245 scheme on identifiers, an incomplete supplier or buyer address.
Warning: a suspicious tax ID or company ID format, a missing legal form, tax-representative inconsistencies.

Validation result via the API

GET /api/v1/invoices/{id}/validation
X-Api-Key: …

Returns the latest verdict stored for the invoice. Results are append-only — revalidating after a fix adds a new record and the previous one stays in history.

Status	When
`200`	a verdict exists
`202`	the invoice is still `PENDING` or `VALIDATING`; both `retry_after` and the `Retry-After` header tell you how many seconds to wait
`404`	the invoice does not exist — or predates result persistence and will never get a verdict

{
  "valid": false,
  "overallSeverity": "FATAL",
  "validationLevels": {
    "L1_xml": "OK",
    "L2_xsd": "OK",
    "L3_en16931": "OK",
    "L4_peppol": "FATAL",
    "L5_sk": "SKIPPED"
  },
  "errors": [{
    "ruleId": "PEPPOL-EN16931-R001",
    "level": 4,
    "ruleSet": "PEPPOL",
    "severity": "FATAL",
    "message": "Business process MUST be provided.",
    "location": "/Invoice[1]/cbc:ProfileID"
  }],
  "warnings": [],
  "durationMs": 1840
}

The example is trimmed — the response also carries id, invoiceId, organizationId and createdAt, so you can tell which validation run produced the verdict.

Findings come back verbatim here: message is the original Schematron text and location is an XPath. Those are exactly what you need when working the problem with your ERP vendor. ruleId is a stable rule identifier, so you can safely build your own translation or a mapping onto fields in your system on top of it.

If you want ready-made localized text straight from the API, use pre-flight validation — it returns title, explanation and fix according to the Accept-Language header, and it does so before the document is sent.

This endpoint’s response uses camelCase (overallSeverity, validationLevels), unlike the rest of the v1 API and pre-flight validation, which use snake_case.