Guide d'Utilisation de l'API Certilink (Magic Link)

Ce guide vous accompagnera dans l'utilisation de l'API Certilink pour créer, récupérer et supprimer des Magic Links. Ces liens permettent à vos utilisateurs d'accéder à des fonctionnalités spécifiques sans nécessiter une authentification préalable.

Prérequis

Avant de commencer, assurez-vous que :

Vous disposez des identifiants d'accès API. Si ce n'est pas le cas, contactez votre administrateur Certificall.
Vous avez obtenu un token d'authentification JWT nécessaire pour interagir avec l'API.

Authentification

Obtenir un Token d'Accès

Pour utiliser l'API Certilink, vous devez d'abord obtenir un token d'authentification JWT.

Endpoint : POST /certificall/api/auth/token
Description : Récupère le token d'identification Certificall à ajouter dans vos requêtes.

Corps de la requête :

{
  "username": "votre_nom_utilisateur",
  "password": "votre_mot_de_passe"
}

Exemple de réponse :

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

Codes de réponse :

200 OK : Token d'accès retourné avec succès
401 Unauthorized : Identifiants incorrects

Important : Conservez ce token de manière sécurisée. Il doit être inclus dans l'en-tête Authorization de toutes vos requêtes API :

Authorization: Bearer <votre_token>

Étapes d'Utilisation de l'API Certilink

1. Récupération des Trames

Pour créer un Certilink, il est nécessaire de récupérer une trame qui détermine la structure du dossier.

Endpoint : GET /certificall/api/frames
Description : Récupère la liste des trames disponibles pour votre entreprise.

Headers requis :

Authorization: Bearer <votre_token>

Exemple de réponse :

[
  {
    "id": 1,
    "name": "Inspection Visuelle",
    "steps": [
      {
        "id": 10,
        "title": "Photo du matériel",
        "description": "Prendre une photo du matériel à inspecter"
      },
      {
        "id": 11,
        "title": "État général",
        "description": "Évaluer l'état général du matériel"
      }
    ]
  },
  {
    "id": 2,
    "name": "Inspection Technique",
    "steps": [
      {
        "id": 20,
        "title": "Vérification électrique",
        "description": "Contrôle des installations électriques"
      }
    ]
  }
]

Pour plus de détails, consultez la documentation Certificall.

2. Création d'un Certilink

Une fois que vous avez la trame, vous pouvez créer un Certilink. Cela permet à vos utilisateurs d'accéder directement à un formulaire ou un dossier sans avoir besoin de s'authentifier.

Endpoint : POST /certilink/create

Headers requis :

Authorization: Bearer <votre_token>

Paramètres requis :

reportToken (String): Un identifiant unique pour le dossier (fourni par vous).
frameId (Number): L'identifiant de la trame que vous souhaitez associer au Magic Link.

Paramètres optionnels :

expirationDate (String): Date d'expiration du Magic Link (format : aaaa-mm-jjThh:mm:ss.sss+hhmm).
maxUses (Number): Nombre maximal d'utilisations autorisées pour ce Magic Link.
companyId (Number): ID de l'entreprise (généralement déduit automatiquement).
context (Object): Contexte du Magic Link avec visibleData et metadata.
- visibleData (Object):
  - beneficiary (Object): Informations sur le bénéficiaire (lastName, firstName, address, city, postCode, email)
  - issuer (String): Nom de l'émetteur
  - photoRef (String): Référence de photo
  - reportRef (String): Référence du rapport
  - instructions (String): Instructions pour l'utilisateur lors de la complétion du dossier
  - user (String): Nom de l'utilisateur à afficher dans le PDF (remplace l'utilisateur Kizeo)
- metadata (Object): Métadonnées personnalisées (paires clé-valeur de type string)

Exemple de requête simple :

{
  "reportToken": "mon-identifiant-de-dossier",
  "frameId": 1
}

Exemple de requête complète :

{
  "reportToken": "mon-identifiant-de-dossier",
  "frameId": 1,
  "expirationDate": "2025-12-31T23:59:59.000+0100",
  "maxUses": 5,
  "context": {
    "visibleData": {
      "beneficiary": {
        "lastName": "Dupont",
        "firstName": "Jean",
        "address": "123 Rue de la Paix",
        "city": "Paris",
        "postCode": "75001",
        "email": "jean.dupont@example.com"
      },
      "issuer": "ACME Company",
      "photoRef": "photo-123-ref",
      "reportRef": "report-456-ref",
      "instructions": "Veuillez noter le numéro d'appartement",
      "user": "Jean Dupont"
    },
    "metadata": {
      "source": "web-portal",
      "version": "1.0",
      "department": "claims"
    }
  }
}

Exemple de réponse :

L'API vous renverra l'URL du Magic Link généré :

{
  "url": "https://app.certificall.app?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3"
}

3. Création en Masse de Certilinks

Si vous avez besoin de créer plusieurs Certilinks en une seule opération, vous pouvez utiliser l'endpoint de création en masse.

Endpoint : POST /certilink/bulk-create
Description : Créer plusieurs magic links en une seule requête.

Headers requis :

Authorization: Bearer <votre_token>

Corps de la requête : Array de certilinks à créer

[
  {
    "reportToken": "dossier-001",
    "frameId": 1,
    "maxUses": 3,
    "expirationDate": "2025-12-31T23:59:59.000+0100"
  },
  {
    "reportToken": "dossier-002",
    "frameId": 1,
    "maxUses": 5,
    "expirationDate": "2025-12-31T23:59:59.000+0100"
  },
  {
    "reportToken": "dossier-003",
    "frameId": 2
  }
]

Exemple de réponse :

{
  "state": "Certilink bulk creation ended",
  "date": "2025-01-14T10:30:00.000+0100",
  "company": 123,
  "success": [
    {
      "reportToken": "dossier-001",
      "url": "https://app.certificall.app?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3"
    },
    {
      "reportToken": "dossier-002",
      "url": "https://app.certificall.app?mt=1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6"
    },
    {
      "reportToken": "dossier-003",
      "url": "https://app.certificall.app?mt=a1b2c3d4-e5f6-7g8h-9i0j-1k2l3m4n5o6p"
    }
  ],
  "error": []
}

4. Récupération des Certilinks

Vous pouvez récupérer la liste des Certilinks créés pour votre entreprise en utilisant l'API. Cela permet d'avoir une vue d'ensemble des Magic Links actifs et d'en assurer le suivi.

Endpoint : POST /certilink/findCompanyMagicLinks

Headers requis :

Authorization: Bearer <votre_token>

Paramètres :

start (Number): Point de départ de la liste (utile pour la pagination).
limit (Number): Nombre de Magic Links à retourner (maximum 100 par requête).

Exemple de requête :

{
  "start": 0,
  "limit": 50
}

Exemple de réponse :

[
  {
    "reportToken": "abc123",
    "url": "https://app.certificall.app?mt=09ca0baf-ce70-47a0-b84e-0b4acb0ecec3",
    "magicLinkToken": "09ca0baf-ce70-47a0-b84e-0b4acb0ecec3",
    "createdAt": "2024-01-01T12:00:00Z",
    "expirationDate": "2024-01-31T12:00:00Z",
    "enabled": true,
    "frame": {
      "id": 1,
      "name": "Inspection Visuelle"
    }
  }
]

5. Mise à Jour d'un Certilink

Si vous souhaitez modifier la date d'expiration ou le contexte d'un Magic Link existant, vous pouvez le faire en appelant l'endpoint suivant :

Endpoint : PATCH /certilink/:magicLinkToken
Paramètre : Le token du Magic Link à mettre à jour (dans l'URL).

Headers requis :

Authorization: Bearer <votre_token>

Corps de la requête :

expirationDate (String, optionnel): Nouvelle date d'expiration (format : aaaa-mm-jjThh:mm:ss.sss+hhmm).
context (Object, optionnel): Nouveau contexte avec visibleData et metadata.

Exemple de requête :

{
  "expirationDate": "2025-12-31T23:59:59.000+0100",
  "context": {
    "visibleData": {
      "beneficiary": {
        "lastName": "Martin",
        "firstName": "Sophie",
        "email": "sophie.martin@example.com"
      },
      "instructions": "Mise à jour des instructions"
    },
    "metadata": {
      "updated": "true",
      "version": "2.0"
    }
  }
}

Exemple de réponse :

{
  "status": "Success",
  "message": "Magic link updated successfully"
}

6. Suppression d'un Certilink

Si vous souhaitez désactiver ou supprimer un Magic Link, vous pouvez le faire en appelant l'endpoint suivant :

Endpoint : DELETE /certilink/:magicLinkToken
Paramètre : Le token du Magic Link à supprimer (dans l'URL).

Headers requis :

Authorization: Bearer <votre_token>

Exemple de réponse :

{
  "status": "Success",
  "message": "Magic link deleted successfully"
}

Sécurité et Permissions

Pour garantir la sécurité de vos opérations, chaque requête à l'API Certilink est soumise à des vérifications d'authentification et de permissions :

Vous devez être authentifié via un token JWT valide.
Seuls les utilisateurs ayant les droits nécessaires peuvent créer ou gérer des Certilinks.
Les Magic Links doivent être associés à une trame valide et à une entreprise autorisée.
Stockez et gérez le token d'authentification de manière sécurisée.
Toutes les interactions avec l'API Certificall doivent être effectuées via HTTPS.

Résumé des Endpoints

Méthode	Endpoint	Description
`POST`	`/certificall/api/auth/token`	Obtenir un token d'authentification
`GET`	`/certificall/api/frames`	Récupérer les trames disponibles
`POST`	`/certilink/create`	Créer un certilink
`POST`	`/certilink/bulk-create`	Créer plusieurs certilinks en masse
`POST`	`/certilink/findCompanyMagicLinks`	Récupérer les certilinks de l'entreprise
`PATCH`	`/certilink/:magicLinkToken`	Mettre à jour un certilink
`DELETE`	`/certilink/:magicLinkToken`	Supprimer un certilink

Prérequis​

Authentification​

Obtenir un Token d'Accès​

Étapes d'Utilisation de l'API Certilink​

1. Récupération des Trames​

2. Création d'un Certilink​

3. Création en Masse de Certilinks​

4. Récupération des Certilinks​

5. Mise à Jour d'un Certilink​

6. Suppression d'un Certilink​

Sécurité et Permissions​

Résumé des Endpoints​

Prérequis

Authentification

Obtenir un Token d'Accès

Étapes d'Utilisation de l'API Certilink

1. Récupération des Trames

2. Création d'un Certilink

3. Création en Masse de Certilinks

4. Récupération des Certilinks

5. Mise à Jour d'un Certilink

6. Suppression d'un Certilink

Sécurité et Permissions

Résumé des Endpoints