Konektor (odoslanie jedným volaním)

Jedno-prúdové odoslanie cez POST /v1/agent/peppol/connector/send. Jedno volanie spraví všetko: zvaliduje dodané UBL/CII XML (+ voliteľná auto-oprava normalizáciou), rezervuje kredit a zaradí doklad na odoslanie cez Peppol. Náhrada za reťazenie preflight → send — s tromi bezpečnostnými poistkami.

Endpoint je súčasťou Agent API — autentifikuje sa hlavičkami X-API-Key a X-Organization-Id, scope invoice:send. Test kľúč (efk_pk_test_…) smeruje do sandbox AP a nikdy neúčtuje kredit; live kľúč odošle naostro a spotrebuje kredit.

Endpoint

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

Bezpečnostné poistky

Tri poistky robia z jedného volania bezpečnú operáciu aj pri opakovaní alebo čiastočnom zlyhaní:

Poistka	Správanie
Idempotency-Key je povinný	Vynechanie hlavičky vráti `400`. Rovnaký kľúč s iným telom požiadavky vráti `409`. Replay (rovnaký kľúč aj telo) vráti uloženú odpoveď a neodošle druhýkrát.
Kredit až pri pripravenosti	Kredit sa rezervuje len keď je doklad `send_ready: true`. Doklad s chybami sa zamietne ešte pred rezerváciou — kredit nikdy nepretečie a strhnutie nastane práve raz pri odoslaní (žiadne dvojité účtovanie).
Auto-oprava je opt-in	Normalizačné zmeny sa aplikujú len pri `options.autoRepair: true` a každá je vypísaná v `repair_applied` — upravený doklad sa nikdy neodošle ticho. Bez `autoRepair` sa doklad vyžadujúci úpravu zamietne ako `needs_repair`.

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.
`options.autoRepair`	boolean	Nie	Keď true, normalizačné zmeny (BIS 3.0 identifikátory, CII→UBL) sa aplikujú a doklad sa odošle. Predvolene false.
`options.validateOnly`	boolean	Nie	Keď true, vykoná len validáciu (status validated) — nerezervuje kredit ani neodosiela.
`options.dispatch`	`now` \| `later`	Nie	Predvolene now (rezervuje kredit a hneď zaradí na odoslanie). later len pripraví (stage) doklad bez strhnutia kreditu a vráti staged_id — viď „Priprav teraz, odošli neskôr“ nižšie.

POST /v1/agent/peppol/connector/send
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…
Idempotency-Key: 7d1f2c9a-3b4e-4f5a-8c6d-1e2f3a4b5c6d
Content-Type: application/json

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

Odpoveď

Odpoveď je 200 vždy, keď operácia prebehla — samotný výsledok je v poli status (queued / rejected / validated) a send_ready. Polia invoice_id, document_id a job_id sú vyplnené len pri status: queued.

{
  "data": {
    "status": "queued",
    "invoice_id": "b1f0d7a2-…",
    "document_id": "0245:2123456789#OF2026001",
    "job_id": "0245:2123456789#OF2026001",
    "send_ready": true,
    "validator_unavailable": false,
    "validation": {
      "ran": true,
      "valid": true,
      "error_count": 0,
      "warning_count": 1
    },
    "repair": [],
    "repair_applied": [
      { "change": "Doplnené Peppol BIS 3.0 identifikátory (CustomizationID/ProfileID)." }
    ],
    "recipient": {
      "peppol_id": "0245:2123456789",
      "found": true,
      "sml_state": "active"
    }
  }
}

Pole	Typ	Popis
`status`	`queued` \| `rejected` \| `validated`	queued = kredit rezervovaný + zaradené na odoslanie; rejected = neodoslané (viď reason); validated = len validácia (validateOnly).
`reason`	string \| null	Dôvod zamietnutia (len pri rejected): validation \| needs_repair \| credit \| validator_unavailable.
`invoice_id`	string \| null	ID vytvorenej faktúry (len pri queued).
`document_id`	string \| null	Identifikátor dokladu v prenose (len pri queued).
`job_id`	string \| null	ID zaradeného odosielacieho jobu (len pri queued).
`send_ready`	boolean \| null	true = doklad bol pripravený na odoslanie. 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).
`repair_applied`	pole objektov	Konkrétne zmeny aplikované auto-opravou: field, change. Vyplnené len keď autoRepair=true a doklad sa odoslal.
`recipient`	objekt \| null	Výsledok SMP lookupu príjemcu, ak bol receiverPeppolId uvedený; inak null.

Priprav teraz, odošli neskôr

Keď chcete doklad najprv pripraviť (zvalidovať) a odoslať ho až neskôr — napríklad po schválení — pošlite options.dispatch: "later". Pri pripravenom doklade sa nerezervuje ani nestrháva kredit; odpoveď má status: staged a vráti staged_id, ktorým doklad odošlete samostatným volaním. Predvolené dispatch: "now" sa správa ako doteraz (rezervuje kredit a hneď zaradí na odoslanie).

POST /v1/agent/peppol/connector/send
{
  "document": { "format": "ubl", "xmlBase64": "PD94bWwg..." },
  "options": { "dispatch": "later" }
}

→ 200
{
  "data": {
    "status": "staged",
    "staged_id": "5f2a9c1b-…",
    "send_ready": true,
    "validation": { "ran": true, "valid": true, "error_count": 0, "warning_count": 0 }
  }
}

Pripravený doklad odošlete cez POST /v1/agent/peppol/connector/dispatch/{stagedId} (scope invoice:send). Až teraz sa skontroluje a rezervuje kredit a doklad sa zaradí na odoslanie. Volanie je prirodzene idempotentné — pripravený doklad sa pri prvom odoslaní zmaže, takže opakovanie s rovnakým stagedId vráti 404. Pripravené doklady sa držia prechodne (7 dní) a sú viazané na organizáciu.

Metóda	Cesta	Scope	Hlavičky
POST	`/v1/agent/peppol/connector/dispatch/{stagedId}`	`invoice:send`	`X-API-Key`, `X-Organization-Id`

POST /v1/agent/peppol/connector/dispatch/5f2a9c1b-…

→ 200
{
  "data": {
    "status": "queued",
    "invoice_id": "b1f0d7a2-…",
    "document_id": "0245:2123456789#OF2026001",
    "job_id": "0245:2123456789#OF2026001"
  }
}

Pole	Typ	Popis
`status`	`queued` \| `rejected`	queued = kredit rezervovaný + zaradené na odoslanie; rejected = neodoslané (viď reason).
`reason`	string \| null	Dôvod zamietnutia (len pri rejected). Aktuálne credit = nedostatok kreditu.
`invoice_id`	string \| null	ID vytvorenej faktúry (len pri queued).
`document_id`	string \| null	Identifikátor dokladu v prenose (len pri queued).
`job_id`	string \| null	ID zaradeného odosielacieho jobu (len pri queued).

404 dostanete aj keď stagedId neexistuje, aj keď už bol raz odoslaný — pripravený doklad sa po odoslaní zmaže, takže dispatch nikdy neodošle dvakrát.

Chyby

Validačné nálezy samotného dokladu nie sú chyba 4xx — sú vždy súčasťou 200 odpovede v poliach status / repair. Stavové kódy 4xx sú len pre chyby protokolu:

Kód	Význam
`400`	Chýba hlavička Idempotency-Key, alebo je telo / doklad neplatné.
`401`	Neplatný alebo chýbajúci API kľúč.
`403`	Chýbajúci scope invoice:send alebo neplatná organizácia.
`409`	Idempotency-Key už bol použitý s iným telom požiadavky.

Idempotency-Key je povinný. Použite stabilný kľúč odvodený od čísla faktúry (nie náhodný pri každom retry) — inak by retry po timeoute mohol vytvoriť druhé odoslanie. Replay s rovnakým kľúčom aj telom je bezpečný a vráti pôvodný výsledok.

Súvislosti

Na hromadné odoslanie z tabuľky použite CSV ingest. Príjemcu viete overiť samostatne cez Overenie príjemcu a dôkaz o doručení po odoslaní cez Dôkaz o doručení.