# efakturia.sk — návod pre integrátora

Ako napojiť ERP, CRM alebo e-shop na efakturia.sk: faktúry odosielate cez sieť
Peppol a prijaté doklady preberáte bez ručnej práce. Presná definícia všetkých
endpointov je v [openapi.yaml](https://efakturia.sk/integracia/openapi.yaml)
(OpenAPI 3.1, dá sa naimportovať do Postmanu, Insomnie aj generátora klienta).

Adresa API: `https://efakturia.sk`. Všetko je JSON v UTF-8, dátumy ISO 8601,
sumy v EUR ako čísla.

## 1. Predpoklady

- Firma má konto na efakturia.sk a je zapísaná v sieti Peppol
  (`GET /api/peppol/status` vráti registráciu so stavom `ACTIVE`).
- Firma má predplatený kredit. Každý odoslaný aj prijatý doklad sa strhne
  z kreditu podľa cenníka firmy (obrazovka Kredit v aplikácii). Podľa dohody
  môže mať firma namiesto kreditu **mesačnú fakturáciu podľa spotreby** —
  vtedy sa kredit nekontroluje, `402` nepríde a doklady sa vyúčtujú faktúrou
  po skončení mesiaca (spotrebu mesiaca vidno v aplikácii na obrazovke
  Kredit).
- Na odoslanie musí mať odberateľ vyplnené **DIČ**. Slovenské firmy sa v sieti
  adresujú `0245:DIČ`. Či je odberateľ v sieti, zistíte cez
  `GET /api/peppol/lookup?id=<DIČ>` (verejné, bez kľúča).

## 2. API kľúč

Kľúč vytvorí správca firmy v aplikácii: **Nastavenia → API kľúče → Nový
kľúč**. Kľúč (`efk_…`) sa zobrazí len raz, uložte si ho do trezoru tajomstiev,
nie do zdrojového kódu.

```
Authorization: Bearer efk_xxxxxxxxxxxxxxxxxxxxxxxx
```

- Kľúč patrí firme a koná s právami jej správcu.
- Limit je 10 000 požiadaviek za kalendárny mesiac. Kľúč pre integráciu môže
  prevádzkovateľ prepnúť na plán **Integrácia** s limitom 300 000 požiadaviek.
  Po prekročení limitu príde `429`.
- Bez kľúča alebo s neplatným kľúčom príde `401`.
- Kľúč sa dá kedykoľvek zrušiť v Nastaveniach. Zrušený kľúč prestane platiť
  okamžite.

## 3. Odoslanie faktúry

Postup má dva kroky: najprv faktúru vytvoríte, potom ju odošlete.

### 3a. Vytvorenie

```bash
curl -X POST https://efakturia.sk/api/faktury \
  -H "Authorization: Bearer $EFK_KEY" -H "Content-Type: application/json" \
  -d '{
    "invoiceNumber": "2026103049",
    "invoiceType": "INVOICE",
    "issueDate": "2026-10-20",
    "dueDate": "2026-11-03",
    "orderReference": "PO-4500123",
    "supplier": { "name": "Moja firma s. r. o.", "ico": "12345678",
                  "dic": "2020123456", "icDph": "SK2020123456" },
    "customer": { "name": "Zákazník s. r. o.", "ico": "87654321",
                  "dic": "2021987654", "street": "Hlavná 1",
                  "city": "Žilina", "postalCode": "01001" },
    "iban": "SK3112000000198742637541",
    "variableSymbol": "2026103049",
    "lines": [
      { "description": "Služba", "quantity": 1, "unitPrice": 100, "vatRate": 23 }
    ]
  }'
```

Odpoveď `201` obsahuje uloženú faktúru s `id`. Súčty a DPH vypočíta server.

Na čo si dať pozor:

- **Číslo faktúry.** Bez `invoiceNumber` dostane faktúra ďalšie číslo z radu
  firmy. Ak číslo už existuje, príde `409`, takže to isté číslo nevznikne
  dvakrát.
- **Typ dokladu (`invoiceType`).**
  - `INVOICE`: faktúra.
  - `CREDIT_NOTE`: dobropis. Položky majú záporné množstvá (v UBL CreditNote
    odídu ako kladné sumy). Opravovanú faktúru určuje **presne jedno** z:
    - `relatedInvoiceId`: id faktúry vystavenej v Efakturii,
    - `originalInvoice`: `{ "number": "2026/0815", "issueDate": "2026-09-30" }`
      pre faktúru z iného programu. Číslo a dátum idú do UBL ako
      `BillingReference` (BT-25, BT-26). Dôvod opravy je vtedy povinný v `note`.

    Obe naraz alebo ani jedno vráti `400`.
  - `PREPAYMENT`: daňový doklad k prijatej platbe (UBL kód 386).
  - `PROFORMA`: zálohová výzva. Nie je to daňový doklad, cez Peppol sa
    neposiela.
- **Daňový režim položky (`taxRegime`).** Vyplňte len pri výnimkách, napríklad
  `AE_REVERSE_CHARGE` (prenesenie daňovej povinnosti), `K_INTRA_COMMUNITY`
  alebo `O_NOT_VAT_PAYER`. Úplný zoznam je v openapi.yaml.
- **Číslo objednávky odberateľa.** Patrí do `orderReference`. Veľké firmy ho
  na faktúre často vyžadujú.

Dobropis k faktúre z iného programu (pôvodná faktúra v Efakturii nie je):

```bash
curl -X POST https://efakturia.sk/api/faktury \
  -H "Authorization: Bearer $EFK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceType": "CREDIT_NOTE",
    "originalInvoice": { "number": "2026/0815", "issueDate": "2026-09-30" },
    "note": "Vrátenie tovaru",
    "issueDate": "2026-11-15",
    "dueDate": "2026-11-29",
    "supplier": { "name": "Moja firma s. r. o.", "ico": "12345678",
                  "dic": "2020123456", "icDph": "SK2020123456" },
    "customer": { "name": "Zákazník s. r. o.", "ico": "87654321",
                  "dic": "2021987654" },
    "lines": [
      { "description": "Vrátený tovar", "quantity": -1, "unitPrice": 100, "vatRate": 23 }
    ]
  }'
```

Odošle sa rovnako ako faktúra (`POST /api/faktury/{id}/peppol`), ako UBL
CreditNote 381.

### 3b. Odoslanie do siete

```bash
curl -X POST https://efakturia.sk/api/faktury/$ID/peppol \
  -H "Authorization: Bearer $EFK_KEY"
```

```json
{
  "success": true,
  "messageId": "…",
  "delivery": "pending",
  "credit": { "charged": 0.15, "balance": 12.35 }
}
```

- Pred odoslaním sa overí kredit. Ak nestačí, príde `402` s
  `code: "INSUFFICIENT_CREDIT"` a nič neodíde. Pri mesačnej fakturácii sa
  kredit neoveruje a `charged` je `0`.
- Cena sa strhne až po úspešnom odovzdaní do siete, rovnako ako pri odoslaní
  z aplikácie.
- `charged` je suma strhnutá z kreditu vrátane DPH. Od 1. 11. 2026 je
  prevádzkovateľ platiteľ DPH a suma môže mať štyri desatinné miesta
  (napr. `0.1845` = 0,15 € + 23 % DPH); `balance` tiež.
- **Opakovanie po timeoute.** Neposielajte ten istý doklad dvakrát súbežne.
  Po timeoute počkajte aspoň minútu. Potom si cez `GET /api/faktury/{id}`
  pozrite `peppolMessageId`: ak je vyplnené, faktúra odišla. Ak nie, zavolajte
  odoslanie znova. Už odoslaná faktúra vráti `400` („už bola odoslaná") a
  druhýkrát neodíde.
- `502` znamená, že sieť doklad neprevzala. Dôvod je v `error`. Po oprave
  (napríklad doplnení DIČ) sa dá odoslať znova.
- `messageId` je id dokladu v sieti. O doručení sa dozviete neskôr, pozri
  časť 5.

### Hotové UBL zo súboru

Ak si váš systém generuje UBL (Peppol BIS Billing 3) sám, pošlite súbor priamo.
Odíde do siete bez zmeny:

```bash
curl -X POST https://efakturia.sk/api/faktury/nahrat \
  -H "Authorization: Bearer $EFK_KEY" \
  -F file=@faktura.xml -F action=send
```

S `action=analyze` sa súbor len skontroluje a nič sa neuloží.

### Kópie dokladu

- `GET /api/faktury/{id}/xml`: UBL vydanej faktúry.
- `GET /api/faktury/{id}/pdf`: PDF vydanej faktúry.

## 4. Príjem dokladov

Odporúčaný postup je **pravidelné preberanie s potvrdením**. Funguje aj vtedy,
keď váš server chvíľu nebeží.

1. Načítajte nepotvrdené doklady:
   `GET /api/prijate?acknowledged=false&limit=100`.
2. Pre každý doklad stiahnite XML (`GET /api/prijate/{id}/xml`) a podľa
   potreby PDF (`GET /api/prijate/{id}/pdf`). Uložte ich u seba.
3. Potvrďte prevzatie: `POST /api/prijate/ack` s telom
   `{"ids": ["…", "…"]}` (najviac 200 naraz).
4. Ak odpoveď obsahuje `nextCursor`, pokračujte ďalšou stranou
   (`&cursor=<nextCursor>`), inak skončite.

```bash
curl "https://efakturia.sk/api/prijate?acknowledged=false&limit=100" \
  -H "Authorization: Bearer $EFK_KEY"
```

```json
{
  "data": [
    { "id": "cm…", "invoiceNumber": "FV2026-118", "senderName": "Dodávateľ a. s.",
      "senderIco": "11223344", "issueDate": "2026-10-18T00:00:00.000Z",
      "dueDate": "2026-11-01T00:00:00.000Z", "totalInclVat": 123.0,
      "currency": "EUR", "receivedAt": "2026-10-20T07:15:02.311Z",
      "apiAcknowledgedAt": null, "status": "NEW" }
  ],
  "nextCursor": null
}
```

- Doklady sú zoradené od najstaršieho.
- Potvrdenie je idempotentné. Opakované `ack` toho istého dokladu nič nezmení.
- Ak spracovanie padne pred `ack`, doklad príde znova pri ďalšom behu. Párujte
  podľa `id`.
- Interval 5–15 minút úplne stačí. Doklady zo siete sa k nám dostávajú
  priebežne.
- `GET /api/prijate?since=2026-10-01` vráti doklady prijaté od dátumu, napríklad
  pri prvom napojení.
- `status` (`NEW`, `ACCEPTED`, …) je pracovný stav, ktorý nastavuje človek
  v aplikácii. Potvrdenie integráciou ho nemení.

### Odpoveď dodávateľovi

Odberateľ môže dodávateľovi poslať obchodnú odpoveď cez Peppol:

```bash
curl -X POST https://efakturia.sk/api/prijate/$ID/response \
  -H "Authorization: Bearer $EFK_KEY" -H "Content-Type: application/json" \
  -d '{"status": "RE", "note": "Faktúra nezodpovedá objednávke PO-4500123"}'
```

Kódy odpovede:

| Kód | Význam |
|---|---|
| `AP` | prijatá |
| `CA` | prijatá s výhradou |
| `UQ` | reklamovaná |
| `RE` | odmietnutá |
| `PD` | uhradená |

Pri kódoch `RE`, `UQ` a `CA` je `note` povinná.

## 5. Webhooky

Webhook doručí udalosť hneď, bez čakania na ďalšie preberanie. Neúspešné
doručenie sa opakuje (pozri nižšie), no po vyčerpaní pokusov udalosť ostane
zlyhaná. Webhook preto berte ako signál „stiahni teraz" a preberanie z časti 4
nechajte bežať ako zálohu.

### Povolená adresa

- Len `https://`. Adresa nesmie obsahovať meno ani heslo (`https://u:p@…`).
- Doména musí smerovať na **verejnú** adresu. Odmietnuté sú `localhost`,
  mená bez bodky a domény `.local`, `.internal`, `.lan` a podobné, privátne
  siete (10/8, 172.16/12, 192.168/16), loopback (127/8, `::1`), link-local
  (169.254/16, `fe80::/10`) vrátane metadátovej adresy 169.254.169.254,
  CGNAT (100.64/10), multicast, rezervované a dokumentačné rozsahy, IPv6 ULA
  (`fc00::/7`) a IPv4 zabalené v IPv6 (`::ffff:10.0.0.1`, `64:ff9b::…`).
  Ak má doména viac záznamov, nesmie byť neverejný ani jeden.
- Port môže byť ľubovoľný.
- Adresa sa overuje pri uložení **aj pri každom odoslaní**, a to adresa,
  na ktorú sa naozaj pripájame. Keď doména neskôr začne smerovať do privátnej
  siete, doručenie skončí ako zlyhané a neopakuje sa.
- **Presmerovania (3xx) sa nesledujú.** Odpoveď 3xx je neúspešný pokus.
  Uložte rovno konečnú adresu.

Neplatná adresa vráti `400` s `code: "WEBHOOK_URL_NOT_ALLOWED"` a dôvodom v
`details.reason` (`not_https`, `credentials`, `local_name`,
`forbidden_address`, `unresolvable`, `invalid`).

### Založenie

V aplikácii (Nastavenia → Webhooky) alebo cez API:

```bash
curl -X POST https://efakturia.sk/api/webhooks \
  -H "Authorization: Bearer $EFK_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://crm.example.sk/hooks/efakturia",
       "events": ["document.received", "invoice.delivered",
                  "invoice.rejected", "invoice.response_received"]}'
```

Odpoveď obsahuje `secret`. Zobrazí sa len raz a slúži na overenie podpisu.

### Udalosti

| udalosť | kedy príde |
|---|---|
| `document.received` | prišiel nový doklad. V `data` je `receivedInvoiceId`, `xmlUrl` a `pdfUrl` |
| `invoice.sent` | faktúra bola odovzdaná do siete. V `data` je `messageId` |
| `invoice.delivered` | prístupový bod odberateľa doklad prevzal. Príde raz |
| `invoice.rejected` | doklad neprešiel. `rejectedBy: "network"` znamená, že ho odmietla sieť (dôvod je v `reason`). `rejectedBy: "buyer"` znamená, že ho odmietol odberateľ odpoveďou RE (dôvod je v `response.note`) |
| `invoice.response_received` | odberateľ poslal obchodnú odpoveď. V `response` je `code`, `note` a `at` |
| `invoice.paid` | faktúra je uhradená. Buď ju tak označil človek, alebo odberateľ poslal odpoveď PD (`source: "peppol_pd"`) |

Ďalšie udalosti: `invoice.created`, `invoice.overdue`, `invoice.cancelled` a
`invoice.reminder_sent`.

### Príklad: odmietnutie odberateľom

```
POST /hooks/efakturia
Content-Type: application/json
X-Webhook-Event: invoice.rejected
X-Webhook-Id: invoice.rejected:cm2x…:buyer
X-Webhook-Attempt: 1
X-Webhook-Signature: sha256=…
```

```json
{
  "id": "invoice.rejected:cm2x…:buyer",
  "event": "invoice.rejected",
  "timestamp": "2026-10-21T09:12:44.120Z",
  "data": {
    "invoiceId": "cm2x…",
    "invoiceNumber": "2026103049",
    "invoiceType": "INVOICE",
    "messageId": "…",
    "peppolStatus": "accepted",
    "rejectedBy": "buyer",
    "response": { "code": "RE", "note": "Chýba číslo objednávky",
                  "at": "2026-10-21T09:10:00.000Z" }
  }
}
```

### Id udalosti a opakovanie

Každá udalosť má stabilné `id`. Je v tele aj v hlavičke `X-Webhook-Id` a pri
opakovaní sa nemení. Nemení sa ani `timestamp`, telo ani podpis, pretože
opakuje sa presne tá istá správa. Pri zmenách doručenia (`invoice.delivered`,
`invoice.rejected`, `invoice.response_received`) a pri `document.received` je
`id` odvodené od dokladu, takže tú istú zmenu nikdy nedostanete pod dvoma
rôznymi id. **Ak príde `id`, ktoré ste už spracovali, odpovedzte `2xx` a
udalosť zahoďte.**

Hlavička `X-Webhook-Attempt` nesie číslo pokusu (1 = prvé odoslanie).

| pokus | kedy |
|---|---|
| 1 | hneď po udalosti |
| 2 | o 1 min po zlyhaní 1. pokusu |
| 3 | o 5 min po zlyhaní 2. pokusu |
| 4 | o 30 min |
| 5 | o 2 h |
| 6 | o 12 h (posledný) |

Úspech je len odpoveď `2xx` do 10 s. Neúspech je čokoľvek iné: `3xx`,
`4xx`, `5xx`, timeout, chyba TLS alebo spojenia. Pokusy sa spúšťajú raz za
minútu, takže skutočný čas môže byť o niečo dlhší. Po šiestom neúspechu
dostane doručenie stav `FAILED` a viac sa neposiela. Pozastavený webhook
(`active: false`) neposiela nič; udalosti čakajú, a ak ho do 3 dní nezapnete,
skončia ako `FAILED`.

Stav fronty:

```bash
curl -H "Authorization: Bearer $EFK_KEY" \
  "https://efakturia.sk/api/webhooks/deliveries?status=FAILED&limit=50"
```

Vráti pole `{id, webhookId, eventId, event, status, attempts, nextAttemptAt,
lastStatus, lastError, lastAttemptAt, deliveredAt, createdAt}`. Filtre:
`status` (`PENDING`, `DELIVERED`, `FAILED`), `webhookId`, `limit` (max. 200).
`GET /api/webhooks` vracia pri každom webhooku aj `pendingCount` a
`failedCount`. Zlyhané doručenia sa po oprave vašej strany dajú poslať znova,
s rovnakým `id`:

```bash
curl -X POST https://efakturia.sk/api/webhooks/deliveries \
  -H "Authorization: Bearer $EFK_KEY" -H "Content-Type: application/json" \
  -d '{"action": "retry", "ids": ["<id doručenia>"]}'
```

Rovnako to ide v aplikácii (Nastavenia → Webhooky → Zlyhané → Zopakovať).
Úspešné doručenia sa vo fronte držia 30 dní, zlyhané 90 dní.

### Overenie podpisu (HMAC)

`X-Webhook-Signature` má tvar `sha256=<hex>`. Hodnota je HMAC-SHA256
**surového tela požiadavky** s kľúčom `secret`. Počítajte ho z bajtov tela tak,
ako prišli, nie z JSON-u, ktorý ste rozparsovali a znova serializovali. Na
porovnanie použite funkciu s konštantným časom.

Kontrolný príklad: pre secret `tajomstvo` a telo
`{"event":"document.received"}` vyjde
`sha256=3ccb9c9fc85bc843021dca7778a8bc3c292a56ddc7d4f7b2b1dafbfae4ec05d5`.

Node.js:

```js
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, rawBody, header) {
  const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(header ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}
```

PHP:

```php
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}
```

Python:

```python
import hmac, hashlib

def verify(secret: str, raw_body: bytes, header: str | None) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")
```

Na webhook odpovedzte rýchlo statusom `2xx` a samotné spracovanie (stiahnutie
XML) spravte až potom.

## 6. Chyby

Chyba má vždy tvar `{"error": "popis po slovensky"}`. Niekedy obsahuje aj
`code` a `details`.

| HTTP | význam | čo robiť |
|---|---|---|
| 400 | neplatné údaje, faktúra už odoslaná, proforma, chýbajúce DIČ | opraviť údaje, neopakovať naslepo |
| 401 | chýba alebo je neplatný kľúč | skontrolovať kľúč |
| 402 | `INSUFFICIENT_CREDIT` | dobiť kredit v aplikácii (obrazovka Kredit) |
| 404 | doklad neexistuje alebo patrí inej firme | — |
| 409 | duplicitné číslo faktúry | použiť iné číslo alebo načítať existujúcu |
| 429 | vyčerpaný mesačný limit kľúča | ozvať sa prevádzkovateľovi |
| 502, 503 | sieť alebo doručovacia služba je dočasne nedostupná | zopakovať o niekoľko minút |

## 7. Kontakt

Technické otázky k integrácii: info@it-dk.sk.
