{}</>=>()

Documentation API v2.0

Construisez avec iValid

API REST moderne, authentification OAuth 2.0, webhooks temps réel. Tout ce qu'il vous faut pour intégrer iValid.

Recherches populaires:

Guide de démarrage

Explorer

Référence API

Explorer

Webhooks

Explorer

Introduction

L'API iValid vous permet d'intégrer la gestion des rendez-vous directement dans vos applications. Conçue pour les entreprises avec des équipes terrain (BTP, SAV, maintenance), elle offre une solution complète pour automatiser la planification et optimiser les interventions.

URL de base

https://api.ivalid.fr/v2

Format

JSON (application/json)

Authentification

OAuth 2.0 / Bearer Token

Rate Limit

1000 requêtes/minute

Hébergement

100% France (RGPD)

SLA

99.9% disponibilité

Environnement de test

Utilisez https://sandbox.api.ivalid.fr/v2 pour vos tests. Les données sont réinitialisées toutes les 24h.

Authentification

Important

iValid utilise OAuth 2.0 pour l'authentification. Obtenez vos credentials depuis le dashboard développeur dans Paramètres → API → Credentials.

1. Obtenir un token d'accès

auth-request.json

json

1POST https://api.ivalid.fr/oauth/token
2 
3{
4  "grant_type": "client_credentials",
5  "client_id": "your_client_id",
6  "client_secret": "your_client_secret",
7  "scope": "appointments:read appointments:write customers:read"
8}

2. Réponse

auth-response.json

json

1{
2  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
3  "token_type": "Bearer",
4  "expires_in": 3600,
5  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
6  "scope": "appointments:read appointments:write customers:read"
7}

Sécurité

Ne partagez jamais votre client_secret côté client. Utilisez toujours un serveur backend pour les appels authentifiés.

3. Utiliser le token

Incluez le token dans le header Authorization de chaque requête :

bash

"text-emerald-600">Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Scopes disponibles

appointments:readLecture des rendez-vous

appointments:writeCréation/modification des rendez-vous

customers:readLecture des clients

customers:writeCréation/modification des clients

services:readLecture des services

teams:readLecture des équipes et techniciens

webhooks:manageGestion des webhooks

Premier appel API

Testez votre intégration en récupérant la liste de vos rendez-vous.

example.sh

bash

1"text-emerald-600">curl"text-indigo-600"> -X GET "https://api.ivalid.fr/v2/appointments" \
2 "text-indigo-600"> -H "Authorization: Bearer YOUR_API_KEY" \
3 "text-indigo-600"> -H "Content-Type: application/json"

Réponse attendue

response.json

json

1{
2  "data": [
3    {
4      "id": "apt_1234567890",
5      "customer": {
6        "id": "cust_abc123",
7        "name": "Marie Dupont",
8        "email": "marie@example.com",
9        "phone": "+33612345678"
10      },
11      "service": {
12        "id": "srv_installation",
13        "name": "Installation Climatisation",
14        "duration": 120,
15        "price": 150.00
16      },
17      "technician": {
18        "id": "tech_xyz789",
19        "name": "Jean Martin"
20      },
21      "scheduled_at": "2025-01-20T09:00:00Z",
22      "status": "confirmed",
23      "location": {
24        "address": "15 rue des Lilas",
25        "city": "Paris",
26        "postal_code": "75001",
27        "coordinates": { "lat": 48.8566, "lng": 2.3522 }
28      }
29    }
30  ],
31  "meta": {
32    "total": 42,
33    "page": 1,
34    "per_page": 10,
35    "total_pages": 5
36  }
37}

Bravo !

Si vous recevez une réponse 200, votre intégration fonctionne. Vous pouvez maintenant explorer les autres endpoints de l'API.

Rendez-vous

Gérez les rendez-vous de vos clients : création, modification, annulation et consultation. L'API gère automatiquement les conflits de planning et les zones géographiques.

GET/v2/appointmentsListe tous les RDV

GET/v2/appointments/:idDétails d'un RDV

POST/v2/appointmentsCréer un RDV

PUT/v2/appointments/:idModifier un RDV

DELETE/v2/appointments/:idAnnuler un RDV

POST/v2/appointments/:id/confirmConfirmer un RDV

POST/v2/appointments/:id/rescheduleReprogrammer

Créer un rendez-vous

create-appointment.json

json

1POST /v2/appointments
2 
3{
4  "customer_id": "cust_abc123",
5  "service_id": "srv_installation",
6  "scheduled_at": "2025-01-20T09:00:00Z",
7  "technician_id": "tech_xyz789",
8  "duration": 120,
9  "location": {
10    "address": "15 rue des Lilas",
11    "city": "Paris",
12    "postal_code": "75001"
13  },
14  "notes": "Code portail: 1234",
15  "notify_customer": true,
16  "reminder_sms": true,
17  "reminder_email": true
18}

Filtres disponibles

statuspending, confirmed, completed, cancelled

technician_idFiltrer par technicien

customer_idFiltrer par client

date_fromDate de début (ISO 8601)

date_toDate de fin (ISO 8601)

postal_codeFiltrer par code postal

Clients

Gérez votre base clients avec leurs coordonnées, historique de rendez-vous et préférences.

GET/v2/customersListe des clients

GET/v2/customers/:idDétails client

POST/v2/customersCréer un client

PUT/v2/customers/:idModifier un client

GET/v2/customers/:id/appointmentsHistorique RDV

create-customer.json

json

1POST /v2/customers
2 
3{
4  "first_name": "Marie",
5  "last_name": "Dupont",
6  "email": "marie.dupont@example.com",
7  "phone": "+33612345678",
8  "address": {
9    "street": "15 rue des Lilas",
10    "city": "Paris",
11    "postal_code": "75001",
12    "country": "FR"
13  },
14  "preferences": {
15    "preferred_contact": "sms",
16    "preferred_time_slots": ["morning", "afternoon"],
17    "language": "fr"
18  },
19  "tags": ["premium", "fidele"],
20  "custom_fields": {
21    "numero_client": "CLT-2024-001"
22  }
23}

Services

Définissez vos prestations avec leur durée, tarif et compétences requises.

GET/v2/servicesListe des services

GET/v2/services/:idDétails service

POST/v2/servicesCréer un service

PUT/v2/services/:idModifier un service

service-example.json

json

1{
2  "id": "srv_installation",
3  "name": "Installation Climatisation",
4  "description": "Installation complète d'un système de climatisation",
5  "duration": 120,
6  "buffer_before": 15,
7  "buffer_after": 15,
8  "price": 150.00,
9  "currency": "EUR",
10  "required_skills": ["climatisation", "electricite"],
11  "available_online": true,
12  "color": "#10B981",
13  "category": "installation"
14}

Équipes & Techniciens

Gérez vos équipes terrain, leurs compétences et zones d'intervention.

GET/v2/teamsListe des équipes

GET/v2/techniciansListe techniciens

GET/v2/technicians/:idDétails technicien

GET/v2/technicians/:id/schedulePlanning

technician-example.json

json

1{
2  "id": "tech_xyz789",
3  "name": "Jean Martin",
4  "email": "jean.martin@company.com",
5  "phone": "+33698765432",
6  "skills": ["climatisation", "chauffage", "electricite"],
7  "zones": ["75001", "75002", "75003", "75004"],
8  "working_hours": {
9    "monday": { "start": "08:00", "end": "18:00" },
10    "tuesday": { "start": "08:00", "end": "18:00" },
11    "wednesday": { "start": "08:00", "end": "18:00" },
12    "thursday": { "start": "08:00", "end": "18:00" },
13    "friday": { "start": "08:00", "end": "17:00" }
14  },
15  "max_appointments_per_day": 6,
16  "current_location": { "lat": 48.8566, "lng": 2.3522 }
17}

Disponibilités

Consultez les créneaux disponibles en tenant compte des compétences requises, zones géographiques et temps de trajet.

GET/v2/availabilityCréneaux disponibles

GET/v2/availability/slotsSlots optimisés

POST/v2/availability/checkVérifier dispo

availability-response.json

json

1GET /v2/availability?service_id=srv_installation&date=2025-01-20&postal_code=75001
2 
3{
4  "date": "2025-01-20",
5  "slots": [
6    {
7      "start": "09:00",
8      "end": "11:00",
9      "technician_id": "tech_xyz789",
10      "technician_name": "Jean Martin",
11      "travel_time": 15
12    },
13    {
14      "start": "14:00",
15      "end": "16:00",
16      "technician_id": "tech_abc456",
17      "technician_name": "Pierre Dubois",
18      "travel_time": 20
19    }
20  ],
21  "next_available_date": "2025-01-21"
22}

Optimisation des trajets

L'API prend en compte les temps de trajet entre les rendez-vous pour proposer des créneaux optimisés et réduire les déplacements inutiles.

Webhooks

Temps réel

Recevez des notifications en temps réel lorsque des événements se produisent sur votre compte. Les webhooks sont signés avec HMAC-SHA256 pour garantir leur authenticité.

appointment.createdNouveau RDV créé

appointment.updatedRDV modifié

appointment.confirmedRDV confirmé

appointment.cancelledRDV annulé

appointment.completedRDV terminé

appointment.reminderRappel envoyé

customer.createdNouveau client

customer.updatedClient modifié

Configurer un webhook

create-webhook.json

json

1POST /v2/webhooks
2 
3{
4  "url": "https://your-app.com/webhooks/ivalid",
5  "events": [
6    "appointment.created",
7    "appointment.updated",
8    "appointment.cancelled"
9  ],
10  "secret": "whsec_your_webhook_secret",
11  "active": true
12}

Payload reçu

webhook-payload.json

json

1{
2  "id": "evt_1234567890",
3  "event": "appointment.created",
4  "timestamp": "2025-01-15T14:32:05.000Z",
5  "data": {
6    "id": "apt_1234567890",
7    "customer": {
8      "id": "cust_abc123",
9      "name": "Marie Dupont"
10    },
11    "service": {
12      "id": "srv_installation",
13      "name": "Installation Climatisation"
14    },
15    "scheduled_at": "2025-01-20T09:00:00Z",
16    "status": "confirmed"
17  }
18}

Vérification HMAC-SHA256

Chaque webhook inclut une signature dans le header X-iValid-Signature. Vérifiez-la pour garantir l'authenticité :

verify-webhook.js

javascript

1600">"text-violet-600">const crypto = 600">require(600">'crypto');
2 
3600">"text-violet-600">function 600">verifyWebhook(payload, signature, secret) {
4  600">"text-violet-600">const expectedSignature = crypto
5    .600">createHmac(600">'sha256', secret)
6    .600">update(payload)
7    .600">digest(600">'hex');
8 
9  600">"text-violet-600">return crypto.600">timingSafeEqual(
10    Buffer.600">"text-violet-600">from(signature),
11    Buffer.600">"text-violet-600">from(600">'sha256=' + expectedSignature)
12  );
13}

Retry automatique

En cas d'échec (code HTTP != 2xx), iValid retente l'envoi 3 fois avec un délai exponentiel (1min, 5min, 30min). Consultez les logs dans le dashboard.

Intégrations

iValid s'intègre nativement avec vos outils existants pour une synchronisation automatique et bidirectionnelle.

Google Calendar

Sync bidirectionnelle des RDV

/v2/integrations/google-calendar

Microsoft Outlook

Calendrier Microsoft 365

/v2/integrations/outlook

Zoho CRM

Sync contacts et leads

/v2/integrations/zoho

Stripe

Paiements en ligne

/v2/integrations/stripe

Zapier

+5000 apps connectées

/v2/integrations/zapier

Make (Integromat)

Automatisations avancées

/v2/integrations/make

Configuration

Configurez vos intégrations depuis le dashboard iValid dans Paramètres → Intégrations. Les clés API et tokens sont gérés automatiquement.

SDKs & Librairies

Utilisez nos SDKs officiels pour intégrer iValid plus rapidement.

Node.js

nodejs-example.js

javascript

1npm install @ivalid/sdk
2 
3400">// Usage
4600">"text-violet-600">const iValid = 600">require(600">'@ivalid/sdk');
5 
6600">"text-violet-600">const client = 600">"text-violet-600">new iValid.600">Client({
7  apiKey: 600">'your_api_key',
8  environment: 600">'production' 400">// or 600">'sandbox'
9});
10 
11400">// Get appointments
12600">"text-violet-600">const appointments = 600">"text-violet-600">await client.appointments.600">list({
13  status: 600">'confirmed',
14  date_from: 600">'2025-01-01'
15});
16 
17400">// Create appointment
18600">"text-violet-600">const newAppointment = 600">"text-violet-600">await client.appointments.600">create({
19  customer_id: 600">'cust_abc123',
20  service_id: 600">'srv_installation',
21  scheduled_at: 600">'2025-01-20T09:00:00Z'
22});

Python

python-example.py

python

1pip install ivalid
2 
3400"># Usage
4600">"text-violet-600">from ivalid 600">"text-violet-600">import Client
5 
6client = 600">Client(
7    api_key=600">'your_api_key',
8    environment=600">'production'  400"># 600">"text-violet-600">or 600">'sandbox'
9)
10 
11400"># Get appointments
12appointments = client.appointments.600">list(
13    status=600">'confirmed',
14    date_from=600">'2025-01-01'
15)
16 
17400"># Create appointment
18new_appointment = client.appointments.600">create(
19    customer_id=600">'cust_abc123',
20    service_id=600">'srv_installation',
21    scheduled_at=600">'2025-01-20T09:00:00Z'
22)

PHP

php-example.php

php

1composer "text-violet-600">require ivalid/sdk
2 
3<?php
4"text-violet-600">use iValid\Client;
5 
6"text-indigo-600">$client = "text-violet-600">new Client([
7    'api_key' => 'your_api_key',
8    'environment' => 'production'
9]);
10 
11// Get appointments
12"text-indigo-600">$appointments = "text-indigo-600">$client->appointments->list([
13    'status' => 'confirmed',
14    'date_from' => '2025-01-01'
15]);
16 
17// Create appointment
18"text-indigo-600">$newAppointment = "text-indigo-600">$client->appointments->create([
19    'customer_id' => 'cust_abc123',
20    'service_id' => 'srv_installation',
21    'scheduled_at' => '2025-01-20T09:00:00Z'
22]);

Gestion des erreurs

L'API utilise les codes HTTP standards et retourne des messages d'erreur détaillés en JSON.

200Succès

201Créé avec succès

400Requête invalide

401Non authentifié

403Accès refusé

404Ressource non trouvée

409Conflit (ex: créneau occupé)

422Données invalides

429Rate limit dépassé

500Erreur serveur

error-response.json

json

1{
2  "error": {
3    "code": "SLOT_NOT_AVAILABLE",
4    "message": "Le créneau demandé n'est plus disponible",
5    "details": {
6      "requested_slot": "2025-01-20T09:00:00Z",
7      "technician_id": "tech_xyz789",
8      "reason": "already_booked"
9    },
10    "suggestions": [
11      { "slot": "2025-01-20T14:00:00Z", "technician_id": "tech_xyz789" },
12      { "slot": "2025-01-21T09:00:00Z", "technician_id": "tech_abc456" }
13    ]
14  }
15}

Codes d'erreur

Les erreurs incluent un code unique (ex: SLOT_NOT_AVAILABLE) pour faciliter le traitement programmatique et des suggestions quand c'est pertinent.

Besoin d'aide ?

Notre équipe est disponible pour vous accompagner dans votre intégration.

Documentation

Guides complets

Status API

Disponibilité en temps réel

Support

Contacter l'équipe