User API guide/fr

Utilisez notre API développeur pour créer votre propre interface de réservation. Vous pouvez concevoir la solution de votre choix, du widget le plus simple à l'application multifonctionnelle avec des fonctionnalités personnalisées en fonction des spécificités de votre entreprise.

L'interface de programmation d'application Simplybook utilise le protocole JSON-RPC 2.0.

Découvrez un exemple d'interface de réservation basée sur une API et consultez le code source de cette solution.

AUTORISATION

L'utilisation des méthodes API Simplybook nécessite une authentification. Pour vous autoriser dans l'API Simplybook, vous devez obtenir une clé d'accès — access-token. Pour obtenir cette clé d'accès, vous devez appeler la méthode JSON-RPC getToken sur le service https://user-api.simplybook.me/login en transmettant votre clé API personnelle. Vous pouvez copier votre clé API dans l'interface d'administration : allez dans le lien « Fonctionnalités personnalisées » et sélectionnez « Paramètres » dans les fonctionnalités personnalisées de l'API. Vous devez ensuite initialiser l'accès à distance à l'API Simplybook. Votre requête doit contenir les en-têtes suivants : « X-Company-Login », « X-Token ».

L'obtention du jeton d'accès peut être mise en œuvre soit côté client, soit depuis votre serveur, ce qui constitue la solution la plus sécurisée.

Vous pouvez utiliser la bibliothèque client JSON-RPC JavaScript et la bibliothèque client JSON-RPC PHP de nos exemples pour développer votre propre solution.

Veuillez noter que l'accès-token est valable une heure. Ceci est fait pour des raisons de sécurité. Vous devrez le régénérer au moins une fois par heure.

API CLIENT (SERVICE PUBLIC DE L'ENTREPRISE) AUTORISATION

Autorisation depuis le code côté client

Obtention de la clé token.

var loginClient = new JSONRpcClient({
	'url': 'https://user-api.simplybook.me' + '/login',
	'onerror': function (error) {},
});
var token = loginClient.getToken(YOUR_COMPANY_LOGIN, YOUR_API_KEY);

Initialisation du client JSON-RPC.

this.client = new JSONRpcClient({
	'url': 'https://user-api.simplybook.me',
	'headers': {
		'X-Company-Login': VOTRE_IDENTIFIANT_DE_CONNEXION_À_VOTRE_ENTREPRISE,
		'X-Token': token
	},
	'onerror': function (error) {}
});

Autorisation depuis le code côté serveur

Obtention de la clé du jeton.

$loginClient = new JsonRpcClient('https://user-api.simplybook.me' . '/login/');
$token = $loginClient->getToken(YOUR_COMPANY_LOGIN, YOUR_API_KEY);

Initialisation du client JSON-RPC.

$client = new JsonRpcClient('https://user-api.simplybook.me' . '/', array(
   'headers' => array(
       'X-Company-Login: ' . VOTRE_IDENTIFIANT_DE_CONNEXION,
       'X-Token: ' . $token
   )
));

AUTORISATION DE L'API UTILISATEUR/ADMIN (SERVICE D'ADMINISTRATION DE L'ENTREPRISE)

Autorisation depuis le code côté client

Obtention de la clé token.

var loginClient = new JSONRpcClient({
'url': 'https://user-api.simplybook.me' + '/login',
'onerror': function (error) {},
});
var token = loginClient.getUserToken(YOUR_COMPANY_LOGIN, YOUR_USER_LOGIN, YOUR_USER_PASSWORD);

Initialisation du client JSON-RPC.

this.client = new JSONRpcClient({
'url': 'https://user-api.simplybook.me' + '/admin/',
'headers': {
'X-Company-Login': YOUR_COMPANY_LOGIN,
'X-User-Token': token
},
'onerror': function (error) {}
});

Autorisation côté serveur

Obtention de la clé de jeton.

$loginClient = new JsonRpcClient('https://user-api.simplybook.me' . '/login/');
$token = $loginClient->getUserToken(YOUR_COMPANY_LOGIN, YOUR_USER_LOGIN, YOUR_USER_PASSWORD);

Initialisation du client JSON-RPC.

$client = new JsonRpcClient('https://user-api.simplybook.me' . '/admin/', array(
'headers' => array(
'X-Company-Login: ' . YOUR_COMPANY_LOGIN,
'X-User-Token: ' . $token
)
));

OBTENTION DE DONNÉES À PARTIR DU SERVEUR SIMPLYBOOK

Une page de réservation est généralement une page où les clients choisissent le service dont ils ont besoin, un employé et l'heure de leur rendez-vous. Ensuite, le client saisit ses coordonnées et confirme la réservation. Les solutions plus complexes peuvent inclure le remplissage de différents formulaires d'inscription, la création de réservations de groupe ou de plusieurs rendez-vous, etc. Décrivons le processus de création d'une page de réservation simple. Si vous avez besoin d'ajouter des fonctionnalités supplémentaires à votre page, consultez ici la liste complète des méthodes API Simplybook.

La première chose à afficher est donc la liste des services et la liste des employés. Obtenez ces données à l'aide des méthodes getEventList et getUnitList. Elles renvoient toutes deux une liste contenant des informations complètes sur chaque élément, ce qui vous offre de nombreuses possibilités pour afficher les services et les employés sur votre page. Pour filtrer les employés, utilisez la propriété unit_map de la liste des services, qui contient des informations sur les employés pouvant fournir le service sélectionné.

Exemple de code pour obtenir la liste des services

$services = $client->getEventList();
// renvoie array(array(
//     'id' => 1, - identifiant du service
//     'name' => 'Service 1', - nom du service
//     'description' => 'Describe your service...', - description du service
//     'duration' => 60, - durée du service
//     'hide_duration' => 0, - drapeau permettant de masquer la durée aux clients,
//     'picture' => null, - nom du fichier de l'image ou null
//     'picture_path' => '/uploads/apidemo/event__picture/small/', - chemin complet vers l'image,
//     'position' => 1 - position du service
//     'is_active' => 1, - le service est activé
//     'is_public' => 1, - le service peut être réservé par les clients
// ), ...)

Exemple de code pour obtenir la liste des prestataires de services

$services = $client->getUnitList();
// renvoie array(array(
//    'id' => 1, - identifiant du prestataire
//    'name' => 'Prestataire 1', - nom du prestataire
//    'phone' => '111111111', - numéro de téléphone du prestataire
//    'description' => 'Décrivez votre prestataire...', - description du prestataire
//    'email' => 'test@gmail.com', - adresse e-mail du prestataire,
//    'is_active' => 1, - le prestataire est activé
//    'is_visible' => 1, - l'artiste est visible pour les clients,
//    'picture' => null, - nom du fichier de l'image ou null,
//    'picure_path' => '/uploads/apidemo/unit_group__picture/small/', - chemin complet vers l'image
//    'position' => 1, - position de l'artiste
//    'qty' => 1, quantité d'artistes
// ), ...)

L'étape suivante pour un client consiste à choisir une date et une heure pour son service. Nous avons utilisé un sélecteur de date Bootstrap dans l'exemple d'utilisation de l'API, mais vous pouvez également utiliser celui-ci ou tout autre calendrier. Pour définir la première date de votre calendrier, utilisez la méthode getFirstWorkingDay. Elle peut prendre l'identifiant de l'employé comme paramètre et renvoie la prochaine date à laquelle l'employé sélectionné (ou tout employé de l'entreprise par défaut) est disponible pour une réservation. Pour afficher les créneaux horaires disponibles à une date sélectionnée, vous devez utiliser les méthodes getWorkCalendar et getStartTimeMatrix. La première méthode vous donne des informations sur les heures de début et de fin des jours ouvrables, ainsi que sur les jours fériés. La seconde renvoie la liste des créneaux horaires pouvant être réservés pour une date donnée.

Exemple de code pour obtenir des informations sur les jours ouvrables

$année = 2015 ;
$mois = 3 ; // mars
$performerId = 1 ; // Peut être nul 
$workDaysInfo = $client->getWorkCalendar($année, $mois, $performerId) ;				
// renvoie array(
//     '2015-03-01' => array('from' => '09:00:00', 'to' => '18:00:00', 'is_day_off' => 0),
//     '2015-03-02' => array('from' => '09:00:00', 'to' => '18:00:00', 'is_day_off' => 0),
//     ...
//);

Exemple de code pour obtenir la matrice des heures de début

$dateFrom = '2015-03-03';
$dateTo = '2015-03-04';
$serviceId = 1;
$performerId = 1;
$qty = 1;
$availableTime = $client->getStartTimeMatrix($dateFrom, $dateTo, $serviceId, $performerId, $qty);
// renvoie array(
//     '2015-03-03' => array('09:00:00', '09:30:00', '10:00:00', ....),
//     '2015-03-04' => array('09:00:00', '09:30:00', '10:00:00', ....),
//);

Une autre méthode utile dont vous pourriez avoir besoin est calculateEndTime. Chaque service peut avoir sa propre durée, et les employés de votre entreprise peuvent avoir des horaires de travail différents d'un jour à l'autre. Cette méthode vous permet donc d'indiquer à un client la date et l'heure de fin du service qu'il a réservé de manière correcte.

Exemple de code pour calculer l'heure de fin d'une réservation

$startDateTime = '2015-03-03 09:00:00';
$serviceId = 1;
$performerId = 1;
$availableTime = $client->calculateEndTime($startDateTime, $serviceId, $performerId);
// renvoie « 2015-03-03 10:00:00 »

Lorsqu'un client clique sur le bouton « Confirmer la réservation », vous devez appeler la méthode « book ». Il s'agit de la fonction principale qui effectue toutes les validations nécessaires et enregistre une nouvelle réservation dans le système Simplybook. Elle récupère les informations relatives à la réservation, les données du client telles que son nom et son numéro de téléphone, ainsi que certains paramètres supplémentaires. Vous trouverez la description de tous les paramètres de cette méthode dans la liste des fonctions API. La réponse de la méthode book contient un code unique et d'autres détails sur la nouvelle réservation ou la liste des erreurs si des problèmes sont survenus. Vous pouvez utiliser ces informations pour afficher le résultat de la réservation au client de manière pratique et intuitive.

UTILISATION DE LA CLÉ SECRÈTE API

Dans certains cas, la méthode de réservation peut nécessiter une confirmation, par exemple si vous acceptez les paiements de vos clients et que vous ne confirmez la réservation qu'après réception du paiement. La méthode confirmBookng de l'API Simplybook prend comme paramètres l'identifiant de la réservation et une signature sécurisée (une autre méthode qui nécessite une signature sécurisée est cancelBookng). Pour générer une signature sécurisée, vous devez utiliser votre clé API secrète. Découvrez comment procéder dans l'exemple ci-dessous. Vous trouverez la clé secrète dans l'interface d'administration, sous le lien « Paramètres » de la fonctionnalité API personnalisée dans la liste « Fonctionnalités personnalisées ».

Exemple de code pour la réservation d'un service et sa confirmation à l'aide d'une clé API secrète

$additionalFields = array(
	'6740d3bce747107ddb9a789cbb78abf3' => 'value1', 
	'b0657bafaec7a2c9800b923f959f8163' => 'value2'
);
$clientData = array(
	'name' => 'Nom du client',
	'email' => 'client@email.com',
	'phone' => '+13152108338'
);
		
$bookingsInfo = $client->book($eventId, $unitId, $date, $time, $clientData, $additionalFields);

if ($bookingsInfo->require_confirm) {
 foreach ($bookingsInfo->bookings as $booking) {
	 $sign = md5($booking->id . $booking->hash . YOUR_API_SECRET_KEY);
	 $result = $client->confirmBooking($booking->id, $sign);
	 echo '
Confirm result
';
	 var_dump($result);
 }
}

Exemple de code pour obtenir les formulaires d'inscription

$fields = $client->getAdditionalFields($eventId);
// renvoie - array(array(
//		'name' => 'b0657bafaec7a2c9800b923f959f8163', - nom du champ
//		'title' => 'Test digits', - titre du champ
//		'type' => 'digits', - type de champ
//		'values' => null, - valeurs disponibles pour le type de champ de sélection
//		'default' => null, - valeur par défaut pour le champ
//		'is_null' => null, - champ pouvant être vide
//		'on_main_page' => 1, 
//		'pos' => 1, - position du champ
//		'value' => null
// )), ...)

FONCTIONNALITÉS PERSONNALISÉES SIMPLYBOOK

Si votre entreprise a besoin de fonctionnalités supplémentaires, vous pouvez activer certaines de nos fonctionnalités personnalisées. La liste complète des fonctionnalités personnalisées avec une description détaillée est disponible dans votre interface d'administration sous le lien « Fonctionnalités personnalisées ». Une fois la fonctionnalité personnalisée nécessaire activée, les méthodes API correspondantes seront activées afin que vous puissiez les utiliser dans votre code.

FONCTIONNALITÉ DE RÉSERVATION CODEFLOW

Autorisez l'accès à l'API Simplybook à l'aide de la fonction loginClient.getToken(companyLogin, apiKey) ;.

Check if Service categories Custom Feature is activated by isPluginActivated("event_category") if yes then display list of categories getCategoriesList().

Get list of services (events) and performers (units) using getEventList() and getUnitList() functions. If "unit_map" array is available for service it means this service can be provided by given performers only.

If Any Employee Selector Custom Feature is activated isPluginActivated("any_unit") and no special duration is set for service-performer pair in "unit_map" array then user should be allowed to select Any provider option or choose provider manually. But manual selection of performers should not be possible if getCompanyParam("any_unit__hide_other_units") is enabled.

Use getStartTimeMatrix ($from as current date, $to as current date, $eventId, $unitId, $count as selected participants value ) to get available timeslots for given date. $unitId should be null if Any employee option is selected.

If Any Employee selector is active and Any employee was selected call getAvailableUnits($eventId, $dateTime, $count) to get available $unitId

If Intake Forms Custom Feature is activated isPluginActivated("event_field") call getAdditionalFields($eventId) function to get list of fields for client to fill.

Call book($eventId, $unitId, $date, $time, $clientData, $additional, $count, $batchId) to make a booking.