Inviter un invité sur un coffre

Crée (ou réémet) une invitation par e-mail et renvoie un lien d'accès au coffre.

Requête exemple

{
  "note": "Contact côté acquéreur",
  "email": "client@exemple.com",
  "expires_at": "2026-07-01T00:00:00.000Z",
  "can_download": true
}

Réponse exemple

{
  "guest": {
    "id": "gst_8f3a21c0d4e9",
    "note": "Contact côté acquéreur",
    "email": "client@exemple.com",
    "status": "pending",
    "created_at": "2026-06-05T09:14:22.000Z",
    "expires_at": "2026-07-01T00:00:00.000Z",
    "invite_link": "https://app.coffrify.com/c/dossier-fusion-2026?t=tok_a1b2c3d4e5f6",
    "can_download": true,
    "invite_token": "tok_a1b2c3d4e5f6"
  },
  "invite_link": "https://app.coffrify.com/c/dossier-fusion-2026?t=tok_a1b2c3d4e5f6"
}

POST/v1/coffres/{id}/guestsInvite un invité par e-mail sur un coffre et renvoie un lien d'accès.

Invite une personne à accéder à un coffre via son adresse e-mail. L'opération est un upsert sur le couple (coffre_id, email) : si l'adresse avait déjà été invitée puis révoquée, l'invitation est réémise avec un nouveau jeton et le statut repasse à pending. L'e-mail est normalisé (trim + minuscules). Inviter sur un coffre archived est refusé.

Authentification

Requiert une clé API valide portant le scope coffres:manage. L'utilisateur résolu par la clé est enregistré comme invited_by sur l'invitation. Cet endpoint est soumis à l'idempotence : pensez à fournir un en-tête Idempotency-Key pour les réessais sûrs.

Corps de la requête

Champ	Type	Requis	Description
email	string	Oui	Adresse e-mail de l'invité. Trimée et passée en minuscules ; doit contenir un `@`.
can_download	boolean	Non	Autorise le téléchargement des documents. Défaut : `true`.
note	string	Non	Annotation interne (trimée). Défaut : `null`.
expires_at	string	Non	Date d'expiration de l'accès (ISO 8601). Défaut : `null` (pas d'expiration).

Réponse

Renvoie l'objet guest créé ou réémis (id, email, status, can_download, note, expires_at, invite_token, created_at) enrichi de invite_link, ainsi qu'un champ invite_link au niveau racine. Le lien est construit sous la forme {NEXT_PUBLIC_APP_URL}/c/{slug}?t={invite_token} (base par défaut : https://app.coffrify.com). C'est ce lien qu'il faut transmettre à l'invité.

Erreurs

Code	Quand	Résolution
400 validation_error	`email` manquant ou sans `@`, ou coffre `archived`.	Fournir un e-mail valide ; ne pas inviter sur un coffre archivé.
401 invalid_api_key	Clé absente, mal préfixée ou introuvable.	Vérifier l'en-tête Authorization et la clé.
403 scope_missing	La clé ne porte pas `coffres:manage`.	Émettre une clé avec le scope `coffres:manage`.
404 not_found	Le coffre n'existe pas dans le workspace.	Vérifier l'identifiant `{id}` et le workspace.
429 rate_limited	Quota par minute dépassé.	Respecter `Retry-After` puis réessayer.
500 internal_error	Échec de l'upsert ou enregistrement non créé.	Réessayer avec le même `Idempotency-Key` ; contacter le support si besoin.

Voir aussi

GET /v1/coffres/{id}/guests — lister les invités actifs
PATCH /v1/coffres/{id}/guests — ajuster permissions et expiration
DELETE /v1/coffres/{id}/guests — révoquer un invité