eFakturuj / API Docs
Dashboard ↗

Send your first invoice in 5 minutes

This walkthrough takes you from zero to a Peppol invoice that landed in a buyer's Access Point inbox. Every step shows the same call in five flavours — pick the one your stack speaks.

Prerequisites

All requests below target the production base URL https://api.efakturuj.sk/api/v1. Sandbox lives at https://sandbox.efakturuj.sk/api/v1 — same shapes, no real Peppol delivery.

1. Create a customer

Every invoice points at a buyer. POST /customers persists a Slovak entity in your organisation's address book. The peppol_id field (0210:<IČO> for Slovak businesses identified by IČO) is what lets us route the invoice across the Peppol network — supply it explicitly, or omit it and we'll try to discover it via SMP.

curl -X POST https://api.efakturuj.sk/api/v1/customers \
  -H 'X-Api-Key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Príklad s.r.o.",
    "vat_id": "SK1234567890",
    "ico": "12345678",
    "street": "Hlavná 12",
    "city": "Bratislava",
    "postal_code": "811 01",
    "country_code": "SK",
    "peppol_id": "0210:12345678",
    "email": "billing@priklad.sk"
  }'

The 201 response includes a server-generated id (UUID v4). Save it — step 2 references it as customer_id.

2. Create a draft invoice

POST /invoices creates a draft. Drafts can be edited freely; only when you send do we lock the document and validate it. Notice we send quantity, unit_price, and vat_rate as strings — the API accepts them as Decimal to avoid float rounding (financial data must be exact). Slovak VAT rates as of 2026: 0, 5, 19, 23.

curl -X POST https://api.efakturuj.sk/api/v1/invoices \
  -H 'X-Api-Key: <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
  "invoice_number": "2026-001",
  "issue_date": "2026-05-06",
  "due_date": "2026-06-05",
  "currency_code": "EUR",
  "supplier": {
    "name": "Vaša Firma s.r.o.",
    "vat_id": "SK0987654321",
    "ico": "87654321",
    "street": "Mlynské nivy 5",
    "city": "Bratislava",
    "postal_code": "821 09",
    "country_code": "SK",
    "peppol_id": "0210:87654321"
  },
  "buyer": {
    "name": "Príklad s.r.o.",
    "vat_id": "SK1234567890",
    "ico": "12345678",
    "street": "Hlavná 12",
    "city": "Bratislava",
    "postal_code": "811 01",
    "country_code": "SK",
    "peppol_id": "0210:12345678"
  },
  "customer_id": "<CUSTOMER_ID_FROM_STEP_1>",
  "supplier_iban": "SK1234567890123456789012",
  "variable_symbol": "2026001",
  "lines": [
    {
      "line_number": 1,
      "item_name": "Konzultačné služby — Apríl 2026",
      "quantity": "10",
      "unit_code": "HUR",
      "unit_price": "100.00",
      "vat_rate": "23.00",
      "vat_category_code": "S"
    }
  ]
}'

On success you get back the full invoice with status: "draft", a computed total_net, total_vat, and total_gross, plus a vat_breakdown array per VAT rate. The id is what step 3 uses.

3. Send the invoice via Peppol

POST /invoices/{id}/send is the magic step. The endpoint runs the synchronous business-rule validator (mandatory fields, line totals, Slovak VAT rules, the "ZZZ" rounding correction) — if it fails you get a 422 with a per-rule error list and the invoice stays in draft. On success we transition the invoice to queued, write a sent_peppol audit log entry, and dispatch two Celery tasks: one for the Peppol AS4 envelope, one for the Slovak Financial Administration copy. The HTTP response is 202 Accepted — delivery is asynchronous.

curl -X POST https://api.efakturuj.sk/api/v1/invoices/<INVOICE_ID>/send \
  -H 'X-Api-Key: <YOUR_API_KEY>'

4. Track delivery

Two ways to watch the invoice progress through queued → sent → delivered → acknowledged:

  1. Poll GET /invoices/{id} every few seconds until status reaches a terminal value (delivered, acknowledged, or failed). Fine for one-off scripts.
  2. Subscribe to webhooks at /connect/webhooks — register a URL, get a signed POST when the status changes. The right choice for production integrations.
curl https://api.efakturuj.sk/api/v1/invoices/<INVOICE_ID> \
  -H 'X-Api-Key: <YOUR_API_KEY>'

For the production push pattern, see the Webhooks guide.

Next steps

That's it — your first invoice is in the Peppol network. From here: