Hromadné odoslanie z CSV

Hromadný ingest cez POST /v1/agent/peppol/csv. Nahráte kanonické CSV, z každej faktúry sa zostaví Peppol BIS 3.0 UBL a urobí preflight; v režime send sa každá pripravená faktúra skontroluje na kredit a odošle. Chybné riadky a zlyhania jednotlivých faktúr sa reportujú v odpovedi — nikdy sa ticho nezahodia.

Endpoint je súčasťou Agent API — autentifikuje sa hlavičkami X-API-Key a X-Organization-Id, scope invoice:send. Dodávateľom je vždy odosielajúca organizácia (nikdy sa neberie z CSV).

Endpoint

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

Telo požiadavky

Pole	Typ	Povinné	Popis
`csvBase64`	string (base64)	Áno	Base64 zakódované kanonické CSV (UTF-8, BOM tolerovaný; oddeľovač , alebo ;).
`mode`	`preflight` \| `send`	Áno	preflight = len validácia (nerezervuje kredit, neodosiela); send = validácia + rezervácia kreditu + odoslanie pre každú pripravenú faktúru.
`autoRepair`	boolean	Nie	Keď true, normalizačné zmeny sa aplikujú a faktúra sa odošle; keď false (predvolené), faktúra vyžadujúca úpravu sa zamietne ako needs_repair (len v režime send).

POST /v1/agent/peppol/csv
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…
Content-Type: application/json

{
  "csvBase64": "aW52b2ljZV9udW1iZXIsaXNzdWVfZGF0ZSxjdXJyZW5jeSwuLi4=",
  "mode": "preflight"
}

Kanonické CSV

Jeden riadok = jedna položka faktúry. Riadky sa zoskupia do faktúr podľa invoice_number — faktúra s viacerými položkami má viac riadkov s rovnakým číslom (hlavičkové polia sa na každom riadku skupiny opakujú). Dátumy sú vo formáte RRRR-MM-DD, desatinné čísla s desatinnou bodkou (napr. 12.50).

Stĺpec	Povinný	Popis
`invoice_number`	Áno	Číslo faktúry; riadky s rovnakým číslom sa zoskupia do jednej faktúry.
`issue_date`	Áno	Dátum vystavenia (RRRR-MM-DD).
`due_date`	Nie	Dátum splatnosti (RRRR-MM-DD).
`tax_point_date`	Nie	Dátum dodania / daňový bod (RRRR-MM-DD).
`currency`	Áno	Mena dokladu (napr. EUR).
`payment_iban`	Nie	IBAN na úhradu.
`payment_vs`	Nie	Variabilný symbol.
`buyer_name`	Áno	Názov odberateľa.
`buyer_ico`	Nie	IČO odberateľa.
`buyer_ic_dph`	Nie	IČ DPH odberateľa.
`buyer_peppol_id`	Nie	Peppol ID odberateľa (napr. 0245:DIČ); keď je uvedené, urobí sa aj SMP lookup.
`buyer_street`	Nie	Ulica odberateľa.
`buyer_city`	Nie	Mesto odberateľa.
`buyer_zip`	Nie	PSČ odberateľa.
`buyer_country`	Nie	Kód krajiny (napr. SK).
`line_description`	Áno	Popis položky.
`line_quantity`	Áno	Množstvo (desatinné s bodkou).
`line_unit`	Nie	Merná jednotka (napr. ks, l, hod).
`line_unit_price`	Áno	Jednotková cena (desatinné s bodkou).
`line_vat_rate`	Áno	Sadzba DPH v % (napr. 23).
`line_discount`	Nie	Zľava na riadok.

Príklad CSV

Faktúra OF2026001 s dvoma položkami = dva riadky s rovnakým invoice_number (hlavičkové polia sa opakujú):

invoice_number,issue_date,due_date,currency,payment_iban,payment_vs,buyer_name,buyer_ico,buyer_ic_dph,buyer_peppol_id,buyer_street,buyer_city,buyer_zip,buyer_country,line_description,line_quantity,line_unit,line_unit_price,line_vat_rate,line_discount
OF2026001,2026-06-22,2026-07-06,EUR,SK3112000000198742637541,2026001,Firma ABC s.r.o.,12345678,SK2012345678,0245:2012345678,Hlavná 1,Bratislava,81101,SK,Výmena oleja,1,ks,45.00,23,0
OF2026001,2026-06-22,2026-07-06,EUR,SK3112000000198742637541,2026001,Firma ABC s.r.o.,12345678,SK2012345678,0245:2012345678,Hlavná 1,Bratislava,81101,SK,Motorový olej 5W-30,4,l,12.50,23,0

Odpoveď

Odpoveď je 200 a obsahuje summary (počty), invoices (výsledok po jednotlivých faktúrach) a row_errors (chyby na úrovni riadkov CSV).

{
  "data": {
    "summary": { "total": 2, "ready_or_queued": 1, "failed": 1 },
    "invoices": [
      {
        "invoice_number": "OF2026001",
        "send_ready": true,
        "status": "queued",
        "invoice_id": "b1f0d7a2-…",
        "validation": { "ran": true, "valid": true, "error_count": 0, "warning_count": 0 },
        "repair": []
      },
      {
        "invoice_number": "OF2026002",
        "send_ready": false,
        "status": "rejected",
        "reason": "validation",
        "validation": { "ran": true, "valid": false, "error_count": 1, "warning_count": 0 },
        "repair": [
          {
            "code": "BR-CO-15",
            "message": "Invoice total with VAT must equal total without VAT plus the VAT amount.",
            "severity": "error"
          }
        ]
      }
    ],
    "row_errors": [
      { "row": 5, "column": "line_vat_rate", "message": "Neplatné číslo (sadzba DPH)." }
    ]
  }
}

Pole	Typ	Popis
`summary`	objekt	total = počet zostavených faktúr; ready_or_queued = pripravené (preflight) alebo zaradené (send); failed = neúspešné.
`invoices`	pole objektov	Výsledok po jednotlivých faktúrach — viď tabuľku nižšie.
`row_errors`	pole objektov	Chyby na úrovni riadkov CSV: row (1-based), column (voliteľné), message.

Objekt invoice

Pole	Typ	Popis
`invoice_number`	string	Číslo faktúry z CSV.
`send_ready`	boolean \| null	Preflight verdikt; null, keď validátor nebol dostupný.
`status`	string	Len v režime send: queued \| rejected \| needs_repair \| failed.
`reason`	string	Dôvod zamietnutia / zlyhania: validation \| needs_repair \| credit \| validator_unavailable \| build.
`invoice_id`	string \| null	ID vytvorenej faktúry (len pri queued).
`validation`	objekt	Súhrn behu: ran, valid, error_count, warning_count.
`repair`	pole objektov	Nálezy validácie: field, code, message, severity.
`recipient`	objekt \| null	Výsledok SMP lookupu, ak CSV obsahoval buyer_peppol_id; inak null.
`message`	string	Ľudsky čitateľná správa (napr. dôvod build / credit zlyhania).

V režime send sa kredit rezervuje len pre faktúry, ktoré sú send_ready: true (a nevyžadujú úpravu, ak nie je autoRepair: true). Faktúra bez kreditu sa zamietne so reason: credit — ostatné faktúry v dávke sa spracujú nezávisle. Najprv si dávku otestujte v režime preflight.

Súvislosti

Na odoslanie jediného dokladu z hotového UBL/CII použite Konektor. Stav doručenia po odoslaní sledujte cez Prijímanie a stavy a Dôkaz o doručení.