Plánované a hromadné odosielanie Peppol faktúr

Faktúra odoslaná cez Peppol má odísť v deň svojho vyhotovenia — platforma preto podržané odoslania pustí najneskôr tak, aby odišli do 21:00(Europe/Bratislava). Namiesto odosielania faktúra po faktúre si viete zvoliť, aby sa odoslania cez deň hromadili a odišli naraz — buď v presný čas, alebo na váš pokyn.

Režimy odosielania

Raw-UBL cesty (POST /peppol/connector/send, CSV konektor, SAPI-SK, SFTP) sa režimom odosielania neriadia — vždy odosielajú hneď (konektor má na to vlastný parameter dispatch: later). Aj tieto cesty ale podliehajú ochrane dátumu vyhotovenia nižšie.

Nastavenie (send-settings)

PUT /v1/agent/peppol/send-settings
X-API-Key: efk_pk_live_...
X-Organization-Id: 0a2c1f3e-…
Content-Type: application/json

{
  "send_mode": "scheduled",
  "send_time": "18:00"
}

{
  "data": {
    "send_mode": "scheduled",
    "send_time": "18:00",
    "timezone": "Europe/Bratislava",
    "deadline": "21:00"
  }
}

send_time je povinný pri scheduled a najneskôr 21:00; pri immediate/manual sa zahodí (GET potom vráti null). Jediná podporovaná timezone je Europe/Bratislava — lehoty vychádzajú zo zákona o DPH. Neplatné telo vráti 400 VALIDATION_ERROR s details po poliach. Zmena sa zapisuje do auditného logu organizácie.

Odosielanie, keď je faktúra podržaná

POST /v1/agent/peppol/send/{invoiceId} a POST /v1/agent/peppol/send/batch fungujú rovnako ako doteraz — len v scheduled/manual režime namiesto zaradenia faktúru podržia.

POST /v1/agent/peppol/send/b1f0d7a2-…
X-API-Key: efk_pk_live_...
X-Organization-Id: 0a2c1f3e-…

HTTP/1.1 202
{
  "data": {
    "invoice_id": "b1f0d7a2-…",
    "status": "scheduled",
    "send_at": "2026-09-23T16:00:00.000Z"
  }
}

Pri dávke sa rovnakým spôsobom podrží celá dávka; jednotlivé faktúry, ktoré nesplnia validáciu (vrátane ochrany dátumu vyhotovenia nižšie), sú aj tak vypísané v skipped:

POST /v1/agent/peppol/send/batch
X-API-Key: efk_pk_live_...
X-Organization-Id: 0a2c1f3e-…

{ "invoiceIds": ["b1f0d7a2-…", "c2a1e8b3-…"] }

HTTP/1.1 202
{
  "data": {
    "batch_id": null,
    "status": "scheduled",
    "send_at": "2026-09-23T16:00:00.000Z",
    "queued": 0,
    "scheduled": 1,
    "skipped": [
      { "id": "c2a1e8b3-…", "reason": "INVOICE_ISSUE_DATE_NOT_SEND_DATE: …" }
    ],
    "total": 2
  }
}

Manuálne uvoľnenie (batches/send)

Uvoľní všetky podržané odoslania organizácie pre režim volajúceho kľúča (live/test) hneď — bez tela požiadavky. Odoslanie, ktoré medzičasom prestalo vyhovovať (napr. prešiel deň vyhotovenia), skončí ako error a vyvolá webhook peppol.document.failed.

POST /v1/agent/peppol/batches/send
X-API-Key: efk_pk_live_...
X-Organization-Id: 0a2c1f3e-…

HTTP/1.1 202
{
  "data": {
    "batch_id": "8b2e1c4a-…",
    "queued": 42,
    "skipped": []
  }
}

Fronta a stavy

GET /v1/agent/peppol/queue
X-API-Key: efk_pk_live_...
X-Organization-Id: 0a2c1f3e-…

HTTP/1.1 200
{
  "data": {
    "scheduled": 5000,
    "queued": 0,
    "sending": 40,
    "sent_today": 12300,
    "failed": 3,
    "estimated_finish": "19:42",
    "safety_cutoff": "19:48",
    "deadline": "21:00",
    "send_mode": "scheduled",
    "send_time": "18:00",
    "timezone": "Europe/Bratislava"
  }
}

estimated_finish a safety_cutoff sú odhady za celú platformu (zdieľaný Access Point), nie len za vašu organizáciu — pri veľkom objeme na platforme sa preto môžu meniť v priebehu dňa. sent_today a failed počítajú aktuálny deň v Europe/ Bratislava.

Stav jednotlivej faktúry vracia GET /v1/agent/peppol/status/{invoiceId} rovnako ako doteraz, s novou hodnotou state:

Bezpečnostný uzáver

Aj v scheduled/manual režime platí automatická poistka: platforma priebežne počíta safety_cutoff — čas, do ktorého musí uvoľniť každé podržané odoslanie, aby stihlo odísť do 21:00aj s rezervou 30 minút na opakovania pri prechodných chybách. Pri 40 000 čakajúcich odoslaniach a kapacite ~120/min vychádza uzáver na 14:56. Po uzávere sa nové odoslania spracujú hneď, aj keď je organizácia v manual režime a klient batches/send nezavolal. Podržané odoslanie z predchádzajúceho dňa sa uvoľní okamžite (a padne na ochranu dátumu vyhotovenia nižšie, ak je gate aktívny).

Ochrana dátumu vyhotovenia

Podľa FAQ Finančnej správy k e-Faktúre (11.9.2026, príklad 74) je pri e-faktúre odoslanej cez poskytovateľa doručovacích služieb dňom vyhotovenia deň jej odovzdania — a dátum vyhotovenia na doklade sa musí zhodovať so skutočným dňom odoslania. Právny základ: § 85o ods. 9, 11 a 12 zákona č. 222/2004 Z. z. o dani z pridanej hodnoty (report v momente vyhotovenia, splnený odovzdaním poskytovateľovi doručovacích služieb; pokuta do 10 000 €, pri opakovanom porušení do 100 000 €). Pravidlo o zhode dátumov je výklad Finančnej správy k tomuto ustanoveniu, nie doslovné znenie zákona; pre záväzný výklad vo vašom prípade sa poraďte s daňovým poradcom.

HTTP/1.1 422
{
  "error": "INVOICE_ISSUE_DATE_NOT_SEND_DATE",
  "message": "INVOICE_ISSUE_DATE_NOT_SEND_DATE: Dátum vyhotovenia faktúry (01.01.2027) sa musí zhodovať s dňom odoslania cez Peppol (03.01.2027). Upravte dátum vyhotovenia na dnešný deň a odošlite faktúru znova."
}

POST /send/{invoiceId} vráti chybu okamžite (v tomto neštandardnom plochom tvare, viď Chybové kódy); dávkové volanie vypíše faktúru v skipped; podržané odoslanie na ňu padne pri uvoľnení; raw-UBL/konektor/SAPI/SFTP pošlú rovnakú správu a vyvolajú webhook peppol.document.failed. Náprava: vystavte doklad znova s dnešným dátumom, plánujte odoslania tak, aby odišli v ten istý deň, a send_time nikdy nenastavujte po 21:00. Pred 1.1.2027 gate neplatí.

Veľké objemy

Odosielanie zdieľa jeden Access Point pre celú platformu, tempo je preto PEPPOL_SEND_CAPACITY_PER_MINUTE (konzervatívny odhad, orientačne ~120/min) rozdelené spravodlivo medzi organizácie — jedna veľká dávka nezablokuje ostatných. Odoslania podržané pri prechodnej chybe Access Pointu sa opakujú automaticky do ~30 minút (6 pokusov, exponenciálne od 1 minúty). Odhad estimated_finish z GET /queue je zámerne konzervatívny — počítajte s rezervou pri plánovaní send_time.

Chybové kódy