Créer un enregistrement

La syntaxe permettant de modifier un enregistrement avec un identifiant unique est la suivante (méthode PUT):

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{"field":"value"}'
     -X PUT
     'https://<host>/api/v1/<taskId>'

Si le code de retour HTTP est 200, la réponse sera structurée comme ceci (comme le retour de récupération):

{
  "metadata": {
    "apiVersion": "1.0",
    "taskId": "<taskId>",
    "taskType": "<type>",
    "domainId": "<domain>"
  },
  "data": { ... }
}

Paramètres	Type	Description
autoAcknowledge	Boolean	Voir la description générale. Vaut aussi bien pour la création d’un enregistrement que pour la création d’une page.

La création d’une page s’effectue avec la commande suivante:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{"field":"value"}'
     -X PUT
     'https://<host>/api/v1/<taskId>/<recordId>/pages/<pageId>'

Si le code de retour HTTP est 200, la réponse sera structurée comme ceci:

{
  "metadata": {
    "apiVersion": "1.0",
    "taskId": "<taskId>",
    "taskType": "<type>",
    "domainId": "<domain>"
  },
  "data": { ... }
}

Selon la configuration, la création d’un nouveau dossier s’effectue par la création de la page d’en-tête. La génération de l’identifiant du dossier est généraement automatique, dans ce cas utiliser la valeur AUTO comme identifiant générique lors de la création:

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{"field":"value"}'
     -X PUT
     'https://<host>/api/v1/ADR02/AUTO/pages/DONNEESBASE'

L’identifiant généré sera retourné dans les données de la page en réponse.

Pour une tâche à double niveau (taskType = F), la création se fait en un seul appel: le corps de la requête contient à la fois l’en-tête (clé header) et les lignes (clé lines), sur le même modèle que la structure retournée par une lecture.

curl --insecure --silent \
     -H "Authorization: Bearer <bearer_token>" \
     --json '{
       "header": {
         "NO_DEBITEUR": "D1000",
         "NO_LIGNE": 0,
         "DATE_FACTURE": "2020-01-01T00:00:00+0100"
       },
       "lines": [
         { "SUB_NO_ARTICLE": "INTSER", "SUB_QUANTITE": 1, "SUB_MONTANT": 1000.0 },
         { "SUB_NO_ARTICLE": "FRAIS", "SUB_QUANTITE": 1, "SUB_MONTANT": 500.0 }
       ]
     }'
     -X PUT
     'https://<host>/api/v1/STO30'

En interne, le traitement exécute successivement la création de l’en-tête, puis la création de chaque ligne de lines (dans l’ordre du tableau), puis la validation (terminate) de l’enregistrement complet.

En interface, sélectionner un article sur une ligne déclenche une cascade qui remplit automatiquement plusieurs autres champs de la ligne. L’API REST, elle, applique le contenu de lines tel quel: cette cascade n’est pas rejouée, et les champs qu’elle aurait renseignés restent vides si le client ne les fournit pas lui-même, ce qui peut ensuite faire échouer la validation finale, parfois avec un message qui n’en indique pas clairement la cause.

Pour une ligne de facture (STO30), trois champs sont concernés en pratique:

• le code de TVA de la ligne (SUB_NO_TVA): sans valeur par défaut, il devient obligatoire dès qu’un article est sélectionné et que la TVA est active pour le domaine, et doit donc être fourni explicitement;
• le type de TVA de la ligne (SUB_TYPE_TVA, TVA incluse ou à ajouter): sa valeur par défaut, générique au framework, peut diverger de celle que la cascade de l’écran aurait calculée à partir de l’article sélectionné, et donc faire diverger le total de la ligne recalculé par le serveur du total saisi en en-tête, provoquant un refus à la validation;
• le montant brut de la ligne (SUB_MONTANT_BRUT): jamais renseigné par le chemin API, son absence fait échouer toute relecture ou modification ultérieure de la facture.

Si le code de retour HTTP est 200, la réponse sera structurée comme le retour d’une lecture, avec le $recordId de chaque ligne créée.