Hromadný export dokladov celého portfólia

Proces

Export v 4 krokoch

1. 1

   Požiadajte o export

   POST /partner/exports so zvoleným obdobím (voliteľne zoznam klientov).

2. 2

   Export beží na pozadí

   Doklady sa balia po mesiacoch; veľký mesiac sa rozdelí na viac častí na hranici klienta.

3. 3

   Dostanete notifikáciu

   Webhook export.completed s odkazmi, e-mail z konzoly, alebo polling cez GET.

4. 4

   Stiahnite a overte

   Každá časť má podpísaný odkaz (7 dní) a SHA-256 kontrolný súčet.

Partner API

Vytvorenie a sledovanie exportu

Obdobie je povinné (period_from / period_to, max. 5 rokov na jednu požiadavku). client_ids vynechajte alebo pošlite null pre celé portfólio. API kľúč potrebuje scope invoices:read. Na jedného partnera beží vždy najviac jeden hromadný export.

curl -X POST https://api.sandbox.efakturuj.sk/api/v1/partner/exports \
  -H 'X-API-Key: efk_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "period_from": "2026-01-01",
    "period_to": "2026-06-30",
    "client_ids": null
  }'

# 202 Accepted
{
  "id": "9f2c41d0-…",
  "scope": "partner",
  "status": "pending",
  "period_from": "2026-01-01",
  "period_to": "2026-06-30",
  "invoice_count": 0,
  "parts": []
}

curl https://api.sandbox.efakturuj.sk/api/v1/partner/exports/9f2c41d0-… \
  -H 'X-API-Key: efk_…'

# 200 OK (po dokončení)
{
  "id": "9f2c41d0-…",
  "scope": "partner",
  "status": "completed",
  "invoice_count": 18452,
  "expires_at": "2026-09-05T10:15:00+00:00",
  "parts": [
    {
      "period": "2026-01",
      "part_no": 1,
      "size_bytes": 812345678,
      "sha256": "d1a5…",
      "invoice_count": 3120,
      "download_url": "https://api.efakturuj.sk/api/v1/exports/download/…"
    },
    { "period": "2026-02", "part_no": 1, "…": "…" }
  ]
}

2026-01-part-01.zip
└── 2026-01/
    ├── 2020111111/                 ← DIČ klienta
    │   ├── invoices.csv            ← súhrn mesiaca (14 stĺpcov)
    │   ├── invoices.json           ← strojovo čitateľný súhrn
    │   └── ubl/
    │       ├── FA-2026-001.xml     ← UBL originály (názov = číslo faktúry)
    │       └── FA-2026-002.xml
    └── 2020222222/
        └── …

Notifikácia

Webhook export.completed

Rovnaký kanál ako client.linked a client.activated: v konzole otvorte Connect → Webhooky na vlastnej firme partnera a pridajte endpoint s udalosťou export.completed. Doručenie je podpísané (HMAC-SHA256), s opakovaním a delivery logom. Payload nesie priamo podpísané odkazy na stiahnutie — príjemca môže export odčerpať bez ďalšieho volania API.

{
  "id": "3f6c…",
  "event": "export.completed",
  "created_at": "2026-08-29T10:15:00+00:00",
  "data": {
    "export_id": "9f2c41d0-…",
    "status": "completed",
    "period_from": "2026-01-01",
    "period_to": "2026-06-30",
    "invoice_count": 18452,
    "expires_at": "2026-09-05T10:15:00+00:00",
    "parts": [
      {
        "period": "2026-01",
        "part_no": 1,
        "size_bytes": 812345678,
        "sha256": "d1a5…",
        "invoice_count": 3120,
        "download_url": "https://api.efakturuj.sk/api/v1/exports/download/…"
      }
    ]
  }
}

Stiahnutie

Podpísané odkazy a kontrola integrity

Odkazy fungujú bez prihlásenia — autorizáciou je podpísaný token v URL s platnosťou 7 dní (rovnako dlho žijú aj samotné súbory; potom sa automaticky zmažú). Časti sťahujte pokojne paralelne a každú overte podľa sha256. Ak odkaz vyprší, požiadajte o nový export — vytvorenie je lacné a idempotentné vo výsledku.

# Každú časť stiahnite a overte podľa sha256 z manifestu
curl -L -o 2026-01-part-01.zip "https://api.efakturuj.sk/api/v1/exports/download/…"
sha256sum 2026-01-part-01.zip   # musí sa zhodovať s "sha256" časti

Jednoduchý export

Export jedného klienta alebo vlastnej firmy

Limity a odporúčania

Praktické pravidlá

• 1 bežiaci export na partnera — ďalšia požiadavka vráti 422 export_already_running.
• Obdobie max. 5 rokov na jednu požiadavku; dlhšiu históriu rozdeľte.
• Súbory žijú 7 dní — po vypršaní jednoducho požiadajte o nový export.
• Odporúčanie: mesačný rytmus — priebežný export uzavretého mesiaca (1–2 časti) namiesto jedného obrieho exportu pri odchode.