Von deiner Bestellung zum archivierten Beleg.

Quickstart

Ein Schlüssel, zwei Berechtigungen

Erstelle unter Einstellungen → API einen projektgebundenen Schlüssel. Der vollständige Schlüssel wird genau einmal angezeigt und gehört ausschließlich in dein Backend oder Secret-Management.

Integrationsablauf

Deine Referenz bleibt der rote Faden

Du musst keine interne Rechnungskit-ID kennen. Nutze eine dauerhaft eindeutige orderNo und – bei Zahlung über Stripe, Mollie oder einen anderen Provider – dessen eindeutige paymentRef.

1. 1
   Bestellung senden

   Deine orderNo wird zum stabilen Korrelationsschlüssel.

2. 2
   Zahlung oder Erfüllung

   Zahlungswebhook matcht über paymentRef; physische Ware wartet auf Fulfillment.

3. 3
   Status abfragen

   GET /v1/orders/{orderNo} liefert die zugeordneten Rechnungen.

4. 4
   Exakte Beleg-ID übernehmen

   Speichere die zurückgegebene Invoice-UUID oder Belegnummer für diesen Beleg.

5. 5
   Dokument laden

   PDF und XML bleiben Bearer-geschützt und werden serverseitig abgerufen.

1 · Bestellung

Bestellung idempotent senden

Jeder POST benötigt einen stabilen Idempotency-Key. Bei einem Timeout kannst du dieselbe Anfrage mit demselben Key wiederholen, ohne eine zweite Bestellung anzulegen.

curl https://api.rechnungskit.de/v1/orders \
  -X POST \
  -H "Authorization: Bearer $RK_API_KEY" \
  -H "Idempotency-Key: order:CM-10482:v1" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNo": "CM-10482",
    "paymentRef": "pi_3PqK8w2eZvKYlo2C",
    "currency": "EUR",
    "requiresShipping": false,
    "billingAddress": {
      "name": "Lisa Brandt",
      "street": "Torstraße 99",
      "postal_code": "10119",
      "city": "Berlin",
      "country_code": "DE"
    },
    "items": [{
      "name": "Monatsabo Pro · Juni 2026",
      "sku": "saas-pro",
      "quantity": 1,
      "unitNetCents": 4118,
      "taxRate": 19
    }]
  }'

{
  "data": {
    "id": "6d754aec-40d9-4c1a-a78c-50dbb6c8e307",
    "orderNo": "CM-10482",
    "status": "created"
  },
  "requestId": "9d61558e-3c00-465d-b980-c074db600047"
}

Pflichtangaben

2 · Erfüllung

Versand oder Leistungserfüllung melden

Bei physischer Ware ist das Versanddatum das relevante Leistungsdatum. Melde daher den vollständigen Versand. Teilfulfillments erzeugen noch keinen vollständigen Beleg.

curl https://api.rechnungskit.de/v1/fulfillments \
  -X POST \
  -H "Authorization: Bearer $RK_API_KEY" \
  -H "Idempotency-Key: fulfillment:CM-10482:fulfilled:v1" \
  -H "Content-Type: application/json" \
  -d '{
    "orderNo": "CM-10482",
    "status": "fulfilled",
    "shippedAt": "2026-07-27T10:30:00Z",
    "trackingNumber": "003404341612"
  }'

3 · Status & Dokumente

So erhältst du die Rechnungs-ID

Frage den Status mit deiner eigenen Bestellnummer ab. Sobald eine Rechnung angelegt wurde, enthält invoices[] ihre UUID, Belegnummer und ihren Archivstatus.

curl https://api.rechnungskit.de/v1/orders/CM-10482 \
  -H "Authorization: Bearer $RK_API_KEY"

{
  "data": {
    "orderNo": "CM-10482",
    "status": "invoiced",
    "fulfillmentStatus": "fulfilled",
    "invoices": [{
      "id": "f77ba43d-6f06-4b84-bd24-5cfab76a1192",
      "number": "RK-2026-0148",
      "status": "archived",
      "url": "/v1/invoices/f77ba43d-6f06-4b84-bd24-5cfab76a1192"
    }]
  },
  "requestId": "3a61c30d-4386-4c60-9354-841342cbc372"
}

Verwende anschließend die UUID, wenn du einen ganz bestimmten Beleg herunterladen willst. Das ist bei Stornos oder mehreren Dokumenten zu einer Bestellung eindeutig.

curl https://api.rechnungskit.de/v1/invoices/f77ba43d-6f06-4b84-bd24-5cfab76a1192/pdf \
  -H "Authorization: Bearer $RK_API_KEY" \
  --output RK-2026-0148.pdf

Alternative · Rechnungskauf

Rechnung zuerst, Zahlung später

Bei Kauf auf Rechnung gibt es zunächst keine Provider-Zahlung. Sende stattdessen den in Rechnungskit unter Connect freigegebenen Gateway-Namen. Nach vollständigem Fulfillment entsteht die Rechnung mit offenem Posten und Zahlungsziel.

{
  "orderNo": "CM-10483",
  "paymentGateway": "invoice",
  "financialStatus": "pending",
  "requiresShipping": true,
  "billingAddress": { "...": "vollständige Rechnungsanschrift" },
  "items": [ "..." ]
}

Referenz

API v1 Endpunkte

Maschinenlesbare Referenz: OpenAPI 3.1 herunterladen ↗

Fehler & Wiederholungen

Jede Antwort trägt eine Request-ID

Der Header X-Request-Id und das JSON-Feld requestId identifizieren dieselbe Anfrage. Du findest sie 30 Tage lang in der API-Aktivität deines Projekts.

{
  "error": {
    "code": "validation_failed",
    "message": "billingAddress.country_code is required for VAT determination",
    "field": "billingAddress.country_code"
  },
  "requestId": "9d61558e-3c00-465d-b980-c074db600047"
}

Sandbox

Erst testen, dann live gehen

Jedes Konto hat einen Testmodus: Ein Klick in den Projekteinstellungen erstellt ein separates Sandbox-Projekt mit eigenen rk_test_…-Schlüsseln. Die Sandbox nutzt dieselbe API und dieselbe Pipeline wie die Produktion, inklusive EN-16931-Validierung und PDF/A-3-Rendering. Du testest also exakt das Verhalten, das später live läuft.

Sicherheit

Secrets bleiben im Backend

• API-Schlüssel nie in Browser-, Mobile- oder öffentliches Repository einbauen.
• Schlüssel in Secret-Manager oder verschlüsselten Umgebungsvariablen speichern.
• Unbefristete Produktionsschlüssel bewusst rotieren; kurze Laufzeiten nur für Tests oder Übergänge verwenden.
• Schlüssel, die länger als 90 Tage nicht verwendet wurden, in der API-Einstellung prüfen und bei nicht mehr benötigten Integrationen widerrufen.
• Bei Verdacht sofort einen neuen Schlüssel anlegen, ausrollen und den alten widerrufen.
• Dokumente serverseitig abrufen; keine dauerhaften Bearer-Links an Kunden geben.