Documentation de l'API - Gestion de Rendez-vous

Date de mise à jour : 02 janvier 2025 | Version : 2.0

Base URL : /api/v2

Introduction

Cette API permet de gérer les horaires d'ouverture, les créneaux horaires, leurs capacités, les rendez-vous, et la validation des données pour une application de prise de rendez-vous. Elle introduit une gestion multi-entités via une table tap4Book_entities, chaque entité étant isolée et accessible via un access_token. Les créneaux sont séparés en deux entités : les plages horaires (tap4Book_calendar_slots) et leurs capacités (tap4Book_slot_appointments). Toutes les réponses sont au format JSON.

Authentification

Tous les endpoints nécessitent un access_token fourni dans l'en-tête HTTP Access-Token ou en paramètre GET access_token. Le token est généré via : sha1(sha1(entity_account_id) . entity_secret_key).

Exemple :

GET /api/v2/opening-hours
Header: Access-Token: a1b2c3d4e5f6...

Erreur d'authentification (401) :

{
    "success": false,
    "data": [],
    "message": "Access token requis ou invalide"
}

Endpoints

Description : Récupère les horaires d'ouverture hebdomadaires pour l'entité authentifiée.

Paramètres : Aucun

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": [
        {
            "day_of_week": "mon",
            "start_time1": "09:00:00",
            "end_time1": "12:00:00",
            "start_time2": "14:00:00",
            "end_time2": "18:00:00",
            "is_open": 1
        },
        ...
    ]
}

Réponse (Erreur) :

{
    "success": false,
    "data": [],
    "message": "Erreur serveur: [détail]"
}

Exemple :

GET /api/v2/opening-hours
Header: Access-Token: a1b2c3d4e5f6...

Description : Vérifie si une date est ouverte (horaires et jours fériés).

Paramètres :

Nom	Type	Description	Obligatoire
date	String	YYYY-MM-DD	Oui

En-tête requis : Access-Token

Réponse (Succès - Ouvert) :

{
    "success": true,
    "data": {
        "is_open": true,
        "is_holiday": false,
        "opening_hours": {
            "start_time1": "09:00:00",
            "end_time1": "12:00:00",
            "start_time2": "14:00:00",
            "end_time2": "18:00:00"
        }
    }
}

Réponse (Succès - Férié) :

{
    "success": true,
    "data": {
        "is_open": false,
        "is_holiday": true,
        "holiday": {
            "name": "Pâques",
            "date": "2025-04-20"
        }
    }
}

Réponse (Erreur) :

{
    "success": false,
    "data": [],
    "message": "Date invalide (YYYY-MM-DD)"
}

Exemple :

GET /api/v2/opening-hours/check-date?date=2025-04-20
Header: Access-Token: a1b2c3d4e5f6...

Description : Récupère les horaires d'ouverture pour une date spécifique.

Paramètres :

Nom	Type	Description	Obligatoire
date	String	YYYY-MM-DD	Oui

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": {
        "start_time1": "09:00:00",
        "end_time1": "12:00:00",
        "start_time2": "14:00:00",
        "end_time2": "18:00:00"
    }
}

Réponse (Erreur) :

{
    "success": false,
    "data": [],
    "message": "Ce jour est fermé"
}

Exemple :

GET /api/v2/opening-hours/date?date=2025-03-17
Header: Access-Token: a1b2c3d4e5f6...

Description : Récupère les créneaux disponibles pour une date donnée.

Paramètres :

Nom	Type	Description	Obligatoire
date	String	YYYY-MM-DD	Oui

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": [
        {
            "id": 1,
            "date": "2025-03-17",
            "start_time": "09:00:00",
            "end_time": "09:30:00",
            "status": "open",
            "max_appointments": 6,
            "available_slots": 5
        },
        ...
    ]
}

Réponse (Aucun créneau) :

{
    "success": true,
    "data": [],
    "message": "Aucun créneau disponible"
}

Exemple :

GET /api/v2/calendar-slots?date=2025-03-17
Header: Access-Token: a1b2c3d4e5f6...

Description : Génère des créneaux pour une date donnée selon les horaires d'ouverture.

Paramètres (Body JSON) :

Nom	Type	Description	Obligatoire
date	String	YYYY-MM-DD	Oui
duration	Integer	Durée (min), défaut via settings	Non
max_appointments	Integer	Max RDV, défaut via settings	Non

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": [
        {
            "id": 1,
            "date": "2025-03-17",
            "start_time": "09:00:00",
            "end_time": "09:30:00",
            "status": "open",
            "max_appointments": 6,
            "available_slots": 6
        },
        ...
    ],
    "message": "Créneaux générés avec succès"
}

Réponse (Erreur) :

{
    "success": false,
    "data": [],
    "message": "Erreur lors de la génération"
}

Exemple :

POST /api/v2/calendar-slots/generate
Header: Access-Token: a1b2c3d4e5f6...
{
    "date": "2025-03-17",
    "duration": 30,
    "max_appointments": 6
}

Description : Met à jour un créneau spécifique (statut ou capacités).

Paramètres (Body JSON) :

Nom	Type	Description	Obligatoire
slot_id	Integer	ID du créneau	Oui
status	String	"open" ou "closed"	Non
max_appointments	Integer	Max RDV	Non
available_slots	Integer	Créneaux disponibles	Non
date	String	YYYY-MM-DD (retourne créneaux)	Non

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": [
        {
            "id": 1,
            "date": "2025-03-17",
            "start_time": "09:00:00",
            "end_time": "09:30:00",
            "status": "closed",
            "max_appointments": 6,
            "available_slots": 5
        },
        ...
    ],
    "message": "Créneau mis à jour"
}

Réponse (Erreur) :

{
    "success": false,
    "data": [],
    "message": "Créneau non trouvé"
}

Exemple :

POST /api/v2/calendar-slots/update
Header: Access-Token: a1b2c3d4e5f6...
{
    "slot_id": 1,
    "status": "closed",
    "max_appointments": 8,
    "available_slots": 7,
    "date": "2025-03-17"
}

Description : Supprime un créneau et ses capacités.

Paramètres (Body JSON) :

Nom	Type	Description	Obligatoire
slot_id	Integer	ID du créneau	Oui

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": [],
    "message": "Créneau supprimé"
}

Réponse (Erreur) :

{
    "success": false,
    "data": [],
    "message": "Créneau non trouvé"
}

Exemple :

POST /api/v2/calendar-slots/delete
Header: Access-Token: a1b2c3d4e5f6...
{
    "slot_id": 1
}

Description : Réserve un rendez-vous et met à jour les capacités.

Paramètres (Body JSON) :

Nom	Type	Description	Obligatoire
client_name	String	Nom du client	Oui
client_phone	String	Téléphone	Oui
slot_id	Integer	ID du créneau	Oui
client_email	String	Email	Non
contract_number	String	Numéro contrat	Non

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": {
        "id": 123,
        "client_id": 1,
        "slot_id": 1,
        "status": "confirmed",
        "cancel_token": "a1b2c3d4...",
        "client_name": "Jean Dupont",
        "client_phone": "0612345678",
        "client_email": "jean.dupont@example.com",
        "contract_number": "CT-12345",
        "date": "2025-03-17",
        "start_time": "09:00:00",
        "end_time": "09:30:00",
        "max_appointments": 6,
        "available_slots": 5
    },
    "message": "Rendez-vous réservé"
}

Réponse (Erreur) :

{
    "success": false,
    "data": [],
    "message": "Créneau non disponible"
}

Exemple :

POST /api/v2/appointments
Header: Access-Token: a1b2c3d4e5f6...
{
    "client_name": "Jean Dupont",
    "client_phone": "0612345678",
    "client_email": "jean.dupont@example.com",
    "contract_number": "CT-12345",
    "slot_id": 1
}

Description : Valide un numéro de téléphone.

Paramètres (Body JSON) :

Nom	Type	Description	Obligatoire
phone_number	String	Numéro	Oui
validation_type	String	"all" ou "mobiles" (défaut: "all")	Non

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": {
        "valid": true,
        "formatted": "06 12 34 56 78",
        "e164": "+33612345678",
        "is_mobile": true
    }
}

Réponse (Erreur) :

{
    "success": false,
    "data": {
        "valid": false,
        "message": "Numéro mobile requis (06/07)"
    }
}

Exemple :

POST /api/v2/validation/phone
Header: Access-Token: a1b2c3d4e5f6...
{
    "phone_number": "0612345678",
    "validation_type": "mobiles"
}

Description : Valide une adresse email.

Paramètres (Body JSON) :

Nom	Type	Description	Obligatoire
email	String	Adresse email	Oui
validation_type	String	"all" ou "nofreeemail" (défaut: "all")	Non

En-tête requis : Access-Token

Réponse (Succès) :

{
    "success": true,
    "data": {
        "valid": true
    }
}

Réponse (Erreur) :

{
    "success": false,
    "data": {
        "valid": false,
        "message": "Emails gratuits non autorisés"
    }
}

Exemple :

POST /api/v2/validation/email
Header: Access-Token: a1b2c3d4e5f6...
{
    "email": "jean.dupont@gmail.com",
    "validation_type": "nofreeemail"
}

Notes

Réponses avec success (booléen) pour le statut.
Codes HTTP : 401 (authentification), 400 (paramètres), 500 (serveur), 404 (inconnu).
Créneaux dans tap4Book_calendar_slots et capacités dans tap4Book_slot_appointments.
Données isolées par entité via access_token.
Compatible avec calendarFinal.js.
Paramètres par défaut configurables via tap4Book_settings.

Outil génération de Token

Générer votre Token

Contact

Pour toute question, contactez le développeur via le canal utilisé pour cette documentation.

Documentation de l'API - Gestion de Rendez-vous

Introduction

Authentification

Endpoints

GET /opening-hours

GET /opening-hours/check-date

GET /opening-hours/date

GET /calendar-slots

POST /calendar-slots/generate

POST /calendar-slots/update

POST /calendar-slots/delete

POST /appointments

POST /validation/phone

POST /validation/email

Notes

Outil génération de Token

Contact