Utiliser l'API Certyneo : votre premier appel en 5 minutes

L'API REST Certyneo permet d'automatiser l'envoi, le suivi et la récupération de vos enveloppes de signature depuis vos propres applications : CRM, ERP, back-office métier, scripts internes. En cinq minutes, vous pouvez créer votre premier token, faire votre premier appel et lister vos enveloppes. Ce tutoriel vous accompagne étape par étape, avec des exemples curl prêts à copier-coller.

Étape 1 : créer un token d'API

Connectez-vous à votre compte Certyneo puis rendez-vous sur Paramètres → API. Cliquez sur Créer un token. Donnez-lui un nom explicite (par exemple Import CRM HubSpot) et choisissez un scope : envelope:read pour les tokens en lecture seule, envelope:write pour pouvoir créer et envoyer des enveloppes (inclut implicitement read). Le token apparaît une seule fois sous la forme ct_live_XXXXXXXX — copiez-le immédiatement dans votre gestionnaire de secrets.

Étape 2 : comprendre l'authentification

Toutes les routes /api/v1/* exigent un en-tête Authorization: Bearer ct_live_XXXXXXXX. Le token est secret : jamais dans du code client (JavaScript de navigateur), jamais commité dans un dépôt public. Utilisez-le uniquement en backend, stocké dans une variable d'environnement ou un vault. La documentation interactive complète est disponible sur https://certyneo.com/docs (ou https://api.certyneo.com) — vous pouvez y tester chaque endpoint en direct.

Étape 3 : votre premier appel — lister les enveloppes

Testons la connexion en listant vos enveloppes existantes. Ouvrez un terminal et exécutez (remplacez par votre token) : curl -H "Authorization: Bearer ct_live_XXXXXXXX" https://certyneo.com/api/v1/envelopes. Vous recevez une réponse JSON avec un tableau data (les enveloppes, du plus récent au plus ancien) et un objet pagination (page, limit, total, totalPages). Ajoutez ?status=COMPLETED pour filtrer par statut, ?limit=50 pour augmenter la taille de page.

Étape 4 : créer une enveloppe (brouillon)

La création d'une enveloppe suppose d'avoir déjà uploadé un document via l'interface (futur endpoint d'upload disponible en backlog). Récupérez un document_id depuis /documents puis appelez : curl -X POST -H "Authorization: Bearer ct_live_XXXXXXXX" -H "Content-Type: application/json" -d '{"subject":"Contrat de prestation","documentIds":["doc_abc"],"recipients":[{"email":"alice@example.com","name":"Alice Durand"}]}' https://certyneo.com/api/v1/envelopes. La réponse 201 contient l'objet enveloppe avec son id.

Étape 5 : envoyer l'enveloppe aux signataires

L'enveloppe est créée en mode DRAFT : pas encore envoyée. Pour la déclencher, appelez le endpoint d'envoi : curl -X POST -H "Authorization: Bearer ct_live_XXXXXXXX" https://certyneo.com/api/v1/envelopes/env_123/send. L'enveloppe passe en SENT, chaque destinataire reçoit un email avec son lien personnel. Vous pouvez à tout moment récupérer le détail avec GET /api/v1/envelopes/env_123 (inclut recipients, events, statut actuel).

Webhooks pour suivre les événements

Plutôt que de poller l'API toutes les minutes, configurez un webhook : Paramètres → Webhooks → Ajouter un endpoint. Certyneo POSTe un JSON signé HMAC-SHA256 (header X-Certyneo-Signature) à chaque événement du cycle de vie : envelope.sent, envelope.completed, recipient.signed, etc. Les payloads sont documentés dans les schémas WebhookEnvelope* de notre OpenAPI spec. Vérifiez toujours la signature HMAC avant d'agir sur un événement.

Limite de débit et erreurs

L'API accepte jusqu'à 60 requêtes par minute et par token. Au-delà, vous recevez un 429 Too Many Requests avec un en-tête Retry-After en secondes. Les autres codes d'erreur courants : 400 (payload invalide, voir le champ details), 401 (token absent ou invalide), 403 (scope insuffisant), 404 (ressource introuvable). Toutes les erreurs suivent un format standard { "error": "...", "details": {...} } documenté dans le schéma Error.

Aller plus loin

Consultez la documentation interactive complète sur https://certyneo.com/docs — elle liste tous les endpoints, les schémas de requêtes/réponses, des exemples pour chaque scénario (signature simple, signature avancée avec OTP SMS, flux séquentiel multi-signataires). Si vous souhaitez générer un SDK client dans votre langage, la spec OpenAPI 3.1 est téléchargeable sur /api/openapi.json et compatible avec openapi-generator-cli, speakeasy ou Stainless.