API WAD — Guide d'intégration

L'API WAD permet à des systèmes externes de lire et d'écrire des données dans votre espace WAD de manière programmatique, sans passer par l'interface web. Elle suit le standard REST et échange des données au format JSON.

Pourquoi utiliser l'API ?

• Synchroniser WAD avec un CRM, un ERP ou un outil de facturation
• Importer automatiquement des clients et des chantiers depuis une source externe
• Exporter les données de terrain vers un outil de reporting ou de BI
• Créer des automatisations (ex. : créer un projet WAD dès qu'une commande est validée)
• Développer des applications personnalisées qui s'appuient sur les données WAD

📖 Documentation interactive (Swagger) :

Documentation (Swagger)

🔐 Authentification

Chaque appel à l'API requiert deux éléments d'identification passés dans les headers HTTP :

Obtenir un token JWT

Avant tout autre appel, authentifiez-vous pour récupérer un token :

POST /api/index.php/v2/public/login

// Header requis
X-API-KEY: votre_clé_api

// Réponse
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Ce token doit ensuite être inclus dans tous les appels suivants via Authorization: Bearer {token}.

⚠️ Les tokens JWT ont une durée de vie limitée. Prévoyez une gestion automatique des erreurs 401 pour vous ré-authentifier.

📋 Endpoints disponibles

Tous les endpoints retournent un objet JSON avec les champs data, total et has_more. La pagination se fait via le paramètre ?page=N.

👤 Clients

Gérez le référentiel clients de votre organisation.

Champs obligatoires (création) : name, email, address_street, address_zip, address_city, address_country_code.

📍 Points de Travail (POW)

Un POW représente un site physique rattaché à un client (adresse de chantier, site d'intervention…).

Champs obligatoires : customer_id, address_street, address_zip, address_city, address_country_code. Les champs geo_latitude / geo_longitude sont optionnels mais recommandés.

🗂️ Projets

Les projets sont le cœur opérationnel de WAD. Chaque projet est rattaché à un client et peut être lié à des POW et des catégories d'actions.

Champs obligatoires (création) : customer_id, type_id, name. Statut possible : OPEN ou CLOSED.

⚡ Actions & Catégories d'actions

Les actions représentent les tâches réalisables sur le terrain, organisées en catégories.

📅 Événements de projet

Journalisez des jalons ou faits marquants sur un projet (visite client, réception de chantier…).

🖼️ Médias (photos)

Accédez aux photos prises par les équipes de terrain, associées à des travaux ou à des Todo Memos.

Le paramètre ?size=bigs|mediums permet de choisir la résolution souhaitée.

📆 Plannings, équipe & tags

📦 Format des réponses

Toutes les réponses suivent une structure cohérente :

// Réponse liste
{
  "data":     [ { ... }, { ... } ],  // tableau d'objets
  "total":    42,                    // nombre total d'enregistrements
  "has_more": true                  // s'il reste des pages
}

// Réponse création / mise à jour
{
  "data": { "id": 123 }              // ID de la ressource créée/modifiée
}

Codes HTTP

💡 Exemple d'intégration

Exemple complet en JavaScript : authentification puis création d'un client avec son chantier.

const BASE_URL = 'https://app.wad.work/api/v2/public';
const API_KEY  = 'votre_clé_api';

// 1. Authentification
const { token } = await fetch(`${BASE_URL}/login`, {
  method: 'POST',
  headers: { 'X-API-KEY': API_KEY }
}).then(r => r.json());

const headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': API_KEY,
  'Authorization': `Bearer ${token}`
};

// 2. Créer le client avec son premier POW
const { data } = await fetch(`${BASE_URL}/customers`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name:                 'Dupont SA',
    email:                '[email protected]',
    address_street:       'Rue de la Paix 12',
    address_zip:          '1000',
    address_city:         'Bruxelles',
    address_country_code: 'BE',
    pows: [{
      address_street:       'Chaussée de Namur 45',
      address_zip:          '1400',
      address_city:         'Nivelles',
      address_country_code: 'BE'
    }]
  })
}).then(r => r.json());

console.log('Client créé, ID :', data.id);
console.log('POW créé, ID :',    data.pow_ids[0]);

✅ Bonnes pratiques

Pagination

Toutes les listes sont paginées. Parcourez les pages en incrémentant ?page=N jusqu'à ce que has_more soit false. Ne supposez jamais recevoir tous les enregistrements en un seul appel.

Identifiants externes

Les endpoints Actions et Projets exposent les champs id_external et ref_external. Utilisez-les pour stocker les identifiants de votre système source — cela facilite la synchronisation bidirectionnelle sans table de correspondance externe.

Sécurité

• Ne jamais exposer votre X-API-KEY dans du code client (navigateur, app mobile).
• Toutes les communications doivent se faire via HTTPS.
• Gérez les erreurs 401 automatiquement en vous ré-authentifiant.