API Variables

L'objet variable

• id : identifiant unique
• title : nom de la variable, unique au sein de son modèle
• description : requis, explique le contenu attendu
• field_type : text, checkbox, radio, select, ou collection
• seed_value : valeur d'exemple pour prévisualiser le modèle. Jamais renvoyée par ces endpoints ; seule la vue détaillée de création/mise à jour/publication/dépublication du modèle la renvoie, voir API Modèles
• allowed_values : tableau, pertinent uniquement pour radio/select

collection est un type de champ construit pour les modèles workflow, où une API dédiée accepte un tableau fields décrivant chaque ligne. Les paramètres permis par cet endpoint sont uniquement title, description, seed_value, field_type, et allowed_values. fields n'en fait pas partie, donc une variable collection créée ici n'a aucun moyen de satisfaire la validation de description de ligne qu'elle requiert, et ne peut pas être créée via cet endpoint.

Chaque action ci-dessous résout d'abord le modèle parent via le même scope que les endpoints d'écriture des modèles : custom, non archivé, dans votre organisation. Un identifiant de modèle fillable_form ou workflow, un modèle archivé, ou un modèle d'une autre organisation répondent tous 404 {"error": "Template not found"}. Voir Les écritures ne touchent que les modèles custom.

Les titres ne sont pas normalisés sur une variable toute neuve

title doit correspondre à un motif de nommage (lettres, chiffres, underscores ; ni espaces ni accents) et doit être unique au sein de son modèle, à la création comme à la mise à jour.

Lister les variables

curl https://app.doclift.io/api/v1/templates/100013/variables \
  --header "X-Api-Key: <your-api-key>"

[
  {
    "id": 200003,
    "title": "client_name",
    "description": "Name of the client",
    "field_type": "text",
    "allowed_values": []
  },
  {
    "id": 200004,
    "title": "status",
    "description": "Client status",
    "field_type": "select",
    "allowed_values": ["active", "inactive", "pending"]
  }
]

Renvoie toutes les variables du modèle (pas de pagination). seed_value est volontairement absent de cette forme.

Créer une variable

curl https://app.doclift.io/api/v1/templates/100013/variables \
  --request POST \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "variable": {
      "title": "payment_method",
      "description": "Selected payment method",
      "field_type": "select",
      "seed_value": "bank_transfer",
      "allowed_values": ["bank_transfer", "credit_card", "check"]
    }
  }'

{
  "id": 200005,
  "title": "payment_method",
  "description": "Selected payment method",
  "field_type": "select",
  "allowed_values": ["bank_transfer", "credit_card", "check"]
}

seed_value est accepté dans le corps de la requête mais jamais présent dans la réponse de cet endpoint (voir l'encadré ci-dessus pour l'endroit où il est lisible).

Mettre à jour une variable

curl https://app.doclift.io/api/v1/templates/100013/variables/200005 \
  --request PATCH \
  --header "X-Api-Key: <your-api-key>" \
  --header "Content-Type: application/json" \
  --data '{
    "variable": {
      "description": "Updated description",
      "allowed_values": ["bank_transfer", "credit_card"]
    }
  }'

{
  "id": 200005,
  "title": "payment_method",
  "description": "Updated description",
  "field_type": "select",
  "allowed_values": ["bank_transfer", "credit_card"]
}

Mêmes champs que la création. allowed_values remplace le tableau stocké, il ne fusionne pas avec lui. Renommer title ici est mis en minuscules et débarrassé de ses espaces (contrairement à la création). Faire évoluer field_type (ex. text vers select) tout en définissant allowed_values dans le même appel fonctionne.

Supprimer une variable

curl https://app.doclift.io/api/v1/templates/100013/variables/200005 \
  --request DELETE \
  --header "X-Api-Key: <your-api-key>"

204 No Content. C'est une suppression définitive (aucune validation ne s'exécute), il n'y a donc pas de chemin 422 ici.

Créer une variable en ligne

Plutôt qu'un appel séparé, variables_attributes sur POST /api/v1/templates ou PATCH /api/v1/templates/:id accepte les mêmes champs (title, description, seed_value, field_type, allowed_values) plus id et _destroy pour la mise à jour. Voir API Modèles pour la forme de la requête. La réponse de ces endpoints de modèle est l'unique endroit où id et seed_value d'une variable apparaissent ensemble.

Le même comportement non normalisé s'applique à une variable toute neuve ajoutée via variables_attributes, que ce soit sur POST /api/v1/templates ou sur PATCH /api/v1/templates/:id. Seule une variable qui existait déjà avant l'appel voit son titre mis en minuscules et débarrassé de ses espaces.