Preflight (dry-run)

Suchý beh validácie cez POST /v1/agent/peppol/preflight. Zvaliduje vaše UBL/CII XML proti EN 16931 + Peppol BIS Billing 3.0 (a SK FS overlayu) a voliteľne overí príjemcu v SMP — bez zápisu do DB a bez strhnutia kreditu. Použite ho tesne pred POST /v1/agent/peppol/send/{invoiceId}, aby ste chyby zachytili skôr, než doklad pošlete do siete.

Na rozdiel od partnerskej validácie (session, telo partnerId) je preflight súčasťou Agent API — autentifikuje sa hlavičkou X-API-Key aX-Organization-Id, scope invoice:read. Navyše vie urobiť SMP lookup príjemcu a vrátiť normalizované BIS 3.0 UBL.

Endpoint

Metóda	Cesta	Scope	Hlavičky
POST	`/v1/agent/peppol/preflight`	`invoice:read`	`X-API-Key`, `X-Organization-Id`

Endpoint nezapisuje do DB ani neúčtuje kredit — je bezpečné ho volať opakovane v slučke „oprav → preflight → odošli“.

Telo požiadavky

Pole	Typ	Povinné	Popis
`receiverPeppolId`	string	Nie	Peppol identifikátor príjemcu (napr. 0245:DIČ). Keď je uvedený, vykoná sa aj SMP lookup a vyplní sa pole recipient.
`document`	objekt	Áno	Zdrojový doklad — viď nižšie.
`document.format`	`ubl` \| `cii`	Áno	Formát zdrojového XML.
`document.xmlBase64`	string (base64)	Áno	Base64 zakódované UBL / CII XML.

POST /v1/agent/peppol/preflight
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…
Content-Type: application/json

{
  "receiverPeppolId": "0245:2123456789",
  "document": {
    "format": "ubl",
    "xmlBase64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+..."
  }
}

Odpoveď

Odpoveď je 200 vždy, keď kontrola mohla prebehnúť — samotný výsledok je v poli send_ready. Keď validačný runtime nebol dostupný, je send_ready: null a validator_unavailable: true (namiesto chyby 5xx).

{
  "data": {
    "send_ready": true,
    "validator_unavailable": false,
    "validation": {
      "ran": true,
      "valid": true,
      "error_count": 0,
      "warning_count": 1
    },
    "repair": [
      {
        "field": "cac:TaxTotal",
        "code": "BR-CO-15",
        "message": "Invoice total with VAT must equal total without VAT plus the VAT amount.",
        "severity": "error"
      }
    ],
    "recipient": {
      "peppol_id": "0245:2123456789",
      "found": true,
      "sml_state": "active"
    },
    "normalized_ubl_base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+..."
  }
}

Pole	Typ	Popis
`send_ready`	boolean \| null	true = doklad je pripravený na odoslanie (validný, bez chýb). null, keď validátor nebol dostupný.
`validator_unavailable`	boolean	true, ak validačný runtime nebol dostupný — send_ready je vtedy null.
`validation`	objekt	Súhrn behu: ran, valid, error_count, warning_count.
`repair`	pole objektov	Nálezy / návrhy opráv: field, code, message, severity (error \| warning).
`recipient`	objekt \| null	Výsledok SMP lookupu príjemcu, ak bol receiverPeppolId uvedený; inak null. Viď Overenie príjemcu.
`normalized_ubl_base64`	string \| null	Base64 znormalizovaného BIS 3.0 UBL (z CII konvertované, doplnené defaulty).

Chyby

Keď doklad chýba alebo sa nedá rozparsovať, endpoint vráti 400 s VALIDATION_ERROR. Validačné nálezy samotného dokladu nie sú chyba 4xx — sú vždy súčasťou 200 odpovede v poliach send_ready / repair.

Kód	Význam
`400`	Doklad chýba alebo sa nedá rozparsovať.
`401`	Neplatný alebo chýbajúci API kľúč.
`403`	Chýbajúci scope invoice:read alebo neplatná organizácia.

Odporúčaný postup

Pred každým odoslaním zavolajte preflight; ak je send_ready: false, opravte položky z poľa repair (severity error blokujú, warning nie) a zopakujte. Až pri send_ready: true volajte POST /v1/agent/peppol/send/{invoiceId}. Príjemcu viete overiť aj samostatne — viď Overenie príjemcu.