API-Integration mit Output.Rocks

Was ist die Output.Rocks API?

Die Output.Rocks API ermöglicht es technischen Administratoren und Entwicklern, die Dokumentenerstellung und E-Mail-Versendung programmatisch zu steuern. Über einen einzigen POST-Request an api/renderings/ können sowohl Dokument- als auch E-Mail-Vorlagen mit demselben template-Identifier angesprochen werden.

Die ersten Schritte

1. Authentifizierung mit API-Token
2. Basis-Workflow: POST /api/renderings
3. Synchrone Vorschau: POST /api/renderings/preview
4. Powercloud-Integration einrichten
5. Erweiterte Features nutzen
6. User-Interaktion-Feedback

1. Authentifizierung mit API-Token

Bevor Sie die API nutzen können, müssen Sie einen API-Token erstellen. Dieser Token authentifiziert alle API-Requests von Ihrem System.

API-Token erstellen

1. Navigieren Sie zu Integration → API-Token → API-Token erstellen
2. Geben Sie einen sprechenden Identifier ein (z.B. powercloud-production oder sap-backend)
3. Fügen Sie eine Beschreibung hinzu, die den Verwendungszweck erklärt
4. Setzen Sie das Aktiv ab-Datum, falls der Token erst später aktiv werden soll
5. Speichern Sie den Token

Token im API-Request verwenden

Der API-Token wird im HTTP-Header X-AUTH-TOKEN übergeben:

curl -X POST https://app.output.rocks/api/renderings \
  -H "Content-Type: application/json" \
  -H "X-AUTH-TOKEN: Ihr-Token-Hier" \
  -H "accept: application/json" \
  -d '{
    "template": "rechnung_monatsabschluss",
    "format": "pdf",
    "data": {
      "kunde": {
        "nummer": "K-12345",
        "name": "Max Mustermann"
      }
    }
  }'

2. Basis-Workflow: POST /api/renderings

Der zentrale Endpunkt für alle Rendering-Requests ist POST /api/renderings. Ein Request kann sowohl Dokumente als auch E-Mails gleichzeitig auslösen, wenn die entsprechenden Vorlagen denselben Identifier oder Group Identifier verwenden.

Workflow-Diagramm

Request-Struktur

Ein minimaler API-Request sieht folgendermaßen aus:

{
  "template": "rechnung_monatsabschluss",
  "format": "pdf",
  "data": {
    "kunde": {
      "nummer": "K-12345",
      "name": "Max Mustermann",
      "email": "max.mustermann@example.com"
    },
    "vertrag": {
      "id": "V-98765",
      "datum": "2024-01-15"
    }
  }
}

Request-Parameter

Statische PDF-Anhänge im Request

Mit staticAttachments können Sie mehrere bereits fertige PDFs gemeinsam mit dem Rendering übergeben. Jeder Eintrag benötigt einen literalen PDF-Dateinamen und den Base64-kodierten Inhalt:

{
  "template": "rechnung_monatsabschluss",
  "format": "pdf",
  "staticAttachments": [
    {
      "fileName": "anschreiben-anlage.pdf",
      "content": "JVBERi0x..."
    },
    {
      "fileName": "agb.pdf",
      "content": "JVBERi0x..."
    }
  ],
  "data": {}
}

• Bei einem reinen Dokument-Request werden die PDFs in dieser Reihenfolge nach dem Output.Rocks-Dokument und den in der Vorlage konfigurierten statischen Anhängen angefügt.
• Sobald der Request eine E-Mail erzeugt, werden die Dateien stattdessen an jede erzeugte E-Mail angehängt und nicht in Dokument-PDFs zusammengeführt.
• Dateinamen dürfen höchstens 255 Zeichen lang sein, keine Pfad- oder Steuerzeichen enthalten und müssen auf .pdf enden. Platzhalter im Dateinamen werden nicht ausgewertet; doppelte Namen sind erlaubt.
• Ungültiges Base64, Nicht-PDF-Inhalte, strukturell fehlerhafte PDFs sowie überschrittene Anzahl oder Gesamtgröße werden vor Erstellung des Rendering Requests mit HTTP 400 abgelehnt.

Für POST /api/rendering/kvasy stehen dieselben Anhänge als wiederholte Elemente direkt unter <formular> zur Verfügung:

<formular id="21925">
  <staticAttachment fileName="anschreiben-anlage.pdf">JVBERi0x...</staticAttachment>
  <staticAttachment fileName="agb.pdf">JVBERi0x...</staticAttachment>
  <abschlagsformular>
    <!-- Template-Daten -->
  </abschlagsformular>
</formular>

XML-Requests statt JSON

Sendet Ihr System XML statt JSON, stehen zwei Endpunkte zur Verfügung. Beide erwarten den Content-Type application/xml oder text/xml, verwenden dieselbe Authentifizierung und liefern dieselbe Response-Struktur wie POST /api/renderings.

curl -X POST "https://app.output.rocks/api/rendering/xml?template=Z_V_RECHNUNG&externalId=VR-1000349266" \
  -H "X-AUTH-TOKEN: IHR_API_TOKEN" \
  -H "Content-Type: application/xml" \
  --data-binary @rechnung.xml

Beim generischen Endpunkt wird das Wurzelelement in den Renderdaten beibehalten. Für die Vorlagenentwicklung gelten diese Umwandlungsregeln:

• Element- und Attributnamen werden kleingeschrieben, jedes Zeichen außerhalb von [a-zA-Z0-9_] wird zu _. Zwei Geschwisterelemente oder zwei Attribute desselben Elements, deren Namen auf denselben Schlüssel fallen (etwa <b-c> und <b_c>), werden mit HTTP 400 abgelehnt statt still zusammengeführt. Elemente werden dabei über Namespace und lokalen Namen verglichen: dasselbe Element mit zwei Präfixen desselben Namespace bleibt ein wiederholtes Element.
• Ein Element, das einmal vorkommt, wird zum Objekt beziehungsweise zur Zeichenkette; ein Element, das mehrfach vorkommt, wird zur Liste. Vorlagen mit Wiederholungsbereichen (rr_) müssen deshalb gegen ein Testdatenpaket entwickelt werden, das tatsächlich mehrere Einträge enthält.
• Attribute landen unter _attributes, gemischter Text neben Kindelementen unter _text.
• In der DTD deklarierte interne Entities werden aufgelöst; externe Entities werden nie geladen.
• Der Schlüssel or auf oberster Ebene ist für Output.Rocks-Steuerdaten reserviert. Ein Wurzelelement, das auf or abgebildet wird, wird mit HTTP 400 abgelehnt.

Response-Struktur

Bei erfolgreichem Request erhalten Sie einen HTTP-Status-Code 201 und eine Response mit Informationen zum erstellten Request:

{
  "id": 12345,
  "externalId": "external-id",
  "template": "rechnung_monatsabschluss",
  "format": "pdf",
  "webhook": "my-webhook",
  "comment": "My Comment",
  "emailServer": "my-smtp"
}

3. Synchrone Vorschau: POST /api/renderings/preview

Mit POST /api/renderings/preview prüfen Sie eine gespeicherte Dokumentvorlage, ohne einen Rendering-Request anzulegen. Die Antwort ist unmittelbar das fertige PDF - kein Polling, keine gespeicherten Prozesse, kein E-Mail-Versand.

curl -X POST https://app.output.rocks/api/renderings/preview \
  -H "Content-Type: application/json" \
  -H "X-AUTH-TOKEN: Ihr-Token-Hier" \
  -H "accept: application/pdf" \
  --output vorschau.pdf \
  -d '{
    "template": "rechnung_monatsabschluss",
    "data": {
      "kunde": {
        "nummer": "K-12345",
        "name": "Max Mustermann"
      }
    }
  }'

Die Vorschau verwendet dieselben Mappings, Marken, Standardwerte, Charts, QR-Codes und Prerender-Webhooks wie ein reguläres Rendering. Passen mehrere Dokumentvorlagen zum Identifier, werden sie in ihrer bestehenden Reihenfolge zusammengefügt. Optionale staticAttachments folgen danach in Request-Reihenfolge – allerdings nur, wenn der Request keine E-Mails erzeugt. Passt zum Identifier auch eine E-Mail-Vorlage, gehen die Anhänge produktiv an die E-Mail und nicht an das Dokument; die Vorschau lässt sie dann ebenfalls weg. Das feste Wasserzeichen VORSCHAU wird anschließend auf jede Seite gesetzt.

4. Powercloud-Integration einrichten

Powercloud.retail kann so konfiguriert werden, dass Events automatisch an Output.Rocks gesendet werden. Dies ermöglicht eine vollständig automatisierte Dokumentenerstellung bei Powercloud-Events.

Voraussetzungen:

Bevor Sie die Powercloud-Integration einrichten, benötigen Sie:

1. API-Token in Output.Rocks (siehe Authentifizierung)
2. Berechtigung in Powercloud für Event Endpoint-Konfiguration
3. Vorlagen in Output.Rocks mit entsprechenden Identifiers

Event Endpoint in Powercloud konfigurieren

1. Navigieren Sie in Powercloud zu All Apps → Settings → Events → Event Endpoints → Endpoint erstellen

2. Füllen Sie das Event Endpoint-Formular aus:

JSON Event Mapping konfigurieren

Um Events an Output.Rocks zu senden:

1. Navigieren Sie zu All Apps → Settings → Events → JSON Event Mapping
2. Klicken Sie auf Bearbeiten bei dem Event, das Sie an Output.Rocks senden möchten
3. Im Abschnitt Event Endpoints fügen Sie den konfigurierten Output.Rocks Event Endpoint zu Assigned Endpoints hinzu

Erweiterte und dynamische Features nutzen

Output.Rocks bietet mehrere erweiterte Möglichkeiten, die über die Basis-API-Nutzung hinausgehen.

Viele Eigenschaften von Dokumenten und E-Mails können dynamisch über die <<>>-Syntax gesetzt werden. Dies ermöglicht es, Werte aus dem Request-Payload, Standardwerten oder Komponenten zu verwenden.

Verfügbare dynamische Eigenschaften:

Dokument-Prozesse:

• Beschreibung
• Dateiname
• Benutzerdefinierte ID

E-Mail-Prozesse:

• Beschreibung
• Dateiname
• Benutzerdefinierte ID
• Empfänger (An)
• CC
• BCC
• Betreff

Beispiel: Dynamische E-Mail-Eigenschaften

Angenommen, Sie senden folgende Daten im Request:

{
  "contract": {
    "id": 1234,
    "firstName": "Max",
    "lastName": "Mustermann",
    "balance": 199.0,
    "email": "max.mustermann@example.com"
  }
}

E-Mail-Empfänger dynamisch setzen:

In der E-Mail-Vorlage-Konfiguration im Backend:

Dateiname dynamisch setzen:

CC mit Standardwert:

Komplexe Logik mit Vorlagenkomponenten

Für komplexere Logik (z.B. bedingte Betreffzeilen) verwenden Sie Vorlagenkomponenten:

Vorlagenkomponente definieren:

• Identifier: balance_sign
• Wert: <<cs_{contract.balance >= 0}>>positive<<else>>negative<<es_>>

In E-Mail-Betreff verwenden:

Betreff: Sehr geehrte(r) <<contract.firstName>>, Ihr Saldo ist <<component.balance_sign>>

Ergebnis: Sehr geehrte(r) Max, Ihr Saldo ist positive (bei positivem Saldo)

Datenvalidierung

Output.Rocks bietet ein flexibles Validierungskonzept, um sicherzustellen, dass E-Mails und Dokumente nur bei gültigen Daten gerendert werden.

Validatoren erstellen

1. Navigieren Sie zu Vorlagen-Management → Validierung → Validator erstellen

2. Details-Tab:

   • Identifier: Eindeutiger Identifier für den Validator (wird in Vorlagen verwendet)
   • Beschreibung: Beschreibung der Validierungslogik (z.B. "Prüfung auf positives Saldo")
   • Fehlermeldung: Nachricht, die bei fehlgeschlagener Validierung angezeigt wird
   • Aktiv ab: Optional für zeitgesteuerte Validatoren
   • Aktiv: Checkbox zum Aktivieren/Deaktivieren

3. Datenvalidierung-Tab:

   • Invalid, if defined condition returns "true": Wenn aktiviert, wird die Bedingung als "true" erwartet, wenn Daten ungültig sind
   • Condition: Die zu prüfende Bedingung (Symfony Expression Language)

Validierungs-Beispiel

Angenommen, Sie möchten sicherstellen, dass das Saldo positiv ist, bevor gerendert wird:

Daten im Request:

{
  "contract": {
    "id": 1234,
    "balance": 199.0
  }
}

Validatoren-Konfiguration:

• Invalid, if defined condition returns "true" ist aktiviert
• Condition: data['contract']['balance'] < 0

Oder alternativ:

• Invalid, if defined condition returns "true" ist deaktiviert
• Condition: data['contract']['balance'] >= 0

Validatoren Vorlagen zuweisen

1. Bearbeiten Sie eine Dokument- oder E-Mail-Vorlage
2. Öffnen Sie den Tab Validierung
3. Weisen Sie die Validator-Identifier zu

User-Interaktion-Feedback

Output.Rocks kann User-Interaktionen in Powercloud-Systemen erzeugen, wenn Validierungen fehlschlagen oder Prozesse blockiert sind. Zusätzlich bietet Output.Rocks eine API, um Feedback zu geschlossenen User-Interaktionen von Powercloud zu empfangen.

Webhook für User-Interaktionen konfigurieren

1. Erstellen Sie einen Webhook in Output.Rocks unter Integration → Webhooks
2. Wählen Sie den Typ Powercloud User Interaction oder einen Custom-Webhook
3. Konfigurieren Sie die Webhook-Parameter entsprechend Ihrer Powercloud-Instanz

Powercloud für Feedback konfigurieren

Nach der Webhook-Konfiguration in Output.Rocks muss Powercloud so konfiguriert werden, dass geschlossene User-Interaktionen an Output.Rocks zurückgemeldet werden.

Schritt 1: Event Endpoint für Feedback erstellen

1. Navigieren Sie in Powercloud zu All Apps → Settings → Events → Event Endpoints → Endpoint erstellen

2. Füllen Sie das Event Endpoint-Formular aus:

Schritt 2: Expert Settings konfigurieren

1. Navigieren Sie zu All Apps → Settings → Expert Settings
2. Setzen Sie die folgenden beiden Expert Settings auf den Event Endpoint-Namen output_rocks_user_interactions:
   • hook.integration_layer.endpoint_name
   • hook.integration_layer.order_endpoint_name

User-Interaktion-Feedback-Loop

Fehlerbehandlung und Monitoring

HTTP-Status-Codes

Output.Rocks verwendet standardmäßige HTTP-Status-Codes:

Fehler-Response-Struktur

Bei Fehlern enthält die Response ein error-Objekt:

{
  "error": {
    "code": 422,
    "message": "Validation failed",
    "details": [
      "Template 'rechnung_monatsabschluss' not found",
      "Required field 'data.customer.number' is missing"
    ]
  }
}

Monitoring im Backend

Alle API-Requests werden im Backend unter Requests gelistet. Hier können Sie:

• Den Status jedes Requests einsehen
• Fehlerhafte Prozesse identifizieren
• Blockierte Prozesse (invalid) verwalten
• Erstellte Dokumente und E-Mails einsehen

Fehlerantworten und Fehlercodes

Die öffentliche REST-API ergänzt synchrone JSON-Fehlerantworten mit einem gemeinsamen Grundformat. Es gilt für Ressourcen-, Rendering- und Archiv-Endpunkte sowie deren Authentifizierung. Verwaltungs-API (/api/spa), Legacy, Word-Add-in, OAuth/MCP, Provider-Callbacks und asynchrone Verarbeitungsergebnisse sind nicht Teil dieses Vertrags.

Beispiel: doppelte QR-Code-Anlage

POST /api/qr-codes antwortet bei einer Verletzung der Eindeutigkeitsprüfung mit HTTP 422. Der neue Code validation.not_unique gilt auch für entsprechende Eindeutigkeitsfehler anderer Ressourcen. Endpunkt und propertyPath liefern den Kontext.

{
  "status": 422,
  "message": "identifier: Active QR-Code definition already exists for client at same activation time",
  "errorCode": "validation.failed",
  "violations": [
    {
      "propertyPath": "identifier",
      "message": "Active QR-Code definition already exists for client at same activation time",
      "code": "23bd9dbf-6b9b-41cd-a99e-4844bcf3077f",
      "errorCode": "validation.not_unique"
    }
  ]
}

Der Ausschnitt zeigt die für die Fehlerbehandlung relevanten Felder. Zusätzliche Felder wie detail, type, title oder JSON-LD-/Hydra-Metadaten bleiben erhalten.

Codes der gesamten Antwort

Die bestehenden HTTP-Statuscodes ändern sich nicht. Ein fachlicher Konflikt kann weiterhin HTTP 409 ergeben; die Eindeutigkeitsvalidierung liefert HTTP 422. Bei 5xx wird für das neue Meldungsfeld ein allgemeiner Fehlertext verwendet.

Codes der einzelnen Feldfehler

Vorhandene fachliche Codes in punktgetrennter Kleinschreibung werden übernommen. Eigene Validatoren ohne spezifischen Code liefern validation.invalid. Der Meldungstext wird nicht zur Bestimmung des Codes ausgewertet.

Kompatibilität und Auswertung

Die Erweiterung ist additiv: Vorhandene Felder und Werte werden nicht überschrieben, auch explizite null-Werte bleiben erhalten. Bei 5xx wird nur ein fehlendes message-Feld mit einem allgemeinen Fehlertext ergänzt; vorhandene Meldungsfelder bleiben unverändert. Insbesondere bleibt die bisherige UUID unter violations[].code bestehen. Es gibt dafür kein angekündigtes Abschaltdatum. Fehlende message-Felder werden bei 4xx aus detail, hydra:description oder title ergänzt; andernfalls wird ein Standardtext verwendet.

Neue Integrationen sollten den HTTP-Status und errorCode auswerten. Für einzelne Felder alle Einträge unter violations prüfen. Unbekannte Codes und zusätzliche Felder müssen generisch behandelt werden können. Ältere Deployments liefern die neuen Felder möglicherweise noch nicht; in diesem Fall den HTTP-Status als Rückfall verwenden.

Content-Type und vorhandene Fehlerformate bleiben bestehen, etwa application/json, application/problem+json und unterstützte JSON-LD-Fehlerantworten. Die Erweiterung betrifft JSON-Objekte mit HTTP 400–599. Downloads, Streams, HTML, Erfolgsantworten und Fehler von vorgeschalteten Diensten sind davon ausgenommen. Aus demselben Grund sind die drei Felder in der OpenAPI-Beschreibung nicht als required markiert: Sie sind für JSON-Objekt-Fehlerantworten der öffentlichen Endpunkte vorgesehen, eine Auswertung sollte ihr Fehlen aber verkraften.