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. Powercloud-Integration einrichten
4. Erweiterte Features nutzen
5. 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

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. 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