So generieren Sie Dokumente über die API

Generieren von Dokumenten mit der Omnidocs Create API.

INHALTSVERZEICHNIS

• Einführung
• Voraussetzungen
• Endpunkte
• Knotentypen
• Vollständiges Payload-Beispiel
• Häufige Validierungsprobleme
• Zusammenfassung

Einführung

In diesem Leitfaden erfahren Sie, wie Sie Dokumente mit dynamischen Vorlagen über die Omnidocs Create API generieren.

Dynamische Vorlagen verwenden eine strukturierte JSON-Payload, um die Daten zu definieren, die in das Dokument eingefügt werden sollen. Jedes Feld in der Payload muss dem erwarteten Knoten-/Bausteintyp in der Vorlage entsprechen, z. B. Text, Zahl, Datum, Gruppe, Element, Auswahl, Wiederholung oder Tabelle.

Sie können dasselbe Schema für dynamische Vorlagen in zwei verschiedenen Abläufen verwenden:

• Prepare-Ablauf
  Verwenden Sie den Prepare-Endpunkt, wenn Omnidocs Create den Generierungsablauf initialisieren und Informationen zurückgeben soll, die für die Fortsetzung des Prozesses benötigt werden. Dies ist nützlich, wenn die Integration die Dokumentgenerierung vorbereiten muss, bevor das endgültige Dokument erstellt wird.
• Generate-Ablauf
  Verwenden Sie den Generate-Endpunkt, wenn Sie das Dokument direkt aus der bereitgestellten Payload generieren möchten.

Beide Endpunkte verwenden dasselbe Datenschema, sodass die Payload-Struktur für Text-, Zahlen-, Datums-, Gruppen-, Element-, Auswahl-, Wiederholungs- und Tabellenknoten in beiden Abläufen identisch ist.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie Folgendes haben:

• Zugriff auf die Omnidocs Create API
• Ein gültiges API-Token
• Eine unitId
• Eine templateId
• Kenntnisse über das von der Vorlage verwendete Schema für dynamische Vorlagen

Endpunkte

Generierung vorbereiten

Verwenden Sie den Prepare-Endpunkt, um einen Generierungsablauf für dynamische Vorlagen zu initialisieren:

POST /api/v1/units/{unitId}/generate/prepare

Der Anfragetext enthält die von der dynamischen Vorlage benötigten Daten.

Dokument generieren

Verwenden Sie den Generate-Endpunkt, um ein Dokument direkt aus einer Vorlage zu generieren:

POST /api/v1/units/{unitId}/recipes/{templateId}/generate

Der Anfragetext verwendet dasselbe Schema wie der Prepare-Endpunkt.

Einfaches Anfragebeispiel

{
  "senderName": "Jane Doe",
  "recipientName": "John Doe",
  "amount": 1234.56,
  "date": "2025-10-10T00:00:00"
}

Jede Eigenschaft in der Payload muss einem Knotenschlüssel entsprechen, der in der dynamischen Vorlage konfiguriert ist.

Knotentypen

Textknoten

Verwenden Sie einen Textknoten, wenn die Vorlage einfachen Text erwartet.

{
  "senderName": "Jane Doe"
}

Der Wert muss ein JSON-String sein.

Zahlenknoten

Verwenden Sie einen Zahlenknoten, wenn die Vorlage einen numerischen Wert erwartet.

{
  "amount": 1234.56
}

Der Wert muss eine JSON-Zahl sein.

Datumsknoten

Verwenden Sie einen Datumsknoten, wenn die Vorlage einen Datumswert erwartet.

{
  "startDate": "2025-10-10T00:00:00"
}

Der Wert muss ein String sein, der das erwartete ISO-8601-Datumszeitformat verwendet.

Gruppenknoten

Verwenden Sie einen Gruppenknoten, wenn Sie ein verschachteltes Objekt senden müssen.

{
  "company": {
    "name": "Omnidocs",
    "address": "Wilders Plads 15A 1403 Copenhagen K Denmark",
    "cvr": 35679529
  }
}

Gruppen sind nützlich, um zusammengehörige Daten gemeinsam zu verwalten.

Elementknoten

Verwenden Sie einen Elementknoten, wenn die Vorlage Inline-Inhalte oder einen Verweis auf eine andere Vorlage erwartet.

{
  "employeeCard": {
    "referenceId": "000000000000",
    "data": {
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

Wenn referenceId ausgelassen wird, verwendet das Element die in der Vorlage konfigurierten Inline-Inhalte.

Auswahlknoten

Verwenden Sie einen Auswahlknoten, wenn die Vorlage vordefinierte Optionen enthält.

Die Eigenschaft option definiert, welche Elementoption ausgewählt werden soll.

Sie können die Option auf drei Arten referenzieren:

• Über den Namen des Elements
• Über den Index (0, 1, 2 usw.)
• Über einen Objektwert (für zukünftige Unterstützung reserviert)

Wenn der Knoten mit Als Sichtbarkeit verwenden konfiguriert ist, werden alle Optionen eingefügt und die Daten jeder Option abgeglichen.

Wenn Ihre Vorlage beispielsweise Folgendes enthält:

• Ein Element mit dem Namen Copenhagen Office
• Ein Element mit dem Namen New York Office

Sie können das Element wie folgt über den Namen auswählen:

{
  "office": {
    "option": "Copenhagen Office",
    "data": {
      "name": "Copenhagen Office",
      "location": "Wilders Plads 15A 1403 Copenhagen K Denmark",
      "agent": "John"
    }
  }
}

Sie können auch über den Index auswählen:

{
  "office": {
    "option": 0,
    "data": {
      "name": "Copenhagen Office",
      "location": "Wilders Plads 15A 1403 Copenhagen K Denmark",
      "agent": "John"
    }
  }
}

Wenn der Auswahlknoten so konfiguriert ist, dass mehrere Auswahlen zulässig sind, geben Sie ein Array von Optionsobjekten an:

{
  "offices": [
    {
      "option": 0,
      "data": {
        "name": "Copenhagen Office"
      }
    },
    {
      "option": 2,
      "data": {
        "name": "New York Office"
      }
    }
  ]
}

Wiederholungsknoten

Verwenden Sie einen Wiederholungsknoten, wenn derselbe Inhalt mehrfach mit unterschiedlichen Daten generiert werden soll.

{
  "locations": [
    {
      "name": "Copenhagen Office",
      "location": "Wilders Plads 15A 1403 Copenhagen K Denmark",
      "cost": "$$$",
      "agent": "John"
    },
    {
      "name": "New York Office",
      "location": "World Trade Center",
      "cost": "$$$",
      "agent": "John"
    }
  ]
}

Sie können auch eine referenceId angeben, um eine referenzierte Vorlage zu wiederholen:

{
  "locations": {
    "referenceId": "000000000000",
    "items": [
      {
        "name": "Copenhagen Office",
        "location": "Wilders Plads 15A 1403 Copenhagen K Denmark"
      },
      {
        "name": "New York Office",
        "location": "World Trade Center"
      }
    ]
  }
}

Tabellenknoten

Verwenden Sie einen Tabellenknoten, wenn die Vorlage eine Tabelle aus strukturierten Daten generieren soll.

Das einfachste Format ist ein Array von Zeilenobjekten:

{
  "officesTable": [
    {
      "name": "Copenhagen Office",
      "location": "Wilders Plads 15A 1403 Copenhagen K Denmark",
      "cost": "$$$",
      "agent": "John"
    },
    {
      "name": "New York Office",
      "location": "World Trade Center",
      "cost": "$$$",
      "agent": "John"
    }
  ]
}

Sie können auch Spalten explizit definieren:

{
  "officesTable": {
    "columns": [
      {
        "title": "Name",
        "fraction": 1,
        "bindingConfiguration": {
          "bindingType": "text",
          "bindingKey": "name"
        }
      },
      {
        "title": "Location",
        "fraction": 1,
        "bindingConfiguration": {
          "bindingType": "text",
          "bindingKey": "location"
        }
      }
    ],
    "items": [
      {
        "name": "Copenhagen Office",
        "location": "Wilders Plads 15A 1403 Copenhagen K Denmark"
      },
      {
        "name": "New York Office",
        "location": "World Trade Center"
      }
    ]
  }
}

Vollständiges Payload-Beispiel

{
  "title": "Office overview",
  "createdDate": "2025-10-10T00:00:00",
  "company": {
    "name": "Omnidocs",
    "address": "Wilders Plads 15A 1403 Copenhagen K Denmark",
    "cvr": 35679529
  },
  "selectedOffice": {
    "option": "Copenhagen Office",
    "data": {
      "name": "Copenhagen Office",
      "location": "Wilders Plads 15A 1403 Copenhagen K Denmark",
      "agent": "John"
    }
  },
  "locations": [
    {
      "name": "Copenhagen Office",
      "location": "Wilders Plads 15A 1403 Copenhagen K Denmark",
      "cost": "$$$",
      "agent": "John"
    },
    {
      "name": "New York Office",
      "location": "World Trade Center",
      "cost": "$$$",
      "agent": "John"
    }
  ]
}

Häufige Validierungsprobleme

Häufige Gründe, warum eine Anfrage fehlschlagen kann, sind:

• Ein erforderlicher Knoten fehlt in der Payload
• Ein Wert verwendet den falschen JSON-Typ
• Ein Datumswert entspricht nicht dem erwarteten Format
• Ein Auswahlknoten verweist auf eine Option, die nicht existiert
• Ein Wiederholungs- oder Tabellenknoten erhält ein Objekt, obwohl ein Array erwartet wird
• Eine referenzierte Vorlagen-ID ist ungültig oder nicht verfügbar

Zusammenfassung

Dynamische Vorlagen ermöglichen es Ihnen, Dokumente aus strukturierten JSON-Payloads zu generieren.

Um ein Dokument erfolgreich zu generieren, stellen Sie sicher, dass jede Eigenschaft in Ihrer Anfrage dem erwarteten Knotentyp und dem Binding Key in der Vorlage entspricht.

Verwenden Sie:

• Strings für Text und Datumswerte
• Zahlen für numerische Werte
• Objekte für Gruppen und Elemente
• Arrays für Wiederholungen, Mehrfachauswahlen und einfache Tabellen
• Explizite Spaltendefinitionen, wenn die API die Tabellenstruktur steuern soll