TAP4BOOK API - Documentation Complète

Introduction à l'API

L'API TAP4BOOK permet d'accèder à plusieurs méthodes afin d'optimiser la gestion de vos rendez-vous de façon programmatique. Cette API requiert une activation de la part du service client.

URL de base : https://[DOMAINE]/api/

Authentification sécurisée

L'API reponse sur sun système de token et activation préalable.

Multi-format

Support JSON, XML et CSV

Mode Debug

Données fictives pour tests sans authentification

URL de base

L'URL du widget suit cette structure standardisée :

https://[DOMAINE]/api/

Environnements disponibles

Environnement	Domaine	Usage
Staging (test)	`staging-api.tap4book.com`	Tests et développement
Production	`api.tap4book.com`	Environnement de production

Attention

Les environnements de staging et de production sont distincts. Les clés API sur staging-app.tap4book.com ne fonctionneront pas nécessairement sur app.tap4book.com et vice versa.

Assurez-vous d'utiliser le bon domaine et le bon jeu de clés pour chaque environnement.

Formats de sortie

L'API supporte trois formats de sortie. Le format peut être spécifié via le paramètre format ou l'en-tête Accept.

Nouveau : JSON est maintenant le format par défaut pour tous les navigateurs et clients API.

Réponses standardisées : Toutes les réponses réussies retournent HTTP 200 avec error_code: "SUCCESS" pour une intégration simplifiée.

JSON (défaut)

GET /api/calendars
Accept: application/json

XML

GET /api/calendars?format=xml
Accept: application/xml

CSV

GET /api/calendars?format=csv
Accept: text/csv

Exemple de réponse JSON

{
    "success": true,
    "data": [
        {
            "calendar_id": 1,
            "calendar_name": "Cabinet Principal",
            "widgetID": "widget_123_abc",
            "is_active": true,
            "created_at": "2024-01-15T09:00:00+01:00",
            "total_appointments": 125,
            "total_slots": 450
        }
    ],
    "message": "Calendars retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Authentification

L'API utilise une authentification par token HMAC-SHA256 identique à la v1.

Méthode 1 : Via header (recommandé)

curl -H "Access-Token: votre_token_hmac" \
     https://[DOMAINE]/api/calendars

Méthode 2 : Via paramètre de requête

curl "https://[DOMAINE]/api/calendars?access_token=votre_token_hmac"

Important : Le token HMAC est généré avec votre entity_account_id et entity_secret_key. Ne partagez jamais votre clé secrète. Si vous pensez que votre clé sécrète est corrompue n'hésitez pas à la révoquer et à en générer une nouvelle via la console client.

Mode Debug

Le mode debug permet de tester l'API avec des données fictives sans authentification.

Activation

# Via paramètre
GET /api/calendars?debug=true

# Via header
X-Debug: true

Données fictives générées

5 calendriers avec statistiques
50 clients fictifs avec historique
Créneaux sur 30 jours

Rendez-vous avec statuts variés
Statistiques calculées en temps réel
Métriques de performance

Exemple de réponse complète en mode debug

{
    "success": true,
    "data": [
        {
            "calendar_id": 1,
            "calendar_name": "Cabinet Principal",
            "widgetID": "widget_123_abc",
            "is_active": true,
            "created_at": "2024-01-15T09:00:00+01:00",
            "total_appointments": 125,
            "total_slots": 450
        },
        {
            "calendar_id": 2,
            "calendar_name": "Cabinet Secondaire",
            "widgetID": "widget_456_def",
            "is_active": true,
            "created_at": "2024-02-20T10:00:00+01:00",
            "total_appointments": 89,
            "total_slots": 320
        }
    ],
    "message": "Calendars retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json",
    "debug": {
        "memory_usage": 2097152,
        "execution_time": 0.0456,
        "query_count": 0,
        "request_method": "GET",
        "endpoint": "/api/calendars",
        "debug_mode": true
    }
}

Endpoints d'information

GET

/api/

Retourne les informations générales de l'API et la liste des endpoints disponibles.

Réponse

{
    "success": true,
    "data": {
        "name": "TAP4BOOK API",
        "version": "1.0",
        "status": "operational",
        "debug_mode": false,
        "supported_formats": ["json", "xml", "csv"],
        "endpoints": {
            "calendars": "/api/calendars",
            "slots": "/api/slots",
            "appointments": "/api/appointments",
            "statistics": "/api/statistics",
            "clients": "/api/clients"
        }
    },
    "message": "API information retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/health

Vérifie l'état de santé de l'API et la connexion à la base de données.

Réponse

{
    "success": true,
    "data": {
        "status": "healthy",
        "timestamp": 1717769400,
        "version": "1.0",
        "debug_mode": false,
        "database": "connected"
    },
    "message": "Health check successful",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Endpoints Calendriers

GET

/api/calendars

Récupère la liste de tous les calendriers avec leurs statistiques.

Réponse complète

{
    "success": true,
    "data": [
        {
            "calendar_id": 1,
            "calendar_name": "Cabinet Principal",
            "widgetID": "widget_123_abc",
            "is_active": true,
            "created_at": "2024-01-15T09:00:00+01:00",
            "total_appointments": 125,
            "total_slots": 450
        },
        {
            "calendar_id": 2,
            "calendar_name": "Cabinet Secondaire", 
            "widgetID": "widget_456_def",
            "is_active": true,
            "created_at": "2024-02-20T10:00:00+01:00",
            "total_appointments": 89,
            "total_slots": 320
        }
    ],
    "message": "Calendars retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/calendars/{id}

Récupère les détails d'un calendrier spécifique avec statistiques détaillées.

Paramètre	Type	Description
`id`	integer	ID du calendrier

Exemple : `GET /api/calendars/1`

{
    "success": true,
    "data": {
        "calendar_id": 1,
        "calendar_name": "Cabinet Principal",
        "widgetID": "widget_123_abc",
        "is_active": true,
        "created_at": "2024-01-15T09:00:00+01:00",
        "updated_at": "2025-06-01T14:30:00+01:00",
        "total_appointments": 125,
        "total_slots": 450
    },
    "message": "Calendar retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Endpoints Créneaux

GET

/api/slots

Récupère les créneaux disponibles pour un calendrier et une période.

Paramètre	Type	Requis	Description
`calendar_id`	integer	Oui	ID du calendrier
`date_from`	string	Oui	Date de début (YYYY-MM-DD)
`date_to`	string	Non	Date de fin (défaut: date_from)

Exemple : `GET /api/slots?calendar_id=1&date_from=2025-06-15&date_to=2025-06-20`

{
    "success": true,
    "data": [
        {
            "slot_id": 123,
            "calendar_id": 1,
            "date": "2025-06-15",
            "start_time": "09:00:00",
            "end_time": "09:30:00",
            "capacity": 1,
            "is_available": true,
            "booked_appointments": 0,
            "created_at": "2025-05-01T10:00:00+01:00"
        },
        {
            "slot_id": 124,
            "calendar_id": 1,
            "date": "2025-06-15",
            "start_time": "09:30:00",
            "end_time": "10:00:00",
            "capacity": 1,
            "is_available": true,
            "booked_appointments": 0,
            "created_at": "2025-05-01T10:00:00+01:00"
        }
    ],
    "message": "Available slots retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/slots/{id}

Récupère les détails d'un créneau spécifique avec informations sur le calendrier.

Réponse détaillée

{
    "success": true,
    "data": {
        "slot_id": 123,
        "calendar_id": 1,
        "date": "2025-06-15",
        "start_time": "09:00:00",
        "end_time": "09:30:00",
        "capacity": 1,
        "is_available": true,
        "booked_appointments": 0,
        "created_at": "2025-05-01T10:00:00+01:00",
        "updated_at": "2025-05-01T10:00:00+01:00",
        "calendar_name": "Cabinet Principal"
    },
    "message": "Slot retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Endpoints Rendez-vous

GET

/api/appointments

Récupère la liste des rendez-vous avec filtrage et pagination avancés.

Paramètre	Type	Défaut	Description
`page`	integer	1	Numéro de page
`per_page`	integer	50	Résultats par page (max: 1000)
`calendar_id`	integer	-	Filtrer par calendrier
`status`	string	-	confirmed, pending, cancelled, completed
`date_from`	string	-	Date de début (YYYY-MM-DD)
`date_to`	string	-	Date de fin (YYYY-MM-DD)
`client_id`	integer	-	Filtrer par client

Exemple avec filtres : `GET /api/appointments?calendar_id=1&status=confirmed&page=2&per_page=20`

{
    "success": true,
    "data": [
        {
            "appointment_id": 456,
            "status": "confirmed",
            "created_at": "2025-06-01T14:30:00+01:00",
            "updated_at": "2025-06-01T14:30:00+01:00",
            "slot_id": 123,
            "date": "2025-06-15",
            "start_time": "09:00:00",
            "end_time": "09:30:00",
            "calendar_id": 1,
            "calendar_name": "Cabinet Principal",
            "client_id": 789,
            "client_firstname": "Jean",
            "client_lastname": "Dupont",
            "client_email": "jean.dupont@example.com",
            "client_phone": "+33123456789"
        }
    ],
    "pagination": {
        "total": 125,
        "page": 2,
        "per_page": 20,
        "total_pages": 7,
        "has_more": true
    },
    "message": "Appointments retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/appointments/{id}

Récupère les détails complets d'un rendez-vous avec informations client et calendrier.

Réponse détaillée

{
    "success": true,
    "data": {
        "appointment_id": 456,
        "status": "confirmed",
        "created_at": "2025-06-01T14:30:00+01:00",
        "updated_at": "2025-06-02T09:15:00+01:00",
        "slot_id": 123,
        "date": "2025-06-15",
        "start_time": "09:00:00",
        "end_time": "09:30:00",
        "calendar_id": 1,
        "calendar_name": "Cabinet Principal",
        "client_id": 789,
        "client_firstname": "Jean",
        "client_lastname": "Dupont",
        "client_email": "jean.dupont@example.com",
        "client_phone": "+33123456789"
    },
    "message": "Appointment retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Gestion des rendez-vous

Créez et modifiez des rendez-vous en respectant les contraintes de disponibilité et de calendrier.

Contraintes importantes :

Le créneau doit avoir au moins 1 place disponible
Impossible de réserver un créneau dans le passé
Les heures sont gérées en UTC et converties selon le fuseau du calendrier

POST

/api/appointment

Crée un nouveau rendez-vous pour un client dans un créneau disponible.

Corps de la requête (JSON)

Champ	Type	Requis	Description
`calendar_id`	integer	Oui	ID du calendrier
`slot_id`	integer	Oui	ID du créneau
`client_firstname`	string	Oui	Prénom du client
`client_lastname`	string	Oui	Nom du client
`client_email`	string	Oui	Email du client
`client_phone`	string	Oui	Téléphone du client
`status`	string	Non	Statut (pending, confirmed, cancelled, completed)

Exemple de requête

{
    "calendar_id": 1,
    "slot_id": 123,
    "client_firstname": "Jean",
    "client_lastname": "Dupont",
    "client_email": "jean.dupont@example.com",
    "client_phone": "+33123456789",
    "status": "pending"
}

Réponse de succès (200)

{
    "success": true,
    "data": {
        "appointment": {
            "appointment_id": 789,
            "status": "pending",
            "created_at": "2025-06-07T15:30:00+01:00",
            "updated_at": "2025-06-07T15:30:00+01:00",
            "slot_id": 123,
            "date": "2025-06-15",
            "start_time": "09:00:00",
            "end_time": "09:30:00",
            "calendar_id": 1,
            "calendar_name": "Cabinet Principal",
            "client_id": 456,
            "client_firstname": "Jean",
            "client_lastname": "Dupont",
            "client_email": "jean.dupont@example.com",
            "client_phone": "+33123456789"
        }
    },
    "message": "Appointment created successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

PUT

/api/appointment/{id}

Modifie un rendez-vous existant (changement de statut ou de créneau).

Corps de la requête (JSON)

Champ	Type	Description
`slot_id`	integer	Nouvel ID de créneau (facultatif)
`status`	string	Nouveau statut (pending, confirmed, cancelled, completed)

Exemple de requête - Changement de statut

{
    "status": "confirmed"
}

Exemple de requête - Changement de créneau

{
    "slot_id": 124
}

Réponse de succès (200)

{
    "success": true,
    "data": {
        "appointment": {
            "appointment_id": 789,
            "status": "confirmed",
            "created_at": "2025-06-07T15:30:00+01:00",
            "updated_at": "2025-06-07T16:00:00+01:00",
            "slot_id": 124,
            "date": "2025-06-15",
            "start_time": "09:30:00",
            "end_time": "10:00:00",
            "calendar_id": 1,
            "calendar_name": "Cabinet Principal",
            "client_id": 456,
            "client_firstname": "Jean",
            "client_lastname": "Dupont",
            "client_email": "jean.dupont@example.com",
            "client_phone": "+33123456789"
        }
    },
    "message": "Appointment updated successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T16:00:00+01:00",
    "format": "json"
}

Codes d'erreur spécifiques

Code HTTP	Error Code	Description
400	`MISSING_REQUIRED_FIELD`	Champ obligatoire manquant
400	`INVALID_JSON`	JSON invalide dans le corps de la requête
404	`CALENDAR_NOT_FOUND`	Calendrier non trouvé ou inactif
404	`SLOT_NOT_FOUND`	Créneau non trouvé
409	`SLOT_UNAVAILABLE`	Aucune place disponible dans ce créneau
409	`SLOT_IN_PAST`	Impossible de réserver un créneau dans le passé

Endpoints spécifiques à un calendrier

Nouveauté : Accédez directement aux données d'un calendrier spécifique avec ces endpoints optimisés.

Performance : Ces endpoints filtrent automatiquement par calendrier pour des requêtes plus rapides.

GET

/api/appointments/{calendarId}

Récupère tous les rendez-vous d'un calendrier spécifique avec filtrage avancé.

Paramètre	Type	Description
`calendarId`	integer	ID du calendrier (dans l'URL)
`status`	string	Filtrer par statut (confirmed, pending, etc.)
`date_from`	string	Date de début (YYYY-MM-DD)
`date_to`	string	Date de fin (YYYY-MM-DD)

Exemple : `GET /api/appointments/1?status=confirmed&date_from=2025-06-01`

{
    "success": true,
    "data": [
        {
            "appointment_id": 456,
            "status": "confirmed",
            "created_at": "2025-06-01T14:30:00+01:00",
            "updated_at": "2025-06-01T14:30:00+01:00",
            "slot_id": 123,
            "date": "2025-06-15",
            "start_time": "09:00:00",
            "end_time": "09:30:00",
            "calendar_id": 1,
            "calendar_name": "Cabinet Principal",
            "client_id": 789,
            "client_firstname": "Jean",
            "client_lastname": "Dupont",
            "client_email": "jean.dupont@example.com",
            "client_phone": "+33123456789"
        }
    ],
    "pagination": {
        "total": 25,
        "page": 1,
        "per_page": 50,
        "total_pages": 1,
        "has_more": false
    },
    "meta": {
        "calendar_id": 1
    },
    "message": "Calendar appointments retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/clients/{calendarId}

Récupère tous les clients ayant des rendez-vous dans un calendrier spécifique.

Exemple : `GET /api/clients/1?search=martin`

{
    "success": true,
    "data": [
        {
            "client_id": 789,
            "client_firstname": "Marie",
            "client_lastname": "Martin",
            "client_email": "marie.martin@example.com",
            "client_phone": "+33123456789",
            "created_at": "2025-01-15T10:30:00+01:00",
            "appointments_count": 3,
            "last_appointment": "2025-06-15"
        }
    ],
    "pagination": {
        "total": 1,
        "page": 1,
        "per_page": 50,
        "total_pages": 1,
        "has_more": false
    },
    "meta": {
        "calendar_id": 1
    },
    "message": "Calendar clients retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/statistics/{calendarId}

Récupère les statistiques d'un calendrier spécifique pour une période donnée.

Paramètre	Type	Requis	Description
`calendarId`	integer	Oui	ID du calendrier (dans l'URL)
`period`	string	Oui	today, last7days, last30days, custom
`start_date`	string	Si custom	Date de début (YYYY-MM-DD)
`end_date`	string	Si custom	Date de fin (YYYY-MM-DD)

Exemple : `GET /api/statistics/1?period=last30days`

{
    "success": true,
    "data": {
        "period": "last30days",
        "calendar_id": 1,
        "start_date": "2025-05-08",
        "end_date": "2025-06-07",
        "summary": {
            "total_appointments": 28,
            "confirmed_appointments": 24,
            "pending_appointments": 2,
            "cancelled_appointments": 2,
            "completed_appointments": 22,
            "calendars_with_appointments": 1,
            "unique_clients": 25,
            "days_with_appointments": 18,
            "success_rate": 0.93
        },
        "daily_breakdown": [
            {
                "date": "2025-05-08",
                "appointments_count": 2,
                "confirmed_count": 2,
                "cancelled_count": 0
            },
            {
                "date": "2025-05-09",
                "appointments_count": 1,
                "confirmed_count": 1,
                "cancelled_count": 0
            }
        ]
    },
    "message": "Calendar statistics retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Endpoints Clients

GET

/api/clients

Récupère la liste des clients avec recherche textuelle et pagination.

Paramètre	Type	Description
`search`	string	Recherche dans nom, prénom et email
`email`	string	Filtrer par email exact
`phone`	string	Filtrer par téléphone
`created_from`	string	Date de création minimum (YYYY-MM-DD)
`created_to`	string	Date de création maximum (YYYY-MM-DD)

Exemple avec recherche : `GET /api/clients?search=jean&page=1&per_page=10`

{
    "success": true,
    "data": [
        {
            "client_id": 789,
            "client_firstname": "Jean",
            "client_lastname": "Dupont",
            "client_email": "jean.dupont@example.com",
            "client_phone": "+33123456789",
            "created_at": "2025-01-15T10:30:00+01:00",
            "appointments_count": 5,
            "last_appointment": "2025-06-15"
        }
    ],
    "pagination": {
        "total": 1,
        "page": 1,
        "per_page": 10,
        "total_pages": 1,
        "has_more": false
    },
    "message": "Clients retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/clients/{id}

Récupère les détails complets d'un client avec ses statistiques de rendez-vous.

Réponse avec statistiques

{
    "success": true,
    "data": {
        "client_id": 789,
        "client_firstname": "Jean",
        "client_lastname": "Dupont",
        "client_email": "jean.dupont@example.com",
        "client_phone": "+33123456789",
        "created_at": "2025-01-15T10:30:00+01:00",
        "updated_at": "2025-06-01T14:30:00+01:00",
        "appointments_count": 5,
        "last_appointment": "2025-06-15"
    },
    "message": "Client retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Endpoints Statistiques

GET

/api/statistics/appointments

Récupère des statistiques détaillées sur les rendez-vous pour différentes périodes.

Paramètre	Type	Requis	Description
`period`	string	Oui	today, last7days, last15days, last30days, specific_day, custom
`calendar_id`	integer	Non	Filtrer par calendrier
`date`	string	Si specific_day	Date spécifique (YYYY-MM-DD)
`start_date`	string	Si custom	Date de début (YYYY-MM-DD)
`end_date`	string	Si custom	Date de fin (YYYY-MM-DD, max 365 jours)

Exemples d'utilisation

# Statistiques d'aujourd'hui
GET /api/statistics/appointments?period=today

# Statistiques des 7 derniers jours pour un calendrier
GET /api/statistics/appointments?period=last7days&calendar_id=1

# Statistiques d'un jour spécifique
GET /api/statistics/appointments?period=specific_day&date=2025-06-15

# Statistiques personnalisées
GET /api/statistics/appointments?period=custom&start_date=2025-06-01&end_date=2025-06-30

Réponse complète avec analyse quotidienne

{
    "success": true,
    "data": {
        "period": "last7days",
        "start_date": "2025-06-01",
        "end_date": "2025-06-07",
        "summary": {
            "total_appointments": 42,
            "confirmed_appointments": 35,
            "pending_appointments": 3,
            "cancelled_appointments": 4,
            "completed_appointments": 30,
            "calendars_with_appointments": 3,
            "unique_clients": 38,
            "days_with_appointments": 6,
            "success_rate": 0.90
        },
        "daily_breakdown": [
            {
                "date": "2025-06-01",
                "appointments_count": 8,
                "confirmed_count": 7,
                "cancelled_count": 1
            },
            {
                "date": "2025-06-02",
                "appointments_count": 6,
                "confirmed_count": 6,
                "cancelled_count": 0
            },
            {
                "date": "2025-06-03",
                "appointments_count": 7,
                "confirmed_count": 5,
                "cancelled_count": 2
            }
        ]
    },
    "message": "Appointment statistics retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/statistics/calendars

Récupère des statistiques globales sur tous les calendriers et leur utilisation.

Réponse avec métriques détaillées

{
    "success": true,
    "data": {
        "total_calendars": 5,
        "active_calendars": 4,
        "inactive_calendars": 1,
        "calendars_with_appointments": 3,
        "average_appointments_per_calendar": 15.5,
        "calendars": [
            {
                "calendar_id": 1,
                "calendar_name": "Cabinet Principal",
                "appointments_count": 25,
                "slots_count": 150,
                "utilization_rate": 0.17
            },
            {
                "calendar_id": 2,
                "calendar_name": "Cabinet Secondaire",
                "appointments_count": 18,
                "slots_count": 120,
                "utilization_rate": 0.15
            }
        ]
    },
    "message": "Calendar statistics retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

GET

/api/statistics/clients

Récupère des statistiques détaillées sur les clients et leur activité.

Réponse avec top clients

{
    "success": true,
    "data": {
        "total_clients": 250,
        "active_clients": 220,
        "clients_with_appointments": 185,
        "new_clients_last_30_days": 32,
        "repeat_clients": 145,
        "average_appointments_per_client": 2.3,
        "top_clients": [
            {
                "client_id": 45,
                "client_name": "Marie Martin",
                "appointments_count": 12,
                "last_appointment": "2025-06-06"
            },
            {
                "client_id": 89,
                "client_name": "Pierre Dubois",
                "appointments_count": 10,
                "last_appointment": "2025-06-05"
            }
        ]
    },
    "message": "Client statistics retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Codes d'erreur

L'API utilise des codes d'erreur standardisés pour faciliter le débogage et l'intégration.

Code HTTP	Error Code	Description	Action recommandée
400	`INVALID_PARAMETER`	Paramètre invalide ou manquant	Vérifier les paramètres de la requête
400	`INVALID_DATE_FORMAT`	Format de date incorrect	Utiliser le format YYYY-MM-DD
400	`DATE_RANGE_TOO_LARGE`	Plage de dates trop large (>365 jours)	Réduire la plage de dates
401	`AUTH_REQUIRED`	Authentification requise	Inclure le token d'accès
401	`AUTH_INVALID`	Token d'authentification invalide	Vérifier le token HMAC
404	`ENDPOINT_NOT_FOUND`	Endpoint non trouvé	Vérifier l'URL de l'endpoint
404	`RESOURCE_NOT_FOUND`	Ressource non trouvée	Vérifier l'ID de la ressource
500	`INTERNAL_ERROR`	Erreur interne du serveur	Réessayer plus tard

Exemple de réponse d'erreur

{
    "success": false,
    "message": "calendar_id parameter is required",
    "error_code": "MISSING_CALENDAR_ID",
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00"
}

Pagination

Les endpoints qui retournent des listes supportent une pagination avancée pour gérer efficacement de grandes quantités de données.

Paramètres de pagination

Paramètre	Type	Par défaut	Limites
`page`	integer	1	Minimum : 1
`per_page`	integer	50	Minimum : 1, Maximum : 1000

Structure de la réponse paginée

{
    "success": true,
    "data": [...],
    "pagination": {
        "total": 250,        // Nombre total d'éléments
        "page": 1,           // Page actuelle
        "per_page": 50,      // Éléments par page
        "total_pages": 5,    // Nombre total de pages
        "has_more": true     // Y a-t-il d'autres pages ?
    },
    "meta": {},             // Métadonnées supplémentaires
    "message": "Data retrieved successfully",
    "error_code": "SUCCESS",
    "http_code": 200,
    "api_version": "1.0",
    "timestamp": "2025-06-07T15:30:00+01:00",
    "format": "json"
}

Exemples d'utilisation

# Première page avec 20 résultats
GET /api/appointments?per_page=20

# Page 3 avec 100 résultats par page
GET /api/appointments?page=3&per_page=100

# Combinaison avec des filtres
GET /api/appointments?page=2&per_page=50&status=confirmed&calendar_id=1

# Export CSV de toutes les données (max 1000)
GET /api/appointments?format=csv&per_page=1000

Exemples d'utilisation

Dashboard avec statistiques

Récupérer toutes les données nécessaires pour un tableau de bord

# 1. Informations générales de l'API
curl -H "Access-Token: token" "https://[DOMAINE]/api/"

# 2. Statistiques du jour
curl -H "Access-Token: token" "https://[DOMAINE]/api/statistics/appointments?period=today"

# 3. Prochains rendez-vous
curl -H "Access-Token: token" "https://[DOMAINE]/api/appointments?date_from=2025-06-07&per_page=10"

# 4. Statistiques par calendrier
curl -H "Access-Token: token" "https://[DOMAINE]/api/statistics/calendars"

Export pour facturation

Exporter les données du mois en CSV pour la facturation

# Export CSV de tous les rendez-vous du mois
curl -H "Access-Token: token" \
     "https://[DOMAINE]/api/appointments?format=csv&date_from=2025-06-01&date_to=2025-06-30&per_page=1000" \
     -o "facturation_juin_2025.csv"

# Export des clients pour synchronisation
curl -H "Access-Token: token" \
     "https://[DOMAINE]/api/clients?format=csv&created_from=2025-06-01" \
     -o "nouveaux_clients_juin.csv"

Intégration JavaScript

Exemple d'intégration avec l'API en JavaScript

const API_BASE = 'https://[DOMAINE]/api';
const ACCESS_TOKEN = 'votre_token_hmac';

// Fonction helper pour les requêtes
async function apiRequest(endpoint, params = {}) {
    const url = new URL(`${API_BASE}/${endpoint}`);
    Object.keys(params).forEach(key => 
        url.searchParams.append(key, params[key])
    );
    
    const response = await fetch(url, {
        headers: {
            'Access-Token': ACCESS_TOKEN,
            'Accept': 'application/json'
        }
    });
    
    return response.json();
}

// Récupérer les calendriers
const calendars = await apiRequest('calendars');
console.log('Calendriers:', calendars.data);

// Récupérer les statistiques
const stats = await apiRequest('statistics/appointments', {
    period: 'last30days',
    calendar_id: 1
});
console.log('Statistiques:', stats.data.summary);

// Rechercher des clients
const clients = await apiRequest('clients', {
    search: 'jean',
    per_page: 10
});
console.log('Clients trouvés:', clients.data);

Tests en mode debug

Tester l'API sans authentification avec des données fictives (format JSON par défaut)

# Test des calendriers en mode debug (JSON par défaut)
curl "https://[DOMAINE]/api/calendars?debug=true" | jq .

# Test des nouveaux endpoints par calendrier
curl "https://[DOMAINE]/api/appointments/1?debug=true&status=confirmed" | jq .

# Test des statistiques spécifiques à un calendrier
curl "https://[DOMAINE]/api/statistics/1?debug=true&period=last7days" | jq .

# Test de recherche de clients par calendrier
curl "https://[DOMAINE]/api/clients/1?debug=true&search=jean" | jq .

# Test d'export CSV (toujours possible)
curl "https://[DOMAINE]/api/appointments?debug=true&format=csv" \
     -o "test_appointments.csv"

Intégration PHP complète

Exemple d'intégration complète avec gestion d'erreurs

<?php
class Tap4BookAPIv2 {
    private $baseUrl;
    private $accessToken;
    
    public function __construct($baseUrl, $accessToken) {
        $this->baseUrl = rtrim($baseUrl, '/');
        $this->accessToken = $accessToken;
    }
    
    public function request($endpoint, $params = []) {
        $url = $this->baseUrl . '/' . ltrim($endpoint, '/');
        
        if (!empty($params)) {
            $url .= '?' . http_build_query($params);
        }
        
        $context = stream_context_create([
            'http' => [
                'method' => 'GET',
                'header' => "Access-Token: {$this->accessToken}\r\n"
            ]
        ]);
        
        $response = file_get_contents($url, false, $context);
        
        if ($response === false) {
            throw new Exception('API request failed');
        }
        
        return json_decode($response, true);
    }
    
    public function getCalendars() {
        return $this->request('calendars');
    }
    
    public function getAppointmentStats($period, $calendarId = null) {
        $params = ['period' => $period];
        if ($calendarId) {
            $params['calendar_id'] = $calendarId;
        }
        return $this->request('statistics/appointments', $params);
    }
    
    public function searchClients($search, $page = 1, $perPage = 50) {
        return $this->request('clients', [
            'search' => $search,
            'page' => $page,
            'per_page' => $perPage
        ]);
    }
}

// Utilisation
$api = new Tap4BookAPIv2(
    'https://[DOMAINE]/api',
    'votre_token_hmac'
);

try {
    // Récupérer les calendriers
    $calendars = $api->getCalendars();
    echo "Nombre de calendriers: " . count($calendars['data']) . "\n";
    
    // Statistiques des 7 derniers jours
    $stats = $api->getAppointmentStats('last7days');
    echo "Rendez-vous cette semaine: " . $stats['data']['summary']['total_appointments'] . "\n";
    
    // Rechercher des clients
    $clients = $api->searchClients('martin');
    echo "Clients trouvés: " . $clients['pagination']['total'] . "\n";
    
} catch (Exception $e) {
    echo "Erreur API: " . $e->getMessage() . "\n";
}
?>

Dernière mise à jour : Mai 2025 v2.0

Retour Accueil Documentations

Navigation

Introduction à l'API

Authentification sécurisée

Multi-format

Mode Debug

URL de base

Environnements disponibles

Attention

Formats de sortie

JSON (défaut)

XML

CSV

Exemple de réponse JSON

Authentification

Méthode 1 : Via header (recommandé)

Méthode 2 : Via paramètre de requête

Mode Debug

Activation

Données fictives générées

Exemple de réponse complète en mode debug

Endpoints d'information

/api/

Réponse

/api/health

Réponse

Endpoints Calendriers

/api/calendars

Réponse complète

/api/calendars/{id}

Exemple : GET /api/calendars/1

Endpoints Créneaux

/api/slots

Exemple : GET /api/slots?calendar_id=1&date_from=2025-06-15&date_to=2025-06-20

/api/slots/{id}

Réponse détaillée

Endpoints Rendez-vous

/api/appointments

Exemple avec filtres : GET /api/appointments?calendar_id=1&status=confirmed&page=2&per_page=20

/api/appointments/{id}

Réponse détaillée

Gestion des rendez-vous

/api/appointment

Corps de la requête (JSON)

Exemple de requête

Réponse de succès (200)

/api/appointment/{id}

Corps de la requête (JSON)

Exemple de requête - Changement de statut

Exemple de requête - Changement de créneau

Réponse de succès (200)

Codes d'erreur spécifiques

Endpoints spécifiques à un calendrier

/api/appointments/{calendarId}

Exemple : GET /api/appointments/1?status=confirmed&date_from=2025-06-01

/api/clients/{calendarId}

Exemple : GET /api/clients/1?search=martin

/api/statistics/{calendarId}

Exemple : GET /api/statistics/1?period=last30days

Endpoints Clients

/api/clients

Exemple avec recherche : GET /api/clients?search=jean&page=1&per_page=10

/api/clients/{id}

Réponse avec statistiques

Endpoints Statistiques

/api/statistics/appointments

Exemples d'utilisation

Réponse complète avec analyse quotidienne

/api/statistics/calendars

Réponse avec métriques détaillées

/api/statistics/clients

Réponse avec top clients

Codes d'erreur

Exemple de réponse d'erreur

Pagination

Paramètres de pagination

Structure de la réponse paginée

Exemples d'utilisation

Exemples d'utilisation

Dashboard avec statistiques

Export pour facturation

Exemple : `GET /api/calendars/1`

Exemple : `GET /api/slots?calendar_id=1&date_from=2025-06-15&date_to=2025-06-20`

Exemple avec filtres : `GET /api/appointments?calendar_id=1&status=confirmed&page=2&per_page=20`

Exemple : `GET /api/appointments/1?status=confirmed&date_from=2025-06-01`

Exemple : `GET /api/clients/1?search=martin`

Exemple : `GET /api/statistics/1?period=last30days`

Exemple avec recherche : `GET /api/clients?search=jean&page=1&per_page=10`