API & développeurs

Introduction

L'API SignCloud est une API REST : requêtes HTTPS, corps et réponses en JSON. Toutes les URLs sont préfixées par https://signcloud.fr/api/v1.

Règle clé : chaque signataire doit avoir un mobile — la signature est vérifiée par code SMS.

Vous utilisez un logiciel de facturation ? Recettes Sellsy, Axonaut, Pennylane (Make / n8n) →

Authentification

Passez votre clé API dans l'en-tête Authorization: Bearer <clé> (ou X-Api-Key). Générez-la depuis Compte → API & Webhooks.

curl https://signcloud.fr/api/v1/ping \
  -H "Authorization: Bearer VOTRE_CLE_API"

$sc = new SignCloud\Client('VOTRE_CLE_API');
$sc->ping();

const sc = new SignCloud('VOTRE_CLE_API');
await sc.ping();

Idempotence des créations

Pour chaque création de document, envoyez une clé métier stable dans Idempotency-Key (8–200 caractères). Un rejeu strictement identique renvoie la réponse initiale avec Idempotency-Replayed: true sans créer ni envoyer un second document. La même clé avec un corps différent est refusée en 422.

-H "Idempotency-Key: commande-1024-contrat-v1"

Créer un document (HTML)

Envoie un contrat HTML : SignCloud le convertit en PDF et l'envoie à signer. Idéal quand vous n'avez pas de PDF sous la main.

curl -X POST https://signcloud.fr/api/v1/documents/html \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrat",
    "html": "<h1>Contrat</h1><p>…</p>",
    "recipients": [{"name":"Jean Dupont","email":"jean@ex.com","phone":"+33612345678"}]
  }'

$doc = $sc->createFromHtml([
  'name' => 'Contrat',
  'html' => '<h1>Contrat</h1><p>…</p>',
  'recipients' => [[
    'name' => 'Jean Dupont', 'email' => 'jean@ex.com', 'phone' => '+33612345678',
  ]],
]);
echo $doc['id'];

const doc = await sc.createFromHtml({
  name: 'Contrat',
  html: '<h1>Contrat</h1><p>…</p>',
  recipients: [{ name: 'Jean Dupont', email: 'jean@ex.com', phone: '+33612345678' }],
});
console.log(doc.id);

FranceConnect & démarches publiques

Cet endpoint permet à un téléservice autorisé (INPI ou autre démarche française) de créer un document puis de rediriger l’usager vers le sign_url renvoyé. FranceConnect authentifie l’identité ; SignCloud assure la lecture du PDF, le consentement, le code SMS, la signature et le dossier de preuve.

Le corps est identique à /api/v1/documents. Utilisez identity_provider="franceconnect", une return_url HTTPS, un webhook et une clé Idempotency-Key stable. L’activation en production nécessite l’habilitation DINUM et les identifiants FranceConnect/FranceConnect+.

curl -X POST https://signcloud.fr/api/v1/partner/signature-requests \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Idempotency-Key: inpi-formalite-2026-00042" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Formalité INPI",
    "pdf_base64": "JVBERi0xLjc…",
    "identity_provider": "franceconnect",
    "return_url": "https://demarches.exemple.fr/dossiers/42",
    "recipients": [{"name":"Jean Dupont","email":"jean@exemple.fr","phone":"+33612345678"}]
  }'

Réponse (201) :

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Contrat",
  "status": "SENT",
  "signers": [{ "email": "jean@ex.com", "status": "PENDING", "sign_url": "https://signcloud.fr/doc/…" }],
  "recipient": { "sign_url": "https://signcloud.fr/doc/…" }
}

API SignCloud Identity seule

Pour un client qui souhaite uniquement vérifier une identité, sans document à signer. L’API renvoie une page dédiée en marque blanche (nom, logo et couleurs du client), un deep link vers l’application NFC et un statut pollable. Le résultat VERIFIED n’est produit qu’après le contrôle NFC, le selfie vivant, l’anti-présentation et le dépôt externe de la preuve.

Le même service est disponible sans code dans le tableau de bord Identity. Une offre « Identity uniquement » masque les documents et ne laisse apparaître que ce parcours, la marque et les réglages.

Après validation, le client récupère l’assertion JSON et l’attestation PDF par API. La personne contrôlée peut aussi télécharger son attestation minimisée depuis son lien sécurisé ; aucun selfie, portrait DG2, numéro complet ni certificat brut n’y figure.

Télécharger le contrat OpenAPI Identity →

curl -X POST https://signcloud.fr/api/identity/v1/verifications \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Idempotency-Key: controle-client-0042" \
  -H "Content-Type: application/json" \
  -d '{"reference":"client-0042","return_url":"https://votre-site.fr/controle/termine","retention_years":10}'

Créer un document (PDF)

Envoie un PDF existant à signer. Le PDF est encodé en base64 dans pdf_base64.

Les options retention_years, verification, return_url et l’en-tête Idempotency-Key sont identiques à la création HTML.

curl -X POST https://signcloud.fr/api/v1/documents \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mandat",
    "pdf_base64": "JVBERi0xLjc…",
    "recipients": [{"name":"Jean","email":"jean@ex.com","phone":"+33612345678"}]
  }'

$doc = $sc->createDocument(
  ['name' => 'Mandat', 'recipients' => [[
    'name' => 'Jean', 'email' => 'jean@ex.com', 'phone' => '+33612345678',
  ]]],
  file_get_contents('mandat.pdf') // encodé en base64 par le SDK
);

import { readFileSync } from 'fs';
const doc = await sc.createDocument({
  name: 'Mandat',
  pdf_base64: readFileSync('mandat.pdf').toString('base64'),
  recipients: [{ name: 'Jean', email: 'jean@ex.com', phone: '+33612345678' }],
});

Lister les documents

Filtres : status (DRAFT, SENT, COMPLETED…), limit (1–100).

Récupérer un document

Retourne le statut détaillé et les signataires (statuts PENDING / WAITING / SIGNED).

Télécharger le PDF signé

Retourne le PDF scellé (une fois le document COMPLETED). Réponse binaire application/pdf.

Relancer / Annuler

Relance le signataire en attente (nouveau lien) ou annule un envoi en cours.

Webhooks

SignCloud notifie votre URL à chaque étape. Événements : recipient.signed, document.completed.

Idempotent par URL : appelez-le depuis chaque site (PrestaShop, WordPress…) pour enregistrer plusieurs webhooks — chacun reçoit tous les événements et obtient SON propre secret (renvoyé dans webhook_secret). Chaque envoi est signé X-SignCloud-Signature: sha256=<hmac>. Vérifiez-la :

// $secret : renvoyé à la création du webhook
if (!SignCloud\Client::verifyWebhook(
  file_get_contents('php://input'),
  $_SERVER['HTTP_X_SIGNCLOUD_SIGNATURE'] ?? '',
  $secret
)) { http_response_code(401); exit; }

const ok = SignCloud.verifyWebhook(
  rawBody,
  req.headers['x-signcloud-signature'],
  secret
);
if (!ok) return res.status(401).end();

Corps reçu :

{
  "event": "document.completed",
  "sent_at": "2026-08-09T10:12:00Z",
  "tenant": "…",
  "data": {
    "document": { "id": "…", "name": "Contrat", "sha256": "…", "signed_pdf_url": "…" },
    "signers": [{ "name": "Jean Dupont", "email": "jean@ex.com", "signed_at": "…" }]
  }
}

REST Hooks

Pour des abonnements multiples (Zapier, Make…) qui coexistent avec le webhook principal.

Codes d'erreur

Les erreurs renvoient { "error": "...", "message": "..." }.

SDK officiels

Clients mono-fichier, sans dépendance, pour PHP et JavaScript/Node. Ils couvrent tous les endpoints et la vérification des webhooks.

⬇ Télécharger le SDK