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 defaults to the firm's currency; for another one see currency below.

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",
  "exchange_rate": null,
  "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.

Foreign currency and exchange rate

Without currency the invoice is issued in the firm's currency (EUR for a Slovak firm, CZK for a Czech one). Send another currency in currency (EUR, CZK, USD, GBP, PLN, CHF, HUF, RON, BGN, SEK, DKK, NOK, HRK, RSD, UAH, RUB, TRY, CNY, JPY, CAD, AUD). exchange_rate is a decimal string greater than 0 (up to 7 integer and 8 decimal digits): units of currency per one unit of the firm's home currency. Slovak firm, 1 EUR = 1.0842 USD: "exchange_rate": "1.0842".

{
  "customer_id": "550e8400-…",
  "currency": "USD",
  "exchange_rate": "1.0842",
  "items": [ { "description": "Consulting", "quantity": 1, "unit": "ks", "unit_price": 500, "vat_rate": 0 } ]
}

Without exchange_rate on a foreign-currency invoice the server fills in the ECB rate (Slovak firm) or the CNB rate (Czech firm) for the tax point (delivery_date, else issue_date). If no rate can be fetched the invoice is still created with exchange_rate: null. The response of POST /v1/agent/invoices and of GET /v1/agent/invoices/{id} carry exchange_rate (string or null) next to currency.

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>

Mutual set-off

A set-off (vzájomný zápočet) of an issued invoice against a received document of the same counterparty (e.g. a platform invoices a client for a service and records the client's fee as a received document). One call writes a payment with method offset on the invoice and on the received document and pairs them. Slovak firms only. To settle just one side, use POST /v1/agent/invoices/{id}/payments.

POST /v1/agent/offsets
X-API-Key: efk_pk_test_...
X-Organization-Id: 0a2c1f3e-…
Idempotency-Key: 3c8e1d52-settlement-2026-10
Content-Type: application/json

{
  "invoice_id": "b1f0d7a2-…",
  "expense_id": "5b7e91c4-…",
  "amount": "110.70",
  "offset_date": "2026-10-31",
  "reference": "SETTLEMENT-2026-10"
}

HTTP/1.1 201 Created

{
  "data": {
    "id": "3d9a60f8-…",
    "invoice_id": "b1f0d7a2-…",
    "expense_id": "5b7e91c4-…",
    "amount": "110.70",
    "currency": "EUR",
    "offset_date": "2026-10-31",
    "reference": "SETTLEMENT-2026-10",
    "note": null,
    "accounting_program": { "status": "pending", "reason": null },
    "created_at": "2026-10-31T09:12:00.000Z",
    "invoice": { "id": "b1f0d7a2-…", "total": "270.60", "paid_amount": "110.70", "outstanding": "159.90", "status": "partially_paid" },
    "expense": { "id": "5b7e91c4-…", "total": "110.70", "paid_amount": "110.70", "outstanding": "0.00", "payment_status": "paid" }
  }
}

The payments of a set-off cannot be deleted on their own, nor can the documents it settled (409). A missing document returns 404. 400 errors:

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, check it with a dry run via POST /v1/agent/invoices/{id}/preflight (see Recommended flow): no DB writes and no credit charge. The separate /peppol/preflight is only for UBL/CII you assemble yourself. If 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.