Référence de l'API REST

Tous les appels avec leurs paramètres, codes de statut et schémas.

Cette page décrit l'interface de manière complète. Si vous configurez l'API pour la première fois, mieux vaut commencer par le guide pas à pas.

L'adresse de base est /api sur votre propre installation, donc https://example.com/api dans les exemples. Tous les appels sont effectués depuis votre serveur, et non depuis le navigateur de vos clients : aucun en-tête CORS n'est envoyé et le token ne doit pas être intégré dans un site web ou une application.

Authentification

Chaque appel nécessite un token. Vous le générez dans l'espace d'administration sous Configuration → API. Le token commence par apm_, suivi de 64 caractères, et n'est affiché qu'une seule fois. Il existe exactement un token par installation : un nouveau token invalide immédiatement le précédent.

Authorization: Bearer apm_ihr-token

Sans token valide, chaque appel répond par 401 {"error":"Unauthorized"}. Si l'API n'est pas activée dans l'espace d'administration, elle répond par 503 API disabled.

GET/schedules

Renvoie tous les calendriers des rendez-vous de l'installation. Vous utilisez les valeurs id renvoyées comme paramètre schedule dans tous les autres appels.

Codes de statut

Statut	Signification
200	Liste des calendriers des rendez-vous
401	Le token est absent ou invalide
429	Limite de requêtes atteinte
503	L'API n'est pas activée ou l'installation n'est pas encore terminée

Réponse 200

{
    "data": [
        { "id": 1, "name": "Hauptstandort" },
        { "id": 2, "name": "Filiale" }
    ]
}

Appel avec curl

curl -H "Authorization: Bearer apm_ihr-token" \
  https://example.com/api/schedules

GET/reasons

Renvoie les motifs de rendez-vous (prestations) d'un calendrier des rendez-vous. Si aucun motif de rendez-vous n'est configuré pour ce calendrier, data est un tableau vide. duration est la durée en secondes.

Paramètres de requête

Nom	Type	Obligatoire	Description	Exemple
`schedule`	integer ≥ 1	Obligatoire	Numéro du calendrier des rendez-vous issu de `GET /schedules`	`1`

Codes de statut

Statut	Signification
200	Liste des motifs de rendez-vous (peut être vide)
401	Le token est absent ou invalide
404	Calendrier des rendez-vous introuvable
429	Limite de requêtes atteinte
503	L'API n'est pas activée ou l'installation n'est pas encore terminée

Réponse 200

{
    "data": [
        {
            "id": 1,
            "name": "Beratungsgespräch",
            "description": "Standardberatung",
            "duration": 1800
        },
        {
            "id": 2,
            "name": "Folgetermin",
            "description": "",
            "duration": 900
        }
    ]
}

Appel avec curl

curl -H "Authorization: Bearer apm_ihr-token" \
  "https://example.com/api/reasons?schedule=1"

GET/days

Renvoie les jours pour lesquels au moins une heure est libre pour ce calendrier des rendez-vous et ce motif de rendez-vous. Le format est AAAA-MM-JJ. Les paramètres du calendrier des rendez-vous déterminent jusqu'où la liste s'étend dans le futur.

Paramètres de requête

Nom	Type	Obligatoire	Description	Exemple
`schedule`	integer ≥ 1	Obligatoire	Numéro du calendrier des rendez-vous	`1`
`reason`	integer ≥ 1	Obligatoire	Numéro du motif de rendez-vous issu de `GET /reasons`	`1`

Codes de statut

Statut	Signification
200	Liste des jours comportant des rendez-vous libres
401	Le token est absent ou invalide
404	Calendrier des rendez-vous ou motif de rendez-vous introuvable
429	Limite de requêtes atteinte
503	L'API n'est pas activée ou l'installation n'est pas encore terminée

Réponse 200

{
    "data": ["2026-05-23", "2026-05-24", "2026-05-26"]
}

Appel avec curl

curl -H "Authorization: Bearer apm_ihr-token" \
  "https://example.com/api/days?schedule=1&reason=1"

GET/slots

Renvoie les heures libres d'un jour. Les heures indiquées sont les heures locales de l'installation, le format est AAAA-MM-JJ HH:MM:SS. S'il n'y a plus rien de libre ce jour-là, data est un tableau vide.

Paramètres de requête

Nom	Type	Obligatoire	Description	Exemple
`schedule`	integer ≥ 1	Obligatoire	Numéro du calendrier des rendez-vous	`1`
`reason`	integer ≥ 1	Obligatoire	Numéro du motif de rendez-vous	`1`
`day`	string	Obligatoire	Jour au format `AAAA-MM-JJ` issu de `GET /days`	`2026-05-23`

Codes de statut

Statut	Signification
200	Liste des heures libres (peut être vide)
401	Le token est absent ou invalide
404	Calendrier des rendez-vous, motif de rendez-vous ou jour introuvable
429	Limite de requêtes atteinte
503	L'API n'est pas activée ou l'installation n'est pas encore terminée

Réponse 200

{
    "data": [
        "2026-05-23 09:00:00",
        "2026-05-23 09:30:00",
        "2026-05-23 10:00:00"
    ]
}

Appel avec curl

curl -H "Authorization: Bearer apm_ihr-token" \
  "https://example.com/api/slots?schedule=1&reason=1&day=2026-05-23"

GET/forms

Renvoie les champs de formulaire qui doivent être remplis pour la réservation de cette heure. Vous utilisez les noms des champs comme clés dans l'objet submission de POST /bookings. Interrogez toujours les champs au lieu de les inscrire en dur dans votre propre programme. Le champ password n'est jamais renvoyé.

Paramètres de requête

Nom	Type	Obligatoire	Description	Exemple
`schedule`	integer ≥ 1	Obligatoire	Numéro du calendrier des rendez-vous	`1`
`reason`	integer ≥ 1	Obligatoire	Numéro du motif de rendez-vous	`1`
`slot`	string	Obligatoire	Heure au format `AAAA-MM-JJ HH:MM:SS`. L'espace doit être encodé par `%20`.	`2026-05-23%2009:00:00`

Codes de statut

Statut	Signification
200	Champs de formulaire, indexés par nom de champ
401	Le token est absent ou invalide
404	Calendrier des rendez-vous, motif de rendez-vous ou heure introuvable
429	Limite de requêtes atteinte
503	L'API n'est pas activée ou l'installation n'est pas encore terminée

Réponse 200

{
    "data": {
        "first_name": {
            "form_type": "textbox",
            "input_type": "text",
            "label": "Vorname",
            "required": true,
            "value": ""
        },
        "last_name": {
            "form_type": "textbox",
            "input_type": "text",
            "label": "Nachname",
            "required": true,
            "value": ""
        },
        "email": {
            "form_type": "textbox",
            "input_type": "email",
            "label": "E-Mail-Adresse",
            "required": false,
            "value": ""
        },
        "phone": {
            "form_type": "textbox",
            "input_type": "tel",
            "label": "Telefonnummer",
            "required": false,
            "value": ""
        }
    }
}

Appel avec curl

curl -H "Authorization: Bearer apm_ihr-token" \
  "https://example.com/api/forms?schedule=1&reason=1&slot=2026-05-23%2009:00:00"

POST/bookings

Crée un rendez-vous. Interrogez d'abord les champs de formulaire via GET /forms et envoyez leurs valeurs dans l'objet submission. L'en-tête doit contenir Content-Type: application/json.

Champs du corps de la requête

Nom	Type	Obligatoire	Description	Exemple
`schedule`	integer ≥ 1	Obligatoire	Numéro du calendrier des rendez-vous	`1`
`reason`	integer ≥ 1	Obligatoire	Numéro du motif de rendez-vous	`1`
`slot`	string	Obligatoire	Heure au format `AAAA-MM-JJ HH:MM:SS`, exactement 19 caractères	`2026-05-23 09:00:00`
`submission`	object	Obligatoire	Valeurs correspondant aux noms de champs issus de `GET /forms`

Corps de la requête

{
    "schedule": 1,
    "reason": 1,
    "slot": "2026-05-23 09:00:00",
    "submission": {
        "first_name": "Hans",
        "last_name": "Pitt",
        "email": "hans.pitt@example.com",
        "phone": "+49 30 1234567"
    }
}

Codes de statut

Statut	Signification
201	Le rendez-vous a été créé
400	Requête invalide, champ obligatoire manquant ou JSON invalide
401	Le token est absent ou invalide
404	Calendrier des rendez-vous, motif de rendez-vous ou heure introuvable
415	`Content-Type: application/json` manquant
429	Limite de requêtes atteinte
500	La fiche client ou le rendez-vous n'a pas pu être enregistré
503	L'API n'est pas activée ou l'installation n'est pas encore terminée

Réponse 201

{
    "booking_id": 142,
    "booking_details_id": "a3f8c2d1e5b6",
    "user_id": 87,
    "slot": "2026-05-23T09:00:00Z"
}

Réponse 400 en cas de champ obligatoire manquant

{
    "error": "Field is required",
    "field": "email"
}

Appel avec curl

curl -X POST https://example.com/api/bookings \
  -H "Authorization: Bearer apm_ihr-token" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": 1,
    "reason": 1,
    "slot": "2026-05-23 09:00:00",
    "submission": {
        "first_name": "Hans",
        "last_name": "Pitt",
        "email": "hans.pitt@example.com"
    }
  }'

Schémas

Les structures de données qui apparaissent dans les réponses.

Schedule

{
    "id": integer,
    "name": string
}

Reason

{
    "id": integer,
    "name": string,
    "description": string,
    "duration": integer   // secondes
}

FormField

{
    "form_type": string,
    "input_type": string,
    "label": string,
    "required": boolean,
    "value": any
}

BookingRequest

{
    "schedule": integer,
    "reason": integer,
    "slot": "AAAA-MM-JJ HH:MM:SS",
    "submission": {
        "<nom_du_champ>": <valeur>
    }
}

BookingResponse

{
    "booking_id": integer,
    "booking_details_id": string,
    "user_id": integer,
    "slot": "2026-05-23T09:00:00Z"   // UTC, ISO 8601
}

Error / BookingError

{
    "error": string,
    "field": string   // optionnel
}

Réponses d'erreur communes

Ces réponses peuvent survenir lors de tous les appels.

Statut	Signification	Explication
401	Unauthorized	Le token est absent, erroné ou a été remplacé par un nouveau. Certains serveurs suppriment l'en-tête `Authorization` ; en cas de doute, demandez à votre hébergeur.
404	Not Found	Le calendrier des rendez-vous, le motif de rendez-vous, le jour ou l'heure demandé n'est pas (ou plus) disponible. Un paramètre manquant ou mal formaté produit lui aussi un 404, et non un 400.
429	Too Many Requests	La limite de 300 requêtes par minute et par token est atteinte. L'en-tête `Retry-After` indique le temps d'attente en secondes.
503	Service Unavailable	L'API n'est pas activée dans l'espace d'administration (`API disabled`) ou l'installation n'est pas encore terminée (`Not configured`). Ces deux cas concernent tous les appels.

Les erreurs sont toujours renvoyées en JSON et ont toujours la même forme :

{ "error": "Description de l'erreur" }

Lors de la réservation, une erreur de validation indique en plus le champ concerné :

{ "error": "Field is required", "field": "email" }

Vous trouverez la liste complète des messages d'erreur par appel dans le guide.

Description lisible par machine

Tous les appels sont en outre décrits dans un fichier OpenAPI conforme à la version 3.1. Vous pouvez ainsi générer des bibliothèques clientes ou charger l'interface dans des outils comme Postman, Insomnia ou Swagger UI.

Afficher openapi.json

Dans le fichier, l'adresse /api est indiquée sous servers. Il s'agit délibérément d'une indication relative, afin que le fichier soit valable sur toute installation. Saisissez donc dans votre outil l'adresse de votre propre agenda, par exemple https://example.com/api. Le même fichier se trouve également dans votre installation sous /api/openapi.json.

Retour au guide ou à la vue d'ensemble : module "API (interface)".

Haut de page