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 predvolene mena firmy, inú viď currency nižšie.

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",
  "exchange_rate": null,
  "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.

Cudzia mena a kurz

Bez currency sa faktúra vystaví v mene firmy (EUR pre slovenskú, CZK pre českú). Inú menu pošlite v poli currency (EUR, CZK, USD, GBP, PLN, CHF, HUF, RON, BGN, SEK, DKK, NOK, HRK, RSD, UAH, RUB, TRY, CNY, JPY, CAD, AUD). Pole exchange_rate je desatinné číslo v texte väčšie ako 0 (najviac 7 celých a 8 desatinných miest): počet jednotiek currency na jednu jednotku domácej meny firmy. Slovenská firma, 1 EUR = 1.0842 USD: "exchange_rate": "1.0842".

{
  "customer_id": "550e8400-…",
  "currency": "USD",
  "exchange_rate": "1.0842",
  "items": [ { "description": "Konzultácie", "quantity": 1, "unit": "ks", "unit_price": 500, "vat_rate": 0 } ]
}

Bez exchange_rate na faktúre v cudzej mene server doplní kurz ECB (slovenská firma) alebo ČNB (česká firma) k dátumu zdaniteľného plnenia (delivery_date, inak issue_date). Ak sa kurz nepodarí získať, faktúra sa aj tak vytvorí s exchange_rate: null. Odpoveď POST /v1/agent/invoices aj GET /v1/agent/invoices/{id} nesú exchange_rate (string alebo null) vedľa currency.

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>

Vzájomný zápočet

Zápočet vydanej faktúry s prijatým dokladom tej istej protistrany (napr. platforma fakturuje klientovi službu a jeho odmenu eviduje ako prijatý doklad). Jedno volanie zapíše úhradu so spôsobom offset na faktúru aj na prijatý doklad a obe spáruje. Len pre slovenské firmy. Ak potrebujete uhradiť len jednu stranu, použite POST /v1/agent/invoices/{id}/payments.

POST /v1/agent/offsets
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…
Idempotency-Key: 3c8e1d52-settlement-2026-10
Content-Type: application/json

{
  "invoice_id": "b1f0d7a2-…",
  "expense_id": "5b7e91c4-…",
  "amount": "110.70",
  "offset_date": "2026-10-31",
  "reference": "VYUCT-2026-10"
}

HTTP/1.1 201 Created

{
  "data": {
    "id": "3d9a60f8-…",
    "invoice_id": "b1f0d7a2-…",
    "expense_id": "5b7e91c4-…",
    "amount": "110.70",
    "currency": "EUR",
    "offset_date": "2026-10-31",
    "reference": "VYUCT-2026-10",
    "note": null,
    "accounting_program": { "status": "pending", "reason": null },
    "created_at": "2026-10-31T09:12:00.000Z",
    "invoice": { "id": "b1f0d7a2-…", "total": "270.60", "paid_amount": "110.70", "outstanding": "159.90", "status": "partially_paid" },
    "expense": { "id": "5b7e91c4-…", "total": "110.70", "paid_amount": "110.70", "outstanding": "0.00", "payment_status": "paid" }
  }
}

Úhrady zápočtu sa nedajú zmazať samostatne, ani doklady, ktoré zápočet uhradil (409). Ak niektorý doklad neexistuje, odpoveď je 404. Chyby 400:

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 skontrolujte suchým behom (dry‑run) cez POST /v1/agent/invoices/{id}/preflight (viď Odporúčaný tok): bez zápisu do DB a bez strhnutia kreditu. Samostatný /peppol/preflight je len pre UBL/CII, ktoré si skladáte sami. Ak si UBL/CII skladáte sami a nechcete ísť cez /agent/invoices, jedným volaním zvalidujete, rezervujete kredit a odošlete cez Konektor.