Documentation

Introduction

Ceci est une documentation concernant toutes les APIs REST publiques disponibles sur Teachizy.

URL racine de l'API REST

https://api.teachizy.fr/api/v1

Authentification sur l'API REST

L'authentification passe par une clé d'API générée sur votre compte app.teachizy.fr

Le header HTTP de chaque requête doit contenir la clé suivante :

Authorization: Bearer <token>

INFO

Toutes les dates sont renvoyées au format UTC.

Endpoints

Voici la liste des enpoints disponibles

Lister les formations

Requête

GET /externals/automations/trainings

Exemple de réponse

{
  "data": [
    {
      "uuid": "xxxx-xxxx-xxxx-xxxx",
      "name": "nom d'une formation",
      "created_at": "2021-01-01 20:00:00"
    }
  ]
}

Lister les leçons

INFO

Les leçons de type chapitre ont des sous leçons dans une clé children.
Il n'y a qu'un niveau de children.

Requête

GET /externals/automations/trainings/{uuid}/items

Paramètres

• uuid : C'est l'UUID de la formation

Champs

• type : une des valeurs GENERIC, SECTION, QUIZ ou TASKS

Exemple de réponse

{
  "data": [
    {
      "id": "xx",
      "order": 1,
      "name": "nom d'une leçon",
      "type": "GENERIC"
    },
    {
      "id": "xx",
      "order": 2,
      "name": "nom d'un chapitre",
      "type": "SECTION",
      "children": [
        {
          "id": "xx",
          "order": 1,
          "name": "nom d'une sous leçon",
          "type": "GENERIC"
        }
      ]
    }
  ]
}

Infos du Store

Requête

GET /externals/automations/store

Champs

• logo : URL du logo, ou null
• favicon : URL du favicon, ou null

Exemple de réponse

{
    "data": {
        "uuid": "xx-xx-xx-xx-xx",
        "name": "Nom de l'espace de formation",
        "description": "desc",
        "logo": "https://api.teachizy.fr/storage/xxx/xxx/xxx.png",
        "favicon": "https://api.teachizy.fr/storage/xxx/xxx/xxx.png",
        "created_at": "2021-01-01 20:00:00"
    }
}

Inviter un apprenant

Requête

POST /externals/automations/customers

{
  "firstname": "un prénom",
  "lastname": "un nom",
  "email": "un email",
  "training_uuids": ["uuid", "uuid", ... ]
}

Réponses

Tout s'est bien passé
HTTP 200

Erreur de validation
HTTP 422

Bloquer un apprenant

Requête

POST /externals/blocked-customers

{
  "email": "email de l'apprenant",
  "training_uuids": ["uuid", "uuid", ... ]
}

Réponses

Tout s'est bien passé
HTTP 200

Erreur de validation
HTTP 422

Débloquer un apprenant

Requête

POST /externals/unblocked-customers

{
  "email": "email de l'apprenant",
  "training_uuids": ["uuid", "uuid", ... ]
}

Réponses

Tout s'est bien passé
HTTP 200

Erreur de validation
HTTP 422

Récupérer un apprenant par email

Renvoie le profil complet d'un apprenant et la liste de ses formations (avec inscription, progression, expiration).

Requête

GET /externals/automations/customers?email={email}

Paramètres (query)

• email (requis) : email de l'apprenant

Champs

• custom_fields (apprenant et formation) : objet clé/valeur s'il contient des champs, sinon un tableau vide []
• started_at : null si non commencée
• completed_at : null si non terminée
• last_activity_at : null si aucune activité
• expiration : null si pas de durée d'accès
• blocked_at : null si non bloqué
• total_duration_in_sec : temps passé total, en secondes
• training_items_count : nombre de leçons
• training_items_completed_count : nombre de leçons terminées
• progression_percent : progression en %
• quiz_total_percent : score quiz en %, -1 si pas de quiz

Exemple de réponse

{
  "data": {
    "uuid": "xxxx-xxxx-xxxx-xxxx",
    "email": "apprenant@example.com",
    "firstname": "Prénom",
    "lastname": "Nom",
    "created_at": "2024-12-22 11:21:42",
    "last_login_at": "2026-04-17 12:00:00",
    "custom_fields": {
      "matricule": "ABC123",
      "autoriser_le_partage_d_info": "true"
    },
    "trainings": [
      {
        "training": {
          "uuid": "xxxx-xxxx-xxxx-xxxx",
          "name": "nom de la formation",
          "created_at": "2021-01-01 20:00:00"
        },
        "enrolled_at": "2025-01-01 20:00:00",
        "started_at": "2025-01-02 10:00:00",
        "completed_at": null,
        "last_activity_at": "2026-04-17 12:00:13",
        "expiration": null,
        "blocked_at": null,
        "custom_fields": {
          "champ_formation": "valeur"
        },
        "total_duration_in_sec": 12,
        "training_items_count": 9,
        "training_items_completed_count": 3,
        "progression_percent": 33.33,
        "quiz_total_percent": 100
      }
    ]
  }
}

Réponses

Apprenant trouvé
HTTP 200

Email manquant ou mal formé
HTTP 422

Apprenant introuvable dans ce store
HTTP 404

Exporter les apprenants (liste filtrée et paginée)

Renvoie la liste paginée des apprenants du store. Le payload de chaque apprenant est identique à l'endpoint ci-dessus (profil + formations).

Requête

GET /externals/automations/customers/export

Paramètres (query, tous optionnels)

Paramètre	Type	Effet
training_uuid	uuid	Limite aux apprenants inscrits à cette formation
status	ACTIVE ou DISABLED	Statut du compte apprenant
begin	date YYYY-MM-DD	Date min de création de l'apprenant (incluse)
end	date YYYY-MM-DD	Date max de création de l'apprenant (incluse)
page	int ≥ 1	Numéro de page (défaut 1)
per_page	int ≥ 1	Taille de page (défaut 500, max 1000)

INFO

Pour recevoir une erreur de validation au format JSON (HTTP 422) plutôt qu'une redirection, le header Accept: application/json doit être présent.

Exemple de réponse

{
  "data": [
    {
      "uuid": "xxxx-xxxx-xxxx-xxxx",
      "email": "apprenant@example.com",
      "firstname": "Prénom",
      "lastname": "Nom",
      "created_at": "2024-12-22 11:21:42",
      "last_login_at": "2026-04-17 12:00:00",
      "custom_fields": {
        "matricule": "ABC123"
      },
      "trainings": [
        {
          "training": {
            "uuid": "xxxx-xxxx-xxxx-xxxx",
            "name": "nom de la formation",
            "created_at": "2021-01-01 20:00:00"
          },
          "enrolled_at": "2025-01-01 20:00:00",
          "started_at": null,
          "completed_at": null,
          "last_activity_at": null,
          "expiration": null,
          "blocked_at": null,
          "custom_fields": [],
          "total_duration_in_sec": 0,
          "training_items_count": 9,
          "training_items_completed_count": 0,
          "progression_percent": 0,
          "quiz_total_percent": -1
        }
      ]
    }
  ],
  "links": {
    "first": "https://api.teachizy.fr/api/v1/externals/automations/customers/export?page=1",
    "last": "https://api.teachizy.fr/api/v1/externals/automations/customers/export?page=12",
    "prev": null,
    "next": "https://api.teachizy.fr/api/v1/externals/automations/customers/export?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 500,
    "last_page": 12,
    "per_page": 500,
    "total": 5723,
    "path": "https://api.teachizy.fr/api/v1/externals/automations/customers/export"
  }
}

Réponses

Liste retournée (peut être vide)
HTTP 200

Filtre invalide (uuid mal formé, status hors valeurs, date hors format)
HTTP 422