Rechnungskit API

Quickstart

Ein Schlüssel, zwei Berechtigungen

Erstelle unter Verbindungen → 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. Nur physische Ware (requiresShipping: true) wartet auf Fulfillment; SaaS und digitale Leistungen überspringen diesen Schritt, die Rechnung entsteht direkt mit der Zahlung.

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"
    },
    "service_period": {
      "start_date": "2026-06-01",
      "end_date": "2026-06-30"
    },
    "items": [{
      "name": "Monatsabo Pro · Juni 2026",
      "sku": "saas-pro",
      "quantity": 1,
      "unitNetCents": 4118,
      "discountNetCents": 500,
      "taxRate": 19
    }]
  }'

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

Pflichtangaben

Optionale Felder

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": [ "..." ]
}

Guthaben · Push

Empfehlungs- und Kundenguthaben melden

Verwaltet deine Anwendung Guthaben selbst, etwa Empfehlungsprämien, schickst du jede Bewegung an POST /v1/credit-transactions: Verdienen (earn), Einlösen (redeem), Rücknahme (reverse), Auszahlung (payout) und Verfall (expire). Jede Transaktion trägt deine eindeutige id; ein wiederholter Aufruf legt nichts doppelt an. Bis zu 500 je Aufruf.

{
  "transactions": [
    {
      "id": "tx_81",
      "type": "earn",
      "email": "kundin@example.com",
      "amount_cents": 500,
      "occurred_at": "2026-10-02T09:14:00+02:00",
      "order_ref": "103002"
    },
    {
      "id": "tx_82",
      "type": "redeem",
      "email": "kundin@example.com",
      "amount_cents": 500,
      "occurred_at": "2026-10-05T18:40:00+02:00",
      "order_ref": "103950"
    }
  ]
}

{ "accepted": 2, "duplicates": 0, "applied": 1 }

Einmal am Tag meldest du die Salden je Kunde an PUT /v1/credit-balances ({ "balances": [{ "email": "…", "balance_cents": 1250 }] }). Rechnungskit vergleicht sie mit dem Verlauf; weicht ein Kunde ab, entsteht eine Aufgabe. So fällt auch eine verlorene Meldung auf.

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 startet im Testmodus, mit derselben API, derselben Pipeline und demselben rk_key_…-Schlüssel wie im Echtbetrieb, inklusive EN-16931-Validierung und PDF/A-3-Rendering. Du testest also exakt das Verhalten, das später live läuft — mit dem Schlüssel, der auch live gilt.

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.