API-Dokumentation

Überblick

Die Dokumente-API ist eine lesende HTTP-Schnittstelle. Sie liefert die Dokumente, die Easy Invoices für einen Shop ausgestellt hat, als Liste von Änderungen und dazu jedes PDF.

• Drei Dokumentarten: Rechnungen, Gutschriften und Stornorechnungen, jede mit eigener Liste.
• Nur lesend: Über die API lässt sich nichts erstellen, ändern oder löschen.
• Pull statt Push: Dein System ruft regelmäßig ab, wir senden nichts an deine Server.
• Nur ausgestellte Dokumente mit fertigem PDF erscheinen, auch rückwirkend für alle bisherigen.

Authentifizierung

Jede Anfrage braucht einen API-Token des Shops im Authorization-Header. Den Token legt der Shop-Inhaber in der App an: Einstellungen → Erweitert → API-Zugriff verwalten.

• Ein Token beginnt mit ei_live_ und wird nur ein einziges Mal angezeigt. Wir speichern ihn nicht im Klartext.
• Gültigkeit 30, 90, 180 oder 365 Tage, danach erstellst du einen neuen Token. Für eine Anbindung, die dauerhaft unbeaufsichtigt läuft, gibt es auch einen Token, der nie abläuft: Er gilt, bis er widerrufen wird.
• Höchstens drei aktive Tokens pro Shop. Ein Token lässt sich in der App jederzeit widerrufen und funktioniert dann sofort nicht mehr.
• Der Token gehört ausschließlich in den Header, nie in die URL, den Quelltext oder eine E-Mail.

Authorization: Bearer ei_live_…

Schnellstart

Eine Synchronisation besteht aus vier Schritten. Beim ersten Lauf erhältst du alles, danach nur noch, was neu ist oder sich geändert hat.

1. 1

   Erster Abruf

   Rufe die Liste mit type=INVOICE und einem Startdatum in updatedSince auf. Ohne updatedSince erhältst du alle Dokumente von Anfang an.

2. 2

   Weiterblättern

   Solange hasMore true ist, rufst du sofort erneut ab und übergibst nextCursor als cursor.

3. 3

   PDF laden

   Jedes Dokument enthält pdfUrl. Rufe die Adresse mit demselben Token ab.

4. 4

   Regelmäßig wiederholen

   Speichere den letzten nextCursor und übergib ihn beim nächsten Lauf, z. B. alle 15 Minuten.

curl -s -H "Authorization: Bearer $EI_TOKEN" \
  "https://api.easy-invoices.de/api/v1/public/documents?type=INVOICE&updatedSince=2026-01-01T00:00:00Z"

curl -s -H "Authorization: Bearer $EI_TOKEN" \
  "https://api.easy-invoices.de/api/v1/public/documents?type=INVOICE&cursor=$NEXT_CURSOR"

curl -s -H "Authorization: Bearer $EI_TOKEN" -o RE-2909.pdf \
  "https://api.easy-invoices.de/api/v1/public/documents/cm2x8k1q40001/pdf?type=INVOICE"

OpenAPI und Postman

Die Schnittstelle gibt es auch maschinenlesbar: als OpenAPI-Spezifikation und als fertige Postman-Collection. Beide werden aus dem Code der API erzeugt und sind deshalb immer auf dem Stand dieser Seite.

• openapi.json

  OpenAPI 3.0. Zum Erzeugen eines Clients, zum Import in Postman, Insomnia oder Bruno, oder als Kontext für einen KI-Assistenten.

• postman-collection.json

  Die drei Schritte des Schnellstarts als Postman-Collection. Die Abrufe merken sich cursor und die id des ersten Dokuments selbst.

1. 1

   Importieren

   postman-collection.json herunterladen und in Postman über Import auswählen.

2. 2

   Token eintragen

   In der Collection den Reiter Authorization öffnen (Auth Type: Bearer Token) und das Token einfügen. Das Token gehört nicht in eine geteilte Workspace.

Dokumente abrufen

GET /public/documents liefert eine Seite der Liste, sortiert nach updatedAt und id, älteste zuerst.

{
  "data": [
    {
      "id": "cm2x8k1q40001",
      "type": "INVOICE",
      "number": "RE-2909",
      "issueDate": "2026-10-28T09:14:00.000Z",
      "status": "EMAIL_SENT",
      "isActive": true,
      "orderId": "8594129453322",
      "orderNumber": "2909",
      "orderAttributes": [
        { "name": "Order placed from", "value": "Shop Apotheke" },
        { "name": "Channel_id", "value": "0227" },
        { "name": "Order_id", "value": "COM-277476493-2-A" }
      ],
      "orderTags": ["COM-277476493-2-A", "Mirakl", "Shop Apotheke"],
      "relatedInvoiceId": null,
      "currency": "EUR",
      "totalGross": "41.80",
      "createdAt": "2026-10-28T09:14:04.000Z",
      "updatedAt": "2026-10-28T09:15:12.000Z",
      "pdfUrl": "https://api.easy-invoices.de/api/v1/public/documents/cm2x8k1q40001/pdf?type=INVOICE"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJ0IjoiSU5WT0lDRSIsInUiOiIyMDI2LTEwLTI4VDA5OjE1OjEyLjAwMFoiLCJpIjoiY20yeDhrMXE0MDAwMSJ9",
  "hasMore": false
}

PDF laden

GET /public/documents/{id}/pdf?type=… liefert das PDF eines gelisteten Dokuments als Download. Nutze einfach die pdfUrl aus der Liste.

• Der ETag-Header ist ein SHA-256 der Datei. Er bleibt gleich, solange das PDF unverändert ist.
• Dokumente eines anderen Shops oder noch nicht fertige Dokumente ergeben 404.

Felder eines Dokuments

Jedes Element in data hat diese Felder.

Zuverlässig synchronisieren

Die Liste ist ein Änderungsprotokoll: Nichts wird übersprungen, aber ein Dokument kann mehrfach erscheinen.

• Ein Dokument erscheint erneut, wenn es sich ändert, etwa wenn die E-Mail zugestellt oder eine Rechnung ersetzt wurde. Erkenne Duplikate an type und id.
• nextCursor kommt in jeder Antwort, auch in einer leeren. Speichere immer den letzten.
• Änderungen der letzten 30 Sekunden werden zurückgehalten, damit keine gerade entstehende Änderung übersprungen wird.
• Merke dir, welche Dokumente dein Zielsystem schon erhalten hat, statt dich nur auf den cursor zu verlassen.

Dokumente einer Marktplatz-Bestellung zuordnen

Marktplatz-Anbindungen speichern ihre eigene Bestellnummer in den zusätzlichen Details der Shopify-Bestellung. Diese findest du in orderAttributes, du brauchst dafür keinen Zugriff auf Shopify.

Mirakl Connect: Der Upload einer Rechnung (POST /v2/orders/{order_id}/documents) erwartet die Connect-Bestell-ID, nicht die Marktplatz-Nummer. Lade die Connect-Bestellungen über v2-listOrders mit updated_from, suche die Bestellung, deren channel_order_id zu Order_id passt, und lade das PDF als CUSTOMER_INVOICE hoch. Ob eine Rechnung schon vorhanden ist, zeigt v2-listOrderDocuments.

Fehler und Limits

Fehler kommen als HTTP-Status mit JSON-Body. Fehlerantworten enthalten nie Dokumentdaten.

• Pro Token: 60 Listenabrufe und 120 PDF-Downloads pro Minute, 25.000 Abrufe pro Tag.
• Pro IP-Adresse: 120 Anfragen pro Minute und Route.