Welchen Inhaltstyp verwende ich beim API-Aufruf?

Der Content-Type-Header in einer HTTP-Anfrage gibt den Medientyp oder MIME-Typ (Multipurpose Internet Mail Extensions) der im Anfrage-Body gesendeten Ressource an. Er teilt dem Server mit, welche Art von Daten im Anfrage-Payload gesendet werden, damit der Server sie entsprechend verarbeiten kann. Zwei häufig verwendete Werte sind:

• application/json: Für JSON-Daten verwendet
• multipart/form-data: Für das Senden von Binärdaten oder Dateien in einem Formular verwendet

Die Notwendigkeit, den Content-Type-Header anzugeben, hängt von der Art der HTTP-Anfrage ab und davon, ob sie einen Nachrichtentext enthält oder nicht. Der Content-Type-Header ist für Anfragen mit einem Nachrichtentext obligatorisch, wie POST- und PUT-Anfragen, aber nicht für Anfragen ohne einen solchen, wie GET- und DELETE-Anfragen.

Für die DocuGenerate-API ist es entscheidend, dass Ihre Anfragen den richtigen Inhaltstyp verwenden. Im Folgenden sehen Sie, welchen Inhaltstyp Sie beim Erstellen oder Aktualisieren einer Vorlage bzw. beim Generieren oder Aktualisieren eines Dokuments verwenden können.

Vorlage erstellen oder aktualisieren

Bitte stellen Sie sicher, dass Sie beim Erstellen oder Aktualisieren einer Vorlage den folgenden Header verwenden:

Content-Type: multipart/form-data

Beim Aufruf des Endpunkts POST /template oder PUT /template/{id} muss der Inhaltstyp multipart/form-data sein, um den file-Parameter zu unterstützen, der die binäre Darstellung der hochgeladenen Vorlagendatei erwartet:

curl -X 'POST' \
  'https://api.docugenerate.com/v1/template' \
  -H 'Authorization: 491c000c5fad32ed7787005b0723ad55' \
  -H 'Accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@Invoice.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document' \
  -F 'name=Invoice' \
  -F 'delimiters={
  "left": "[",
  "right": "]"
}' \
  -F 'enhanced_syntax=false'

Der multipart/form-data-Inhaltstyp ist besonders nützlich bei Webformularen mit Datei-Uploads. Er ermöglicht die Übertragung von Text- und Binärdaten in einer einzigen Anfrage und ist somit für verschiedene Datentypen vielseitig einsetzbar.

Dokument Generieren oder Aktualisieren

Ebenso können Sie beim Erstellen oder Aktualisieren eines Dokuments einen der folgenden Header verwenden:

Content-Type: application/json
Content-Type: multipart/form-data

Zusätzlich zur Möglichkeit, den multipart/form-data-Inhaltstyp zu verwenden, akzeptiert der Dokumentgenerierungs-Endpunkt auch den application/json-Inhaltstyp.

Wahl zwischen Inhaltstypen

Wenn Sie eine binäre Datei mit Daten übergeben müssen, ist die Verwendung von multipart/form-data obligatorisch. Wenn Ihre Daten als JSON bereitgestellt werden, können Sie entweder application/json oder multipart/form-data verwenden.

Verwendung einer Datendatei
Um Dokumente in großen Mengen aus einer Vorlage und einer Excel-Datei mit den Daten zu generieren, verwenden Sie den multipart/form-data-Inhaltstyp beim Aufruf des POST /document-Endpunkts:

curl -X 'POST' \
  'https://api.docugenerate.com/v1/document' \
  -H 'Authorization: 491c000c5fad32ed7787005b0723ad55' \
  -H 'Accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'template_id=B7mRfQIxjAu4Mm3IwJVz' \
  -F 'name=Invoice' \
  -F 'page_break=true' \
  -F 'single_file=true' \
  -F 'output_format=.pdf' \
  -F 'file=@Data.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'

Verwendung von JSON-Daten
Wenn die Daten als JSON bereitgestellt werden, kann jeder der beiden Inhaltstypen verwendet werden.
Für multipart/form-data enthält der data-Parameter die String-Darstellung des JSON-Objekts (in JavaScript z.B. mit JSON.stringify() erhalten):

curl -X 'POST' \
  'https://api.docugenerate.com/v1/document' \
  -H 'Authorization: 491c000c5fad32ed7787005b0723ad55' \
  -H 'Accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'template_id=B7mRfQIxjAu4Mm3IwJVz' \
  -F 'data=[{"Invoice No":"INV-1001","Invoice Date":"2023-12-15","Total": "$200"},{"Invoice No":"INV-1002","Invoice Date":"2023-12-16","Total":"$500"}]' \
  -F 'name=Invoice' \
  -F 'page_break=true' \
  -F 'single_file=true' \
  -F 'output_format=.pdf'

Für application/json ist der gesamte Anfrage-Payload ein JSON-Objekt und enthält die data-Eigenschaft, die ein Array von JSON-Objekten (zur Generierung mehrerer Dokumente) oder ein einzelnes JSON-Objekt (zur Generierung eines Dokuments) sein kann:

curl -X 'POST' \
  'https://api.docugenerate.com/v1/document' \
  -H 'Authorization: 491c000c5fad32ed7787005b0723ad55' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "template_id": "B7mRfQIxjAu4Mm3IwJVz",
  "data": [{
      "Invoice No": "INV-1001",
      "Invoice Date": "2023-12-15",
      "Total": "$200"
    },
    {
       "Invoice No": "INV-1002",
       "Invoice Date": "2023-12-16",
       "Total": "$500"
    }],
  "name": "Invoice",
  "output_format": ".pdf",
  "single_file": true,
  "page_break": true
}'

Ebenso kann beim Aufruf des PUT /document/{id}-Endpunkts zur Aktualisierung eines bestehenden Dokuments einer der beiden Inhaltstypen verwendet werden.