exportly

API und Webhooks für deine E-Rechnungen

Hole die ZUGFeRD-PDFs und XRechnung-XMLs, die „Exportly E-Rechnung“ in Stripe erzeugt, automatisch auf deinen Server – per Abruf oder per signiertem Webhook.

Live-Modus ab Business · Testmodus in allen Tarifen · keine Zusatzkosten

Einführung

Deine E-Rechnungen, maschinenlesbar abrufen

Mit der Abruf-API holt dein Server die E-Rechnungen, die die Stripe-App „Exportly E-Rechnung“ erzeugt hat, automatisch ab – zum Beispiel für dein ERP, deine Buchhaltung oder dein Dokumentenarchiv. Die Zuordnung läuft über die Stripe-ID der Rechnung (in_…) bzw. Gutschrift (cn_…).

Statt regelmäßig abzufragen, kann Exportly dir jede Änderung auch sofort per Webhook melden.

Verfügbarkeit nach Modus
ModusSchlüsselVerfügbar
Testmoduserk_test_…in jedem Tarif
Live-Moduserk_live_…Business und Enterprise

Die API und die Webhooks verursachen keine Zusatzgebühren.

Du willst deine E-Rechnungen lieber per KI-Assistent abfragen? Mit demselben Schlüssel verbindest du Claude Code, Cursor oder VS Code über den MCP-Server.

Alle Beispiele zeigen fiktive Rechnungen der Lumen Studio GmbH.

Beispiel
Stripe-Rechnung in_…  →  Exportly E-Rechnung (App)
                          │
        GET /v1/documents ┤  du fragst ab
        Webhook (signiert)┘  oder wirst benachrichtigt
                          │
               ZUGFeRD-PDF + XRechnung-XML

Schnellstart

In drei Schritten zum ersten Abruf

  1. Öffne die App im Stripe-Dashboard unter Einstellungen → Exportly E-Rechnung → Reiter „API“ und erzeuge einen Schlüssel. Das geht nur als Administrator des Stripe-Kontos.
  2. Kopiere den Schlüssel sofort – er wird genau einmal angezeigt.
  3. Rufe die Liste deiner Dokumente ab, zum Beispiel mit dem Aufruf rechts. Ersetze den Platzhalter durch deinen Schlüssel.
Anfrage
curl "https://api.exportly.de/v1/documents?limit=10" \
  -H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"

Einstieg

Authentifizierung

Jede Anfrage trägt deinen API-Schlüssel als Bearer-Token im Authorization-Header. Ein Schlüssel gilt für ein Stripe-Konto und einen Modus – den Modus, in dem du die App beim Erzeugen geöffnet hast:

  • erk_test_… sieht nur Dokumente aus dem Testmodus,
  • erk_live_… sieht nur Live-Dokumente.
Header
GET /v1/documents HTTP/1.1
Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX

Einstieg

Basis-URL

Alle Endpunkte liegen unter https://api.exportly.de/v1. Eine eigene Domain ist geplant; die gültige Adresse zeigt dir auch der Reiter „API“ in der App.

Maschinenlesbar: OpenAPI-Spezifikation (JSON) – OpenAPI 3.1, für Code-Generatoren, Postman und API-Explorer.

Basis-URL
https://api.exportly.de/v1

Abruf-API

Dokumente auflisten

GET/v1/documents

Liefert die Dokumente, die sich seit since geändert haben (erzeugt, fehlgeschlagen, versendet, zugestellt, abgewiesen, storniert, Zahlungsvermerk), aufsteigend nach Änderungszeit – je Dokument den aktuellen Stand. Ein Dokument erscheint pro Seite höchstens einmal; hat es sich nach deinem letzten Abruf erneut geändert, kommt es beim nächsten Abruf wieder.

Parameter

Query-Parameter von GET /v1/documents
NameTypPflichtBeschreibung
sinceISO-8601optionalÄnderungen ab diesem Zeitpunkt (inklusive). Ohne since: alle gespeicherten Änderungen – die Änderungsliste reicht 97 Tage zurück.
limitinteger 1–100optionalSeitengröße, Standard 50.
cursorstringoptionalnext_cursor der vorherigen Antwort. Hat Vorrang vor since.
selleracct_…optionalNur Dokumente dieses verbundenen Kontos (Stripe Connect). Gefiltert wird je Seite – eine Seite kann weniger als limit Einträge haben; next_cursor und has_more gelten unverändert.
versionenumoptionalWelche Fassung je Dokument (ab 1.9.1): original (Standard) oder latest (jüngste, nach Zahlung die Fassung mit Zahlvermerk).

Antwort

Felder der Listenantwort
NameTypBeschreibung
object"list"Immer list.
dataDokument[]Liste von Dokument-Objekten.
has_morebooleantrue, wenn es weitere Seiten gibt.
next_cursorstringCursor für den nächsten Abruf.
next_urlstringFertige URL für den nächsten Abruf (Cursor und limit schon eingesetzt) – einfach als nächste Anfrage aufrufen.

Empfohlenes Abrufmuster

Setze beim ersten Mal since, frage danach immer mit dem letzten next_cursor weiter – auch wenn has_more false ist. So bekommst du jede Änderung in Reihenfolge. Ist nichts Neues da, kommt data: [] und derselbe Cursor zurück. Änderungen erscheinen mit etwa 5 Sekunden Verzögerung, damit gleichzeitige Schreibvorgänge nie hinter einem bereits ausgegebenen Cursor landen.

Abruf-Schleife
let cursor = loadCursor(); // zuletzt gespeicherter next_cursor
const headers = { Authorization: "Bearer " + process.env.EXPORTLY_API_KEY };

for (;;) {
  const url = new URL("https://api.exportly.de/v1/documents");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  else url.searchParams.set("since", "2026-11-01T00:00:00Z");

  const res = await fetch(url, { headers });
  if (res.status === 429) {
    const wait = Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
    continue;
  }
  const page = await res.json();
  for (const doc of page.data) await handle(doc);

  cursor = page.next_cursor;
  saveCursor(cursor); // nach jeder Seite sichern
  if (!page.has_more) break;
}
Nichts Neues
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": "eyJ2IjoxLCJzayI6…",
  "next_url": "https://api.exportly.de/v1/documents?cursor=eyJ2IjoxLCJzayI6…"
}
Anfrage
curl -G "https://api.exportly.de/v1/documents" \
  -H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -d since=2026-11-01T00:00:00Z \
  -d limit=100
Antwort
{
  "object": "list",
  "data": [
    {
      "id": "in_1QxLumen7hK2",
      "object": "invoice",
      "invoice_id": null,
      "number": "LS-2026-0142",
      "status": "sent",
      "format": "both",
      "livemode": false,
      "amount_gross": 11900,
      "currency": "eur",
      "issue_date": "2026-11-03",
      "created_at": "2026-11-03T09:12:41.000Z",
      "updated_at": "2026-11-03T09:13:05.000Z",
      "generated_at": "2026-11-03T09:12:44.000Z",
      "sent_at": "2026-11-03T09:13:02.000Z",
      "delivery_status": "delivered",
      "error": null,
      "warnings": [],
      "archived_until": null,
      "seller_account": null,
      "error_code": null,
      "paid_at": "2026-11-03T09:12:39.000Z",
      "settlement": "payment",
      "customer_id": "cus_QxR2fA81bLm3",
      "buyer_name": "Nordwind Solutions GmbH",
      "amount_net": 10000,
      "amount_tax": 1900,
      "version": {
        "number": 1,
        "id": null,
        "trigger": "finalized",
        "generated_at": "2026-11-03T09:12:44.000Z",
        "variant": "original"
      },
      "versions_count": 2,
      "validation": {
        "zugferd": {
          "status": "checked",
          "profile": "en16931",
          "mode": "observe",
          "checked_at": "2026-11-03T09:12:43.000Z",
          "rules_version": "en16931-cii 1.3.16 / kosit-config 2026-08-31",
          "valid": true,
          "error_count": 0,
          "warning_count": 0,
          "findings": [],
          "findings_truncated": false,
          "reason": null,
          "summary": "geprüft nach EN 16931 (KoSIT-Prüfregeln en16931-cii 1.3.16 / kosit-config 2026-08-31) am 03.11.2026, 0 Fehler, 0 Hinweise"
        },
        "xrechnung": null
      },
      "files": {
        "pdf": {
          "url": "https://…/LS-2026-0142.pdf?X-Amz-Expires=900&…",
          "expires_at": "2026-11-09T10:15:00.000Z",
          "sha256": "…"
        },
        "xml": {
          "url": "https://…/LS-2026-0142.xml?X-Amz-Expires=900&…",
          "expires_at": "2026-11-09T10:15:00.000Z",
          "sha256": "9f2c…e41a"
        }
      }
    }
  ],
  "has_more": false,
  "next_cursor": "eyJ2IjoxLCJzayI6…",
  "next_url": "https://api.exportly.de/v1/documents?cursor=eyJ2IjoxLCJzayI6…"
}

Abruf-API

Ein Dokument abrufen

GET/v1/documents/{id}

Liefert ein einzelnes Dokument samt frischen Download-Links – standardmäßig das Original.

Parameter

Parameter von GET /v1/documents/{id}
NameTypPflichtBeschreibung
idstringPflichtStripe-ID der Rechnung (in_…) oder Gutschrift (cn_…).
versionenumoptionalQuery-Parameter (ab 1.9.1): original (Standard) oder latest.

Antwort

Das Dokument-Objekt. Unbekannte Dokumente – und Dokumente eines anderen Kontos oder Modus – liefern 404 not_found.

Anfrage
curl "https://api.exportly.de/v1/documents/in_1QxLumen7hK2" \
  -H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"
Antwort
{
  "id": "in_1QxLumen7hK2",
  "object": "invoice",
  "invoice_id": null,
  "number": "LS-2026-0142",
  "status": "sent",
  "format": "both",
  "livemode": false,
  "amount_gross": 11900,
  "currency": "eur",
  "issue_date": "2026-11-03",
  "created_at": "2026-11-03T09:12:41.000Z",
  "updated_at": "2026-11-03T09:13:05.000Z",
  "generated_at": "2026-11-03T09:12:44.000Z",
  "sent_at": "2026-11-03T09:13:02.000Z",
  "delivery_status": "delivered",
  "error": null,
  "warnings": [],
  "archived_until": null,
  "seller_account": null,
  "error_code": null,
  "paid_at": "2026-11-03T09:12:39.000Z",
  "settlement": "payment",
  "customer_id": "cus_QxR2fA81bLm3",
  "buyer_name": "Nordwind Solutions GmbH",
  "amount_net": 10000,
  "amount_tax": 1900,
  "version": {
    "number": 1,
    "id": null,
    "trigger": "finalized",
    "generated_at": "2026-11-03T09:12:44.000Z",
    "variant": "original"
  },
  "versions_count": 2,
  "validation": {
    "zugferd": {
      "status": "checked",
      "profile": "en16931",
      "mode": "observe",
      "checked_at": "2026-11-03T09:12:43.000Z",
      "rules_version": "en16931-cii 1.3.16 / kosit-config 2026-08-31",
      "valid": true,
      "error_count": 0,
      "warning_count": 0,
      "findings": [],
      "findings_truncated": false,
      "reason": null,
      "summary": "geprüft nach EN 16931 (KoSIT-Prüfregeln en16931-cii 1.3.16 / kosit-config 2026-08-31) am 03.11.2026, 0 Fehler, 0 Hinweise"
    },
    "xrechnung": null
  },
  "files": {
    "pdf": {
      "url": "https://…/LS-2026-0142.pdf?X-Amz-Expires=900&…",
      "expires_at": "2026-11-09T10:15:00.000Z",
      "sha256": "…"
    },
    "xml": {
      "url": "https://…/LS-2026-0142.xml?X-Amz-Expires=900&…",
      "expires_at": "2026-11-09T10:15:00.000Z",
      "sha256": "9f2c…e41a"
    }
  }
}

Abruf-API

Fassungen eines Dokuments

GET/v1/documents/{id}/versions

Ab App 1.9.1 ist das Original maßgeblich – die Rechnung, die dein Kunde bekommen hat. Nach einer echten Zahlung entsteht die Fassung mit Zahlvermerk zusätzlich, das Original bleibt unverändert. Dieser Endpunkt listet alle Fassungen, älteste zuerst, mit Auslöser, Prüfsumme und frischen Links.

  • variant: original, paid (Fassung mit Zahlvermerk) oder superseded (durch „Neu erzeugen“ ersetzt).
  • source: archive im Live-Modus mit GoBD-Archiv bzw. im Testmodus aus dem Testarchiv (ab 1.9.2, 30 Tage), sonst working_copy (90 Tage; danach files: null).
  • Dokumente von vor 1.9.1: Wurde die Arbeitskopie damals durch die Fassung mit Zahlvermerk ersetzt, kommt das Original aus dem Archiv. Ohne Archiv liefert GET /v1/documents/{id} die vorhandene Datei mit version.variant: "paid"; mit ?version=original dagegen files: null und version_unavailable.
Anfrage
curl "https://api.exportly.de/v1/documents/in_1QxLumen7hK2/versions" \
  -H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"

# Jüngste Fassung (nach Zahlung: mit Zahlvermerk)
curl "https://api.exportly.de/v1/documents/in_1QxLumen7hK2?version=latest" \
  -H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"
Antwort
{
  "object": "list",
  "document_id": "in_1QxLumen7hK2",
  "data": [
    {
      "object": "document_version",
      "number": 1,
      "id": null,
      "trigger": "finalized",
      "generated_at": "2026-11-03T09:12:44.000Z",
      "variant": "original",
      "source": "working_copy",
      "reason": null,
      "archived_until": null,
      "validation": null,
      "files": {
        "pdf": { "url": "https://…/LS-2026-0142.pdf?X-Amz-Expires=900&…", "expires_at": "2026-11-09T10:15:00.000Z", "sha256": "…" },
        "xml": { "url": "https://…/LS-2026-0142.xml?X-Amz-Expires=900&…", "expires_at": "2026-11-09T10:15:00.000Z", "sha256": "…" }
      }
    },
    {
      "object": "document_version",
      "number": 2,
      "id": null,
      "trigger": "paid",
      "generated_at": "2026-11-04T08:02:10.000Z",
      "variant": "paid",
      "source": "working_copy",
      "reason": null,
      "archived_until": null,
      "validation": null,
      "files": {
        "pdf": { "url": "https://…/LS-2026-0142-Zahlvermerk.pdf?X-Amz-Expires=900&…", "expires_at": "2026-11-09T10:15:00.000Z", "sha256": "…" },
        "xml": { "url": "https://…/LS-2026-0142-Zahlvermerk.xml?X-Amz-Expires=900&…", "expires_at": "2026-11-09T10:15:00.000Z", "sha256": "…" }
      }
    }
  ],
  "has_more": false
}

Abruf-API

Das Dokument-Objekt

Ein Dokument beschreibt den aktuellen Stand einer Rechnung oder Gutschrift in „Exportly E-Rechnung“. Felder mit „nullable“ können null sein.

Attribute des Dokument-Objekts
NameTypNullBeschreibung
idstringStripe-ID der Rechnung (in_…) bzw. Gutschrift (cn_…).
object"invoice" | "credit_note"Art des Dokuments.
invoice_idstringnullableBei Gutschriften die zugehörige Rechnung.
numberstringRechnungs- bzw. Gutschriftnummer.
statusenumprocessing, generated, sent, failed oder voided.
formatenumWirksames E-Rechnungsformat: zugferd, xrechnung oder both.
livemodebooleantrue für Live-Dokumente, false für Testmodus.
amount_grossintegerBruttobetrag in Cent (kleinste Währungseinheit), wie bei Stripe.
currencystringISO 4217, klein geschrieben (eur).
issue_datestringnullableRechnungsdatum YYYY-MM-DD.
created_atISO-8601Erste Erzeugung.
updated_atISO-8601Letzte Änderung.
generated_atISO-8601nullableLetzte erfolgreiche Erzeugung.
sent_atISO-8601nullableVersand per E-Mail.
delivery_statusstringnullableZustellstatus der Mail: sent, delivered, bounced, complained.
errorstringnullableFehlergrund (bei failed) bzw. Hinweis (bei voided).
warningsstring[]Hinweise der Prüfung (deutsch).
archived_untilISO-8601nullableEnde der GoBD-Aufbewahrung, falls archiviert.
seller_accountstringnullableStripe Connect: verbundenes Konto (acct_…), in dessen Namen die Rechnung gestellt wurde – Verkäufer ist dann dieser Händler. null = dein eigenes Konto. Siehe Händler.
error_codeenumnullableFehlergrund bei failed: seller_missing, connect_plan_required, connect_disabled, connect_key_invalid (Plattform-Schlüssel von Stripe abgelehnt), xrechnung_validation_unavailable (Prüfung der XRechnung war nach mehreren Versuchen nicht möglich – erneut erzeugen) oder xrechnung_validation_error (der Prüfdienst konnte dieses Dokument nicht verarbeiten – erneutes Erzeugen hilft nicht, bitte Support kontaktieren). Bei allen anderen Fehlern null – der Grund steht dann in error.
paid_atISO-8601nullableZeitpunkt, zu dem die Rechnung laut Stripe beglichen wurde (bezahlt, per Gutschrift oder Guthaben ausgeglichen, Rechnung über 0 €). null solange offen und bei Gutschriften.
settlementenumnullableWodurch beglichen: payment (gezahlt), credit_note (durch Gutschrift ausgeglichen, nichts gezahlt), balance (Kundenguthaben), zero (Rechnung über 0 €), mixed (teils Gutschrift, teils Zahlung).
customer_idstringnullableStripe-Kunde (cus_…) – für die Zuordnung im ERP.
buyer_namestringnullableKäufername (BT-44).
amount_netintegernullableNetto in Cent (BT-109).
amount_taxintegernullableUmsatzsteuer in Cent (BT-110).
versionobjectnullableGelieferte Fassung – ab App 1.9.1 standardmäßig das Original: number (1 = erste Erzeugung), id (Archiv-ID, nur mit GoBD-Archiv), trigger (z. B. finalized, regenerate, paid), generated_at, variant (original oder paid = Fassung mit Zahlvermerk). Entdoppeln beim Import über id + version.number.
versions_countintegernullableAnzahl bisher erzeugter Fassungen (ab 1.9.1). Alle Fassungen: GET /v1/documents/{id}/versions.
filesobjectnullableDownload-Links, siehe Download-Links.
files_unavailable_reasonenumnullableNur wenn files null ist: expired, not_generated oder version_unavailable (?version=original, aber das Original wurde vor 1.9.1 durch die Fassung mit Zahlvermerk ersetzt und ist nicht archiviert).
Objekt
{
  "id": "in_1QxLumen7hK2",
  "object": "invoice",
  "invoice_id": null,
  "number": "LS-2026-0142",
  "status": "sent",
  "format": "both",
  "livemode": false,
  "amount_gross": 11900,
  "currency": "eur",
  "issue_date": "2026-11-03",
  "created_at": "2026-11-03T09:12:41.000Z",
  "updated_at": "2026-11-03T09:13:05.000Z",
  "generated_at": "2026-11-03T09:12:44.000Z",
  "sent_at": "2026-11-03T09:13:02.000Z",
  "delivery_status": "delivered",
  "error": null,
  "warnings": [],
  "archived_until": null,
  "seller_account": null,
  "error_code": null,
  "paid_at": "2026-11-03T09:12:39.000Z",
  "settlement": "payment",
  "customer_id": "cus_QxR2fA81bLm3",
  "buyer_name": "Nordwind Solutions GmbH",
  "amount_net": 10000,
  "amount_tax": 1900,
  "version": {
    "number": 1,
    "id": null,
    "trigger": "finalized",
    "generated_at": "2026-11-03T09:12:44.000Z",
    "variant": "original"
  },
  "versions_count": 2,
  "validation": {
    "zugferd": {
      "status": "checked",
      "profile": "en16931",
      "mode": "observe",
      "checked_at": "2026-11-03T09:12:43.000Z",
      "rules_version": "en16931-cii 1.3.16 / kosit-config 2026-08-31",
      "valid": true,
      "error_count": 0,
      "warning_count": 0,
      "findings": [],
      "findings_truncated": false,
      "reason": null,
      "summary": "geprüft nach EN 16931 (KoSIT-Prüfregeln en16931-cii 1.3.16 / kosit-config 2026-08-31) am 03.11.2026, 0 Fehler, 0 Hinweise"
    },
    "xrechnung": null
  },
  "files": {
    "pdf": {
      "url": "https://…/LS-2026-0142.pdf?X-Amz-Expires=900&…",
      "expires_at": "2026-11-09T10:15:00.000Z",
      "sha256": "…"
    },
    "xml": {
      "url": "https://…/LS-2026-0142.xml?X-Amz-Expires=900&…",
      "expires_at": "2026-11-09T10:15:00.000Z",
      "sha256": "9f2c…e41a"
    }
  }
}

Abruf-API

Fehlercodes

Alle Fehler kommen als JSON mit englischer Meldung. Werte deine Logik am code aus, nicht am Meldungstext.

HTTP-Status und Fehlercodes
HTTPcodeBedeutung
400invalid_requestUngültiger Parameter (limit, since, cursor).
401invalid_api_keySchlüssel fehlt, ist falsch, widerrufen oder die App ist deinstalliert.
403plan_requiredLive-Schlüssel ohne Business/Enterprise bzw. /v1/sellers live ohne Enterprise.
404not_foundDokument bzw. Händler unbekannt (oder gehört zu einem anderen Konto/Modus).
404seller_not_found/v1/sellers/{account}…: kein Händler deiner Plattform (mit Plattform-Schlüssel: kein verbundenes Konto; ohne: kein angelegter Händler).
409connect_key_rejectedStripe lehnt den in der App hinterlegten Plattform-Schlüssel ab – bitte neu hinterlegen.
429rate_limitedMehr als 60 Anfragen je Minute und Schlüssel; Header Retry-After (Sekunden).
500internal_errorUnerwarteter Fehler – bitte später erneut versuchen.
Fehlerantwort
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided."
  }
}

Abruf-API

Mengenbegrenzung

Es gelten 60 Anfragen pro Minute und Schlüssel (festes Minutenfenster, UTC). Mit limit=100 sind das bis zu 6.000 Dokumente pro Minute.

Bei 429 wartest du die Sekunden aus dem Header Retry-After ab und fragst dann erneut.

Antwort
HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Limit: 60 requests per minute per API key."
  }
}

Händler (Stripe Connect)

Rechnungen im Namen deiner Händler

Rechnest du als Plattform über Stripe Connect ab und stellst Rechnungen im Namen deiner Händler – Rechnung auf deinem Konto mit issuer[type]=account und issuer[account]=acct_… oder mit on_behalf_of=acct_… –, ist rechtlich der Händler der Verkäufer. Exportly erzeugt die E-Rechnung dann mit seinen Firmendaten (Name, Anschrift, USt-IdNr. bzw. Steuernummer, Kontakt, Bankverbindung) – nie mit deinen. Gutschriften folgen ihrer Rechnung.

  • Erkennung: issuer.type = account → issuer.account, sonst on_behalf_of. Ohne beides bleibt alles wie bisher.
  • Die Händlerdaten liegen in den Metadaten des verbundenen Kontos in Stripe (siehe Händlerdaten aus Stripe) – gepflegt von dir per Stripe-API, im Formular der App (Vollbild-Ansicht Händler) oder per PUT /v1/sellers/{account}.
  • In der App schaltest du „Rechnungen im Namen verbundener Konten“ ein (Standard: aus). Testmodus für alle Tarife, Live-Modus mit Enterprise.
  • Fehlen Händlerdaten, Freischaltung oder Schalter, wird das Dokument failed – mit error_code seller_missing, connect_plan_required bzw. connect_disabled und dem Webhook document.failed. Das Feld seller_account nennt den Händler, auch in der Webhook-Nutzlast.
Fehlende Händlerdaten
{
  "id": "evt_7Qp2…",
  "type": "document.failed",
  "created": 1762682400,
  "livemode": false,
  "data": {
    "object": {
      "id": "in_1QxNordH4e1",
      "object": "invoice",
      "status": "failed",
      "seller_account": "acct_1NordLicht7",
      "error_code": "seller_missing",
      "error": "Händlerdaten fehlen für acct_1NordLicht7 — …",
      "…": "…"
    }
  }
}

Händler (Stripe Connect)

Händlerdaten aus Stripe

Weg 1 (empfohlen): Setze die Händlerdaten beim Onboarding als Metadaten am verbundenen Konto (POST /v1/accounts/{account} mit metadata[einvoice_…]). Die USt-IdNr. kann alternativ als Steuer-ID des Kontos mit settings.invoices.default_account_tax_ids hinterlegt werden – Stripe schreibt sie dann mit dem Namen (account_name, account_tax_ids) auf jede Rechnung. Eine manuelle Pflege bei Exportly ist dann nicht nötig.

Standard-Schlüssel in den Metadaten des verbundenen Kontos
Metadaten-SchlüsselBedeutung
einvoice_nameFirmenname
einvoice_streetStraße und Hausnummer
einvoice_street2Adresszusatz (optional)
einvoice_postal_codePLZ
einvoice_cityOrt
einvoice_countryLand (ISO 3166-1 alpha-2, z. B. DE)
einvoice_vat_idUSt-IdNr. (falls nicht über default_account_tax_ids)
einvoice_tax_numberSteuernummer
einvoice_registerRegistereintrag
einvoice_managing_directorsGeschäftsführung
einvoice_contact_name / _phone / _emailAnsprechpartner (Pflicht für XRechnung)
einvoice_account_holder / _iban / _bic / _bankBankverbindung (IBAN mit Prüfziffer)
einvoice_email / _phone / _websiteKontakt (Antworten der Kunden gehen an die E-Mail)
einvoice_small_businesstrue = Kleinunternehmer nach § 19 UStG

Eigene Schlüssel zuordnen

Nutzt deine Plattform schon eigene Metadaten (z. B. hrb für den Registereintrag), ordnest du sie in der App unter Händler → Metadaten zuordnen unseren Feldern zu. Die Zuordnung hat Vorrang vor den Standard-Schlüsseln und gilt beim Lesen und Speichern.

Vorrang je Feld

  1. Metadaten des verbundenen Kontos (Zuordnung, dann einvoice_*)
  2. Bei Exportly gespeicherte Händlerdaten (Bestand, ohne Plattform-Schlüssel)
  3. Rechnung: account_name → Name, account_tax_ids → USt-IdNr.
  4. Stammdaten des Kontos: company.address bzw. Support-Anschrift, E-Mail, Name

Ungültige Werte (z. B. IBAN mit falscher Prüfziffer) werden ignoriert und in der App als Hinweis gezeigt. Fehlen danach Name, Anschrift oder USt-IdNr./Steuernummer, wird das Dokument failed (seller_missing). Änderungen an den Metadaten gelten sofort für neue Rechnungen.

Beim Onboarding setzen
curl https://api.stripe.com/v1/accounts/acct_1NordLicht7 \
  -u "$STRIPE_SECRET_KEY:" \
  -d "metadata[einvoice_name]=Nordlicht Studio GmbH" \
  -d "metadata[einvoice_street]=Deichweg 3" \
  -d "metadata[einvoice_postal_code]=28195" \
  -d "metadata[einvoice_city]=Bremen" \
  -d "metadata[einvoice_country]=DE" \
  -d "metadata[einvoice_register]=HRB 12345 Amtsgericht Bremen" \
  -d "metadata[einvoice_iban]=DE89370400440532013000"

Händler (Stripe Connect)

Händler anlegen oder ändern

PUT/v1/sellers/{account}

Legt die Firmendaten des verbundenen Kontos account an oder ersetzt sie vollständig. Unbekannte Felder werden abgelehnt, IBANs auf ihre Prüfziffer geprüft. Die Antwort enthält zusätzlich retried_documents – die Zahl der nachgeholten Dokumente.

Body

Felder von PUT /v1/sellers/{account}
NameTypPflichtBeschreibung
namestringPflichtFirmenname (BT-27).
addressobjectPflichtline1, postal_code, city, country (ISO 3166-1 alpha-2); optional line2.
vat_idstringoptionalUSt-IdNr. mit Länderpräfix. vat_id oder tax_number ist Pflicht.
tax_numberstringoptionalSteuernummer.
emailstringoptionalKontakt; Antworten der Kunden auf die Rechnungs-Mail gehen hierhin.
bankobjectoptionaliban, bic, bank_name – Bankverbindung in der PDF-Fußzeile (Zahlungsziel ist nur die Banküberweisung der Stripe-Rechnung).
contactobjectoptionalname, phone, email – Ansprechpartner, Pflicht für XRechnung.
phone, website, registry, managing_directorstringoptionalAngaben für Fußzeile und Impressum.
small_businessbooleanoptionalKleinunternehmer nach § 19 UStG.
Anfrage
curl -X PUT "https://api.exportly.de/v1/sellers/acct_1NordLicht7" \
  -H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Nordlicht Handel GmbH", "address": { "line1": "Speicherstadt 3", "postal_code": "20457", "city": "Hamburg", "country": "DE" }, "vat_id": "DE811907980", "email": "rechnung@nordlicht-handel.example", "bank": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX" }, "contact": { "name": "Hanna Nord", "phone": "+49 40 123456", "email": "buchhaltung@nordlicht-handel.example" } }'
Antwort
{
  "id": "acct_1NordLicht7",
  "object": "seller",
  "livemode": false,
  "name": "Nordlicht Handel GmbH",
  "address": {
    "line1": "Speicherstadt 3",
    "line2": null,
    "postal_code": "20457",
    "city": "Hamburg",
    "country": "DE"
  },
  "vat_id": "DE811907980",
  "tax_number": null,
  "email": "rechnung@nordlicht-handel.example",
  "phone": "+49 40 123456",
  "website": null,
  "registry": "HRB 99999 Amtsgericht Hamburg",
  "managing_director": "Hanna Nord",
  "bank": { "iban": "DE89370400440532013000", "bic": "COBADEFFXXX", "bank_name": null },
  "contact": { "name": "Hanna Nord", "phone": "+49 40 123456", "email": "buchhaltung@nordlicht-handel.example" },
  "small_business": false,
  "source": "api",
  "created_at": "2026-11-09T10:00:00.000Z",
  "updated_at": "2026-11-09T10:00:00.000Z",
  "retried_documents": 2
}

Händler (Stripe Connect)

Händler abrufen und löschen

GET/v1/sellers
GET/v1/sellers/{account}
DELETE/v1/sellers/{account}

GET /v1/sellers liefert alle gepflegten Händler deines Kontos und Modus als Liste (object, data, has_more), GET /v1/sellers/{account} einen Händler. DELETE löscht die Firmendaten; neue Rechnungen dieses Händlers werden danach wieder failed (seller_missing). Mit GET /v1/documents?seller=acct_… holst du nur die Dokumente eines Händlers.

Anfrage
curl "https://api.exportly.de/v1/sellers" \
  -H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"

Händler (Stripe Connect)

Das Händler-Objekt

Felder des Händler-Objekts
NameTypBeschreibung
idstringVerbundenes Konto (acct_…).
object"seller"Immer seller.
livemodebooleanModus des Schlüssels.
namestringFirmenname.
addressobjectline1, line2, postal_code, city, country.
vat_idstringUSt-IdNr.
tax_numberstringSteuernummer.
emailstringKontakt-E-Mail.
bankobjectiban, bic, bank_name.
contactobjectname, phone, email (jeweils nullable).
small_businessbooleanKleinunternehmer nach § 19 UStG.
sourceenumapi oder app – wo zuletzt gespeichert.
created_at, updated_atISO-8601Anlage und letzte Änderung.

Händler (Stripe Connect)

Rechnungsdesign je Händler

GET/v1/sellers/{account}/design
PUT/v1/sellers/{account}/design
DELETE/v1/sellers/{account}/design
POST/v1/sellers/{account}/files
GET/v1/sellers/{account}/preview

Jeder Händler kann ein eigenes Erscheinungsbild bekommen: Vorlage, Logo, Akzentfarbe, Schrift oder eigenes Briefpapier, dazu optional eine eigene Mail-Vorlage. Es gilt für alle künftigen Rechnungen des Händlers. Ohne eigenes Design gilt dein Design – aber nie dein Briefpapier (es trägt deine Firmendaten).

  • PUT …/design ist ein Teil-Update: weggelassene Felder bleiben, null setzt zurück. DELETE stellt auf dein Design zurück.
  • Logo und Briefpapier lädst du mit POST …/files hoch (Logo PNG/JPG bis 2 MB, Briefpapier PDF/PNG/JPG bis 10 MB), danach logo_file_id bzw. letterhead_file_id im Design setzen. Briefpapier wird gerastert, freie Ränder werden automatisch erkannt.
  • GET …/preview rendert eine Beispielrechnung mit den Händlerdaten und liefert Links auf PDF und PNG (15 Minuten gültig).
Anfrage
curl -X POST "https://api.exportly.de/v1/sellers/acct_1NordLicht7/files" \
  -H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "purpose": "logo", "content_type": "image/png", "size": 48213 }'
# Antwort: id + upload_url – Datei genau so hochladen:
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @nordlicht.png
Antwort
{
  "seller": "acct_1NordLicht7",
  "object": "seller_design",
  "livemode": false,
  "source": "own",
  "template": "modern",
  "accent_color": "#1f6f5a",
  "font": null,
  "logo": { "file_name": "nordlicht.png", "content_type": "image/png", "width": 600, "height": 180 },
  "letterhead": null,
  "mail": { "subject": "Ihre {{dokumentart}} {{rechnungsnummer}} von {{firma}}", "body": null, "signature": null },
  "updated_at": "2026-11-10T09:30:00.000Z"
}

Webhooks

Webhooks einrichten

Statt regelmäßig abzufragen, meldet Exportly deinem Server jede Änderung sofort. Den Webhook richtest du in der Stripe-App unter Einstellungen → Exportly E-Rechnung → API → Webhook ein (nur Administratoren; Tarif wie die API: Test für alle, Live ab Business). Je Konto und Modus gibt es einen Webhook.

  • Nur https://-Adressen, die öffentlich erreichbar sind (keine privaten Netze, kein localhost, keine internen Namen; jede DNS-Auflösung wird geprüft, auch bei jeder Zustellung).
  • Weiterleitungen (3xx) werden nicht verfolgt und zählen als Fehler.
  • Beim Anlegen (und bei „Secret erneuern“) wird das Signatur-Secret (whsec_…) einmal angezeigt.
  • „Test senden“ schickt ein Ereignis webhook.test; das Ergebnis steht im Zustellprotokoll (letzte 50 Zustellungen) im selben Reiter.
Zustellprotokoll
1. App → Einstellungen → Exportly E-Rechnung
   → Reiter „API“ → Webhook
2. https://-Adresse eintragen
3. Signatur-Secret (whsec_…) einmal kopieren
4. „Test senden“ → Ereignis webhook.test

Webhooks

Ereignistypen

Webhook-Ereignistypen
typeWann
document.generatedE-Rechnung erzeugt (auch erneut erzeugt).
document.failedErzeugung fehlgeschlagen.
document.sentPer E-Mail versendet.
document.delivery_updatedZustellstatus der Mail geändert (zugestellt, abgewiesen, Beschwerde).
document.voidedRechnung in Stripe storniert.
document.paidRechnung beglichen (paid_at, settlement gesetzt). Nur bei echter Zahlung entsteht zusätzlich die Fassung mit Zahlvermerk (versions_count steigt, das Original bleibt); bei Gutschrift, Guthaben oder 0 € ändern sich nur die Felder.
webhook.test„Test senden“ in der App.
Ereignisse
document.generated
document.failed
document.sent
document.delivery_updated
document.voided
document.paid
webhook.test

Webhooks

Nutzlast

Exportly sendet jedes Ereignis als POST mit JSON-Body. data.object ist das Dokument-Objekt zum Zeitpunkt des Ereignisses, ohne files – die Download-Links holst du mit GET /v1/documents/{id}. Bei webhook.test ist data.object ein kurzes Testobjekt. Bei Rechnungen im Namen verbundener Konten enthält es seller_account (bei document.failed zusätzlich error_code).

Felder des Ereignisses
NameTypBeschreibung
idstringEreignis-ID (evt_…), identisch mit dem Header Exportly-Delivery.
typestringEreignistyp, siehe oben.
createdintegerUnix-Zeit des Ereignisses.
livemodebooleanModus des Dokuments.
data.objectDokumentDokument-Objekt ohne files.
  • Exportly-Delivery (= id) bleibt bei Wiederholungen gleich – verwirf Duplikate anhand dieser ID.
  • Die Reihenfolge der Zustellungen ist nicht garantiert; maßgeblich ist updated_at des Dokuments.
Zustellung
POST /dein/webhook HTTP/1.1
Content-Type: application/json; charset=utf-8
User-Agent: Exportly-ERechnung/1.0 (+https://exportly.de)
Exportly-Signature: t=1762682400,v1=<64 Hex-Zeichen>
Exportly-Delivery: evt_2Lk9…

{
  "id": "evt_2Lk9…",
  "type": "document.generated",
  "created": 1762682400,
  "livemode": false,
  "data": {
    "object": {
      "id": "in_1QxLumen7hK2",
      "object": "invoice",
      "number": "LS-2026-0142",
      "status": "generated",
      "…": "…"
    }
  }
}

Webhooks

Signatur prüfen

Jede Zustellung trägt den Header Exportly-Signature: t=<Unix-Zeit>,v1=<Hex>. Prüfe

  1. die Signatur über den unveränderten Roh-Body (nicht über neu serialisiertes JSON),
  2. mit einem zeitkonstanten Vergleich,
  3. dass t nicht älter als 5 Minuten ist (Schutz vor Wiedereinspielung).

Mit dem Prüfvektor testest du deine Implementierung, bevor du live gehst.

Signatur
Exportly-Signature: t=<Unix-Zeit>,v1=<Hex>

v1 = HMAC-SHA256(Signatur-Secret, "<t>.<roher Request-Body>")
Prüfung
import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.EXPORTLY_WEBHOOK_SECRET; // whsec_…
const TOLERANCE_SECONDS = 300;

function verifyExportlySignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    String(header ?? "").split(",").map((part) => part.split("=", 2)),
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`, "utf8").digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(parts.v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();
app.post("/exportly-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const rawBody = req.body.toString("utf8");
  if (!verifyExportlySignature(rawBody, req.get("Exportly-Signature"), SECRET)) {
    return res.status(400).send("invalid signature");
  }
  const event = JSON.parse(rawBody);
  // Duplikate über event.id verwerfen, dann asynchron verarbeiten:
  // z. B. bei document.generated GET /v1/documents/{event.data.object.id} und Dateien laden.
  res.sendStatus(200);
});
app.listen(3000);

Webhooks

Antwort und Wiederholungen

Antworte innerhalb von 10 Sekunden mit einem 2xx-Status. Alles andere – auch 3xx, ein Timeout oder ein Netzwerkfehler – gilt als nicht zugestellt.

Exportly wiederholt nach 1 min, 5 min, 30 min, 2 h, 6 h, 7 h und 8 h – insgesamt 8 Versuche über knapp 24 Stunden. Danach gilt die Zustellung als fehlgeschlagen; du siehst sie im Zustellprotokoll. Verpasste Änderungen holst du jederzeit mit GET /v1/documents?cursor=… nach.

Zurück zur Produktseite

Zeitplan
Versuch 1   sofort
Versuch 2   nach 1 min Pause
Versuch 3   nach 5 min Pause
Versuch 4   nach 30 min Pause
Versuch 5   nach 2 h Pause
Versuch 6   nach 6 h Pause
Versuch 7   nach 7 h Pause
Versuch 8   nach 8 h Pause