# API de signature AbySign

Créer une enveloppe et récupérer le document signé et ses preuves.

## Une surface distincte

La signature de documents arbitraires utilise `/api/abysign/v1`, avec un jeton d'app autorisé et les scopes de signature. Cette adresse est un alias de `/api/v1/abysign`, dont les opérations figurent dans la référence REST sous la rubrique abysign. Elle est distincte de la simple transition de statut d'un devis. Les scopes sont `signatures:read` et `signatures:write`.

## Créer une enveloppe

Envoyez un formulaire `multipart/form-data` à `POST /api/abysign/v1/envelopes`. Il porte le fichier PDF, les informations de titre et de destinataires ainsi que les champs de signature selon le parcours choisi. Utilisez `draft=true` pour préparer le document sans envoyer immédiatement les invitations.

Le contrat accepte notamment `recipients`, une liste JSON avec `name`, `email`, `role` et `rank`, et `sequential` pour ordonner la signature. Les rôles comprennent `signer`, `viewer`, `cc` et `in_person`. Prévoyez au moins un destinataire qui signe.

Les champs doivent tenir dans les pages du PDF. Un fichier invalide, une zone hors page ou un signataire incorrect provoque une validation refusée. La limite de taille est configurable sur l'instance.

## Préparer puis envoyer

| Route sous /api/abysign/v1 | Usage |
|---|---|
| GET /envelopes | Liste et filtres |
| GET /envelopes/{id} | Détail, destinataires, champs, état et événements |
| PUT /envelopes/{id}/fields | Remplacer les champs d'un brouillon |
| POST /envelopes/{id}/send | Envoyer un brouillon préparé |
| POST /envelopes/{id}/remind | Relancer une demande encore en attente |
| POST /envelopes/{id}/cancel | Annuler lorsque l'état le permet |

Une relance est limitée et une opération incompatible avec le statut peut répondre `409`. Un `signUrl` est une capacité d'accès personnelle au parcours : ne le journalisez pas dans un outil public.

## Récupérer le résultat

Les routes `signed.pdf`, `certificate.pdf` et `proof.json` sous l'enveloppe fournissent les pièces disponibles. `timestamp.tsr` dépend de la configuration d'horodatage et peut répondre `404` en son absence. Les téléchargements de l'API exigent l'authentification.

Suivez les webhooks `signature.*` et, à plusieurs destinataires, `signature.recipient.*`. Utilisez `externalId` pour relier l'enveloppe à votre dossier externe. Vérifiez le résultat final, pas seulement l'envoi de l'invitation.

## Exemple : préparer un brouillon

Le fichier et le destinataire sont fictifs. Le jeton doit posséder `signatures:write`.

```sh
curl --fail-with-body --silent --show-error \
  "$CERCLA_URL/api/abysign/v1/envelopes" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Idempotency-Key: demo-signature-2026-001' \
  -F 'document=@./document-exemple.pdf;type=application/pdf' \
  -F 'title=Document de démonstration' \
  -F 'recipients=[{"name":"Camille Exemple","email":"camille@example.com","role":"signer","rank":1}]' \
  -F 'draft=true'
```

Cet exemple crée un brouillon sans envoyer l'invitation. Relisez les champs et les destinataires avant l'appel d'envoi. Pour un autre document, utilisez une nouvelle clé d'idempotence ; pour la reprise de cette même demande, conservez la même clé et le même corps.

La forme JSON porte `document.filename` et `document.contentBase64`. Les schémas complets des deux parcours, des destinataires et des champs figurent dans [la référence abysign](/documentation/reference-api-abysign/).