Documenten genereren via de API

Documenten genereren met de Omnidocs Create API.

INHOUDSOPGAVE

• Introductie
• Vereisten
• Endpoints
• Nodetypen
• Volledig payloadvoorbeeld
• Veelvoorkomende validatieproblemen
• Samenvatting

Introductie

In deze handleiding leer je hoe je documenten genereert met dynamische sjablonen via de Omnidocs Create API.

Dynamische sjablonen gebruiken een gestructureerde JSON-payload om de gegevens te definiëren die in het document moeten worden ingevoegd. Elk veld in de payload moet overeenkomen met het verwachte node-/bouwbloktype in het sjabloon, zoals tekst, nummer, datum, groep, element, selecteren, herhalen of tabel.

Je kunt hetzelfde schema voor dynamische sjablonen in twee verschillende flows gebruiken:

• Voorbereidingsflow
  Gebruik het prepare-endpoint wanneer je wilt dat Omnidocs Create de generatieflow initialiseert en de informatie retourneert die nodig is om het proces voort te zetten. Dit is nuttig wanneer de integratie de documentgeneratie moet voorbereiden voordat het definitieve document wordt gemaakt.
• Generatieflow
  Gebruik het generate-endpoint wanneer je het document direct wilt genereren vanuit de opgegeven payload.

Beide endpoints gebruiken hetzelfde gegevensschema, dus de payloadstructuur voor tekst-, nummer-, datum-, groep-, element-, select-, herhaal- en tabelnodes is identiek in beide flows.

Vereisten

Voordat je begint, zorg ervoor dat je beschikt over:

• Toegang tot de Omnidocs Create API;
• Een geldige API-token;
• Een unitId;
• Een templateId;
• Kennis van het schema voor dynamische sjablonen dat door het sjabloon wordt gebruikt.
  
  

Endpoints

Generatie voorbereiden

Gebruik de prepare-endpoint om een generatieflow voor een dynamisch sjabloon te initialiseren:

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

De requestbody bevat de gegevens die vereist zijn door het dynamische sjabloon.

Document genereren

Gebruik de generate-endpoint om een document direct vanuit een sjabloon te genereren:

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

De requestbody gebruikt hetzelfde schema als de prepare-endpoint.

Basisvoorbeeld van een request

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

Elke eigenschap in de payload moet overeenkomen met een node key die in het dynamische sjabloon is geconfigureerd.

Nodetypen

Tekstnode

Gebruik een Tekstnode wanneer het sjabloon platte tekst verwacht.

{
  "senderName": "Jane Doe"
}

De waarde moet een JSON-string zijn.

Nummernode

Gebruik een Nummernode wanneer het sjabloon een numerieke waarde verwacht.

{
  "amount": 1234.56
}

De waarde moet een JSON-getal zijn.

Datumnode

Gebruik een Datumnode wanneer het sjabloon een datumwaarde verwacht.

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

De waarde moet een string zijn die de verwachte ISO 8601-datetime-indeling gebruikt.

Groepsnode

Gebruik een Groepsnode wanneer je een genest object moet verzenden.

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

Groepen zijn nuttig om gerelateerde gegevens bij elkaar te houden.

Elementnode

Gebruik een Elementnode wanneer het sjabloon inline-inhoud of een verwijzing naar een ander sjabloon verwacht.

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

Als referenceId wordt weggelaten, gebruikt het element de inline-inhoud die in het sjabloon is geconfigureerd.

Selectnode

Gebruik een Selectnode wanneer het sjabloon vooraf gedefinieerde opties bevat.

De eigenschap option definieert welke elementoptie moet worden geselecteerd.

Je kunt op drie manieren naar de optie verwijzen:

• Op naam van het element
• Op index (0, 1, 2, enz.)
• Met een objectwaarde (gereserveerd voor toekomstige ondersteuning)

Als de node is geconfigureerd met Gebruik als checkbox, worden alle opties ingevoegd en worden de gegevens van elke optie gematcht.

Als je sjabloon bijvoorbeeld het volgende bevat:

• Een element met de naam Copenhagen Office
• Een element met de naam New York Office

Je kunt het element als volgt op naam selecteren:

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

Je kunt ook op index selecteren:

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

Als de selectnode is geconfigureerd om meerdere selecties toe te staan, geef dan een array met optieobjecten op:

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

Repeatnode

Gebruik een Repeatnode wanneer dezelfde inhoud meerdere keren moet worden gegenereerd met verschillende gegevens.

{
  "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"
    }
  ]
}

Je kunt ook een referenceId opgeven om een sjabloon waarnaar wordt verwezen te herhalen:

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

Tabelnode

Gebruik een Tabelnode wanneer het sjabloon een tabel moet genereren vanuit gestructureerde gegevens.

De eenvoudigste indeling is een array met rijobjecten:

{
  "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"
    }
  ]
}

Je kunt kolommen ook expliciet definiëren:

{
  "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"
      }
    ]
  }
}

Volledig payloadvoorbeeld

{
  "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"
    }
  ]
}

Veelvoorkomende validatieproblemen

Veelvoorkomende redenen waarom een request kan mislukken zijn:

• Een vereiste node ontbreekt in de payload;
• Een waarde gebruikt het verkeerde JSON-type;
• Een datumwaarde komt niet overeen met de verwachte indeling;
• Een selectnode verwijst naar een optie die niet bestaat;
• Een repeat- of tabelnode ontvangt een object terwijl een array wordt verwacht;
• Een referenced template ID is ongeldig of niet beschikbaar.

Samenvatting

Dynamische sjablonen laten je documenten genereren vanuit gestructureerde JSON-payloads.

Om een document succesvol te genereren, moet elke eigenschap in je request overeenkomen met het verwachte nodetype en de Bindende sleutel in het sjabloon.

Gebruik:

• Strings voor tekst en datums;
• Getallen voor numerieke waarden;
• Objecten voor groepen en elementen;
• Arrays voor repeats, multi-selects en eenvoudige tabellen;
• Expliciete kolomdefinities wanneer de API de tabelstructuur moet beheren.