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

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

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

Pole	Typ	Povinné	Popis
`customer_id`	UUID	Podmienečne	ID existujúceho zákazníka. Povinné je customer_id ALEBO customer.
`customer`	objekt	Podmienečne	Inline zákazník (vytvorí sa kontakt). Viď tabuľku nižšie.
`items`	pole objektov	Áno	Aspoň 1 položka. Viď tabuľku položiek nižšie.
`vehicle_id`	UUID	Nie	ID existujúceho vozidla (modul vozidiel).
`vehicle_plate`	string (≤20)	Nie	ŠPZ vozidla — vyhľadá sa vozidlo (normalizuje sa na veľké písmená bez medzier).
`payment_method`	`bank_transfer` \| `cash` \| `card`	Nie	Default bank_transfer (mapuje sa interne na „bank“).
`due_days`	int 0–365	Nie	Splatnosť v dňoch od dátumu vystavenia. Default 14. Pozn.: ak má organizácia nastavené defaultDueDays, použije sa to.
`note`	string (≤2000)	Nie	Poznámka na faktúre (viditeľná zákazníkovi).
`internal_note`	string (≤2000)	Nie	Interná poznámka (nie na PDF).
`issue_date`	YYYY-MM-DD	Nie	Dátum vystavenia. Default dnes.
`delivery_date`	YYYY-MM-DD	Nie	Dátum dodania. Default = issue_date.
`order_number`	string (≤100)	Nie	Číslo objednávky (orderReference).
`already_paid`	boolean	Nie	Default false. Pri true sa faktúra vystaví so stavom „paid“ a plnou úhradou k dátumu vystavenia.
`attachments`	array (≤10)	Nie	Prílohy (PDF/JPG/PNG, base64). Pri odoslaní cez Peppol sa vložia priamo do dokladu → dorazia príjemcovi aj na iné systémy (napr. Doklado).

Každá príloha je objekt { filename, mime_code, base64_content } (voliteľne description). Povolené typy: PDF, JPG, PNG; spolu max 10 MB (Peppol limit). Prílohu možno pridať aj dodatočne k existujúcej faktúre cez POST /v1/agent/invoices/{id}/attachments a spravovať cez GET / DELETE na tej istej ceste.

Objekt customer

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

Pole	Typ	Povinné	Popis
`name`	string 1–300	Áno	Názov firmy alebo meno zákazníka.
`ico`	string (8 cifier)	Nie	IČO — presne 8 číslic.
`dic`	string	Nie	DIČ — 10 cifier (SK) alebo kód krajiny + 8–10 cifier (napr. CZ12345678). Normalizuje sa na veľké písmená bez medzier.
`ic_dph`	string (SK + 10 cifier)	Nie	IČ DPH vo formáte SK2120035951.
`address`	string \| objekt	Nie	Buď celý reťazec, alebo objekt { street, city, postalCode, country }. Pre Peppol je potrebný objekt s úplnou adresou.
`email`	email (≤254)	Nie	Prázdny string sa berie ako neuvedené.
`phone`	string (≤20)	Nie	Prázdny string sa berie ako neuvedené.

address ako objekt vyžaduje neprázdne street, city, postalCode a 2‑písmenový country. Ak pošlete adresu len ako reťazec, reťazec sa uloží do poľa street a country sa nastaví na "SK"; city a postalCode zostanú prázdne — pre Peppol nedostatočné (viď nižšie). Pre Peppol odosielanie vždy posielajte úplný adresný objekt.

Objekt položky (items[])

Pole	Typ	Povinné	Popis
`description`	string 1–500	Áno	Názov / popis položky.
`quantity`	číslo > 0	Áno	Množstvo (akceptuje aj číselný string).
`unit`	enum	Nie	Default ks. Povolené: ks, hod, l, m, km, súbor.
`unit_price`	číslo ≥ 0	Áno	Jednotková cena bez DPH.
`vat_rate`	int	Áno	Sadzba DPH v percentách. Povolené: 0, 5, 19, 23.

Ak organizácia nie je platcom DPH (nemá ic_dph ani isVatPayer), žiadna položka nesmie mať vat_rate> 0 — inak požiadavka zlyhá s VALIDATION_ERROR („Nie ste platcom DPH“). Faktúra dostane výnimku „Dodávateľ nie je platcom DPH“.

Kompletný príklad

POST /v1/agent/invoices
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…
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"
}

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. Pri opakovaní požiadaviek si id ukladajte, aby ste predišli duplicitným faktúram.

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).

Metóda	Cesta	Scope	Content-Type
GET	`/v1/agent/invoices/{id}/pdf`	`invoice:download`	`application/pdf`
GET	`/v1/agent/invoices/{id}/xml`	`invoice:download`	`application/xml`

XML je presné UBL, ktoré bolo odovzdané Prístupovému bodu pri odoslaní cez Peppol (uchované pre zákonnú archiváciu e‑faktúr). Pokiaľ faktúra ešte nebola odoslaná cez Peppol, XML nie je k dispozícii a endpoint vráti 404 („XML pre túto faktúru nie je k dispozícii.“). 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"

<?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:

Pravidlo (BT)	Pole	Zdroj v API
`SK-BT-35`	Ulica predávajúceho	address.street organizácie
`SK-BT-37`	Mesto predávajúceho	address.city organizácie
`SK-BT-38`	PSČ predávajúceho	address.postalCode organizácie
`SK-BT-50`	Ulica kupujúceho	customer.address.street
`SK-BT-52`	Mesto kupujúceho	customer.address.city
`SK-BT-53`	PSČ kupujúceho	customer.address.postalCode
`SK-BT-30`	schemeID pri registračnom ID predávajúceho	odvodené z IČO/DIČ organizácie
`SK-BT-47`	schemeID pri registračnom ID kupujúceho	odvodené z IČO/DIČ kupujúceho

Ak chýba čo i len jedno z polí adresy predávajúceho alebo kupujúceho, odoslanie cez Peppol zlyhá na SK overlayi (napr. SK-BT-35-REQUIRED). Preto pri zakladaní organizácie aj pri vytváraní zákazníka vždy posielajte úplnú adresu (street + city + postalCode + country).

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.