Mit der gotomaxx eRechnungs API zur eRechnung

01Überblick

Sie schicken ein JSON‑Objekt mit den Belegdaten Ihrer Rechnung. Der Dienst validiert die Werte, ergänzt fehlende Angaben (optional) und produziert daraus das eRechnungs‑Format Ihrer Wahl: als PDF/A‑3B mit eingebettetem XML (ZUGFeRD) oder als reines XRechnung‑XML.

Zusätzlich kann derselbe Aufruf das erzeugte Dokument direkt versenden (E‑Mail), archivieren oder Ihnen die Datei nur zum Download zurückgeben. Alles über einen einzigen Request.

02Voraussetzungen

Bevor Sie den Endpunkt nutzen können, müssen ein paar Dinge erfüllt sein:

• Berechtigung: Ihr Portal‑Benutzer braucht die Berechtigung zum Versenden von Dokumenten.
• DSGVO‑AVV: Der Auftragsverarbeitungsvertrag muss für das Portal einmalig akzeptiert worden sein.
• Zugang: Ein aktives PDFMAILER‑Trial oder ein entsprechend gebuchter API‑Zugang.

Authentifizierung

Jeder Aufruf braucht Authentifizierung. Es gibt drei Wege:

03So funktioniert es

Fünf Schritte vom JSON zur fertigen eRechnung.

1. Authentifizieren

   Bearer‑Token besorgen und im Authorization‑Header mitschicken. Sicherstellen, dass Berechtigung und Zugang passen.

2. JSON‑Objekt aufbauen

   Die Rechnungsdaten im Feld json als JsonDocument‑Objekt zusammenstellen: seller, buyer, header, items sowie (falls nicht per Auto‑Complete ergänzt) vat, summary, payment.

3. Zielformat & Optionen wählen

   Über transform das Format bestimmen (ZUGFeRD oder XRechnung). tryAutoComplete: 1 lässt fehlende Werte aus Portal‑ und Empfängerdaten ergänzen. fileName festlegen (bei Versand mit Endung .pdf).

4. Request senden

   Als POST mit Content-Type: application/json an /json. Wahlweise Versandziel (email), Archivierung oder getFileOnly für reinen Download angeben.

5. Antwort auswerten

   Standardmäßig kommt die Dokument‑ID zurück. Mit getResponse ein Antwortobjekt, mit getFileOnly die Datei, mit asynchronous ein Request‑Token zum Abholen. testUpload liefert vorab das Testergebnis, ohne Credits zu verbrauchen.

04Das JSON‑Objekt

Der Kern ist das Objekt im Feld json (Typ gotomaxx_JsonDocument). Es gliedert sich in klar getrennte Bereiche. Zur Orientierung ist bei vielen Feldern als Referenz der zugehörige BT‑xx‑Code der EN‑16931‑Norm angegeben, auf den das Feld abgebildet wird.

seller: Verkäufer / Rechnungssteller

Ihre eigenen Firmendaten. Viele Kontakt‑ und Bankfelder können aus den Portal‑Metadaten ergänzt werden.

buyer: Käufer / Rechnungsempfänger Pflicht

Die Empfängerdaten. Kontaktangaben können aus Ihrer Empfänger‑Datenbank ergänzt werden.

header: Rechnungskopf Pflicht

items[]: Rechnungspositionen Pflicht

Mindestens eine Position. Preise und Summen sind rechnerisch verknüpft und können weitgehend automatisch ergänzt werden (siehe Formeln unten).

vat[]: Steueraufstellung

Auto Wird aus Positionen und Zu‑/Abschlägen berechnet. Nur nötig, wenn Sie die Aufstellung selbst kontrollieren wollen.

summary: Rechnungssummen

Auto Ebenfalls vollständig berechenbar. Die Verknüpfungen:

payment: Zahlungsangaben

allowance[]: Zu‑ & Abschläge (Beleg‑Ebene)

Rabatte oder Zuschläge, die für die gesamte Rechnung gelten.

shipping: Lieferanschrift

Optional. Gleicher Aufbau wie eine Adresse.

attachments[]: Anhänge

Auto Standardmäßig leer. Über Anhänge liefern Sie zusätzliche Belege (Rechnungsdatenblatt, Referenzpapier) als Base64 oder ein eigenes Sicht‑PDF (siehe unten).

"attachments": [
  {
    "id": "0",
    "name": "test",
    "isPdf": true,
    "mime": "PDF",
    "fileName": "Rechnung",
    "file": "JVBERi0xLjcKJdPr6e…"
  }
]

Auszug aus dem json‑Objekt. file enthält die Base64‑Daten des PDF (hier gekürzt).

05Auto‑Complete verstehen

Mit tryAutoComplete: 1 ergänzt der Dienst fehlende Pflichtangaben aus Portal‑Metadaten, Ihrer Empfänger‑Datenbank und aus rechnerischen Zusammenhängen. Das reduziert Ihr JSON auf das Wesentliche.

Verarbeitungsreihenfolge

Die Ergänzung läuft in fester Reihenfolge, spätere Blöcke bauen auf früheren auf:

seller → Standard‑USt (aus Portal) → buyer → shipping → header → payment → items → allowance → vat → summary → attachments

Validierte Werte

Wo möglich werden Werte geprüft: Steuernummer · E‑Mail · Telefon · IBAN · BIC · Enum‑Werte · Werttypen · PLZ · MIME‑Typ.

06XRechnung vs. ZUGFeRD

Beide Formate entstehen aus demselben JSON, gesteuert über den Parameter transform. Sie unterscheiden sich im Ergebnis und in den Pflichtangaben.

Zusätzliche Pflichtfelder für XRechnung

07Request‑Optionen (Hülle)

Neben json steuern diese Felder Format, Versand, Rückgabe und Verarbeitung.

Format & Erzeugung

Versand & Empfänger

Rückgabe & Verarbeitung

08Antworten & Status

Was bei 200 zurückkommt, hängt von Ihren Optionen ab:

HTTP‑Statuscodes

Antwortobjekt & Validierungsfehler

Mit getResponse: 1 (sowie bei testUpload: 1) erhalten Sie statt der reinen Dokument‑ID ein strukturiertes Antwortobjekt mit dem erzeugten Dokument und dem Validierungsergebnis. Das Objekt wird auch dann geliefert, wenn das Dokument ungültig ist. Prüfen Sie deshalb immer das Feld valid. Schlägt die Validierung fehl, trägt error eine Kurzmeldung und das jeweilige …Error‑Feld den ausführlichen Prüfbericht.

{
  "id": 671,
  "test": false,
  "valid": false,
  "error": "XRechnung validation failed",
  "type": "JSON",
  "target": "XRechnung3CII",
  "xrechnung": "<?xml … </rsm:CrossIndustryInvoice>",
  "zugferd": null,
  "xml": "<?xml … </DataDefinition>",
  "json": "{…}",
  "pdf": null,
  "html": null,
  "xrechnungError": "<rep:report valid='false'> … [BR-E-05] … BT-152 shall be 0 (zero) … </rep:report>",
  "zugferdError": null,
  "runtime": 0
}

Der Prüfbericht in xrechnungError nennt die konkrete Ursache, im Beispiel u. a. BR‑E‑05: Bei USt‑Kategorie „steuerbefreit" (E) muss der Steuersatz 0 % betragen.

09Vollständiges Beispiel

1 · ZUGFeRD erzeugen & per E‑Mail versenden

Minimaler Request mit Auto‑Complete: Beträge und Summen werden ergänzt.

{
  "fileName": "rechnung-2026-001.pdf",
  "transform": "ZUGFeRD",
  "tryAutoComplete": 1,
  "copyRecipientData": 1,
  "email": "kunde@example.com",
  "json": {
    "seller": {
      "name": "Muster GmbH",
      "addressLine": "Musterstraße 1",
      "zip": "76870",
      "city": "Kandel",
      "country": "DE",
      "taxId": "DE123456789"
    },
    "buyer": {
      "id": "K-1001",
      "address": {
        "name": "Beispiel AG",
        "addressLine": "Beispielweg 5",
        "zip": "10115",
        "city": "Berlin",
        "country": "DE"
      }
    },
    "header": {
      "id": "2026-001",
      "type": "380",
      "currency": "EUR",
      "date": "2026-07-02"
    },
    "payment": {
      "id": "RE 2026-001",
      "payment": "58"
    },
    "items": [
      {
        "name": "Beratungsleistung",
        "quantity": 10,
        "unit": "HUR",
        "net": 120.00,
        "vat": 19,
        "vatCategory": "S"
      }
    ]
  }
}

Der passende HTTP‑Aufruf:

# Erzeugt & versendet die ZUGFeRD-Rechnung, gibt die Dokument-ID zurück
# IhrFirmenname durch den Namen Ihrer eigenen PDFMAILER CLOUD ersetzen
curl -X POST "https://post.gotomaxx.com/IhrFirmenname/service/rest/outgoing/json" \
  -H "Authorization: Bearer IHR_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @rechnung.json

2 · XRechnung erzeugen (nur Datei, kein Versand)

Zusatzfelder für XRechnung: routing sowie endPoint/endPointType. Mit getFileOnly bekommen Sie das XML direkt zurück, mit testUpload prüfen Sie vorab.

{
  "fileName": "xrechnung-2026-001.xml",
  "transform": "XRechnung",
  "tryAutoComplete": 1,
  "getFileOnly": 1,
  "testUpload": 1,
  "json": {
    "seller": {
      "name": "Muster GmbH",
      "addressLine": "Musterstraße 1",
      "zip": "76870", "city": "Kandel", "country": "DE",
      "endPoint": "info@muster-gmbh.de",
      "endPointType": "EM"
    },
    "buyer": {
      "id": "K-1001",
      "endPoint": "991-12345-67",
      "endPointType": "0204",
      "address": { "name": "Behörde XY", "addressLine": "Amtsweg 3",
        "zip": "10115", "city": "Berlin", "country": "DE" }
    },
    "header": {
      "id": "2026-001", "type": "380", "currency": "EUR",
      "routing": "04011000-1234512345-06"  // Leitweg-ID (BT-10)
    },
    "items": [
      { "name": "Lizenzgebühr", "quantity": 1, "unit": "H87",
        "net": 500.00, "vat": 19, "vatCategory": "S" }
    ]
  }
}

Hinweis: JSON kennt keine Kommentare. Die //‑Anmerkungen dienen hier nur der Erklärung und müssen im echten Request entfernt werden.

10Tipps & Fallstricke

• Booleans als 1/0: Alle bool‑Parameter als 1 oder 0 übergeben.
• Dateiname bei Versand: Soll versendet werden, muss fileName auf .pdf enden.
• Sich ausschließende Optionen: getResponse und getFileOnly nicht zusammen. Mit getFileOnly findet kein Versand statt.
• Erst testen: testUpload: 1 nutzen, um JSON und Transformation zu prüfen, ohne Credits zu verbrauchen (der finale PDF‑Import wird dabei nicht ausgeführt).
• Auto‑Complete ≠ Korrektur: Gelieferte Werte müssen korrekt sein: Validierung greift bei Steuernummer, IBAN, BIC, E‑Mail, Telefon, PLZ, Enums, MIME.
• XRechnung‑Pflichten: routing sowie endPoint/endPointType für Verkäufer und Käufer nicht vergessen (oder Auto‑Complete sicherstellen).
• Eigenes Sicht‑PDF: Bei ZUGFeRD über attachments mit isPdf: true ein eigenes PDF als Sichtdokument vorgeben; ohne Angabe rendert die API es automatisch aus den Belegdaten.
• Async‑Ergebnis verfällt: Nicht abgeholte asynchrone Ergebnisse werden nach einem Tag gelöscht.
• Version bewusst wählen: API‑Versionen verhalten sich unterschiedlich; das Portal kann eine Mindestversion erzwingen.