Validácia

Preflight kontrola UBL XML proti EN 16931 + Peppol BIS Billing 3.0 a slovenskému FS overlayu cez POST /v1/partner/einvoice/validate. Použite ju pred odoslaním vlastného XML, aby ste chyby zachytili skôr, než doklad pošlete do siete.

Tento endpoint je súčasťou partnerského portálu a autentifikuje sa session‑ou (prihlásenie do portálu), nie hlavičkou X-API-Key. V tele preto posielate partnerId. Slúži na pre‑validáciu XML, ktoré si skladáte sami; faktúry vystavené cez POST /v1/agent/invoices generujú UBL automaticky.

Ak integrujete cez Agent API (kľúč X-API-Key), použite namiesto toho Preflight (POST /v1/agent/peppol/preflight) — tá istá validácia bez session, navyše so SMP lookupom príjemcu a normalizovaným BIS 3.0 UBL, stále bez zápisu do DB a bez strhnutia kreditu.

Endpoint

Metóda	Cesta	Autentifikácia
POST	`/v1/partner/einvoice/validate`	Partnerská session (portál)

Telo požiadavky

Pole	Typ	Povinné	Popis
`partnerId`	UUID	Áno	ID partnera, ku ktorému máte prístup.
`xml`	string (1–4 000 000 znakov)	Áno	UBL Invoice / CreditNote XML na validáciu.

POST /v1/partner/einvoice/validate
Content-Type: application/json

{
  "partnerId": "7b8d…",
  "xml": "<?xml version=\"1.0\"?><Invoice …>…</Invoice>"
}

Odpoveď

Validátor je 3‑vrstvový (EN 16931 / Peppol + SK FS overlay). Ak validačný runtime nie je k dispozícii, odpoveď to indikuje cez available: false namiesto chyby 5xx.

{
  "data": {
    "available": true,
    "valid": false,
    "errorCount": 2,
    "warningCount": 1,
    "issues": [
      {
        "layer": "sk-fs-overlay",
        "severity": "error",
        "code": "SK-BT-35-REQUIRED",
        "message": "Seller address line is mandatory for Slovak e-invoice export.",
        "location": "Invoice/AccountingSupplierParty/Party/PostalAddress/StreetName",
        "businessTerm": "BT-35"
      }
    ]
  }
}

Pole	Typ	Popis
`available`	boolean	Či bol validačný runtime dostupný. Pri false sú ostatné polia prázdne / null.
`valid`	boolean \| null	true, ak nie je žiadna chyba (errorCount === 0). null, ak available je false.
`errorCount`	int	Počet chýb (severity error) — blokujú odoslanie.
`warningCount`	int	Počet upozornení (severity warning) — neblokujú, ale odporúčame opraviť.
`issues`	pole objektov	Zoznam nálezov. Viď tabuľku nižšie.

Objekt issue

Pole	Typ	Popis
`layer`	`en16931-peppol` \| `sk-fs-overlay`	Vrstva, ktorá nález vygenerovala.
`severity`	`error` \| `warning`	error blokuje odoslanie, warning nie.
`code`	string	Strojovo čitateľný kód (napr. SK-BT-35-REQUIRED).
`message`	string	Ľudsky čitateľný popis.
`location`	string (voliteľné)	XPath na chybné miesto v dokumente.
`businessTerm`	string (voliteľné)	EN 16931 business term (napr. BT-35).

Kedy validovať

Validáciu spustite vždy, keď generujete UBL XML vlastnou logikou a chcete si overiť kompletnosť pred odoslaním. SK FS overlay sa aktivuje len pre faktúry so slovenským predávajúcim (Country/IdentificationCode = SK); inbound faktúry od zahraničných dodávateľov sa validujú len proti EN 16931 / Peppol. Najčastejšie chyby sa týkajú chýbajúcej adresy predávajúceho/kupujúceho (SK-BT-35/37/38, SK-BT-50/52/53) a chýbajúceho schemeID pri registračnom identifikátore (SK-BT-30/47) — rovnaké pravidlá, ktoré blokujú odoslanie. Viac kontextu v sekcii Faktúry.