Preflight (dry run)

A dry run of validation before sending. For an invoice from the Agent API use POST /v1/agent/invoices/{id}/preflight; for your own UBL/CII use POST /v1/agent/peppol/preflight, which validates your XML against EN 16931 + Peppol BIS Billing 3.0 (and the SK FS overlay), and optionally looks up the recipient in the SMP, with no DB writes and no credit charge. Use it right before POST /v1/agent/peppol/send/{invoiceId}, to catch errors before you send the document to the network.

Unlike partner validation (session, partnerId in the body), preflight is part of the Agent API: it authenticates with the X-API-Key andX-Organization-Id headers, scope invoice:read. It can additionally do an SMP lookup of the recipient and return normalized BIS 3.0 UBL.

Invoice created through the Agent API

Check an invoice created via POST /v1/agent/invoices with POST /v1/agent/invoices/{id}/preflight (scope invoice:read, no body). It validates exactly the UBL that POST /v1/agent/peppol/send/{id} will send, and derives the recipient from the buyer DIČ on the invoice. It doesn't write to the DB or charge credit. Details: Recommended flow.

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 }
  }
}

Your own UBL/CII: endpoint

Method	Path	Scope	Headers
POST	`/v1/agent/peppol/preflight`	`invoice:read`	`X-API-Key`, `X-Organization-Id`

This endpoint doesn't write to the DB or charge credit, so it's safe to call repeatedly in a "fix → preflight → send" loop.

Request body

Field	Type	Required	Description
`receiverPeppolId`	string	No	Peppol identifier of the RECIPIENT (the buyer, e.g. the buyer's 0245:DIČ). When provided, an SMP lookup also runs and fills in the recipient field.
`document`	object	Yes	Source document: see below.
`document.format`	`ubl` \| `cii`	Yes	Format of the source XML.
`document.xmlBase64`	string (base64)	Yes	Base64-encoded UBL / CII XML.

receiverPeppolId is always the recipient (the buyer, 0245:DIČ), never your own or the supplier's id. With your own id the SMP lookup would find you and send_ready: true would be misleading.

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+..."
  }
}

Response

The response is 200 whenever the check could run. The actual result is in the send_ready field. When the validation runtime wasn't available, send_ready: null and validator_unavailable: true (instead of a 5xx error).

{
  "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+..."
  }
}

Field	Type	Description
`send_ready`	boolean \| null	true = the document is ready to send (valid, no errors). null when the validator wasn't available.
`validator_unavailable`	boolean	true if the validation runtime wasn't available, so send_ready is then null.
`validation`	object	Run summary: ran, valid, error_count, warning_count.
`repair`	array of objects	Findings / suggested fixes: field, code, message, severity (error \| warning).
`recipient`	object \| null	Result of the recipient SMP lookup, if receiverPeppolId was provided; otherwise null. See Recipient lookup.
`normalized_ubl_base64`	string \| null	Base64 of the normalized BIS 3.0 UBL (converted from CII, defaults filled in).

Errors

When the document is missing or can't be parsed, the endpoint returns 400 with VALIDATION_ERROR. Validation findings about the document itself are not a 4xx error: they're always part of the 200 response, in the send_ready / repair fields.

Code	Meaning
`400`	The document is missing or can't be parsed.
`401`	Invalid or missing API key.
`403`	Missing invoice:read scope or invalid organization.

Recommended flow

Call preflight before every send; if send_ready: false, fix the items in the repair field (severity error blocks, warning doesn't) and try again. Only call POST /v1/agent/peppol/send/{invoiceId} once send_ready: true. You can also verify the recipient separately: see Recipient lookup.