Documenten genereren via de API

Documenten maken met de Omnidocs Create API.

INHOUDSOPGAVE

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

Introductie

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

Dynamische sjablonen gebruiken een JSON-payload. Dat is een gestructureerd bestand met gegevens. Daarin staat welke gegevens in het document komen. Elke waarde in die payload moet passen bij het type node (of bouwblok) in het sjabloon. Denk aan tekst, nummer, datum, groep, element, selecteren, herhalen of tabel.

Je gebruikt hetzelfde schema voor dynamische sjablonen in twee verschillende flows:

Voorbereidingsflow: gebruik het prepare-endpoint als je wilt dat Omnidocs Create de generatieflow opstart. Je krijgt dan de informatie terug die je nodig hebt om verder te gaan. Dit is handig als de integratie het document eerst moet voorbereiden, voordat het definitieve document wordt gemaakt.

Generatieflow: gebruik het generate-endpoint als je het document meteen wilt maken vanuit de gegevens die je meestuurt.

Beide endpoints gebruiken hetzelfde schema. Daarom is de opbouw van de payload voor tekst-, nummer-, datum-, groep-, element-, select-, herhaal- en tabelnodes in beide flows precies hetzelfde.

Vereisten

Zorg dat je dit hebt, voordat je begint:

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

Endpoints

Generatie voorbereiden

Gebruik het prepare-endpoint om een generatieflow te starten voor een dynamisch sjabloon: 

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

Gebruik het prepare-endpoint om een generatieflow te starten voor een dynamisch sjabloon: 

Document genereren

Gebruik het generate-endpoint om meteen een document te maken vanuit een sjabloon: 

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

De requestbody gebruikt hetzelfde schema als bij het 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 passen bij een node key die in het dynamische sjabloon is ingesteld. 

Nodetypen

Tekstnode

Gebruik een Tekstnode als het sjabloon platte tekst verwacht. 

{
  "senderName": "Jane Doe"
}

De waarde moet een JSON-string zijn.

Nummernode

Gebruik een Nummernode als het sjabloon een getal verwacht. 

{
  "amount": 1234.56
}

De waarde moet een JSON-getal zijn.

Datumnode

Gebruik een Datumnode als het sjabloon een datum 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 als je een genest object wilt versturen. 

{
  "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 als het sjabloon inline-inhoud verwacht, of een verwijzing naar een ander sjabloon. 

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

Laat je referenceId weg? Dan gebruikt het element de inline-inhoud die al in het sjabloon staat. 

Selectnode

Gebruik een Selectnode als het sjabloon vaste opties heeft.

De eigenschap option bepaalt welke optie wordt gekozen.

Je kunt op drie manieren naar een optie verwijzen:

• Met de naam van het element.
• Met een index (0, 1, 2, enzovoort).
• Met een objectwaarde (dit is gereserveerd voor later gebruik).

Gebruik je een tekstwaarde? Dan verwijst option naar de naam van het element. Niet naar de node key.

Staat de node ingesteld als Gebruik als checkbox? Dan worden alle opties toegevoegd. De gegevens van elke optie worden dan gekoppeld.

Stel dat je sjabloon dit bevat:

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

Dan kies je het element zo, op naam:

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

Je kunt ook kiezen met een index: 

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

Staat de selectnode ingesteld op meerdere keuzes toestaan? Geef dan een lijst (array) met keuzeobjecten op: 

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

Repeatnode

Gebruik een Repeatnode als dezelfde inhoud meerdere keren moet komen, maar dan telkens met andere 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 gebruiken. Dan herhaal je een sjabloon waarnaar wordt verwezen: 

{
  "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 als het sjabloon een tabel moet maken van gestructureerde gegevens.

De eenvoudigste manier is een lijst (array) met rijen:

{
  "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 de kolommen ook zelf instellen: 

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

Een request kan om deze redenen mislukken:

• Een verplichte node ontbreekt in de payload.
• Een waarde heeft het verkeerde JSON-type.
• Een datum klopt niet met de verwachte indeling.
• Een selectnode verwijst naar een optie die niet bestaat.
• Een repeat- of tabelnode krijgt een object, terwijl een lijst (array) wordt verwacht.
• Een referenced template ID is ongeldig of niet beschikbaar.

Samenvatting

Met dynamische sjablonen maak je documenten vanuit gestructureerde JSON-payloads.

Wil je een document succesvol maken? Dan moet elke eigenschap in je request passen bij het verwachte nodetype, en bij de bindende sleutel in het sjabloon.

Gebruik:

• Strings voor tekst en datums.
• Getallen voor numerieke waarden.
• Objecten voor groepen en elementen.
• Lijsten (arrays) voor repeats, multi-selects en eenvoudige tabellen.
• Zelf ingestelde kolommen, als de API de tabelstructuur moet bepalen.