Créer une section dans un coffre

Ajoute une nouvelle section à un coffre, avec positionnement automatique en fin de liste si aucune position n'est fournie.

1 min de lectureTélécharger en PDF

Requête exemple

{
  "title": "États financiers",
  "is_visible": true,
  "description": "Bilans et comptes de résultat des 3 derniers exercices"
}

Réponse exemple

{
  "id": "sec_a71b9d02",
  "title": "États financiers",
  "position": 1,
  "coffre_id": "cof_3b9d7e21",
  "created_at": "2026-05-20T09:16:48.000Z",
  "is_visible": true,
  "description": "Bilans et comptes de résultat des 3 derniers exercices"
}

POST/v1/coffres/{id}/sectionsCrée une section dans le coffre identifié par {id}.

Crée une nouvelle section dans le coffre {id}. L'appartenance du coffre au workspace est vérifiée au préalable (sinon 404). Comportement notable : si le champ position n'est pas fourni (ou vaut 0), la section est automatiquement placée en fin de liste, sa position étant calculée à partir du nombre de sections existantes dans le coffre. La section est créée visible par défaut, sauf si is_visible est explicitement passé à false.

Authentification

Cet endpoint exige une clé API valide portant le scope transfers:write. Un jeton sans ce scope reçoit une erreur 403 scope_missing. Étant une opération d'écriture, l'appel est soumis au mécanisme d'idempotence : transmettez un en-tête Idempotency-Key pour éviter les doublons en cas de nouvelle tentative.

Corps de la requête

Champ	Type	Requis	Description
title	string	Oui	Intitulé de la section. Chaîne non vide (espaces de début/fin retirés). Absent ou vide : `400 validation_error`.
description	string	Non	Description de la section. Espaces retirés ; une valeur vide est stockée comme `null`.
position	number	Non	Rang d'affichage. Si absent ou `0`, la section est placée automatiquement en fin de liste.
is_visible	boolean	Non	Visibilité de la section. La section est visible par défaut ; seul `false` la masque.

Réponse

Renvoie 201 Created avec l'objet section créé : id, coffre_id, title, description (peut être null), position (résolue, automatique le cas échéant), is_visible et created_at.

Champ	Type	Description
id	string	Identifiant unique de la section créée.
coffre_id	string	Identifiant du coffre parent.
title	string	Intitulé normalisé (sans espaces de début/fin).
description	string \| null	Description normalisée, ou `null` si non fournie/vide.
position	integer	Rang effectif (calculé automatiquement si non fourni).
is_visible	boolean	Visibilité effective.
created_at	string	Date de création (ISO 8601).

Erreurs

Code	Quand	Résolution
400 validation_error	Identifiant de coffre manquant, corps non-JSON, ou `title` absent/vide.	Envoyez un corps JSON valide avec un `title` non vide.
401 invalid_api_key	Clé API absente, mal formée ou non reconnue.	Fournissez une clé valide dans l'en-tête `Authorization`.
403 scope_missing	Le jeton ne porte pas le scope `transfers:write`.	Émettez une clé incluant `transfers:write`.
404 not_found	Le coffre n'existe pas ou n'appartient pas au workspace.	Vérifiez l'identifiant du coffre et le workspace de la clé.
429 rate_limited	Quota de requêtes par minute dépassé.	Respectez l'en-tête `Retry-After` puis réessayez.
500 internal_error	Échec de l'insertion en base.	Réessayez ; en cas de persistance, contactez le support avec le `request_id`.

Voir aussi

GET /v1/coffres/{id}/sections : lister les sections existantes.
PATCH /v1/coffres/{id}/sections : renommer ou réordonner une section.
DELETE /v1/coffres/{id}/sections : supprimer une section.