# L'API de Cards

{% hint style="info" %}
L'API public de Cards ainsi que les webhooks sont actuellement en BETA. Pensez à nous donner votre avis !
{% endhint %}

Cards peut-être intégré dans vos propres outils, grace à notre API public ainsi que nos webhooks.

L'identification auprès de l'API se fait grace à une clé privée et votre identifiant de tenant.

La clé peut-être générée depuis votre espace Cards. Attention, cette clé doit impérativement rester privée !


# Créer une clé

La génération de clé se fait dans l'interface de Cards.

{% hint style="danger" %}
Vous devez être propriétaire de votre abonnement pour avoir accès à ces informations.
{% endhint %}

Utilisez le menu supérieur droit, et allez dans "Intégration". Vous arrivez alors sur la page qui liste vos clés API.

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FkxjMdmlK9COfXudnyJkW%2Fscreen-api-keys.jpg?alt=media&amp;token=0a1128a5-2741-4a49-90e1-f030f7a62cbb" alt=""><figcaption><p>Page de gestion de vos clés API</p></figcaption></figure>

Vous pouvez créer une nouvelle clé, et choisir si celle-ci a une date d'expiration.

Vous avez la possibilité de choisir le "scope" de vote clé, c'est-à-dire de définir ses droits (quelles actions peuvent être effectuées avec).

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2Fw29eHEhZOiM2ecBmnuuf%2Fapi-create-key.jpg?alt=media&amp;token=9ea2f7a2-2f79-4550-a668-5ae05e3dec7f" alt="" width="500"><figcaption><p>Écran de création de clé API</p></figcaption></figure>

Quand la clé est créée, elle s'affiche dans une fenêtre. Notez la bien, car il n'est plus possible de la revoir ensuite.


# Fonctionnement

Des url embed uniques peuvent être générées avec l'API.

Cela vous permet d'afficher des formations pour vos utilisateurs identifiés, et donc de suivre leur progression dans Cards.

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FsZNhlkBx915l0xrmZQZ5%2Ffonctionnement-embed.jpg?alt=media&amp;token=d159bfa7-0d1f-47f6-865c-1adc3a373e1c" alt=""><figcaption><p>Parcours de création d'une url embed</p></figcaption></figure>


# Générer une url

Pour générer une url embed, vous devez faire un POST en passant bien votre clé d'API en `Bearer Token`.

Pensez aussi à bien ajouter votre ID tenant dans le header `X-Tenant`.

## Générer une url embed

<mark style="color:green;">`POST`</mark> `https://api.cards-microlearning.com/v1/embeds`

#### Headers

| Name                                       | Valeur                                   |
| ------------------------------------------ | ---------------------------------------- |
| Content-Type                               | `application/json`                       |
| Authorization                              | `Bearer <token API>`                     |
| X-Tenant<mark style="color:red;">\*</mark> | `‹Identifiant de votre espace (Tenant)>` |

#### Request Body

| Name                                    | Type    | Description                                                                          |
| --------------------------------------- | ------- | ------------------------------------------------------------------------------------ |
| type<mark style="color:red;">\*</mark>  | String  | <p>Type d'url à générer. Peut-être :<br>- training<br>- trainings</p>                |
| training\_id                            | Uuid    | L'ID de la formation a afficher (requis si le "type" est "training").                |
| email<mark style="color:red;">\*</mark> | Email   | L'adresse mail de l'apprenant pour qui afficher la ou les formations.                |
| once                                    | Boolean | Pour dire si l'url est à usage unique. (Default true)                                |
| expires\_at                             | Date    | <p>Date d'expiration de l'url embed.</p><p>Format : yyyy-mm-dd (ex : 2024-09-25)</p> |

{% tabs %}
{% tab title="200: OK Retourne une réponse en JSON contenant l'url." %}

```json
{
    "message": "Embed link created",
    "url": "https://embed.cards-microlearning.com/xxxxxxxxxx"
}
```

{% endtab %}

{% tab title="400: Bad Request Retourne les infos dans un JSON" %}
Exemples si un champ est mal renseigné :

```json
{
  "message": "The training id field is required when type is training.",
  "errors": {
    "training_id": [
      "The training id field is required when type is training."
    ]
  }
}
```

Exemple si l'apprenant n'existe pas :

```json
{
  "message": "User doesn't exist"
}
```

{% endtab %}
{% endtabs %}


# Fonctionnement

Les webhooks vous permettent d'écouter des évènements de Cards, et d'apliquer des modifications dans vos applications en conséquence.

### Écouter des évènements

La configuration de vos endpoints se fait dans l'interface de Cards.

{% hint style="danger" %}
Vous devez être propriétaire de votre abonnement pour avoir accès à ces informations.
{% endhint %}

Utilisez le menu supérieur droit, et allez dans "Intégration". Rendez-vous ensuite dans l'onglet "Webhooks".

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FADA1797uJZVTm0kUgPTk%2Fscreen-webhooks.jpg?alt=media&amp;token=f203251b-dbe8-461a-b19b-6cca8ccb593d" alt=""><figcaption><p>Liste de vos endpoints</p></figcaption></figure>

Ici vous pouvez créer un ou plusieurs endpoints.

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FGTGcUTpBN94bnVPiPkLJ%2Fscreen-create-webhook.jpg?alt=media&amp;token=97bf5d68-97f4-4214-9401-d70129094996" alt=""><figcaption><p>Création d'un endpoint</p></figcaption></figure>

Voilà la liste des champs que vous pouvez renseigner :

* Activer le webhook : pour décider si le endpoint est actiff ou non
* Endpoint (url) : URL où l'évènement sera envoyé
* Description : Non obligatoire, vous permet de vous y retrouver si vous avez plusieurs endpoints
* Évènements : le ou les évènements que vous souhaitez écouter.

Quand vous enregistrez le endpoint, une clé secrète est générée. Cette clé sera utilisée pour signer l'envoi de l'évènement, vous permettant de votre côté de confirmer que la requête provient bien de Cards.

### Liste des évènements disponibles sur Cards

<table><thead><tr><th width="246">Event slug</th><th>Description</th></tr></thead><tbody><tr><td><code>chapter-complete</code></td><td>Quand l'apprenant complète un chapitre</td></tr><tr><td><code>quiz-complete</code></td><td>Quand l'apprenant répond à un quiz</td></tr><tr><td><code>survey-complete</code></td><td>Quand l'apprenant répond à un sondage</td></tr><tr><td><code>training-complete</code></td><td>Quand l'apprenant termine une formation</td></tr><tr><td><code>routine-complete</code></td><td>Quand l'apprenant termine une Learning Routine©</td></tr><tr><td><code>user-created</code></td><td>Quand un compte utilisateur est créé</td></tr><tr><td><code>user-updated</code></td><td>Quand un compte utilisateur est mis à jour</td></tr><tr><td><code>user-deleted</code></td><td>Quand un compte utilisateur est supprimé</td></tr><tr><td><code>user-group-added</code></td><td>Quand un utilisateur est ajouté à un groupe</td></tr><tr><td><code>user-group-removed</code></td><td>Quand un utilisateur est retiré d'un groupe</td></tr><tr><td><code>group-created</code></td><td>Quand un groupe est créé</td></tr><tr><td><code>group-updated</code></td><td>Quand un groupe est mis à jour</td></tr><tr><td><code>group-deleted</code></td><td>Quand un groupe est supprimé</td></tr><tr><td><code>badge-created</code></td><td>Quand un badge est créé</td></tr><tr><td><code>badge-updated</code></td><td>Quand un badge est mis à jour</td></tr><tr><td><code>badge-deleted</code></td><td>Quand un badge est supprimé</td></tr><tr><td><code>badge-unlocked</code></td><td>Quand un badge est débloqué par un utilisateur</td></tr><tr><td><code>certificate-created</code></td><td>Quand un certificat est créé</td></tr><tr><td><code>certificate-udpated</code></td><td>Quand un certificat est mis à jour</td></tr><tr><td><code>certificate-deleted</code></td><td>Quand un certificat est supprimé</td></tr><tr><td><code>certificate-unlocked</code></td><td>Quand un certificat est débloqué par un utilisateur</td></tr></tbody></table>

### Envoi des évènements

Quand un évènement s'exécute sur Cards, l'information est envoyée à vos endpoints (configurés sur l'évènement en question).

L'envoi contient toujours un corps de message, et un en-tête :

* Le corps du message contient toutes les informations liées à l'évènement. [Voir le détails sur la page "Détails des évènements".](/webhooks/details-des-evenements)
* L'en-tête comprend la signature, envoyé dans la variable : `Cards-Signature`

Lorsque l'application à laquelle nous envoyons le webhook ne parvient pas à envoyer une réponse avec un code d'état 2xx, Cards considérera l'appel comme ayant échoué. L'appel sera également considéré comme ayant échoué si l'application distante ne répond pas dans les 3 secondes.

Sur votre app retour une erreur, Cards renverra l'évènement jusqu'à 3 fois.

{% hint style="info" %}
L'envoi de l'évènement n'est pas immédiat. Il peut y avoir un délai de quelques secondes, lié au traitement en fil d'attente des évènements.

Les 2 dates sont présentes dans la requête : la date de l'action de l'apprenant et la date de l'envoi de l'évènement.
{% endhint %}

### Logs des évènements

Des logs sont disponibles dans l'interface de Cards. Ils affichent pour chaque évènement envoyé, les informations de requête et réponse.

Ces logs vous permettent de voir si des erreurs sont survenues dans votre application. Ils sont disponibles pour chaque endpoint.

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FgIyfKwCDZ2xjJ2IGoOkM%2Fscreen-logs.jpg?alt=media&amp;token=13f703f8-e0be-48a7-a8e4-9d91a31db742" alt=""><figcaption></figcaption></figure>


# Détails des évènements

Retrouvez ici la liste des évènements ainsi que les informations envoyées selon le type d'évènement.

### `chapter-complete`

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "chapter-complete",
    "created_at": "2024-01-20 09:10:00", // date de l'envoi au webhook
    "data": {
        "created_at": "2024-01-20 09:09:00", // date de l'action par le user
        "points": 1, // nb de points obtenus par le user sur l'action
        "user": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        },
        "training": {
            "id": "xxxx",
            "title": "Titre de ma formation",
            "description": "Description de ma formation",
            "image": "https://api.cards-microlearning.com/xxxx",
            "chapters_count": 5, // nb de chapitres dans la formation
            "chapter": {
                "id": "xxxx"
                "title": "Titre de mon chapitre",
                "position": 1 // position du chapitre dans la formation
            }
        },
        "score": {
            "points": 1,
            "max_points": 1,
            "progress": 0.2
        }
    }
}
```

### `quiz-complete`

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "quiz-complete",
    "created_at": "2024-01-20 09:10:00", // date de l'envoi au webhook
    "data": {
        "created_at": "2024-01-20 09:09:00", // date de l'action par le user
        "points": 1, // nb de points obtenus par le user sur l'action
        "user": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        },
        "training": {
            "id": "xxxx",
            "title": "Titre de ma formation",
            "description": "Description de ma formation",
            "image": "https://api.cards-microlearning.com/xxxx",
            "chapters_count": 5, // nb de chapitres dans la formation
            "chapter": {
                "id": "xxxx"
                "title": "Titre de mon chapitre",
                "position": 1, // position du chapitre dans la formation
                "card": {
                    "id": "xxxx",
                    "type": "quiz", // (quiz ou quiz-order)
                    "content": "Question du quiz",
                    "answers": [ // réponses possibles au quiz et réponses de l'apprenant
                        {
                            "id": "xxxx",
                            "content": "Réponse A", 
                            "position": 1,
                            "is_correct": 1,
                            "points": 2,
                            "selected": true
                        },
                        {
                            "id": "xxxx",
                            "content": "Réponse B",
                            "position": 2,
                            "is_correct": 1,
                            "points": 2,
                            "selected": true
                        },
                        {
                            "id": "xxxx",
                            "content": "Réponse C",
                            "position": 3,
                            "is_correct": 0,
                            "points": -1,
                            "selected": false
                        }
                    ]
                }
            }
        },
        "score": {
            "points": 4,
            "max_points": 4,
            "progress": 0.2
        }
    }
}
```

### `survey-complete`

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "survey-complete",
    "created_at": "2024-01-20 09:10:00", // date de l'envoi au webhook
    "data": {
        "created_at": "2024-01-20 09:09:00", // date de l'action par le user
        "points": 1, // nb de points obtenus par le user sur l'action
        "user": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        },
        "training": {
            "id": "xxxx",
            "title": "Titre de ma formation",
            "description": "Description de ma formation",
            "image": "https://api.cards-microlearning.com/xxxx",
            "chapters_count": 5, // nb de chapitres dans la formation
            "chapter": {
                "id": "xxxx"
                "title": "Titre de mon chapitre",
                "position": 1, // position du chapitre dans la formation
                "card": {
                    "id": "xxxx",
                    "type": "survey",
                    "content": "Question du sondage",
                    "answers": [ // réponses possibles au sondage et réponses de l'apprenant
                        {
                            "id": "xxxx",
                            "content": "Réponse A", 
                            "position": 1,
                            "is_correct": 1,
                            "points": 0,
                            "selected": true
                        },
                        {
                            "id": "xxxx",
                            "content": "Réponse B",
                            "position": 2,
                            "is_correct": 1,
                            "points": 0,
                            "selected": true
                        },
                        {
                            "id": "xxxx",
                            "content": "Réponse C",
                            "position": 3,
                            "is_correct": 1,
                            "points": 0,
                            "selected": false
                        }
                    ]
                }
            }
        },
        "score": {
            "points": 0,
            "max_points": 0,
            "progress": 0.2
        }
    }
}
```

### `training-complete`

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "training-complete",
    "created_at": "2024-01-20 09:10:00", // date de l'envoi au webhook
    "data": {
        "created_at": "2024-01-20 09:09:00", // date de l'action par le user
        "points": 1, // nb de points obtenus par le user sur l'action
        "user": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        },
        "training": {
            "id": "xxxx",
            "title": "Titre de ma formation",
            "description": "Description de ma formation",
            "image": "https://api.cards-microlearning.com/xxxx",
            "chapters_count": 5 // nb de chapitres dans la formation
        },
        "score": {
            "points": 6,
            "max_points": 6,
            "progress": 1
        }
    }
}
```

### routine-complete

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "routine-complete",
    "created_at": "2024-01-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "created_at": "2024-01-21 09:09:00", // date de l'action par le user
        "user": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        },
        "routine": {
            "id": "xxxx",
            "title": "Titre de la routine",
            "description": "Description de la routine",
            "type": "progress", // type de routine
            "date_start": null, // si date de début définie
            "date_end": null, // si date de fin définie
            "steps_count": 5 // nb d'étapes
        },
        "score": {
            "points": 10,
            "max_points": 10,
            "progress": 1
        }
    }
}
```

### user-created & user-deleted

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "user-created", // ou "user-deleted"
    "created_at": "2024-01-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "user": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        }
    }
}
```

### user-updated

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "user-updated",
    "created_at": "2024-01-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "user_before": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "phone": "0000",
            "lang": "fr"
        },
        "user_after": {
            "id": "xxxx",
            "firstname": "Johnny",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "Y",
            "phone": "0000",
            "lang": "fr"
        }
    }
}
```

### user-group-added & user-group-removed

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "user-group-added", // ou "user-group-removed"
    "created_at": "2024-01-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "user": { // user added or removed from group
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        },
        "group": { // group where user was added or removed
            "id": "xxxx",
            "name": "group's name"
        }
    }
}
```

### group-created & group-deleted

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "group-created", // ou "group-deleted"
    "created_at": "2024-01-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "group": {
            "id": "xxxx",
            "name": "group's name"
        }
    }
}
```

### group-updated

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "group-updated",
    "created_at": "2024-01-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "group_before": {
            "id": "xxxx",
            "name": "group's name"
        },
        "group_after": {
            "id": "xxxx",
            "name": "new group's name"
        }
    }
}
```

### badge-created & badge-deleted

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "badge-created", // ou "badge-deleted"
    "created_at": "2024-10-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "badge": {
            "id": "xxxx",
            "name": "badge's name",
            "description": "xxxx",
            "imageurl": "https://api.cards-microlearning.com/...",
            "emoji": [],
            "status": "publish" // ou 'draft' / 'expire'
        }
    }
}
```

### badge-updated

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "badge-updated",
    "created_at": "2024-10-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "badge_before": {
            "id": "xxxx",
            "name": "badge's name",
            "description": "xxxx",
            "imageurl": "https://api.cards-microlearning.com/...",
            "emoji": [],
            "status": "draft" // ou 'publish' / 'expire'
        },
        "badge_after": {
            "id": "xxxx",
            "name": "badge's name",
            "description": "xxxx",
            "imageurl": null,
            "emoji": {
                "n": [
                    0: "thinking face",
                    1: "thinking_face"
                ],
                "u": "1f914",
                "r": "1f914",
                "t": "neutral",
                "i": "🤔",             
           },
           "status": "publish" // ou 'draft' / 'expire'
        },
    }
}
```

### badge-unlocked

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "badge-unlocked",
    "created_at": "2024-10-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "badge": {
            "id": "xxxx",
            "name": "badge's name",
            "description": "xxxx",
            "imageurl": "https://api.cards-microlearning.com/...",
            "emoji": []
        },
        "user": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        }        
    }
}
```

### certificate-created & certificate-deleted

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "certificate-created", // ou "certificate-deleted"
    "created_at": "2024-10-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "badge": {
            "id": "xxxx",
            "name": "certificate's name",
            "description": "xxxx",
            "content": "xxxx",
            "status": "publish" // ou 'draft' / 'expire'
        }
    }
}
```

### certificate-updated

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "certificate-updated",
    "created_at": "2024-10-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "certificate_before": {
            "id": "xxxx",
            "name": "certificate's name",
            "description": "xxxx",
            "content": "xxxx",
            "status": "draft" // ou 'publish' / 'expire'
        },
        "certificate_after": {
            "id": "xxxx",
            "name": "certificate's name",
            "description": "xxxx",
            "content": "xxxx",
            "status": "publish" // ou 'draft' / 'expire'
        },
    }
}
```

### certificate-unlocked

```json
{
    "id": "xxxx" // id unique de l'event
    "type": "certificate-unlocked",
    "created_at": "2024-10-21 09:10:00", // date de l'envoi au webhook
    "data": {
        "certificate": {
            "id": "xxxx",
            "name": "certificate's name",
            "description": "xxxx",
            "content": "xxxx"
        },
        "user": {
            "id": "xxxx",
            "firstname": "John",
            "lastname": "Doe",
            "email": "john.doe@example.com",
            "company": "X",
            "lang": "fr"
        }        
    }
}
```


# Signature des requêtes

Toutes les requêtes envoyées sur vos endpoint sont signées à l'aide de la clé secrète liée au endpoint.

Côté Cards, la signature est créée à l'aide du payload, encrypté avec votre clé :

```php
$payloadJson = json_encode($payload); 
$signature = hash_hmac('sha256', $payloadJson, $secret_endpoint_key);
```

Cette signature est présente dans l'en-tête de la requête, dans la variable `Cards-Signature`.

Voilà un exemple de code PHP pour récupérer la requête et la vérifier :&#x20;

```php
// secret key of the webhook endpoint
$endpoint_secret = 'xxxx';

// get payload
$payload = @file_get_contents('php://input');

// get signature
$signature_header = '';
$headers = apache_request_headers();
if (isset($headers['Cards-Signature']) and !empty($headers['Cards-Signature'])) {
    $signature_header = $headers['Cards-Signature'];
}

// verify signature
$buildHash = hash_hmac('sha256', $payload, $secret_endpoint_key);
if ($buildHash !== $signature_header) {
    // key is incorrect
    http_response_code(400);
    exit();
}

// get payload data
$event_type = false;
if (isset($payload) and !empty($payload)) {
    $payload = json_decode($payload);
    $event_type = $payload->type;
}

// handle the request
if ($event_type == 'survey-complete') {
    // a survey has been complete
} elseif ($event_type == 'quiz-complete') {
    // a quiz has been complete
} elseif ($event_type == 'chapter-complete') {
    // a chapter has been complete
} elseif ($event_type == 'training-complete') {
    // a training has been complete
}
```


# Exemple d'utilisation : Zapier

Nous allons ici voir comment utiliser les webhooks de Cards avec Zapier, pour déclencher des évènements personnalisés sur des outils externes.

### Que souhaitons nous faire ?

Pour notre exemple, nous allons faire en sorte qu'un email soit envoyé à chaque fois qu'un apprenant termine une formation.

Nous allons pouvoir personnaliser le mail pour faire remonter automatiquement des informations et données dans l'email.

### Configuration côté Zapier

La 1ère étape consiste à créer un "zap" sur Zapier. En démarrant par un "zap" vierge, vous pouvez alors choisir un "trigger", c'est-à-dire un évènement déclencheur.

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FPOg075ZcL6oCkWN3knL4%2F02-trigger.png?alt=media&amp;token=da678cf8-053b-4afe-8ee7-79264030080f" alt=""><figcaption></figcaption></figure>

Cliquez sur "Trigger" : il faut alors chercher "Webhook" dans la fenêtre qui s'affiche et sélectionner "Webhooks by Zapier".

Vous pouvez maintenant configurer votre point d'entrée :

* onglet "App & event" : choisir l'event "Catch Hook"
* onglet "Trigger" : laisser vide, pour que Zapier reçoive toutes les données arrivant de Cards
* onglet "Test" : Zapier vous affiche l'url webhook. Copiez cette url, il faut aller la configurer dans Cards.

### Configurer le webhook côté Cards

Pour aller configurer le webhook sur Cards, utiliser le menu "mon compte" en haut à droite, puis cliquez sur "Intégrations".

{% hint style="info" %}
Il faut que vous soyez propriétaire de l'espace sur Cards pour avoir accès à ce menu et à la configuration des webhooks.
{% endhint %}

Ensuite, allez sur la page "Webhooks", puis créez un nouveau webhook.

Dans le champ "endpoint", renseignez l'url fournie par Zapier. Et pour les évènements, sélectionnez l'évènement "training-complete".

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FzkHP21RBp9J50AvT99AM%2Fscreen-wreate-webhook.jpg?alt=media&amp;token=0bd86608-27d6-4219-9e0f-5480dc4c3876" alt=""><figcaption><p>Création du webhook côté Cards</p></figcaption></figure>

Renseignez une description si vous le souhaitez, puis cliquez sur "Enregistrer".

### Tester la connexion avec Zapier

L'étape suivante consiste à valider que la connexion fonctionne bien entre Cards et Zapier.

Dans Zapier, vous verrez que votre onglet "Test" a un bouton "Test trigger". Si vous cliquez dessus, rien ne va se passer : c'est normal, il faut qu'un évènement "training-complete" soit d'abord envoyé pour que Zapier le reçoive !

Et donc : direction Cards, côté apprenant, pour compléter une formation jusqu'au bout.

Une fois la formation terminée, retournez dans Zapier, et cliquez à nouveau sur le bouton "Test trigger". Cette fois vous devriez voir des informations remonter !

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FewajehtnmY9WSW9lZwTS%2F03-event-received.png?alt=media&amp;token=bc836786-4891-4714-9df4-f84b8969b5a5" alt=""><figcaption></figcaption></figure>

Vous pouvez cliquer sur "Continue with selected record" :)

### Choisir l'action à déclencher

On peut maintenant configurer l'action à effectuer quand Zapier reçoit notre évènement.

Nous allons ici choisir d'envoyer un mail via Gmail. Choisissez donc "Gmail" dans la liste des applications. Puis sélectionnez l'event "Send email" :

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2Fe6asOiB2b8Qo2OU00Qvp%2F04-send-email.png?alt=media&amp;token=7708ccca-4837-416e-83f2-9296f4e7002c" alt=""><figcaption></figcaption></figure>

L'étape d'après vous permet de connecter votre compte Gmail, pour que les emails envoyés partent de votre adresse mail.

Une fois connecté, vous pouvez configurer l'action, avec notamment les champs les plus importants :

* to : pour décider à qui envoyer l'email
* from : depuis quelle adresse envoyer l'email
* subject : le sujet de votre email
* body : le contenu de votre email

Et c'est là que ça devient intéressant ! En effet, Cards vous envoi le détails des évènements avec de nombreuses informations. Vous pouvez notamment récupérer le prénom, le nom, le score de l'apprenants. Mais aussi le titre de la formation ou sa description.

Avec Zapier, vous pouvez utiliser ces valeurs pour personnaliser l'email.

Voici un exemple de configuration pour le contenu :&#x20;

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2F2tT6mhgIy3ruXpEv9xk3%2F05-body-email.png?alt=media&amp;token=d903657a-e647-4fa3-aa2b-599d9b5a313b" alt=""><figcaption><p>Personnalisation du contenu du mail avec Zapier</p></figcaption></figure>

Pour connaître toutes les infos envoyées par les évènements, rendez-vous sur la page "[Détails des évènements](/webhooks/details-des-evenements)".

### Activer le zap

Quand tout est configuré sur Zapier, vous pouvez tester un envoi, puis activer le "zap".

Et voilà !

Vous recevrez maintenant un email à chaque fois que l'un de vos apprenant termine une formation.

À vous de jouer pour personnaliser vos automatisations !

<figure><img src="https://3297553377-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRPJjEUNK75oXc065bfj7%2Fuploads%2FMjISbRY4hwUquRLWTdjY%2Fex-mail.jpg?alt=media&amp;token=bee4cd34-b86a-41e5-8f19-dad076fc03f9" alt=""><figcaption><p>Exemple de mail reçu</p></figcaption></figure>


# Badges

Ce endpoint est dédié aux badges de Cards.

## Listing des badges

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/badges`

Récupération d'une liste de badges.&#x20;

Cette liste peut être filtrée et est paginée.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="124">Type</th><th width="315">Description</th><th width="166">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr><tr><td><code>filters</code></td><td>Tableau Json</td><td><p>Permet de filtrer sur des paramètre du badge comme : </p><ul><li>status</li><li>option_teasing</li><li>notif</li></ul><p>Chaque entrée dans le tableau correspond à un filtre "AND".<br>Chaque entrée doit avoir 2 clés : </p><ul><li>type</li><li>values</li></ul><p>La clé "values" peut être une chaine ou un tableau de valeurs (filtre "OR").<br>Format :<br>[</p><p>    {<br>        "type": "status",<br>        "values": ["draft","publish","expire"]<br>    }, </p><p>    {<br>        "type": "option_teasing",<br>        "values": 0<br>    },   <br>    {<br>        "type": "notif",<br>        "values": 1<br>    }<br>]<br></p></td><td></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "image": "url",
      "emoji": {
        "i": "emoji",
        "n": [
          "string",
        ],
        "r": "string",
        "t": "string",
        "u": "string"
      },
      "created_at": "datetime",
      "updated_at": "datetime"
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/badges?page=1",
    "last": "https://api.cards-microlearning.com/v1/badges?page=5",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/badges?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/badges?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/badges?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/badges?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/badges?page=5",
        "label": "Next &raquo;",
        "active": false
      }      
    ],
    "path": "https://api.cards-microlearning.com/v1/badges",
    "per_page": int,
    "to": int,
    "total": int
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}
{% endtabs %}

## Récupérer un badge par son identifiant

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/badges/<id_badge>`

Récupérer les informations d'un seul badge.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "image": "url",
    "emoji": {
      "i": "emoji",
      "n": [
        "string",
      ],
      "r": "string",
      "t": "string",
      "u": "string"
    },
    "created_at": "datetime",
    "updated_at": "datetime"
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "Badge doesn't exist",
  "type": "badge"
}
```

{% endtab %}
{% endtabs %}

## Listing des utilisateurs ayant débloqué ce badge

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/badges/<id_badge>/users`

Récupération d'une liste d'utilisateurs ayant débloqué un badge (via son identifiant).&#x20;

Cette liste est paginée.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="124">Type</th><th width="281">Description</th><th width="187">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": [
    {
      "id": "string",
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "role": "string",
      "company": "string",
      "phone": "string",
      "source": "string",
      "enable_ranking": bool,
      "lang": "string",
      "info_win": {
        "en": "string",
        "fr": "string"
      }
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/badges/<id_badge>/users?page=1",
    "last": "https://api.cards-microlearning.com/v1/badges/<id_badge>/users?page=5",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/badges/<id_badge>/users?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/badges/<id_badge>/users?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/badges/<id_badge>/users?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/badges/<id_badge>/users?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/badges/<id_badge>/users?page=5",
        "label": "Next &raquo;",
        "active": false
      }      
    ],
    "path": "https://api.cards-microlearning.com/v1/badges/<id_badge>/users",
    "per_page": int,
    "to": int,
    "total": int
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "Badge doesn't exist",
  "type": "badge"
}
```

{% endtab %}
{% endtabs %}


# Certificates

Ce endpoint est dédié aux certificats de Cards.

## Listing des certificats

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/certificates`

Récupération d'une liste de certificats.&#x20;

Cette liste peut être filtrée et est paginée.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="124">Type</th><th width="315">Description</th><th width="166">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr><tr><td><code>filters</code></td><td>Tableau Json</td><td><p>Permet de filtrer sur des paramètre du certificat comme : </p><ul><li>status</li><li>option_teasing</li><li>notif</li></ul><p>Chaque entrée dans le tableau correspond à un filtre "AND".<br>Chaque entrée doit avoir 2 clés : </p><ul><li>type</li><li>values</li></ul><p>La clé "values" peut être une chaine ou un tableau de valeurs (filtre "OR").<br>Format :<br>[</p><p>    {<br>        "type": "status",<br>        "values": ["draft","publish","expire"]<br>    }, </p><p>    {<br>        "type": "option_teasing",<br>        "values": 0<br>    },   <br>    {<br>        "type": "notif",<br>        "values": 1<br>    }<br>]<br></p></td><td></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "content": "string",
      "created_at": "datetime",
      "updated_at": "datetime"
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/certificates?page=1",
    "last": "https://api.cards-microlearning.com/v1/certificates?page=5",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/certificates?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/certificates?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/certificates?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/certificates?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/certificates?page=5",
        "label": "Next &raquo;",
        "active": false
      }      
    ],
    "path": "https://api.cards-microlearning.com/v1/certificates",
    "per_page": int,
    "to": int,
    "total": int
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}
{% endtabs %}

## Récupérer un certificat par son identifiant

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/certificates/<id_certificate>`

Récupérer les informations d'un seul certificat.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": {
    "id": "string",
    "name": "string",
    "description": "string",
    "content": "string",
    "created_at": "datetime",
    "updated_at": "datetime"
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "Certificate doesn't exist",
  "type": "certificate"
}
```

{% endtab %}
{% endtabs %}

## Listing des utilisateurs ayant obtenu ce certificat

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users`

Récupération d'une liste d'utilisateurs ayant obtenu un certificat (via son identifiant).&#x20;

Cette liste est paginée.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="124">Type</th><th width="281">Description</th><th width="187">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": [
    {
      "id": "string",
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "role": "string",
      "company": "string",
      "phone": "string",
      "source": "string",
      "enable_ranking": bool,
      "lang": "string",
      "info_win": {
        "en": "string",
        "fr": "string"
      }
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users?page=1",
    "last": "https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users?page=5",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users?page=5",
        "label": "Next &raquo;",
        "active": false
      }      
    ],
    "path": "https://api.cards-microlearning.com/v1/certificates/<id_certificate>/users",
    "per_page": int,
    "to": int,
    "total": int
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "Certificate doesn't exist",
  "type": "certificate"
}
```

{% endtab %}
{% endtabs %}


# Groups

Ce endpoint est dédié aux groupes de Cards.

## Listing des groupes

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/groups`

Récupération d'une liste de groupes.&#x20;

Cette liste peut être filtrée et est paginée.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="124">Type</th><th width="300">Description</th><th width="166">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr><tr><td><code>filters</code></td><td>Tableau Json</td><td><p>Permet de filtrer sur des paramètre du groupe comme : </p><ul><li>is_public</li><li>enable_ranking</li></ul><p>Chaque entrée dans le tableau correspond à un filtre "AND".<br>Chaque entrée doit avoir 2 clés : </p><ul><li>type</li><li>values</li></ul><p>La clé "values" peut être une chaine ou un tableau de valeurs (filtre "OR").<br>Format :<br>[</p><p>    {<br>        "type": "enable_ranking",<br>        "values": 0<br>    },   <br>    {<br>        "type": "is_public",<br>        "values": 1<br>    }<br>]<br></p></td><td></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": [
    {
      "id": "string",
      "name": "string"
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/groups?page=1",
    "last": "https://api.cards-microlearning.com/v1/groups?page=5",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/groups?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/groups?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/groups?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/groups?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/groups?page=5",
        "label": "Next &raquo;",
        "active": false
      }      
    ],
    "path": "https://api.cards-microlearning.com/v1/groups",
    "per_page": int,
    "to": int,
    "total": int
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}
{% endtabs %}


# Trainings

Ce endpoint est dédié aux formations de Cards.

## Listing des formation

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/trainings`

Récupération d'une liste de formation.&#x20;

Cette liste peut être filtrée et est paginée.

**Entête (Headers)**

| Nom           | Valeur                                   |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token API>`                     |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="137">Type</th><th width="289">Description</th><th width="166">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr><tr><td><code>filters</code></td><td>Tableau Json</td><td><p>Permet de filtrer sur des champs de la formation, comme : </p><ul><li>groups_id</li><li>groups_name</li><li>is_public</li><li>is_rating</li><li>status</li></ul><p>Chaque entrée dans le tableau correspond à un filtre "AND".<br>Chaque entrée doit avoir 2 clés : </p><ul><li>type</li><li>values</li></ul><p>La clé "values" peut être une chaine ou un tableau de valeurs (filtre "OR").<br>Format :<br>[<br>    {<br>        "type": "groups_name",<br>        "values":"RPS"<br>    },    </p><p>    {<br>        "type": "groups_name",<br>        "values":["vol","sin"]<br>    },     </p><p>    {<br>        "type": "groups_id",<br>        "values":"9c445054-c2f0-46c4-b784-ae6ea4c3ebbe"<br>    }<br>]<br></p></td><td></td></tr></tbody></table>

**Réponse**

{% tabs %}
{% tab title="200" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "data": [
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "status": "string",
      "image": "string",
      "public_url": "string",
      "category": "string",
      "groups": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "date_start": "datetime",
      "date_end": "datetime",
      "created_at": "datetime",
      "updated_at": "datetime"
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/trainings?page=1",
    "last": "https://api.cards-microlearning.com/v1/trainings?page=7",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/trainings?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&#x26;laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/trainings?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/trainings?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/trainings?page=6",
        "label": "6",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/trainings?page=7",
        "label": "Next &#x26;raquo;",
        "active": false
      }
    ],
    "path": "https://api.cards-microlearning.com/v1/trainings",
    "per_page": int,
    "to": int,
    "total": int
  }
}
</code></pre>

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}
{% endtabs %}

## Récupérer une formation par son identifiant

<mark style="color:green;">GET</mark> `/trainings/<id_training>`

Récupérer les information d'une seule formation.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Réponse**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": {
    {
      "id": "string",
      "title": "string",
      "description": "string",
      "status": "string",
      "image": "string",
      "public_url": "string",
      "category": "string",
      "groups": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "date_start": "datetime",
      "date_end": "datetime",
      "created_at": "datetime",
      "updated_at": "datetime"
    }
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "Training doesn't exist",
  "type": "trainings"
}
```

{% endtab %}
{% endtabs %}


# Users

Ce endpoint est dédié aux utilisateurs de Cards.

## Listing des utilisateurs

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/users`

Récupération d'une liste d'utilisateurs.&#x20;

Cette liste peut être filtrée et est paginée.

**Entête (Headers)**

| Nom           | Valeur                                   |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token API>`                     |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="137">Type</th><th width="289">Description</th><th width="166">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr><tr><td><code>filters</code></td><td>Tableau Json</td><td><p>Permet de filtrer sur un rôle, identifiant ou nom du groupe.<br>Chaque entrée dans le tableau correspond à un filtre "AND".<br>Chaque entrée doit avoir 2 clés : </p><ul><li>type</li><li>values</li></ul><p>La clé "values" peut être une chaine ou un tableau de valeurs (filtre "OR").<br>Format :<br>[</p><p>    {<br>        "type": "role",<br>        "values":"users"<br>    },   <br>    {<br>        "type": "groups_name",<br>        "values":"RPS"<br>    },    </p><p>    {<br>        "type": "groups_name",<br>        "values":["vol","sin"]<br>    },     </p><p>    {<br>        "type": "groups_id",<br>        "values":"9c445054-c2f0-46c4-b784-ae6ea4c3ebbe"<br>    }<br>]<br></p></td><td></td></tr></tbody></table>

**Réponse**

{% tabs %}
{% tab title="200" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "data": [
    {
      "id": "string",
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "role": "string",
      "company": "string",
      "phone": "string",
      "source": "string",
      "enable_ranking": boolean,
      "lang": "string",
      "groups": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/users?page=1",
    "last": "https://api.cards-microlearning.com/v1/users?page=52",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/users?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&#x26;laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users?page=51",
        "label": "51",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users?page=52",
        "label": "52",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users?page=2",
        "label": "Next &#x26;raquo;",
        "active": false
      }
    ],
    "path": "https://api.cards-microlearning.com/v1/users",
    "per_page": int,
    "to": int,
    "total": int
  }
}
</code></pre>

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}
{% endtabs %}

## Récupérer un utilisateur par son identifiant

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/users/<id_utilisateur>`

Récupérer les information d'un seul utilisateur

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Réponse**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": {
    {
      "id": "string",
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "role": "string",
      "company": "string",
      "phone": "string",
      "source": "string",
      "enable_ranking": boolean,
      "lang": "string",
      "groups": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "User doesn't exist",
  "type": "user"
}
```

{% endtab %}
{% endtabs %}

## Création d'un nouvel utilisateur

`POST` `https://api.cards-microlearning.com/v1/users`

Créer un nouvel utilisateur sur Cards

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Body**

{% tabs %}
{% tab title="Text/JSON" %}

```json
{
  "firstname": "string",
  "lastname": "string",
  "email": "string",
  "lang": "string",
  "source": "string",
  "phone":"string",
  "company": "string",
  "role": "string", 
  "enable_ranking": boolean,
  "groups": [
    {
      "id":"string",
      "name": "string"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

Les champs obligatoires sont :&#x20;

* firstname&#x20;
* lastname&#x20;
* email

Les contraintes appliquées aux valeurs sont :

* firstname : longueur 190 charactères
* lastname : longueur 190 charactères
* company: firstname : longueur 190 charactères
* lang : fr | en
* source : app | sso | GoogleOAuth | MicrosoftOAuth | AppleOAuth
* role : user | editor | owner
* enable\_ranking : 0 ou 1 (false ou true)
* groups : Tableau de valeurs composé d'un ID et/ou d'un nom. Si l'ID est précisé, il est prioritaire sur le nom. Si le groupe n'existe pas et qu'un nom est donnée, le groupe sera créé automatiquement. Sinon le groupe sera ignoré.

Si tout se passe bien, l'objet de l'utilisateur créé sera renvoyé

**Réponse**

{% tabs %}
{% tab title="201" %}

```json
{
  "data": {
    {
      "id": "string",
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "role": "string",
      "company": "string",
      "phone": "string",
      "source": "string",
      "enable_ranking": boolean,
      "lang": "string",
      "groups": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}

{% tab title="422" %}

```json
{
  "message": "The firstname field is required. (and 2 more errors)",
  "errors": {
    "firstname": [
      "The firstname field is required."
    ],
    "lastname": [
      "The lastname field is required."
    ],
    "email": [
      "The email field is required."
    ]
  }
}
```

{% endtab %}
{% endtabs %}

## Mise à jour d'un utilisateur

<mark style="color:orange;">`PUT`</mark> `https://api.cards-microlearning.com/v1/users/<id_utilisateur>`

Mettre à jour les champs de son choix pour un utilisateur.\
Un champ non ajouté au BODY sera ignoré.\
Un champ vide en revanche supprimera la valeur du champ en question.\
Par exemple, si le champ "groups" est omis, les groupes actuelles seront gardés.\
Si "groups" est ajouté mais vide, tous les groupes pour cet utilisateurs seront retirés.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Body**

{% tabs %}
{% tab title="Text/JSON" %}

```json
{
  "firstname": "string",
  "lastname": "string",
  "lang": "string",
  "source": "string",
  "phone":"string",
  "company": "string",
  "role": "string", 
  "enable_ranking": boolean,
  "groups": [
    {
      "id":"string",
      "name": "string"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

**Aucun champs n'est obligatoire.**

Les contraintes appliquées aux valeurs sont :

* firstname : longueur 190 charactères
* lastname : longueur 190 charactères
* company: firstname : longueur 190 charactères
* lang : fr | en
* source : app | sso | GoogleOAuth | MicrosoftOAuth | AppleOAuth
* role : user | editor | owner
* enable\_ranking : 0 ou 1 (false ou true)
* groups : Tableau de valeurs composé d'un ID et/ou d'un nom. Si l'ID est précisé, il est prioritaire sur le nom. Si le groupe n'existe pas et qu'un nom est donnée, le groupe sera créé automatiquement. Sinon le groupe sera ignoré.

Si tout se passe bien, l'objet de l'utilisateur créé sera renvoyé

**Réponse**

{% tabs %}
{% tab title="201" %}

```json
{
  "data": {
    {
      "id": "string",
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "role": "string",
      "company": "string",
      "phone": "string",
      "source": "string",
      "enable_ranking": boolean,
      "lang": "string",
      "groups": [
        {
          "id": "string",
          "name": "string"
        }
      ]
    }
  }
}
```

{% endtab %}

{% tab title="401" %}

```json
{
  "message": "Unauthenticated."
}
```

{% endtab %}

{% tab title="403" %}

```json
{
  "message": "Incorrect domain"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "User doesn't exist",
  "type": "update"
}
```

{% endtab %}

{% tab title="422" %}

```json
{
  "message": "The selected source is invalid.",
  "errors": {
    "source": [
      "The selected source is invalid."
    ]
  }
}
```

{% endtab %}
{% endtabs %}

## Suppression d'un utilisateur

<mark style="color:red;">`DELETE`</mark> `https://api.cards-microlearning.com/v1/users/<id_utilisateur>`

Supprimer toutes les données d'un utilisateur (profile et parcours de formation).

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "message": "User has been removed"
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "User doesn't exist",
  "type": "remove"
}
```

{% endtab %}
{% endtabs %}

## Listing des badges d'un utilisateur

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/users/<id_user>/badges`

Récupération d'une liste de badges débloqués pour un utilisateur.&#x20;

Cette liste peut être filtrée et est paginée.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="124">Type</th><th width="315">Description</th><th width="166">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr><tr><td><code>filters</code></td><td>Tableau Json</td><td><p>Permet de filtrer sur des paramètre du badge comme : </p><ul><li>option_teasing</li><li>notif</li></ul><p>Chaque entrée dans le tableau correspond à un filtre "AND".<br>Chaque entrée doit avoir 2 clés : </p><ul><li>type</li><li>values</li></ul><p>La clé "values" peut être une chaine ou un tableau de valeurs (filtre "OR").<br>Format :<br>[</p><p>    {<br>        "type": "option_teasing",<br>        "values": 0<br>    },   <br>    {<br>        "type": "notif",<br>        "values": 1<br>    }<br>]<br></p></td><td></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "image": "url",
      "emoji": {
        "i": "emoji",
        "n": [
          "string",
        ],
        "r": "string",
        "t": "string",
        "u": "string"
      },
      "info_win": : {
        "en": "string",
        "fr": "string"
      },
      "created_at": "datetime",
      "updated_at": "datetime"
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/users/<id_user>/badges?page=1",
    "last": "https://api.cards-microlearning.com/v1/users/<id_user>/badges?page=5",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/users/<id_user>/badges?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users/<id_user>/badges?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users/<id_user>/badges?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users/<id_user>/badges?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users/<id_user>/badges?page=5",
        "label": "Next &raquo;",
        "active": false
      }      
    ],
    "path": "https://api.cards-microlearning.com/v1/users/<id_user>/badges",
    "per_page": int,
    "to": int,
    "total": int
  }
}
```

{% endtab %}

{% tab title="404" %}

```json
{
  "message": "User doesn't exist"
}
```

{% endtab %}
{% endtabs %}

## Listing des certificats d'un utilisateur

<mark style="color:green;">GET</mark> `https://api.cards-microlearning.com/v1/users/<id_user>/certificates`

Récupération d'une liste de certificats débloqués pour un utilisateur.&#x20;

Cette liste peut être filtrée et est paginée.

**Entête (Headers)**

| Name          | Value                                    |
| ------------- | ---------------------------------------- |
| Content-Type  | `application/json`                       |
| Authorization | `Bearer <token>`                         |
| X-Tenant      | `<Identifiant de votre espace (Tenant)>` |

**Paramètre de l'url**

<table><thead><tr><th width="155">Nom</th><th width="124">Type</th><th width="315">Description</th><th width="166">Valeurs</th></tr></thead><tbody><tr><td><code>paginate</code></td><td>Nombre entier</td><td>Nombre d'élément dans la liste par page</td><td>Défaut : 100<br>Max : 500</td></tr><tr><td><code>filters</code></td><td>Tableau Json</td><td><p>Permet de filtrer sur des paramètre du certificat comme : </p><ul><li>option_teasing</li><li>notif</li></ul><p>Chaque entrée dans le tableau correspond à un filtre "AND".<br>Chaque entrée doit avoir 2 clés : </p><ul><li>type</li><li>values</li></ul><p>La clé "values" peut être une chaine ou un tableau de valeurs (filtre "OR").<br>Format :<br>[</p><p>    {<br>        "type": "option_teasing",<br>        "values": 0<br>    },   <br>    {<br>        "type": "notif",<br>        "values": 1<br>    }<br>]<br></p></td><td></td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "data": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "content": "string",
      "info_win": : {
        "en": "string",
        "fr": "string"
      },
      "created_at": "datetime",
      "updated_at": "datetime"
    },
    {
      (...)
    }
  ],
  "links": {
    "first": "https://api.cards-microlearning.com/v1/users/<id_user>/certificates?page=1",
    "last": "https://api.cards-microlearning.com/v1/users/<id_user>/certificates?page=5",
    "prev": null,
    "next": "https://api.cards-microlearning.com/v1/users/<id_user>/certificates?page=2"
  },
  "meta": {
    "current_page": int,
    "from": int,
    "last_page": int,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users/<id_user>/certificates?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users/<id_user>/certificates?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "...",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users/<id_user>/certificates?page=4",
        "label": "4",
        "active": false
      },
      {
        "url": "https://api.cards-microlearning.com/v1/users/<id_user>/certificates?page=5",
        "label": "Next &raquo;",
        "active": false
      }      
    ],
    "path": "https://api.cards-microlearning.com/v1/users/<id_user>/certificates",
    "per_page": int,
    "to": int,
    "total": int
  }
}
```

{% endtab %}

{% tab title="404" %}

```
{
  "message": "User doesn't exist"
}
```

{% endtab %}
{% endtabs %}