Rýchly štart

V partnerskom portáli v sekcii API kľúče vytvorte sandbox kľúč. Zobrazí sa iba raz — uložte si ho do secret store. Partnerský kľúč (efk_pk_*) vie zakladať klientske organizácie; je viazaný na váš partnerský účet.

Partnerský kľúč vytvorí white‑label dcérsku organizáciu. Pri tomto volaní neposielate X-Organization-Id — organizácia ešte neexistuje. Vyžaduje sa scope org:provision.

curl -X POST https://api.efaktura.sk/v1/agent/organizations \
  -H "X-API-Key: efk_pk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tatra Servis s.r.o.",
    "ico": "12345678",
    "dic": "2020202020",
    "ic_dph": "SK2020202020",
    "address": {
      "street": "Hlavná 1",
      "city": "Bratislava",
      "postalCode": "81101",
      "country": "SK"
    }
  }'

Odpoveď (201 Created, alebo 200 ak sa existujúca organizácia znova použila):

{
  "data": {
    "org_id": "0a2c1f3e-…",
    "partner_id": "7b8d…",
    "slug": "tatra-servis-sro",
    "reused": false,
    "status": "caka_na_token"
  }
}

org_id je hodnota, ktorú odteraz posielate v X-Organization-Id. Detail organizácie (vrátane participant_id a peppol_status) získate cez GET /v1/agent/organizations/{org_id}.

Enroll zaregistruje DIČ organizácie ako Peppol účastníka v TEST SMP (9915:<DIČ>). Vyžaduje sa scope invoice:send a hlavička X-Organization-Id. V sandboxe je verifikačný token nepovinný; pre produkčný (live) enroll je povinný (FS verifikačný kód — viac v Spustenie naostro).

curl -X POST https://api.efaktura.sk/v1/agent/peppol/enroll \
  -H "X-API-Key: efk_pk_test_..." \
  -H "X-Organization-Id: 0a2c1f3e-…" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "data": {
    "status": "active",
    "registration_id": "…",
    "participant_id": "9915:2020202020"
  }
}

DIČ organizácie musí mať 10 cifier — inak enroll vráti VALIDATION_ERROR.

Faktúru vystavíte cez POST /v1/agent/invoices (scope invoice:create). Predávajúci sa odvodí z organizácie, kupujúci z customer (alebo existujúceho customer_id). Aby bola faktúra odosielateľná cez Peppol, kupujúci musí mať úplnú adresu a (pri firme) ico/dic/ic_dph.

curl -X POST https://api.efaktura.sk/v1/agent/invoices \
  -H "X-API-Key: efk_pk_test_..." \
  -H "X-Organization-Id: 0a2c1f3e-…" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
    },
    "items": [
      {
        "description": "Servisné práce",
        "quantity": 2,
        "unit": "hod",
        "unit_price": 50,
        "vat_rate": 23
      }
    ],
    "payment_method": "bank_transfer",
    "due_days": 14
  }'

Odpoveď (201 Created) — uložte si id:

{
  "id": "b1f0d7a2-…",
  "invoice_number": "2026001",
  "status": "issued",
  "customer": { "id": "…", "name": "Odberateľ s.r.o." },
  "items": [ … ],
  "subtotal": "100.00",
  "vat_total": "23.00",
  "total": "123.00",
  "currency": "EUR",
  "issue_date": "2026-06-22",
  "due_date": "2026-07-06",
  "pdf_url": "https://…",
  "created_at": "2026-06-22T10:00:00.000Z"
}

Odoslanie zaradí faktúru do fronty (scope invoice:send). Test kľúč smeruje send cez sandbox AP na reálnej Peppol TEST sieti — bez kreditov.

curl -X POST https://api.efaktura.sk/v1/agent/peppol/send/b1f0d7a2-… \
  -H "X-API-Key: efk_pk_test_..." \
  -H "X-Organization-Id: 0a2c1f3e-…"

Odpoveď (202 Accepted):

{
  "data": {
    "invoice_id": "b1f0d7a2-…",
    "job_id": "peppol-send:b1f0d7a2-…",
    "status": "queued"
  }
}

Stav prenosu zistíte cez GET /v1/agent/peppol/status/{invoiceId} (scope invoice:read). Skutočné stavy endpointu: QUEUED, SENDING, SENT, DEFERRED, ERROR; ak ešte nič nebolo odoslané, vráti sa syntetická hodnota not_sent. (DELIVERED je stav webhookového eventu, nie polling endpointu.) Detaily v Prijímanie a stavy.

curl https://api.efaktura.sk/v1/agent/peppol/status/b1f0d7a2-… \
  -H "X-API-Key: efk_pk_test_..." \
  -H "X-Organization-Id: 0a2c1f3e-…"

{
  "data": {
    "invoice_id": "b1f0d7a2-…",
    "state": "SENT",
    "error_message": null,
    "receiver_identifier": "9915:2010101010",
    "document_id": "…",
    "updated_at": "2026-06-22T10:00:05.000Z"
  }
}

Namiesto pollingu odporúčame webhooky. Zaregistrujte HTTPS endpoint v portáli a reagujte na peppol.document.sent / peppol.document.delivered / peppol.document.failed, prípadne na príchodzí doklad cez peppol.document.received. Každé doručenie je podpísané HMAC‑om — overte podpis a deduplikujte podľa X-Webhook-Id. Kompletne v Webhooky.

{
  "event": "peppol.document.delivered",
  "timestamp": "2026-06-22T10:00:08.000Z",
  "data": {
    "invoiceId": "b1f0d7a2-…",
    "invoiceNumber": "2026001",
    "documentType": "invoice",
    "mode": "test",
    "state": "DELIVERED",
    "messageId": "…",
    "transactionId": "…",
    "orgId": "0a2c1f3e-…"
  }
}