Sådan genererer du dokumenter via API'et

Generering af dokumenter med Omnidocs Create API.

INDHOLDSFORTEGNELSE

• Introduktion
• Forudsætninger
• Endpoints
• Nodetyper
• Komplet payload-eksempel
• Almindelige valideringsproblemer
• Opsummering

Introduktion

I denne vejledning lærer du, hvordan du genererer dokumenter med dynamiske skabeloner gennem Omnidocs Create API.

Dynamiske skabeloner bruger en struktureret JSON-payload til at definere de data, der skal indsættes i dokumentet. Hvert felt i payloaden skal matche den forventede node-/building block-type i skabelonen, såsom tekst, tal, dato, gruppe, element, select, repeat eller tabel.

Du kan bruge det samme dynamiske skabelonskema i to forskellige flows:

• Prepare flow
  Brug prepare-endpointet, når du vil have Omnidocs Create til at initialisere genereringsflowet og returnere de oplysninger, der er nødvendige for at fortsætte processen. Dette er nyttigt, når integrationen skal forberede dokumentgenereringen, før det endelige dokument oprettes.
• Generate flow
  Brug generate-endpointet, når du vil generere dokumentet direkte fra den angivne payload.

Begge endpoints bruger det samme dataskema, så payload-strukturen for tekst-, tal-, dato-, gruppe-, element-, select-, repeat- og tabelnoder er identisk i begge flows.

Forudsætninger

Før du går i gang, skal du sikre dig, at du har:

• Adgang til Omnidocs Create API
• Et gyldigt API-token
• Et unitId
• Et templateId
• Kendskab til det dynamiske skabelonskema, der bruges af skabelonen

Endpoints

Forbered generering

Brug prepare-endpointet til at initialisere et dynamisk skabelongenereringsflow:

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

Request body indeholder de data, der kræves af den dynamiske skabelon.

Generer dokument

Brug generate-endpointet til at generere et dokument direkte fra en skabelon:

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

Request body bruger det samme skema som prepare-endpointet.

Grundlæggende request-eksempel

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

Hver egenskab i payloaden skal matche en nodenøgle, der er konfigureret i den dynamiske skabelon.

Nodetyper

Tekstnode

Brug en tekstnode, når skabelonen forventer almindelig tekst.

{
  "senderName": "Jane Doe"
}

Værdien skal være en JSON-streng.

Talnode

Brug en talnode, når skabelonen forventer en numerisk værdi.

{
  "amount": 1234.56
}

Værdien skal være et JSON-tal.

Datonode

Brug en datonode, når skabelonen forventer en datoværdi.

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

Værdien skal være en streng, der bruger det forventede ISO 8601-datetimeformat.

Gruppenode

Brug en gruppenode, når du skal sende et indlejret objekt.

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

Grupper er nyttige til at holde relaterede data samlet.

Elementnode

Brug en elementnode, når skabelonen forventer inline-indhold eller en reference til en anden skabelon.

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

Hvis referenceId udelades, bruger elementet det inline-indhold, der er konfigureret i skabelonen.

Select-node

Brug en select-node, når skabelonen indeholder foruddefinerede muligheder.

Egenskaben option definerer hvilken elementmulighed der skal vælges.

Du kan referere til muligheden på tre måder:

• Ved navnet på elementet
• Ved indeks (0, 1, 2 osv.)
• Ved en objektværdi (reserveret til fremtidig understøttelse)

Hvis noden er konfigureret med Brug til synlighed, indsætter den alle muligheder og matcher dataene for hver mulighed.

Hvis din skabelon for eksempel indeholder:

• Et element med navnet Copenhagen Office
• Et element med navnet New York Office

Du kan vælge elementet ved navn på denne måde:

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

Du kan også vælge efter indeks:

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

Hvis select-noden er konfigureret til at tillade flere valg, skal du angive et array af option-objekter:

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

Repeat-node

Brug en repeat-node, når det samme indhold skal genereres flere gange med forskellige data.

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

Du kan også angive et referenceId for at gentage en refereret skabelon:

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

Tabelnode

Brug en tabelnode, når skabelonen skal generere en tabel ud fra strukturerede data.

Det enkleste format er et array af rækkeobjekter:

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

Du kan også definere kolonner eksplicit:

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

Komplet payload-eksempel

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

Almindelige valideringsproblemer

Almindelige årsager til, at et request kan fejle, inkluderer:

• En påkrævet node mangler i payloaden
• En værdi bruger den forkerte JSON-type
• En datoværdi matcher ikke det forventede format
• En select-node refererer til en mulighed, der ikke findes
• En repeat- eller tabelnode modtager et objekt, hvor der forventes et array
• Et refereret skabelon-ID er ugyldigt eller utilgængeligt

Opsummering

Dynamiske skabeloner giver dig mulighed for at generere dokumenter ud fra strukturerede JSON-payloads.

For at generere et dokument korrekt skal du sikre dig, at hver egenskab i dit request matcher den forventede nodetype og bindingsnøgle i skabelonen.

Brug:

• Strenge til tekst og datoer
• Tal til numeriske værdier
• Objekter til grupper og elementer
• Arrays til repeats, multi-selects og simple tabeller
• Eksplicitte kolonnedefinitioner, når API'et skal styre tabelstrukturen