Faktúry

Vystavenie faktúry cez POST /v1/agent/invoices. Predávajúci sa odvodzuje z organizácie (X-Organization-Id), kupujúci z poľa customer alebo z existujúceho customer_id. Číslovanie, výpočet DPH, PDF a QR kód prebiehajú server‑side rovnako ako pri ručnom vystavení.

Endpoint

Na endpoint sa vzťahuje per‑org rate limit 30 požiadaviek / minútu (nad rámec globálneho limitu kľúča). Mena faktúry je vždy EUR.

Telo požiadavky

Objekt customer

Maps na tabuľku kontaktov. Pri inline zákazníkovi sa vytvorí nový kontakt typu customer.

Objekt položky (items[])

Kategórie DPH pri 0 % (mapovanie do UBL)

Sadzba 0 % sama o sebe nestačí — EN 16931 rozlišuje prečo je položka bez dane. Kategóriu určuje tax_treatment položky a exemption_reason dokladu (BT-120):

Kompletný príklad

POST /v1/agent/invoices
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…
Idempotency-Key: 7f0c2a4e-order-2026-042
Content-Type: application/json

{
  "customer": {
    "name": "Odberateľ s.r.o.",
    "ico": "87654321",
    "dic": "2010101010",
    "ic_dph": "SK2010101010",
    "address": {
      "street": "Obchodná 5",
      "city": "Košice",
      "postalCode": "04001",
      "country": "SK"
    },
    "email": "fakturacia@odberatel.sk",
    "phone": "+421900123456"
  },
  "items": [
    {
      "description": "Servisné práce",
      "quantity": 2,
      "unit": "hod",
      "unit_price": 50,
      "vat_rate": 23
    },
    {
      "description": "Náhradný diel",
      "quantity": 1,
      "unit": "ks",
      "unit_price": 80,
      "vat_rate": 23
    }
  ],
  "payment_method": "bank_transfer",
  "due_days": 14,
  "note": "Ďakujeme za dôveru.",
  "order_number": "OBJ-2026-042",
  "invoice_number": "2026-000042"
}

Odpoveď

HTTP/1.1 201 Created

{
  "id": "b1f0d7a2-…",
  "invoice_number": "2026001",
  "status": "issued",
  "customer": { "id": "…", "name": "Odberateľ s.r.o." },
  "items": [ … ],
  "subtotal": "180.00",
  "vat_total": "41.40",
  "total": "221.40",
  "currency": "EUR",
  "issue_date": "2026-06-22",
  "due_date": "2026-07-06",
  "pdf_url": "https://…",
  "created_at": "2026-06-22T10:00:00.000Z"
}

Hodnota id sa používa pri odoslaní cez Peppol (POST /v1/agent/peppol/send/{id}) aj pri zisťovaní stavu.

Idempotencia (retry bez duplikátov)

POST /v1/agent/invoices podporuje voliteľnú hlavičku Idempotency-Key: primárny mechanizmus ochrany pred duplicitnými faktúrami pri automatických retry. Rovnaký kľúč s rovnakým telom vráti uloženú odpoveď (faktúra sa nevytvorí druhýkrát a číslo radu sa neminie); rovnaký kľúč s iným telom, alebo súbežná požiadavka s rovnakým kľúčom, vráti 409. Bez hlavičky sa správanie nemení.

Stiahnutie PDF / XML

Vystavenú faktúru viete stiahnuť ako PDF aj ako UBL XML. Obe operácie sú scopeinvoice:download a vracajú súbor ako prílohu (Content-Disposition: attachment).

Po odoslaní cez Peppol je XML presné UBL, ktoré bolo odovzdané Prístupovému bodu (uchované pre zákonnú archiváciu e‑faktúr). Pred odoslaním endpoint vráti náhľad vygenerovaný tým istým builderom, ktorý používa odosielanie — bez zápisu do DB, bez strhnutia kreditu a bez vložených príloh (tie sa do dokladu vkladajú až pri odoslaní). Ktorý variant ste dostali, hovorí hlavička X-Efaktura-Ubl-Source: archive | preview. Náhľad použite na overenie mapovania business JSON → UBL (jednotky, kategórie DPH, strany). Názov súboru je číslo faktúry ({numberPrefix}{number}.xml).

GET /v1/agent/invoices/b1f0d7a2-…/xml
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Disposition: attachment; filename="OF2026001.xml"
X-Efaktura-Ubl-Source: preview

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">…</Invoice>

Požiadavky na úplnosť pre Peppol

Faktúra vystavená cez tento endpoint je v poriadku ako bežný doklad, ale aby ju bolo možné odoslať cez Peppol, výsledné UBL XML musí prejsť EN 16931 + Peppol BIS Billing 3.0 a navyše slovenským FS overlayom. SK overlay sa uplatní, keď je krajina predávajúceho SK, a vyžaduje:

Smerovanie na príjemcu v Peppol prebieha cez DIČ kupujúceho (sandbox: 9915:<DIČ>, produkcia: 0245:<DIČ>). Pre korektnú VAT kategorizáciu (BR‑S/BR‑E) má mať predávajúci aj kupujúci ic_dph. Pred odoslaním viete UBL XML pre‑validovať: viď Validácia.

Faktúru vystavenú týmto endpointom odošlete cez POST /v1/agent/peppol/send/{id}; tesne pred odoslaním ju viete suchým behom (dry‑run) skontrolovať cez Preflight : to je validácia z Agent API (bez session), bez zápisu do DB a bez strhnutia kreditu. Ak si naopak UBL/CII skladáte sami a nechcete ísť cez /agent/invoices, jedným volaním zvalidujete, rezervujete kredit a odošlete cez Konektor.