Aller au contenu principal

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. Le token peut être récupéré via l'endpoint /certificall/api/auth/token.

1. Récupération de la Trame

Pour créer un Certilink, il est nécessaire de récupérer une trame qui détermine la structure du dossier. Vous pouvez le faire en utilisant l'endpoint suivant :

  • Endpoint : /certificall/api/frames
  • Consultez la documentation Certificall pour plus de détails sur la récupération des trames disponibles.

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
  • Paramètres : Lors de la création d'un Certilink, vous devez fournir les informations suivantes :
    • reportToken : un identifiant unique pour le dossier (fourni par vous).
    • frameId : l'identifiant de la trame que vous souhaitez associer au Magic Link.
  • 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"
    }

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

  • Paramètres :

    • start : le point de départ de la liste (utile pour la pagination).
    • limit : le nombre de Magic Links à retourner (jusqu'à 100 par requête).
  • Exemple de réponse :

    [
    {
    "reportToken": "abc123",
    "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"
    }
    }
    ]

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.

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.