Ajouter un approbateur à un transfert

Ajoute un approbateur (par e-mail ou utilisateur interne) à un transfert et lui envoie une demande de validation par e-mail.

2 min de lectureTélécharger en PDF

Requête exemple

{
  "approver_email": "juridique@acme.fr"
}

Réponse exemple

{
  "id": "tap_71b0e8f4a2c9476d",
  "note": null,
  "decision": "pending",
  "created_at": "2026-06-05T10:12:44.000Z",
  "decided_at": null,
  "notified_at": "2026-06-05T10:12:44.000Z",
  "transfer_id": "trf_8c1d4e90",
  "workspace_id": "ws_3a7b2f10",
  "approver_email": "juridique@acme.fr",
  "approver_user_id": null
}

POST/v1/transfers/{id}/approversAjoute un approbateur au transfert et envoie une demande de validation.

Cet endpoint crée une ligne d'approbateur pour le transfert {id} avec une décision initiale pending, puis envoie (en mode best-effort) un e-mail de demande de validation contenant des liens à usage unique. Vous pouvez désigner l'approbateur par son adresse e-mail (approver_email) ou par un identifiant d'utilisateur interne (approver_user_id) : dans ce dernier cas, l'API résout l'e-mail à partir du profil. Le transfert doit appartenir à l'espace de travail de la clé, sinon une erreur 404 est renvoyée. L'envoi de l'e-mail est non bloquant : la création de l'approbateur réussit même si l'e-mail échoue.

Authentification

Cet endpoint nécessite une clé API valide disposant du scope transfers:manage. Sans ce scope, l'API répond 403 scope_missing. Cet endpoint respecte l'idempotence : envoyez un en-tête Idempotency-Key pour éviter de créer deux fois le même approbateur en cas de nouvel essai réseau.

Corps de la requête

Le corps doit fournir au moins l'un des deux champs ci-dessous. Si ni approver_email ni approver_user_id n'est présent, l'API répond 400 validation_error.

Champ	Type	Requis	Description
approver_email	string	Conditionnel	Adresse e-mail de l'approbateur. Requis si `approver_user_id` est absent.
approver_user_id	string	Conditionnel	Identifiant d'un utilisateur interne. Si fourni seul, l'e-mail est résolu depuis son profil. Requis si `approver_email` est absent.

Réponse

La réponse est l'objet approbateur créé. Les champs clés : id, transfer_id, workspace_id, approver_user_id (ou null), approver_email (e-mail fourni ou résolu), decision initialisée à pending, decided_at et note à null, notified_at (rempli avec l'horodatage de création si un e-mail a pu être ciblé, sinon null) et created_at.

Champ	Type	Description
id	string	Identifiant de l'approbateur créé.
transfer_id	string	Transfert associé.
workspace_id	string	Espace de travail propriétaire.
approver_user_id	string \| null	Utilisateur interne ou null.
approver_email	string \| null	E-mail fourni ou résolu depuis le profil.
decision	string	Toujours `pending` à la création.
notified_at	string \| null	Horodatage si un e-mail a été ciblé, sinon null.
created_at	string	Horodatage de création.

Erreurs

Code	Quand	Résolution
400 validation_error	Ni approver_email ni approver_user_id fourni.	Fournissez au moins l'un des deux champs.
401 missing_api_key	En-tête Authorization absent.	Ajoutez `Authorization: Bearer cof_live_...`.
403 scope_missing	La clé n'a pas le scope `transfers:manage`.	Émettez une clé incluant ce scope.
404 not_found	Le transfert n'existe pas dans cet espace.	Vérifiez l'`id` et l'espace de travail de la clé.
429 rate_limited	Quota de requêtes dépassé.	Respectez l'en-tête Retry-After avant de réessayer.
500 internal_error	Échec d'insertion ou de lecture en base.	Réessayez ; persistant, contactez le support avec le request_id.

Voir aussi

GET /v1/transfers/{id}/approvers — lister les approbateurs et suivre leurs décisions.
GET /v1/transfers/{id} — vérifier le statut d'approbation du transfert.
POST /v1/transfers — créer un transfert avant d'y ajouter des approbateurs.