Quel type de contenu utiliser lors de l'appel de l'API?

L’en-tête Content-Type d’une requête HTTP indique le type de média ou type MIME (Multipurpose Internet Mail Extensions) de la ressource envoyée dans le corps de la requête. Il informe le serveur du type de données envoyées dans la charge utile de la requête, afin qu’il puisse les traiter correctement. Deux valeurs couramment utilisées sont :

• application/json : utilisée pour les données JSON
• multipart/form-data : utilisée pour l’envoi de données binaires ou de fichiers dans un formulaire

La nécessité de spécifier l’en-tête Content-Type dépend du type de requête HTTP et de la présence ou non d’un corps de message. L’en-tête Content-Type est obligatoire pour les requêtes contenant un corps de message, comme les requêtes POST et PUT, mais n’est pas nécessaire pour celles qui n’en contiennent pas, comme les requêtes GET et DELETE.

Pour l’API de DocuGenerate, il est essentiel d’utiliser le bon type de contenu pour garantir une communication réussie. Lisez la suite pour découvrir quel type de contenu utiliser lors de la création ou mise à jour d’un modèle ou lors de la génération ou mise à jour d’un document.

Créer ou mettre à jour un modèle

Veillez à utiliser l’en-tête suivant lors de la création ou la mise à jour d’un modèle :

Content-Type: multipart/form-data

Lors de l’appel du point de terminaison POST /template ou PUT /template/{id}, le type de contenu doit être multipart/form-data pour prendre en charge le paramètre file, qui attend la représentation binaire du fichier de modèle envoyé :

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'

Le type de contenu multipart/form-data est particulièrement utile pour les formulaires web incluant des envois de fichiers. Il permet de transmettre du texte et des données binaires en une seule requête, ce qui le rend polyvalent pour différents types de données.

Générer ou mettre à jour un document

De la même façon, lors de la création ou de la mise à jour d’un document, vous pouvez utiliser l’un des en-têtes suivants :

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

En plus de pouvoir utiliser le type de contenu multipart/form-data, le point de terminaison de génération de documents accepte également le type de contenu application/json.

Choisir entre les types de contenu

Si vous devez transmettre un fichier binaire contenant des données, l’utilisation du type de contenu multipart/form-data est obligatoire. Si vos données sont fournies au format JSON, vous pouvez utiliser soit application/json, soit multipart/form-data.

Utiliser un fichier de données Pour générer des documents en masse à partir d’un modèle et d’un fichier Excel contenant les données, utilisez le type de contenu multipart/form-data lors de l’appel du point de terminaison POST /document :

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'

Utiliser des données JSON Si les données sont fournies au format JSON, l’un ou l’autre des types de contenu peut être utilisé. Pour multipart/form-data, le paramètre data contient la représentation sous forme de chaîne de l’objet JSON (obtenue avec JSON.stringify() en JavaScript par exemple) :

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'

Pour application/json, l’ensemble de la charge utile de la requête est un objet JSON contenant la propriété data, qui peut être un tableau d’objets JSON (pour générer plusieurs documents) ou un seul objet JSON (pour générer un seul document) :

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
}'

De même, lors de l’appel du point de terminaison PUT /document/{id} pour mettre à jour un document existant, l’un ou l’autre des types de contenu peut être utilisé.