Entwickler

REST-API

Binde Belegschmied an dein ERP, deine Warenwirtschaft oder deine eigene Software an: PDF-Rechnungen per API in E-Rechnungen (ZUGFeRD / XRechnung, EN 16931) konvertieren und versenden, Eingangsrechnungen verarbeiten und alle Workspace-Daten abrufen – Ausgang, Eingang, Kunden, Lieferanten, Archiv und Protokoll.

Die API ist ab dem Business-Plan enthalten. API-Keys erstellst du in der App unter Einstellungen → REST-API.

Alle Endpunkte

Authentifizierung

Jeder Request braucht einen API-Key als Bearer-Token. Keys sind an deinen Workspace gebunden, beginnen mit bs_live_ und werden bei uns ausschließlich als SHA-256-Hash gespeichert – der Klartext ist nur einmal bei der Erstellung sichtbar. Kompromittierte Keys kannst du jederzeit in den Einstellungen widerrufen.

curl https://belegschmied.de/api/v1/workspace \
  -H "Authorization: Bearer bs_live_dein_key"

Grundlagen

Fehler

Fehler kommen als JSON mit statusCode und deutscher statusMessage.

Rate-Limits

240 Requests pro Minute und Key. Jede Antwort enthält X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset (Sekunden bis zum Fenster-Reset).

Pagination

Alle Listen-Endpunkte nehmen limit (1–100, Default 50) und offset und antworten einheitlich:

{
  "data": [ { "id": "…", "invoice_number": "2026-1042", "status": "sent", "…": "…" } ],
  "total": 137,
  "limit": 50,
  "offset": 0
}

Datums-Filter (from/to) erwarten YYYY-MM-DD.

Rechnung konvertieren & versenden

Die Kernfunktion: du lädst eine normale Rechnungs-PDF hoch, Belegschmied extrahiert die Rechnungsdaten per KI, prüft sie deterministisch (Arithmetik, Rechnungsnummer, EN-16931-Validierung) und erzeugt die E-Rechnung als ZUGFeRD-PDF mit eingebetteter XRechnung-XML – derselbe Ablauf wie beim Mail-Versand über deine Belegschmied-Adresse.

curl -X POST https://belegschmied.de/api/v1/invoices/outbound \
  -H "Authorization: Bearer bs_live_dein_key" \
  -F "pdf=@rechnung-2026-1042.pdf" \
  -F "recipient_email=buchhaltung@kunde.de"

Antwort 202 Accepted – die Verarbeitung läuft asynchron:

{
  "conversion_id": "3f6a2e10-…",
  "status": "accepted",
  "status_url": "/api/v1/conversions/3f6a2e10-…"
}

Felder

• pdf – die Rechnung als PDF (Pflicht, max 15 MB).
• send – false erzeugt und speichert die E-Rechnung nur (Status generated), ohne Versand. Default: versenden.
• recipient_email – explizite Empfänger-Adresse für den Versand. Fehlt sie, verwendet Belegschmied die aus der PDF extrahierte Kunden-E-Mail-Adresse. Ist auch dort keine zu finden, wird die Rechnung nur gespeichert und nicht versendet.

curl -X POST https://belegschmied.de/api/v1/invoices/outbound \
  -H "Authorization: Bearer bs_live_dein_key" \
  -F "pdf=@rechnung-2026-1042.pdf" \
  -F "send=false"

Verarbeitungsstatus abfragen

Mit der conversion_id aus der Upload-Antwort pollst du den Status. Bei Ausfällen externer Dienste (KI-Provider, Mail-Provider) bleibt der Job in processing und wird automatisch mit steigendem Abstand wiederholt – die Rechnung geht raus, sobald der Dienst wieder verfügbar ist.

curl https://belegschmied.de/api/v1/conversions/3f6a2e10-… \
  -H "Authorization: Bearer bs_live_dein_key"

{
  "id": "3f6a2e10-…",
  "type": "outbound",
  "status": "processed",
  "error_code": null,
  "error_message": null,
  "received_at": "2026-07-30T09:14:02.000Z",
  "processed_at": "2026-07-30T09:14:41.000Z",
  "invoice": {
    "id": "9c01b7aa-…",
    "invoice_number": "2026-1042",
    "invoice_date": "2026-07-30",
    "currency": "EUR",
    "status": "sent",
    "total_net": 1200.00,
    "total_vat": 228.00,
    "total_gross": 1428.00,
    "recipient_emails": ["buchhaltung@kunde.de"],
    "confidence_score": 0.97,
    "validation_valid": true,
    "line_items": [ "…" ]
  }
}

Status-Werte der Verarbeitung

Status-Werte der Ausgangsrechnung

Ausgangsrechnungen abrufen

Liste mit Filtern status, customer_id, invoice_number (Teilstring) und from/to (Rechnungsdatum). Das Detail (/invoices/outbound/{id}) enthält zusätzlich Positionen (line_items), USt-Aufschlüsselung, Validierungs-Issues und die vollständigen Extraktionsdaten.

curl "https://belegschmied.de/api/v1/invoices/outbound?status=sent&from=2026-07-01&limit=50" \
  -H "Authorization: Bearer bs_live_dein_key"

Dateien

curl -o rechnung.pdf "https://belegschmied.de/api/v1/invoices/outbound/9c01b7aa-…/pdf" \
  -H "Authorization: Bearer bs_live_dein_key"

# Original statt ZUGFeRD:
curl -o original.pdf "https://belegschmied.de/api/v1/invoices/outbound/9c01b7aa-…/pdf?variant=original" \
  -H "Authorization: Bearer bs_live_dein_key"

/xml liefert die im ZUGFeRD-PDF eingebettete XRechnung-XML als application/xml.

Eingangsrechnung verarbeiten

Eine empfangene Rechnung (PDF oder E-Rechnungs-XML) hochladen: Belegschmied erkennt das Format, validiert gegen EN 16931, extrahiert die Rechnungsdaten, ordnet den Lieferanten zu und legt die Datei revisionssicher im Archiv ab. Ebenfalls asynchron mit conversion_id und Statusabfrage über /conversions/{id}.

curl -X POST https://belegschmied.de/api/v1/invoices/inbound \
  -H "Authorization: Bearer bs_live_dein_key" \
  -F "file=@eingangsrechnung.pdf"

Eingangsrechnungen abrufen

Liste mit Filtern status, supplier_id, invoice_number und from/to (Empfangsdatum). Das Detail enthält Validierungsfehler und Extraktionsdaten; /invoices/inbound/{id}/file liefert die Original-Datei.

Kunden & Lieferanten

/customers und /suppliers liefern die Stammdaten deines Workspace inkl. Debitoren-/Kreditorennummern (DATEV-kompatibel). Beide unterstützen search (Name, Teilstring). /customers/{id} enthält zusätzlich alle verknüpften E-Mail-Adressen. Die Stammdaten pflegt Belegschmied beim Verarbeiten automatisch – neue Kunden und Lieferanten werden dedupliziert angelegt.

Protokoll (Audit-Log)

Jede relevante Aktion – Empfang, Extraktion, Prüfungen, Freigabe, Versand, API-Uploads, Einstellungs-Änderungen – landet im revisionssicheren Protokoll. Die Einträge sind pro Workspace über eine SHA-256-Hash-Chain verkettet (hash / prev_hash), nachträgliche Manipulation ist damit erkennbar. Filter: action, entity_type, entity_id, from/to.

curl "https://belegschmied.de/api/v1/audit-log?entity_type=outbound_invoice&limit=100" \
  -H "Authorization: Bearer bs_live_dein_key"

Workspace & Kontingent

/workspace liefert Name, Plan, Freigabe-Einstellung und den aktuellen Monats-Verbrauch gegen dein Beleg-Kontingent:

{
  "id": "…",
  "name": "Muster GmbH",
  "plan": "enterprise",
  "default_currency": "EUR",
  "require_approval": false,
  "quota": { "used": 412, "limit": 15000 }
}