Rechnungen über die API ausstellen

POST /invoices mit Idempotency-Key, MwSt. in Prozent, dazu Liste, Storno und Zahlungsvermerk.

Die erste Rechnung in 6 Schritten

Senden Sie POST /v1/invoices mit einem buyer-Objekt und mindestens einem Eintrag in lines.
Fügen Sie den Idempotency-Key-Header hinzu – er ist Pflicht, ein Schlüssel pro logischer Operation.
Senden Sie vat_rate als Prozentwert (21) und unit_price als NETTO-Stückpreis.
Die 201-Antwort enthält id, number, series, die Summen net/vat/gross und die von Ihnen gesendeten metadata.
Rufen Sie das Dokument mit GET /v1/invoices/{id}/pdf ab oder das UBL-XML mit GET /v1/invoices/{id}/xml.

Alle Endpunkte

Methode	Endpunkt	Scope	Idempotency-Key	Anfragen / Minute
POST	/invoices Rechnung oder Proforma ausstellen	invoices:write	erforderlich	30
GET	/invoices Rechnungen auflisten (Cursor-Paginierung)	invoices:read	—	120
POST	/invoices/preview-totals Summen berechnen, ohne etwas anzulegen	invoices:read	—	120
GET	/invoices/{invoice_id} Eine Rechnung abrufen	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Rechnungs-PDF herunterladen	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Gutschrift ausstellen, die diese Rechnung storniert	invoices:write	erforderlich	30
POST	/invoices/{invoice_id}/payments Rechnung als bezahlt markieren	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Rechnung als unbezahlt markieren	invoices:write	—	30

Was die 4invoices-API ist

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{
    "buyer": {
      "name": "Exemplu Comert SRL",
      "tax_id": "RO12345678",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

bash
# Cursor-Paginierung: next_cursor folgen, bis has_more false ist.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

curl -sS "https://api.4invoices.net/v1/invoices?limit=50&cursor=inv_01J..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/storno \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: storno-inv_01J7ABC-1'

# Die Gutschrift erhält eine EIGENE Fiskalnummer; die Nummer des Originals wird nie wiederverwendet.

bash
# Als bezahlt markieren
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Rückgängig
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Fehler

Status	Typ	Code
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Häufige Fehler

Die Auflistung ist cursorbasiert: Folgen Sie next_cursor, bis has_more false ist. Zu den Filtern gehören status, document_kind, buyer_tax_id, issued_from, issued_to und q.
Ein Storno ist POST /v1/invoices/{id}/storno und erhält eine eigene fiskalische Nummer – die ursprüngliche Nummer wird nie wiederverwendet.
Eine Proformarechnung (document_kind proforma) verbraucht keine fiskalische Nummer und kann nicht im nationalen E-Rechnungssystem eingereicht werden.
metadata wird bei Lesezugriffen zurückgegeben: Legen Sie dort Ihre Bestell-ID ab, dann brauchen Sie keine separate Zuordnungstabelle mehr.
POST /v1/invoices/preview-totals führt dieselbe Berechnung ohne Seiteneffekte aus – praktisch, um Summen im eigenen Warenkorb anzuzeigen.

Fragen und Antworten für Entwickler

Wie viele Positionen kann eine Rechnung haben?

Zwischen 1 und 400. description ist auf 1024 Zeichen begrenzt, und quantity muss streng positiv sein.

Was passiert, wenn ich dieselbe Anfrage nach einem Timeout erneut sende?

Mit demselben Idempotency-Key erhalten Sie die ursprüngliche Rechnung plus einen Header Idempotency-Replayed: true. Es wird kein zweites Dokument ausgestellt.

Wie markiere ich eine Rechnung als bezahlt?

POST /v1/invoices/{id}/payments markiert sie als bezahlt, und DELETE auf demselben Pfad macht das rückgängig. Beides erfordert den Scope invoices:write.

Siehe auch