Intégration d'un bouton "Certifier" — du clic au webhook

Ce guide décrit le parcours complet le plus courant pour intégrer Certificall depuis l'interface d'un partenaire :

1. Côté partenaire — Un bouton "Certifier" dans votre interface (back-office, espace client, application métier) déclenche la génération d'un Certilink avec les données contextuelles du dossier (bénéficiaire, références internes, métadonnées).
2. Côté utilisateur final — Le Certilink lui est transmis (email, SMS, lien inline). À l'ouverture, il est redirigé vers l'application mobile Certificall (téléchargement si nécessaire), qui ouvre directement la trame attendue dans le bon contexte grâce au deeplink.
3. Capture de la preuve — L'utilisateur prend la photo, signe, remplit les champs définis par la trame.
4. Côté partenaire — À la clôture du dossier, vous recevez le contenu certifié sur votre webhook : items, photos, géolocalisation, URL du PDF.

Le tout sans authentification de l'utilisateur final, et avec un suivi end-to-end via votre référence métier (reportToken).

---

Vue d'ensemble du parcours

┌─────────────────────┐                ┌──────────────────────┐
│   Interface         │  (1) clic      │   Backend partenaire │
│   partenaire        │──────────────► │                      │
│   (bouton           │                │  POST /auth/token    │
│   "Certifier")      │                │  POST /certilink/    │
└─────────────────────┘                │       create         │
         ▲                             └──────────┬───────────┘
         │                                        │
         │ (5) webhook                            │ (2) URL du Certilink
         │     ShareCasesWith                     │     https://app.
         │     MetaDatasDto                       │     certificall.app
         │                                        │     ?mt=<uuid>
         │                                        ▼
┌────────┴────────────┐                ┌──────────────────────┐
│  Backend Certificall│                │   Utilisateur final  │
│                     │                │   (email / SMS /     │
│  - Validation       │ (4) clôture    │    lien inline)      │
│  - Webhook out      │◄───────────────┤                      │
└─────────────────────┘                └──────────┬───────────┘
                                                  │
                                                  │ (3) ouvre le lien
                                                  ▼
                                       ┌──────────────────────┐
                                       │   App mobile         │
                                       │   Certificall        │
                                       │                      │
                                       │   - install si       │
                                       │     besoin           │
                                       │   - deeplink ouvre   │
                                       │     la bonne trame   │
                                       │     pré-remplie      │
                                       └──────────────────────┘

---

Pré-requis

Avant de démarrer l'intégration, assurez-vous d'avoir :

Pré-requis	Comment l'obtenir
Compte API actif	Demandez à votre administrateur Certificall l'activation d'un utilisateur de type API (login / mot de passe dédiés).
Trame configurée	Une trame définit la séquence d'étapes (photo, signature, champ texte…). Configurez-la dans l'admin Certificall, voir Trame et Étapes.
URL de webhook	Une URL HTTPS de votre côté capable de recevoir des requêtes POST et d'authentifier l'appelant (Bearer, en-tête security-token, ou HMAC).
Identifiants webhook	Enregistrez vous-même l'authToken (Bearer ou security-token) via POST /company-options/api-settings, ou communiquez à Certificall la paire apiKey / apiSecretKey (HMAC). Voir Webhook après validation d'un certificat.

---

Étape 1 — Authentification

Tout appel à l'API Certificall doit être authentifié par un token JWT obtenu via les identifiants de votre compte API.

• Endpoint : POST /certificall/api/auth/token
• Référence détaillée : Authentification Publique
• Swagger : Public authentication

Requête :

curl -X POST https://admin.certificall.app/certificall/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "votre_compte_api",
    "password": "votre_mot_de_passe"
  }'

Réponse :

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Ce token doit être présent dans l'en-tête Authorization: Bearer <token> de tous les appels suivants.

Bonnes pratiques

• Mettez le token en cache côté backend et rafraîchissez-le avant expiration plutôt que de le redemander à chaque clic.
• Ne l'exposez jamais côté navigateur : l'appel d'authentification et la création du Certilink doivent s'effectuer depuis votre backend.

---

Étape 2 — Identifier la trame à utiliser

Chaque Certilink est associé à une trame (frameId) qui détermine ce que l'utilisateur final devra fournir.

• Endpoint : GET /certificall/api/frames
• Référence détaillée : Récupération de la Trame

Requête :

curl https://admin.certificall.app/certificall/api/frames \
  -H "Authorization: Bearer <votre_token>"

Réponse :

[
  {
    "id": 1,
    "name": "Constat sinistre auto",
    "steps": [
      { "id": 10, "title": "Photo du véhicule", "description": "Vue d'ensemble" },
      { "id": 11, "title": "Photo de la plaque", "description": "" },
      { "id": 12, "title": "Photo des dégâts", "description": "Plan rapproché" }
    ]
  }
]

Une seule fois

Les frameId sont stables. Récupérez-les une fois au démarrage de votre intégration, stockez-les côté partenaire, et n'appelez plus cet endpoint à chaque génération.

---

Étape 3 — Côté partenaire : le bouton "Certifier"

Dans votre interface (back-office, espace client, application métier), placez un bouton qui déclenche un appel à votre backend, qui appellera Certificall pour générer le Certilink.

Schéma front (exemple JavaScript)

<button id="btn-certifier" data-dossier="DOSS-2025-001">
  Demander la photo certifiée
</button>

<script>
  document.getElementById('btn-certifier').addEventListener('click', async (e) => {
    const dossierId = e.target.dataset.dossier;

    // ⚠️ Appel à VOTRE backend, pas à Certificall directement
    const res = await fetch('/api/generer-certilink', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ dossierId }),
    });

    const { url } = await res.json();

    // Vous pouvez ensuite : envoyer ce lien par email/SMS,
    // l'afficher dans l'interface, le copier dans le presse-papier, etc.
    navigator.clipboard.writeText(url);
    alert('Lien certifié généré et copié.');
  });
</script>

Côté backend partenaire — appel à /certilink/create

C'est ici que vous injectez le contexte métier (bénéficiaire, références internes, métadonnées) qui :

• sera visible dans l'app pour l'utilisateur final (visibleData),

• vous sera restitué à la clôture dans le champ metadata du dossier (webhook et GET /cases),

• vous permettra de rattacher le dossier reçu à votre enregistrement interne (reportToken).

• Endpoint : POST /certilink/create

• Référence détaillée : Création d'un Certilink

Exemple — pseudo-code Node.js côté partenaire :

// POST /api/generer-certilink (votre route interne)
app.post('/api/generer-certilink', async (req, res) => {
  const { dossierId } = req.body;
  const dossier = await db.getDossier(dossierId);

  const token = await getCertificallToken(); // cf. étape 1, mis en cache

  const response = await fetch('https://admin.certificall.app/certilink/create', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reportToken: dossier.id,                          // votre ref interne
      frameId: 1,                                       // trame "Constat sinistre auto"
      expirationDate: '2026-12-31T23:59:59.000+0100',
      maxUses: 1,                                       // lien à usage unique
      context: {
        visibleData: {
          beneficiary: {
            lastName: dossier.client.nom,
            firstName: dossier.client.prenom,
            email: dossier.client.email,
            address: dossier.client.adresse,
            city: dossier.client.ville,
            postCode: dossier.client.cp,
          },
          issuer: 'Assurance ACME',
          instructions: 'Merci de prendre les 3 photos demandées en bonne lumière.',
          user: `${dossier.client.prenom} ${dossier.client.nom}`,
        },
        metadata: {
          dossierId: dossier.id,
          agence: dossier.agence,
          typeSinistre: 'collision',
        },
      },
    }),
  });

  const { url } = await response.json();
  // url = "https://app.certificall.app?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3"

  res.json({ url });
});

Bonus — visibleData vs metadata

• visibleData → affiché à l'utilisateur dans l'app (nom du bénéficiaire, instructions, etc.) et imprimé dans le PDF.
• metadata → invisible pour l'utilisateur, vous est restituée telle quelle dans le champ metadata du dossier, comme pour un dossier créé par l'API ou par le SDK mobile. Idéal pour transporter des IDs internes, des codes agence, un type de dossier, etc.

Création en masse

Si vous avez besoin de générer plusieurs Certilinks d'un coup (relance d'une cohorte de dossiers, par exemple), utilisez POST /certilink/bulk-create. Voir Création en Masse.

---

Étape 4 — Diffusion du Certilink à l'utilisateur final

Le Certilink est une URL standard : vous êtes libre du canal de diffusion.

Canal	Exemple
Email transactionnel	"Cliquez ici pour finaliser votre dossier : https://app.certificall.app?mt=..."
SMS	"ACME — Pour votre constat, prenez les photos via ce lien : https://app.certificall.app?mt=..."
Lien inline	Bouton dans votre espace client connecté
QR code	Encodage de l'URL pour un parcours en agence / en magasin

Aucun token utilisateur, aucune création de compte : le clic suffit.

---

Étape 5 — Expérience utilisateur final

Au clic sur le Certilink, le parcours est automatique :

1. Détection du device — La page d'atterrissage détecte iOS / Android / Desktop.
2. App déjà installée — Le deeplink ouvre immédiatement l'app Certificall sur la trame ciblée, avec le contexte pré-rempli.
3. App non installée — L'utilisateur est redirigé vers l'App Store / Play Store. Au premier lancement post-installation, le deeplink est rejoué automatiquement.
4. Saisie guidée — L'app affiche les étapes de la trame, avec les instructions et beneficiary visibles ; l'utilisateur exécute chaque étape (photo géolocalisée, signature, champ texte…).
5. Clôture — Quand toutes les étapes sont remplies, le dossier est clôturé et envoyé au backend Certificall.

L'utilisateur final ne s'authentifie pas : la confiance est portée par le Certilink (unique, expirable, limitable en nombre d'usages).

Pour aller plus loin sur les paramètres de deeplink avancés (pré-remplissage spécifique d'étape, reportId partagé entre plusieurs dossiers…), voir reportId et corrélation de certificats.

---

Étape 6 — Réception du dossier sur votre webhook

Dès la clôture du dossier par l'utilisateur final, Certificall vous notifie par un POST sur l'URL de webhook que vous avez fournie.

• Référence détaillée : Webhook après validation d'un certificat

Authentification entrante

Trois modes possibles, choisis à la configuration de l'intégration :

# Bearer
Authorization: Bearer <authToken>
Content-Type: application/json

# HMAC-SHA256
Authorization: HMAC-SHA256 <apiKey>:<signature>
X-Api-Key: <apiKey>
Content-Type: application/json

# En-tête dédié
security-token: <authToken>
Content-Type: application/json

Payload reçu

{
  "cfRef": "CAS-12345_CMP-42",
  "reportId": "DOSS-2025-001",
  "caseUrl": "https://admin.certificall.app/certificall/share/case/<shareToken>",
  "createdAt": "2026-05-13T10:24:15.000+0200",
  "frame": "Constat sinistre auto",
  "closed": true,
  "items": [
    {
      "stepAction": "PHOTOGRAPHY",
      "cfRef": "ITEM-...",
      "createdAt": "2026-05-13T10:22:01.000+0200",
      "title": "Photo du véhicule",
      "geolocLatitude": "48.8566",
      "geolocLongitude": "2.3522",
      "imageUrl": "https://admin.certificall.app/certificall/images/<identifiant>",
      "description": "vehicule_001.jpg"
    },
    {
      "stepAction": "TEXT_FIELD",
      "cfRef": "ITEM-...",
      "createdAt": "2026-05-13T10:23:10.000+0200",
      "title": "Immatriculation",
      "geolocLatitude": "48.8566",
      "geolocLongitude": "2.3522",
      "imageUrl": "",
      "description": "AB-123-CD"
    }
  ],
  "context": {
    "visibleData": {
      "beneficiary": { "lastName": "Dupont", "firstName": "Jean" },
      "issuer": "ACME Assurances"
    },
    "metadata": {
      "dossierId": "DOSS-2025-001",
      "agence": "PAR-09",
      "typeSinistre": "collision"
    }
  }
}

Côté partenaire — traitement minimal

// POST /webhooks/certificall (votre route)
app.post('/webhooks/certificall', verifyCertificallSignature, async (req, res) => {
  const { reportId, caseUrl, context, items } = req.body;

  // 1) Retrouver votre dossier interne via reportId (= votre reportToken)
  const dossier = await db.getDossier(reportId);
  // le dossier porte vos metadata dans son champ `metadata`

  // 2) Stocker l'URL du PDF, télécharger les médias si besoin
  await db.updateDossier(dossier.id, {
    statut: 'certifie',
    pdfUrl: caseUrl,
    certifieAt: new Date(),
  });

  // 3) Récupérer les photos/items (URLs streamables, authentifiées via Bearer)
  for (const item of items) {
    if (item.stepAction === 'PHOTOGRAPHY') {
      await downloadAndStore(item.imageUrl, dossier.id);
    }
  }

  res.status(200).end();
});

Idempotence

Le webhook n'est pas réémis si votre endpoint échoue : répondez vite en 2xx et prévoyez un filet via GET /cases (voir garanties de livraison). Gardez malgré tout un traitement idempotent : identifiez les doublons via cfRef (unique par certificat) avant d'écrire en base.

---

Étape 7 — Récupérer le PDF certifié

Deux possibilités selon votre besoin :

1. caseUrl reçu dans le webhook — URL directe vers le PDF (authentifiée par token Bearer Certificall).
2. Share Token — Si vous voulez exposer le PDF à un tiers sans transmettre votre token, voir Certificat via un Share Token. Le shareToken s'obtient via l'admin Certificall.

---

Récapitulatif des endpoints

Étape	Méthode	Endpoint	Documentation
1. Authentification	POST	/certificall/api/auth/token	/docs/api/token
2. Lister les trames	GET	/certificall/api/frames	/docs/api/create_certificate
3. Créer un Certilink	POST	/certilink/create	/docs/api/certilink
3 bis. Création en masse	POST	/certilink/bulk-create	/docs/api/certilink
6. Webhook entrant	POST	<votre URL>	/docs/api/webhook
7. PDF certifié	GET	/case/:shareToken	/docs/api/share_token

Swagger complet : admin.certificall.app/certificall/public/swagger

---

Check-list de mise en production

• Compte API créé et token testé en sandbox.
• frameId cible identifié et stocké côté partenaire.
• Bouton "Certifier" intégré dans l'interface, appelant votre backend (jamais Certificall directement depuis le navigateur).
• reportToken = identifiant unique et stable de votre dossier (utilisable pour le rapprochement).
• metadata enrichi des IDs internes nécessaires au rattachement.
• URL webhook exposée en HTTPS, authentifiée (Bearer / security-token / HMAC).
• Traitement webhook idempotent (déduplication par cfRef).
• Téléchargement et archivage des médias (imageUrl) côté partenaire si exigence de conservation.
• Gestion des erreurs : alerting sur webhook KO, rattrapage via GET /cases.
• Tests end-to-end : génération → clic → photo → réception webhook.

---

Pour aller plus loin

• Certilink — référence complète (mise à jour, suppression, listing)
• Création de certificats programmée (sans Certilink) — si vous voulez piloter la création d'items côté backend sans passer par l'app mobile
• Gestion des reportId et corrélation multi-dossiers
• Configuration des trames