Odporúčaný tok

Ako poskladať vystavenie a odoslanie faktúry cez Agent API: vytvoriť, voliteľne skontrolovať jedným volaním, odoslať a sledovať stav.

Poradie volaní

Preflight je len pomôcka. Odoslanie dokument zvaliduje znova, takže preflight nemusíte volať pred každým odoslaním.

Preflight faktúry

POST /v1/agent/invoices/{id}/preflight (scope invoice:read) zvaliduje presne ten dokument, ktorý sa odošle (vrátane príloh a Peppol ID) a overí príjemcu odvodeného z DIČ odberateľa. Nikdy nezapisuje a nič neúčtuje.

{
  "data": {
    "send_ready": true,
    "validator_unavailable": false,
    "validation": { "ran": true, "valid": true, "error_count": 0, "warning_count": 1 },
    "repair": [
      { "field": "…", "code": "…", "message": "…", "severity": "warning" }
    ],
    "recipient": { "peppol_id": "0245:2010101010", "found": true },
    "assembly": { "attachments_bytes": 20480 }
  }
}

Náhľad XML pred odoslaním

GET /v1/agent/invoices/{id}/xml pred odoslaním vracia presne ten dokument, ktorý sa odošle, vrátane príloh a Peppol ID odosielateľa aj príjemcu (hlavička X-Efaktura-Ubl-Source: preview). Ak sú údaje odberateľa neúplné, náhľad sa vráti aj tak, len bez EndpointID príjemcu. Problém s prílohou vráti 422.

Server-Timing

Každá odpoveď /v1/agent/* nesie hlavičku Server-Timing: total;dur=<ms>. Oba preflight endpointy pridávajú validate a recipient, preflight faktúry aj assemble (všetko v ms). Hlavička je cez CORS dostupná aj v prehliadači.

Timeouty a opakovanie

Nastavte klientský timeout 10 s. Opakujte iba s rovnakým Idempotency-Key. Pri odpovedi mimo 2xx čítajte JSON telo chyby.

<?php
$ch = curl_init('https://api.efaktura.sk/v1/agent/invoices/' . $id . '/preflight');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'X-Organization-Id: ' . $orgId,
        'Content-Type: application/json',
    ],
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($raw === false) {
    // sieťová chyba alebo timeout: opakujte s rovnakým Idempotency-Key
}
$body = json_decode($raw, true); // 2xx aj chybová odpoveď sú JSON
if ($status >= 200 && $status < 300) {
    $sendReady = $body['data']['send_ready'];
} else {
    // $body obsahuje náš popis chyby
}