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.
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.
| Modus | Schlüssel | Verfügbar |
|---|---|---|
| Testmodus | erk_test_… | in jedem Tarif |
| Live-Modus | erk_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.
Stripe-Rechnung in_… → Exportly E-Rechnung (App)
│
GET /v1/documents ┤ du fragst ab
Webhook (signiert)┘ oder wirst benachrichtigt
│
ZUGFeRD-PDF + XRechnung-XMLSchnellstart
In drei Schritten zum ersten Abruf
- Ö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.
- Kopiere den Schlüssel sofort – er wird genau einmal angezeigt.
- Rufe die Liste deiner Dokumente ab, zum Beispiel mit dem Aufruf rechts. Ersetze den Platzhalter durch deinen Schlüssel.
curl "https://api.exportly.de/v1/documents?limit=10" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"const res = await fetch("https://api.exportly.de/v1/documents?limit=10", {
headers: { Authorization: "Bearer " + process.env.EXPORTLY_API_KEY },
});
const { data, next_cursor } = await res.json();
console.log(data.length, "Dokumente, Cursor:", next_cursor);<?php
$ch = curl_init("https://api.exportly.de/v1/documents?limit=10");
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("EXPORTLY_API_KEY")],
CURLOPT_RETURNTRANSFER => true,
]);
$list = json_decode(curl_exec($ch), true);
echo count($list["data"]) . " Dokumente\n";import os
import requests
res = requests.get(
"https://api.exportly.de/v1/documents",
params={"limit": 10},
headers={"Authorization": "Bearer " + os.environ["EXPORTLY_API_KEY"]},
timeout=10,
)
page = res.json()
print(len(page["data"]), "Dokumente, Cursor:", page["next_cursor"])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.
GET /v1/documents HTTP/1.1
Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXXEinstieg
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.
https://api.exportly.de/v1Abruf-API
Dokumente auflisten
/v1/documentsLiefert 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
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| since | ISO-8601 | optional | Änderungen ab diesem Zeitpunkt (inklusive). Ohne since: alle gespeicherten Änderungen – die Änderungsliste reicht 97 Tage zurück. |
| limit | integer 1–100 | optional | Seitengröße, Standard 50. |
| cursor | string | optional | next_cursor der vorherigen Antwort. Hat Vorrang vor since. |
| seller | acct_… | optional | Nur 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. |
| version | enum | optional | Welche Fassung je Dokument (ab 1.9.1): original (Standard) oder latest (jüngste, nach Zahlung die Fassung mit Zahlvermerk). |
Antwort
| Name | Typ | Beschreibung |
|---|---|---|
| object | "list" | Immer list. |
| data | Dokument[] | Liste von Dokument-Objekten. |
| has_more | boolean | true, wenn es weitere Seiten gibt. |
| next_cursor | string | Cursor für den nächsten Abruf. |
| next_url | string | Fertige 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.
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;
}<?php
$cursor = loadCursor(); // zuletzt gespeicherter next_cursor
do {
$query = ["limit" => 100] + ($cursor ? ["cursor" => $cursor] : ["since" => "2026-11-01T00:00:00Z"]);
$ch = curl_init("https://api.exportly.de/v1/documents?" . http_build_query($query));
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("EXPORTLY_API_KEY")],
CURLOPT_RETURNTRANSFER => true,
]);
$page = json_decode(curl_exec($ch), true);
foreach ($page["data"] as $doc) {
handle($doc);
}
$cursor = $page["next_cursor"];
saveCursor($cursor); // nach jeder Seite sichern
} while ($page["has_more"]);import os
import time
import requests
headers = {"Authorization": "Bearer " + os.environ["EXPORTLY_API_KEY"]}
cursor = load_cursor() # zuletzt gespeicherter next_cursor
while True:
params = {"limit": 100}
params.update({"cursor": cursor} if cursor else {"since": "2026-11-01T00:00:00Z"})
res = requests.get("https://api.exportly.de/v1/documents", params=params, headers=headers, timeout=10)
if res.status_code == 429:
time.sleep(int(res.headers.get("Retry-After", 1)))
continue
page = res.json()
for doc in page["data"]:
handle(doc)
cursor = page["next_cursor"]
save_cursor(cursor) # nach jeder Seite sichern
if not page["has_more"]:
break{
"object": "list",
"data": [],
"has_more": false,
"next_cursor": "eyJ2IjoxLCJzayI6…",
"next_url": "https://api.exportly.de/v1/documents?cursor=eyJ2IjoxLCJzayI6…"
}curl -G "https://api.exportly.de/v1/documents" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
-d since=2026-11-01T00:00:00Z \
-d limit=100const url = new URL("https://api.exportly.de/v1/documents");
url.searchParams.set("since", "2026-11-01T00:00:00Z");
url.searchParams.set("limit", "100");
const res = await fetch(url, {
headers: { Authorization: "Bearer " + process.env.EXPORTLY_API_KEY },
});
const page = await res.json();<?php
$query = http_build_query(["since" => "2026-11-01T00:00:00Z", "limit" => 100]);
$ch = curl_init("https://api.exportly.de/v1/documents?" . $query);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("EXPORTLY_API_KEY")],
CURLOPT_RETURNTRANSFER => true,
]);
$page = json_decode(curl_exec($ch), true);import os
import requests
page = requests.get(
"https://api.exportly.de/v1/documents",
params={"since": "2026-11-01T00:00:00Z", "limit": 100},
headers={"Authorization": "Bearer " + os.environ["EXPORTLY_API_KEY"]},
timeout=10,
).json(){
"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…"
}{
"error": {
"code": "invalid_request",
"message": "Invalid parameter: limit."
}
}{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}Abruf-API
Ein Dokument abrufen
/v1/documents/{id}Liefert ein einzelnes Dokument samt frischen Download-Links – standardmäßig das Original.
Parameter
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| id | string | Pflicht | Stripe-ID der Rechnung (in_…) oder Gutschrift (cn_…). |
| version | enum | optional | Query-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.
curl "https://api.exportly.de/v1/documents/in_1QxLumen7hK2" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"const res = await fetch("https://api.exportly.de/v1/documents/in_1QxLumen7hK2", {
headers: { Authorization: "Bearer " + process.env.EXPORTLY_API_KEY },
});
const doc = await res.json();
// Dateien direkt laden – die Links gelten 15 Minuten
const pdf = Buffer.from(await (await fetch(doc.files.pdf.url)).arrayBuffer());<?php
$ch = curl_init("https://api.exportly.de/v1/documents/in_1QxLumen7hK2");
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("EXPORTLY_API_KEY")],
CURLOPT_RETURNTRANSFER => true,
]);
$doc = json_decode(curl_exec($ch), true);
// Dateien direkt laden – die Links gelten 15 Minuten
file_put_contents($doc["number"] . ".pdf", file_get_contents($doc["files"]["pdf"]["url"]));import os
import requests
doc = requests.get(
"https://api.exportly.de/v1/documents/in_1QxLumen7hK2",
headers={"Authorization": "Bearer " + os.environ["EXPORTLY_API_KEY"]},
timeout=10,
).json()
# Dateien direkt laden – die Links gelten 15 Minuten
pdf = requests.get(doc["files"]["pdf"]["url"], timeout=30).content{
"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"
}
}
}{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}{
"error": {
"code": "not_found",
"message": "No such document: 'in_1QxUnknown'."
}
}Abruf-API
Fassungen eines Dokuments
/v1/documents/{id}/versionsAb 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) odersuperseded(durch „Neu erzeugen“ ersetzt).source:archiveim Live-Modus mit GoBD-Archiv bzw. im Testmodus aus dem Testarchiv (ab 1.9.2, 30 Tage), sonstworking_copy(90 Tage; danachfiles: 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 mitversion.variant: "paid"; mit?version=originaldagegenfiles: nullundversion_unavailable.
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"{
"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.
| Name | Typ | Null | Beschreibung |
|---|---|---|---|
| id | string | Stripe-ID der Rechnung (in_…) bzw. Gutschrift (cn_…). | |
| object | "invoice" | "credit_note" | Art des Dokuments. | |
| invoice_id | string | nullable | Bei Gutschriften die zugehörige Rechnung. |
| number | string | Rechnungs- bzw. Gutschriftnummer. | |
| status | enum | processing, generated, sent, failed oder voided. | |
| format | enum | Wirksames E-Rechnungsformat: zugferd, xrechnung oder both. | |
| livemode | boolean | true für Live-Dokumente, false für Testmodus. | |
| amount_gross | integer | Bruttobetrag in Cent (kleinste Währungseinheit), wie bei Stripe. | |
| currency | string | ISO 4217, klein geschrieben (eur). | |
| issue_date | string | nullable | Rechnungsdatum YYYY-MM-DD. |
| created_at | ISO-8601 | Erste Erzeugung. | |
| updated_at | ISO-8601 | Letzte Änderung. | |
| generated_at | ISO-8601 | nullable | Letzte erfolgreiche Erzeugung. |
| sent_at | ISO-8601 | nullable | Versand per E-Mail. |
| delivery_status | string | nullable | Zustellstatus der Mail: sent, delivered, bounced, complained. |
| error | string | nullable | Fehlergrund (bei failed) bzw. Hinweis (bei voided). |
| warnings | string[] | Hinweise der Prüfung (deutsch). | |
| archived_until | ISO-8601 | nullable | Ende der GoBD-Aufbewahrung, falls archiviert. |
| seller_account | string | nullable | Stripe 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_code | enum | nullable | Fehlergrund 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_at | ISO-8601 | nullable | Zeitpunkt, zu dem die Rechnung laut Stripe beglichen wurde (bezahlt, per Gutschrift oder Guthaben ausgeglichen, Rechnung über 0 €). null solange offen und bei Gutschriften. |
| settlement | enum | nullable | Wodurch beglichen: payment (gezahlt), credit_note (durch Gutschrift ausgeglichen, nichts gezahlt), balance (Kundenguthaben), zero (Rechnung über 0 €), mixed (teils Gutschrift, teils Zahlung). |
| customer_id | string | nullable | Stripe-Kunde (cus_…) – für die Zuordnung im ERP. |
| buyer_name | string | nullable | Käufername (BT-44). |
| amount_net | integer | nullable | Netto in Cent (BT-109). |
| amount_tax | integer | nullable | Umsatzsteuer in Cent (BT-110). |
| version | object | nullable | Gelieferte 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_count | integer | nullable | Anzahl bisher erzeugter Fassungen (ab 1.9.1). Alle Fassungen: GET /v1/documents/{id}/versions. |
| files | object | nullable | Download-Links, siehe Download-Links. |
| files_unavailable_reason | enum | nullable | Nur 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). |
{
"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
Download-Links
Das Feld files enthält vorsignierte Links auf das ZUGFeRD-PDF und das XRechnung-XML.
- Links sind 15 Minuten gültig. Lade die Datei direkt nach dem Abruf herunter oder hole dir mit
GET /v1/documents/{id}frische Links. - Standard ist das Original (ab 1.9.1). Die Fassung mit Zahlvermerk holst du mit
?version=latestoder über die Fassungen. xmlistnull, wenn das Format keine XRechnung enthält (zugferd).- Die ersten 90 Tage kommen die Dateien aus der Arbeitskopie. Danach aus dem GoBD-Archiv (Pro/Business, nur Live-Modus). Beide tragen
sha256(Hex) zur Integritätsprüfung (Arbeitskopien älterer Dokumente noch ohne). - Ohne Archiv nach 90 Tagen:
files: null,files_unavailable_reason: "expired". - Noch nie erfolgreich erzeugt (
processing,failed):files: null,files_unavailable_reason: "not_generated".
{
"pdf": { "url": "https://…", "expires_at": "2026-11-09T10:15:00.000Z", "sha256": "…" },
"xml": { "url": "https://…", "expires_at": "2026-11-09T10:15:00.000Z", "sha256": "…" }
}{
"files": null,
"files_unavailable_reason": "expired"
}Abruf-API
Fehlercodes
Alle Fehler kommen als JSON mit englischer Meldung. Werte deine Logik am code aus, nicht am Meldungstext.
| HTTP | code | Bedeutung |
|---|---|---|
| 400 | invalid_request | Ungültiger Parameter (limit, since, cursor). |
| 401 | invalid_api_key | Schlüssel fehlt, ist falsch, widerrufen oder die App ist deinstalliert. |
| 403 | plan_required | Live-Schlüssel ohne Business/Enterprise bzw. /v1/sellers live ohne Enterprise. |
| 404 | not_found | Dokument bzw. Händler unbekannt (oder gehört zu einem anderen Konto/Modus). |
| 404 | seller_not_found | /v1/sellers/{account}…: kein Händler deiner Plattform (mit Plattform-Schlüssel: kein verbundenes Konto; ohne: kein angelegter Händler). |
| 409 | connect_key_rejected | Stripe lehnt den in der App hinterlegten Plattform-Schlüssel ab – bitte neu hinterlegen. |
| 429 | rate_limited | Mehr als 60 Anfragen je Minute und Schlüssel; Header Retry-After (Sekunden). |
| 500 | internal_error | Unerwarteter Fehler – bitte später erneut versuchen. |
{
"error": {
"code": "invalid_api_key",
"message": "Invalid API key provided."
}
}{
"error": {
"code": "plan_required",
"message": "Live mode API access requires the Business or Enterprise plan. Test mode keys work on every plan."
}
}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.
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, sonston_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– miterror_codeseller_missing,connect_plan_requiredbzw.connect_disabledund dem Webhookdocument.failed. Das Feldseller_accountnennt den Händler, auch in der Webhook-Nutzlast.
{
"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.
| Metadaten-Schlüssel | Bedeutung |
|---|---|
einvoice_name | Firmenname |
einvoice_street | Straße und Hausnummer |
einvoice_street2 | Adresszusatz (optional) |
einvoice_postal_code | PLZ |
einvoice_city | Ort |
einvoice_country | Land (ISO 3166-1 alpha-2, z. B. DE) |
einvoice_vat_id | USt-IdNr. (falls nicht über default_account_tax_ids) |
einvoice_tax_number | Steuernummer |
einvoice_register | Registereintrag |
einvoice_managing_directors | Geschäftsführung |
einvoice_contact_name / _phone / _email | Ansprechpartner (Pflicht für XRechnung) |
einvoice_account_holder / _iban / _bic / _bank | Bankverbindung (IBAN mit Prüfziffer) |
einvoice_email / _phone / _website | Kontakt (Antworten der Kunden gehen an die E-Mail) |
einvoice_small_business | true = 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
- Metadaten des verbundenen Kontos (Zuordnung, dann
einvoice_*) - Bei Exportly gespeicherte Händlerdaten (Bestand, ohne Plattform-Schlüssel)
- Rechnung:
account_name→ Name,account_tax_ids→ USt-IdNr. - Stammdaten des Kontos:
company.addressbzw. 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.
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"# Steuer-ID am verbundenen Konto anlegen und als Standard für Rechnungen setzen –
# Stripe schreibt sie dann auf jede Rechnung (account_tax_ids).
curl https://api.stripe.com/v1/tax_ids \
-u "$STRIPE_SECRET_KEY:" \
-H "Stripe-Account: acct_1NordLicht7" \
-d type=eu_vat -d value=DE123456789
curl https://api.stripe.com/v1/accounts/acct_1NordLicht7 \
-u "$STRIPE_SECRET_KEY:" \
-d "settings[invoices][default_account_tax_ids][0]=txi_…"Händler (Stripe Connect)
Händler anlegen oder ändern
/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
| Name | Typ | Pflicht | Beschreibung |
|---|---|---|---|
| name | string | Pflicht | Firmenname (BT-27). |
| address | object | Pflicht | line1, postal_code, city, country (ISO 3166-1 alpha-2); optional line2. |
| vat_id | string | optional | USt-IdNr. mit Länderpräfix. vat_id oder tax_number ist Pflicht. |
| tax_number | string | optional | Steuernummer. |
| string | optional | Kontakt; Antworten der Kunden auf die Rechnungs-Mail gehen hierhin. | |
| bank | object | optional | iban, bic, bank_name – Bankverbindung in der PDF-Fußzeile (Zahlungsziel ist nur die Banküberweisung der Stripe-Rechnung). |
| contact | object | optional | name, phone, email – Ansprechpartner, Pflicht für XRechnung. |
| phone, website, registry, managing_director | string | optional | Angaben für Fußzeile und Impressum. |
| small_business | boolean | optional | Kleinunternehmer nach § 19 UStG. |
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" } }'const res = await fetch("https://api.exportly.de/v1/sellers/acct_1NordLicht7", {
method: "PUT",
headers: {
Authorization: "Bearer " + process.env.EXPORTLY_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"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" }
}),
});
const seller = await res.json();{
"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
}{
"error": {
"code": "invalid_request",
"message": "Invalid parameter: vat_id. Either vat_id (with country prefix, e.g. DE123456789) or tax_number is required."
}
}Händler (Stripe Connect)
Händler abrufen und löschen
/v1/sellers/v1/sellers/{account}/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.
curl "https://api.exportly.de/v1/sellers" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"curl "https://api.exportly.de/v1/sellers/acct_1NordLicht7" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"curl -X DELETE "https://api.exportly.de/v1/sellers/acct_1NordLicht7" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"curl -G "https://api.exportly.de/v1/documents" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
-d seller=acct_1NordLicht7Händler (Stripe Connect)
Das Händler-Objekt
| Name | Typ | Beschreibung |
|---|---|---|
| id | string | Verbundenes Konto (acct_…). |
| object | "seller" | Immer seller. |
| livemode | boolean | Modus des Schlüssels. |
| name | string | Firmenname. |
| address | object | line1, line2, postal_code, city, country. |
| vat_id | string | USt-IdNr. |
| tax_number | string | Steuernummer. |
| string | Kontakt-E-Mail. | |
| bank | object | iban, bic, bank_name. |
| contact | object | name, phone, email (jeweils nullable). |
| small_business | boolean | Kleinunternehmer nach § 19 UStG. |
| source | enum | api oder app – wo zuletzt gespeichert. |
| created_at, updated_at | ISO-8601 | Anlage und letzte Änderung. |
Händler (Stripe Connect)
Rechnungsdesign je Händler
/v1/sellers/{account}/design/v1/sellers/{account}/design/v1/sellers/{account}/design/v1/sellers/{account}/files/v1/sellers/{account}/previewJeder 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 …/designist ein Teil-Update: weggelassene Felder bleiben,nullsetzt zurück.DELETEstellt auf dein Design zurück.- Logo und Briefpapier lädst du mit
POST …/fileshoch (Logo PNG/JPG bis 2 MB, Briefpapier PDF/PNG/JPG bis 10 MB), danachlogo_file_idbzw.letterhead_file_idim Design setzen. Briefpapier wird gerastert, freie Ränder werden automatisch erkannt. GET …/previewrendert eine Beispielrechnung mit den Händlerdaten und liefert Links auf PDF und PNG (15 Minuten gültig).
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.pngcurl -X PUT "https://api.exportly.de/v1/sellers/acct_1NordLicht7/design" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-d '{ "template": "modern", "accent_color": "#1f6f5a", "logo_file_id": "upl_0f3c9a1b2c3d4e5f60718293a4b5c6d7" }'curl "https://api.exportly.de/v1/sellers/acct_1NordLicht7/preview" \
-H "Authorization: Bearer erk_test_XXXXXXXXXXXXXXXXXXXXXXXX"{
"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"
}{
"id": "upl_0f3c9a1b2c3d4e5f60718293a4b5c6d7",
"object": "file_upload",
"purpose": "logo",
"seller": "acct_1NordLicht7",
"livemode": false,
"content_type": "image/png",
"size": 48213,
"upload_url": "https://…",
"upload_method": "PUT",
"upload_headers": { "Content-Type": "image/png" },
"expires_at": "2026-11-10T09:35:00.000Z"
}{
"object": "seller_preview",
"seller": "acct_1NordLicht7",
"livemode": false,
"source": "own",
"pdf_url": "https://…",
"png_url": "https://…",
"page_count": 1,
"expires_at": "2026-11-10T09:45:00.000Z",
"warnings": []
}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.
1. App → Einstellungen → Exportly E-Rechnung
→ Reiter „API“ → Webhook
2. https://-Adresse eintragen
3. Signatur-Secret (whsec_…) einmal kopieren
4. „Test senden“ → Ereignis webhook.testWebhooks
Ereignistypen
| type | Wann |
|---|---|
document.generated | E-Rechnung erzeugt (auch erneut erzeugt). |
document.failed | Erzeugung fehlgeschlagen. |
document.sent | Per E-Mail versendet. |
document.delivery_updated | Zustellstatus der Mail geändert (zugestellt, abgewiesen, Beschwerde). |
document.voided | Rechnung in Stripe storniert. |
document.paid | Rechnung 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. |
document.generated
document.failed
document.sent
document.delivery_updated
document.voided
document.paid
webhook.testWebhooks
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).
| Name | Typ | Beschreibung |
|---|---|---|
| id | string | Ereignis-ID (evt_…), identisch mit dem Header Exportly-Delivery. |
| type | string | Ereignistyp, siehe oben. |
| created | integer | Unix-Zeit des Ereignisses. |
| livemode | boolean | Modus des Dokuments. |
| data.object | Dokument | Dokument-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_atdes Dokuments.
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
- die Signatur über den unveränderten Roh-Body (nicht über neu serialisiertes JSON),
- mit einem zeitkonstanten Vergleich,
- dass
tnicht älter als 5 Minuten ist (Schutz vor Wiedereinspielung).
Mit dem Prüfvektor testest du deine Implementierung, bevor du live gehst.
Exportly-Signature: t=<Unix-Zeit>,v1=<Hex>
v1 = HMAC-SHA256(Signatur-Secret, "<t>.<roher Request-Body>")Secret: whsec_test
t: 1700000000
Body: {"id":"evt_1"}
v1=c89214b5b5da833daed6f0b8c5bb6bd58cea9022bd80ccc78230f3942d632925import 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);<?php
$secret = getenv('EXPORTLY_WEBHOOK_SECRET'); // whsec_…
$tolerance = 300;
$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_EXPORTLY_SIGNATURE'] ?? '';
$parts = [];
foreach (explode(',', $header) as $part) {
[$key, $value] = array_pad(explode('=', $part, 2), 2, '');
$parts[$key] = $value;
}
$t = isset($parts['t']) ? (int) $parts['t'] : 0;
$v1 = $parts['v1'] ?? '';
$expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
if ($t === 0 || abs(time() - $t) > $tolerance || !hash_equals($expected, $v1)) {
http_response_code(400);
exit('invalid signature');
}
$event = json_decode($rawBody, true);
// Duplikate über $event['id'] verwerfen, dann verarbeiten, z. B.:
// if ($event['type'] === 'document.generated') { … GET /v1/documents/{id} … }
http_response_code(200);import hashlib
import hmac
import os
import time
SECRET = os.environ["EXPORTLY_WEBHOOK_SECRET"] # whsec_…
TOLERANCE_SECONDS = 300
def verify_exportly_signature(raw_body: bytes, header: str, secret: str) -> bool:
parts = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
try:
t = int(parts["t"])
except (KeyError, ValueError):
return False
if abs(time.time() - t) > TOLERANCE_SECONDS:
return False
signed = f"{t}.".encode() + raw_body # roher, unveränderter Body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))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.
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