Preflight (dry-run)

Suchý beh validácie pred odoslaním. Pre faktúru z Agent API použite POST /v1/agent/invoices/{id}/preflight; pre vlastné UBL/CII POST /v1/agent/peppol/preflight, ktorý zvaliduje vaše 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.

Faktúra vytvorená cez Agent API

Faktúru vytvorenú cez POST /v1/agent/invoices kontrolujte cez POST /v1/agent/invoices/{id}/preflight (scope invoice:read, bez tela). Zvaliduje presne to UBL, ktoré odošle POST /v1/agent/peppol/send/{id}, a príjemcu odvodí z DIČ odberateľa na faktúre. Nezapisuje do DB a neúčtuje kredit. Podrobnosti: Odporúčaný tok.

curl -X POST https://api.efaktura.sk/v1/agent/invoices/$INVOICE_ID/preflight \
  -H "X-API-Key: efk_pk_test_..." \
  -H "X-Organization-Id: $SENDER_ORG_ID"

{
  "data": {
    "send_ready": true,
    "validator_unavailable": false,
    "validation": { "ran": true, "valid": true, "error_count": 0, "warning_count": 0 },
    "repair": [],
    "recipient": { "peppol_id": "0245:2010101010", "found": true },
    "assembly": { "attachments_bytes": 0 }
  }
}

Vlastné UBL/CII: 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, takže 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 (odberateľa), napr. 0245:DIČ odberateľa. 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.

receiverPeppolId je vždy príjemca (odberateľ, 0245:DIČ), nikdy vaše vlastné ID ani ID dodávateľa. Pri vlastnom ID by SMP lookup našiel vás a send_ready: true by bol zavádzajúci.

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.