Invoices

Issue an invoice via POST /v1/agent/invoices. The seller is derived from the organization (X-Organization-Id), the buyer from the customer field or an existing customer_id. Numbering, VAT calculation, PDF, and QR code generation all happen server-side, the same as for manual issuance.

Endpoint

This endpoint has a per-org rate limit of 30 requests / minute (on top of the key's global limit). The invoice currency is always EUR.

Request body

Customer object

Maps to the contacts table. For an inline customer, a new contact of type customer is created.

Line item object (items[])

VAT categories for 0 % lines (UBL mapping)

A 0 % rate alone is not enough — EN 16931 distinguishes why a line carries no VAT. The category comes from the line's tax_treatment and the document's exemption_reason (BT-120):

Complete example

POST /v1/agent/invoices
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…
Idempotency-Key: 7f0c2a4e-order-2026-042
Content-Type: application/json

{
  "customer": {
    "name": "Customer 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",
    "phone": "+421900123456"
  },
  "items": [
    {
      "description": "Service work",
      "quantity": 2,
      "unit": "hod",
      "unit_price": 50,
      "vat_rate": 23
    },
    {
      "description": "Spare part",
      "quantity": 1,
      "unit": "ks",
      "unit_price": 80,
      "vat_rate": 23
    }
  ],
  "payment_method": "bank_transfer",
  "due_days": 14,
  "note": "Thank you for your business.",
  "order_number": "OBJ-2026-042",
  "invoice_number": "2026-000042"
}

Response

HTTP/1.1 201 Created

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

The id value is used both when sending via Peppol (POST /v1/agent/peppol/send/{id}) and when checking status.

Idempotency (retry without duplicates)

POST /v1/agent/invoices supports an optional Idempotency-Key header: the primary protection mechanism against duplicate invoices on automatic retries. The same key with the same body returns the stored response (the invoice isn't created twice and the number series isn't consumed); the same key with a different body, or a concurrent request with the same key, returns 409. Without the header, behavior is unchanged.

Downloading PDF / XML

You can download an issued invoice as PDF or as UBL XML. Both operations require the scopeinvoice:download and return the file as an attachment (Content-Disposition: attachment).

Once the invoice has been sent via Peppol, the XML is the exact UBL handed to the Access Point (kept for statutory e-invoice archiving). Before sending the endpoint returns a preview rendered by the same builder the send job uses — no DB write, no credit charged, no embedded attachments (those are embedded only at send time). The X-Efaktura-Ubl-Source: archive | preview header tells you which one you got. Use the preview to verify the business JSON → UBL mapping (units, VAT categories, parties). The file name is the invoice number ({numberPrefix}{number}.xml).

GET /v1/agent/invoices/b1f0d7a2-…/xml
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…

HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Content-Disposition: attachment; filename="OF2026001.xml"
X-Efaktura-Ubl-Source: preview

<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2">…</Invoice>

Completeness requirements for Peppol

An invoice issued via this endpoint is fine as a regular document, but for it to be sendable via Peppol, the resulting UBL XML must pass EN 16931 + Peppol BIS Billing 3.0, plus the Slovak FS overlay. The SK overlay applies when the seller's country is SK, and requires:

Recipient routing in Peppol goes via the buyer's DIČ (sandbox: 9915:<DIČ>, production: 0245:<DIČ>). For correct VAT categorization (BR‑S/BR‑E), both the seller and buyer should have ic_dph. Before sending, you can pre-validate the UBL XML: see Validation.

You send an invoice issued by this endpoint via POST /v1/agent/peppol/send/{id}; right before sending, you can check it with a dry run via Preflight : that's validation from the Agent API (no session), with no DB writes and no credit charge. If instead you assemble the UBL/CII yourself and don't want to go through /agent/invoices, you can validate, reserve credit, and send in a single call via Connector.