Documentation API Roadify

L'API REST Roadify vous permet d'intégrer vos données de tournées, clients et visites dans vos applications tierces : intranet, CRM, ERP, applications mobiles, etc.

Base URL


                        https://www.roadify.fr/api/v1

Sécurisé

Authentification par clé API

Rapide

Réponses JSON optimisées

RESTful

Standards HTTP respectés

Authentification

Toutes les requêtes API doivent inclure votre clé API. Vous pouvez générer vos clés depuis votre espace utilisateur.

# Via header (recommandé)

curl -H "X-API-Key: votre_cle_api" \
     https://www.roadify.fr/api/v1/clients

# Via paramètre URL

curl "https://www.roadify.fr/api/v1/clients?api_key=votre_cle_api"

Sécurité

Ne partagez jamais votre clé API. Utilisez des variables d'environnement pour la stocker. En cas de compromission, régénérez immédiatement une nouvelle clé.

Rate Limiting

Pour garantir la stabilité du service, les requêtes sont limitées :

Plan	Limite	Fenêtre
Standard	`100` requêtes	par minute
Premium	`500` requêtes	par minute

En cas de dépassement, vous recevrez une erreur 429 Too Many Requests.

Gestion des erreurs

L'API utilise les codes HTTP standards et retourne les erreurs au format JSON :

{
  "success": false,
  "error": {
    "code": "CLIENT_NOT_FOUND",
    "message": "Client non trouvé.",
    "details": {}
  },
  "timestamp": "2026-01-16T10:30:00+01:00"
}

Code HTTP	Signification
`200`	Succès
`201`	Créé avec succès
`400`	Requête invalide (données manquantes/incorrectes)
`401`	Non authentifié (clé API manquante/invalide)
`404`	Ressource non trouvée
`429`	Limite de requêtes dépassée
`500`	Erreur serveur

Clients

GET /api/v1/clients Liste des clients

Paramètres de requête

page	Numéro de page (défaut: 1)
per_page	Résultats par page (1-100, défaut: 50)
ville	Filtrer par ville
priorite	Filtrer par priorité (haute, normale, basse)
search	Recherche textuelle (nom, adresse)

Exemple de réponse

{
  "success": true,
  "data": [
    {
      "id": 1,
      "nom": "Boulangerie Martin",
      "adresse": "15 rue du Commerce",
      "code_postal": "75001",
      "ville": "Paris",
      "coordinates": {
        "latitude": 48.8566,
        "longitude": 2.3522
      },
      "contact": {
        "nom": "Jean Martin",
        "telephone": "01 23 45 67 89",
        "email": "contact@boulangerie-martin.fr"
      },
      "priorite": "haute",
      "intervalle_visite_jours": 14,
      "duree_visite_minutes": 30,
      "derniere_visite": "2026-01-10",
      "prochaine_visite": "2026-01-24",
      "statut_visite": "a_jour"
    }
  ],
  "meta": {
    "pagination": {
      "current_page": 1,
      "per_page": 50,
      "total": 127,
      "total_pages": 3
    }
  },
  "timestamp": "2026-01-16T10:30:00+01:00"
}

GET /api/v1/clients/{id} Détail d'un client

Paramètres

id	ID du client (requis, dans l'URL)
include	Données additionnelles : `visites` pour inclure les 10 dernières visites

POST /api/v1/clients Créer un client

Corps de la requête (JSON)

{
  "nom": "Nouveau Client",           // requis
  "adresse": "10 rue Example",
  "code_postal": "75001",
  "ville": "Paris",
  "telephone": "01 23 45 67 89",
  "email": "contact@example.fr",
  "contact_nom": "Jean Dupont",
  "priorite": "normale",             // haute, normale, basse
  "intervalle_visite": 14,           // jours entre visites
  "duree_visite": 30,                // durée estimée en minutes
  "notes": "Notes libres..."
}

Si les coordonnées ne sont pas fournies, elles seront géocodées automatiquement depuis l'adresse.

PUT /api/v1/clients/{id} Modifier un client

Envoyez uniquement les champs à modifier. Même structure que POST.

DELETE /api/v1/clients/{id} Supprimer un client

Supprime définitivement le client et ses données associées.

Tournées

GET /api/v1/tournees Liste des tournées

Paramètres de requête

date_from	Date début (YYYY-MM-DD)
date_to	Date fin (YYYY-MM-DD)
statut	planifiee, en_cours, terminee, annulee
page, per_page	Pagination

GET /api/v1/tournees/{id} Détail d'une tournée avec points

Exemple de réponse

{
  "success": true,
  "data": {
    "id": 42,
    "nom": "Tournée Paris Nord",
    "date": "2026-01-16",
    "statut": "planifiee",
    "distance_km": 45.7,
    "duree_estimee_minutes": 180,
    "points": [
      {
        "ordre": 1,
        "client_id": 12,
        "client_nom": "Client A",
        "adresse": "10 rue A",
        "ville": "Paris",
        "coordinates": {
          "latitude": 48.8566,
          "longitude": 2.3522
        },
        "duree_prevue_minutes": 30
      }
    ],
    "total_points": 5
  }
}

POST /api/v1/tournees Créer une tournée

{
  "nom": "Ma tournée",               // requis
  "date": "2026-01-20",              // défaut: aujourd'hui
  "statut": "planifiee",
  "client_ids": [1, 5, 12, 8],       // optionnel: ajoute ces clients
  "notes": "Notes..."
}

PUT /api/v1/tournees/{id}/statut Changer le statut

{ "statut": "en_cours" }

Statuts: planifiee, en_cours, terminee, annulee

Visites

GET /api/v1/visites Liste des visites

Paramètres de requête

date_from	Date début
date_to	Date fin
client_id	Filtrer par client
type	visite, prospection, livraison, sav

POST /api/v1/visites Enregistrer une visite

{
  "client_id": 12,                   // requis
  "tournee_id": 42,                  // optionnel
  "date": "2026-01-16",              // défaut: aujourd'hui
  "heure_arrivee": "09:30:00",
  "heure_depart": "10:15:00",
  "type": "visite",                  // visite, prospection, livraison, sav
  "resultat": "effectuee",           // effectuee, reportee, annulee, absent
  "compte_rendu": "RDV positif, commande prévue..."
}

Statistiques

GET /api/v1/stats Statistiques globales

Paramètres

date_from	Début période (défaut: -30 jours)
date_to	Fin période (défaut: aujourd'hui)

Exemple de réponse

{
  "success": true,
  "data": {
    "period": {
      "from": "2025-12-17",
      "to": "2026-01-16"
    },
    "clients": {
      "total": 127,
      "en_retard": 12,
      "taux_retard": 9.4
    },
    "tournees": {
      "total": 22,
      "terminees": 18,
      "distance_totale_km": 892.5
    },
    "visites": {
      "total": 156,
      "effectuees": 142,
      "clients_visites": 89,
      "moyenne_jour": 5.2
    },
    "evolution": [
      {"date": "2025-12-17", "count": 6},
      {"date": "2025-12-18", "count": 4}
    ]
  }
}

GET /api/v1/stats/clients-a-visiter Clients prioritaires à visiter

Retourne les clients en retard ou bientôt à visiter, triés par priorité.

limit

Nombre max de résultats (défaut: 20, max: 100)

Exemples de code

JavaScript (fetch)

const API_KEY = 'votre_cle_api';
const BASE_URL = 'https://www.roadify.fr/api/v1';

// Récupérer les clients
async function getClients() {
  const response = await fetch(`${BASE_URL}/clients`, {
    headers: { 'X-API-Key': API_KEY }
  });
  const data = await response.json();
  return data.data;
}

// Créer une visite
async function createVisite(clientId, compteRendu) {
  const response = await fetch(`${BASE_URL}/visites`, {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client_id: clientId,
      compte_rendu: compteRendu,
      resultat: 'effectuee'
    })
  });
  return await response.json();
}

PHP (cURL)

$apiKey = 'votre_cle_api';
$baseUrl = 'https://www.roadify.fr/api/v1';

function roadifyRequest($endpoint, $method = 'GET', $data = null) {
    global $apiKey, $baseUrl;
    
    $ch = curl_init($baseUrl . $endpoint);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'X-API-Key: ' . $apiKey,
            'Content-Type: application/json'
        ]
    ]);
    
    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }
    
    $response = curl_exec($ch);
    curl_close($ch);
    
    return json_decode($response, true);
}

// Utilisation
$clients = roadifyRequest('/clients');
$stats = roadifyRequest('/stats?date_from=2026-01-01');

Python (requests)

import requests

API_KEY = 'votre_cle_api'
BASE_URL = 'https://www.roadify.fr/api/v1'

headers = {'X-API-Key': API_KEY}

# Récupérer les clients en retard
response = requests.get(
    f'{BASE_URL}/stats/clients-a-visiter',
    headers=headers,
    params={'limit': 10}
)
clients = response.json()['data']

# Créer une tournée
new_tournee = requests.post(
    f'{BASE_URL}/tournees',
    headers=headers,
    json={
        'nom': 'Tournée automatique',
        'client_ids': [c['id'] for c in clients]
    }
).json()

Webhooks Bientôt disponible

Les webhooks vous permettront de recevoir des notifications en temps réel lorsque des événements se produisent dans Roadify :

visite.created - Nouvelle visite enregistrée
tournee.completed - Tournée terminée
client.created - Nouveau client ajouté
client.visit_overdue - Client en retard de visite

Documentation API Roadify

Base URL

Sécurisé

Rapide

RESTful

Authentification

Sécurité

Rate Limiting

Gestion des erreurs

Clients

Paramètres de requête

Paramètres

Corps de la requête (JSON)

Tournées

Paramètres de requête

Visites

Paramètres de requête

Statistiques

Paramètres

Exemples de code

JavaScript (fetch)

PHP (cURL)

Python (requests)

Webhooks Bientôt disponible

Besoin d'aide ?