API de signature électronique

Envoyez des documents à signer directement depuis vos propres systèmes : échangez une clé d'API contre un jeton, créez des enveloppes à partir de modèles, gérez des contacts et récupérez les liens de signature via une API REST simple.

L'API de signature électronique permet à votre application de faire ce que votre équipe fait dans l'app : transformer un modèle en demande de signature, l'envoyer et la suivre jusqu'à un PDF signé et horodaté avec piste d'audit, sans que personne n'ouvre BunnyDoc.

C'est une API REST réduite et ciblée. JSON en entrée, JSON en sortie, un seul jeton porteur et exactement les mêmes permissions que celles dont votre équipe dispose déjà dans l'app.

URL de base

Tous les endpoints se trouvent sous https://api2.bunnydoc.com/v1. Tous les chemins de ces pages sont relatifs à cette base.

Comment fonctionne l'authentification

L'accès se fait en deux étapes, et c'est la première chose à mettre en place. Votre clé d'API à longue durée de vie est envoyée une seule fois pour obtenir un jeton d'accès à courte durée de vie ; toutes les autres requêtes ne transportent que le jeton, de sorte que la clé ne circule plus jamais.

Créez une clé d'API

Dans l'app, ouvrez Paramètres → Clés d'API (propriétaire ou administrateur uniquement) et créez une clé. Elle ressemble à bd_live_… et n'est affichée qu'une seule fois, à la création : copiez-la en lieu sûr. Elle ne peut ensuite plus être récupérée, seulement renouvelée.

Échangez la clé contre un jeton d'accès

Envoyez votre clé à POST /v1/auth/token. Vous recevez un jeton porteur valable une heure.

Appelez l'API avec le jeton

Envoyez Authorization: Bearer <token> sur toutes les autres requêtes. Mettez le jeton en cache et réutilisez-le jusqu'à son expiration ; n'en générez pas un nouveau à chaque appel.

Gardez votre clé d'API côté serveur

Une clé d'API agit au nom de toute votre entreprise. Ne l'intégrez jamais dans un navigateur, une app mobile ou un client que vous ne contrôlez pas. Si une clé est exposée, renouvelez-la dans Paramètres → Clés d'API : le renouvellement (ou la révocation) invalide immédiatement ses jetons en cours.

Pour commencer

Obtenir un jeton d'accès

Le premier appel de toute intégration : échangez votre clé d'API contre un jeton porteur.

Envoyer depuis un modèle

Créez une enveloppe à partir d'un de vos modèles et envoyez-la, en un seul appel.

Les endpoints en un coup d'œil

Chaque requête est autorisée à la fois par le scope de votre clé et par la permission de l'utilisateur qui la possède : une clé ne peut jamais faire plus que ce que cette personne peut faire dans l'app.

Pour faire ceci	Endpoint	Scope
Échanger une clé d'API contre un jeton	`POST /v1/auth/token`	—
Lister vos modèles	`GET /v1/templates`	`templates:read`
Obtenir un modèle et ses rôles	`GET /v1/templates/{id}`	`templates:read`
Lister les contacts	`GET /v1/contacts`	`contacts:read`
Créer un contact	`POST /v1/contacts`	`contacts:write`
Créer une enveloppe à partir d'un modèle et l'envoyer	`POST /v1/envelopes/from-template`	`envelopes:send`
Récupérer les liens de signature d'une enveloppe envoyée	`GET /v1/envelopes/{id}/signing-links`	`envelopes:send`

| Lister les événements auxquels vous pouvez vous abonner | GET /v1/webhooks/events | webhooks:read | | Lister vos abonnements webhook | GET /v1/webhooks | webhooks:read | | Abonner un endpoint à des événements | POST /v1/webhooks | webhooks:write | | Désabonner un endpoint | DELETE /v1/webhooks/{id} | webhooks:write |

Vous voulez être notifié lorsqu'un document est signé, refusé ou annulé plutôt que d'interroger l'API ? Utilisez les webhooks — et récupérez le PDF final directement dans la charge utile de envelope.document_ready.

Conventions

JSON en entrée, JSON en sortie — envoyez et attendez application/json.
Limité à votre entreprise — chaque ressource appartient à une entreprise, et les requêtes ne franchissent jamais les frontières entre entreprises.
Les mêmes permissions que l'app — une clé ne peut faire que ce que le rôle de son propriétaire autorise. Voir Utilisateurs et rôles.
Les scopes restreignent l'accès — les scopes d'une clé (templates:read, contacts:read, contacts:write, envelopes:send, webhooks:read, webhooks:write) ne peuvent que limiter ce que son propriétaire pouvait déjà faire, jamais l'étendre.

Pagination

Les endpoints de liste acceptent page (à partir de 1) et per_page (jusqu'à 100, 25 par défaut), et renvoient un objet pagination :

{
  "data": [ /* … */ ],
  "pagination": { "page": 1, "per_page": 25, "total": 134, "total_pages": 6 }
}

Limites de débit

Les requêtes sont limitées par clé d'API (l'endpoint du jeton, par IP). Dépasser une limite renvoie 429 rate_limited : patientez puis réessayez.

Limite	Portée
20 échanges de jeton / 15 min	par IP
100 envois / 15 min	par clé d'API
1000 autres requêtes / 15 min	par clé d'API

Erreurs

Toutes les erreurs ont la même forme : basez-vous sur error.code, jamais sur le texte du message. Voir la référence des erreurs complète.

{ "error": { "code": "unknown_signer_role", "message": "…", "details": { } } }