Kuchárka pre vývojárov: pošlite a prijmite prvú Peppol faktúru cez API

Od 1. januára 2027 bude e‑fakturácia cez sieť Peppol povinná pre platiteľov DPH na Slovensku. Ak vyvíjate ERP, e‑shop alebo účtovný softvér, najrýchlejšia cesta k pripravenosti je vyskúšať si celý tok — od API kľúča až po doručenú faktúru — v testovacom prostredí.

Toto je naša „kuchárka“: recept od začiatku do konca v sandboxe eFakturuj. Žiadny dokument sa nedostane do reálnej siete Peppol a nič sa neúčtuje. Potrebujete len testovací účet a dve firmy vo vašom workspace (odosielateľa a príjemcu), obe s vyplneným peppol_id.

Jedna firma pošle faktúru druhej cez Peppol a na oboch stranách budú registrované webhooky: odosielateľ počúva na invoice.delivered, príjemca na invoice.received. Celý tok: vytvoriť → zvalidovať → odoslať → sledovať doručenie.

Základná URL testovacieho prostredia je https://api.sandbox.efakturuj.sk/api/v1. Dve zásady, ktoré platia v celom API: peňažné sumy sú vždy reťazce s desatinnými miestami ("85.00", nikdy float) a dátumy sú ISO 8601 (YYYY-MM-DD).

API kľúč (efk_…) sa vytvára cez dashboard session token (JWT) s rolou admin. Plaintext kľúč sa vráti iba raz — uložte si ho hneď.

curl -sS -X POST https://api.sandbox.efakturuj.sk/api/v1/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Prvá testovacia faktúra",
    "scopes": ["invoices:read", "invoices:write", "invoices:send"]
  }'

Kľúč je viazaný na firmu, za ktorú ste ho vytvorili — vytvorte ho za odosielateľa. Všetky ďalšie volania faktúr ho posielajú v hlavičke X-API-Key.

Webhook sa registruje cez POST /connect/webhooks. Podpisový secret (whsec_…) sa tiež vracia iba raz.

# ako ODOSIELATEĽ
curl -sS -X POST https://api.sandbox.efakturuj.sk/api/v1/connect/webhooks \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://webhook.site/your-unique-id",
    "events": "invoice.delivered,invoice.fs_acknowledged,invoice.rejected"
  }'

# ako PRÍJEMCA
# { "url": "https://webhook.site/your-receiver-id", "events": "invoice.received" }

Každé doručenie nesie hlavičky X-Webhook-Signature, X-Webhook-Event a X-Webhook-Delivery. Podpis je HMAC‑SHA256 nad surovým telom požiadavky, pričom HMAC kľúčom je SHA‑256 hash vášho whsec_ secretu:

import hashlib, hmac

def valid(raw_body: bytes, signature: str, whsec: str) -> bool:
    key = hashlib.sha256(whsec.encode()).hexdigest()
    expected = hmac.new(key.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Faktúra vzniká ako draft cez POST /companies/{company_id}/invoices. Kupujúcim je príjemca a smerovanie zabezpečuje jeho buyer.peppol_id. Pri platbe prevodom (kód 30) je povinný supplier_iban.

curl -sS -X POST https://api.sandbox.efakturuj.sk/api/v1/companies/$SENDER/invoices \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "TEST-0001",
    "invoice_type": "380",
    "issue_date": "2026-07-04",
    "due_date": "2026-08-03",
    "currency_code": "EUR",
    "supplier_iban": "SK3112000000198742637541",
    "supplier": { "name": "Modrý Vrch s.r.o.", "vat_id": "SK2007233001",
      "ico": "90723301", "street": "Hlavná 12", "city": "Bratislava",
      "postal_code": "81101", "country_code": "SK", "peppol_id": "9925:sk2007233001" },
    "buyer": { "name": "Riečna Dielňa s.r.o.", "vat_id": "SK2007233002",
      "ico": "90723302", "street": "Štúrova 5", "city": "Košice",
      "postal_code": "04001", "country_code": "SK", "peppol_id": "9925:sk2007233002" },
    "lines": [{ "line_number": 1, "item_name": "Konzultačné služby",
      "quantity": "10", "unit_code": "HUR", "unit_price": "85.00",
      "vat_rate": "23.00", "vat_category_code": "S" }],
    "payment_means_code": "30",
    "variable_symbol": "20260001"
  }'

Pred odoslaním faktúru zvalidujte — kontroluje sa XSD, Peppol BIS 3.0 aj slovenské pravidlá:

curl -sS -X POST .../invoices/$INV/validate -H "X-API-Key: $KEY"
# { "valid": true, "errors": [], "xml_validation": { "xsd_valid": true, "peppol_valid": true } }

curl -sS -X POST .../invoices/$INV/send -H "X-API-Key: $KEY"
# { "status": "queued" }

Doručenie je asynchrónne — stav faktúry sledujte cez GET …/invoices/{id}, kým neskončí v terminálnom stave.

Do niekoľkých sekúnd sa u príjemcu objaví prijatá faktúra a vystrelí jeho webhook invoice.received — to je v testovacom prostredí spoľahlivý signál, že dokument reálne prešiel:

{
  "event": "invoice.received",
  "data": {
    "invoice_id": "…",
    "source": "peppol",
    "invoice_number": "TEST-0001",
    "supplier_vat_id": "SK2007233001"
  }
}

Odosielateľova faktúra prejde do stavu delivered (a vystrelí invoice.delivered) po potvrdení AS4 doručenia. Históriu pokusov každého webhooku vrátane HTTP kódov a retry nájdete cez GET /connect/webhooks/{id}/deliveries.

• BR‑61 pri validácii — platba prevodom (kód 30) vyžaduje supplier_iban.
• Varovanie SK‑BR‑04 — variable_symbol musí obsahovať iba číslice.
• Odoslané, ale príjemca nič nevidí — kupujúci nemá vyplnené peppol_id, dokument nie je smerovateľný.
• 409 invoice_number_conflict — číslo faktúry už v danom roku existuje, zvoľte nové.
• Nesedí podpis webhooku — overujete plaintext secretom; HMAC kľúčom je SHA‑256 hash whsec_ secretu a podpisuje sa surové telo požiadavky.

Celý referenčný popis API vrátane príkladov nájdete v dokumentácii: začíname s API, odosielanie faktúr a testovacie prostredie.

Testovací účet si vytvoríte na sandbox.efakturuj.sk — a keď budete pripravení na produkciu, ozvite sa nášmu integračnému tímu. Do januára 2027 je ešte čas urobiť integráciu poriadne — začnite testovacou faktúrou už dnes.