API REST v1

Démarrage rapide

Trois étapes pour votre première requête réussie. Tout se configure depuis le tableau de bord pro.

1. Créez une clé APIParamètres → Développeurs → Nouvelle clé. Copiez le secret immédiatement — il n’est affiché qu’une fois.
2. Testez l’authentificationAppelez GET /integrations/me pour vérifier l’organisation et les permissions actives.
3. Synchronisez vos donnéesLisez le catalogue et l’équipe, créez ou mettez à jour clients et rendez-vous, puis abonnez un webhook pour les mises à jour temps réel.

curl -s https://votre-domaine.iwana.fr/api/v1/pro/integrations/me \
  -H "Authorization: Bearer iw_live_xxxxxxxx_your_secret_here"

Authentification

Chaque requête doit inclure une clé API organisationnelle dans l’en-tête Authorization. Pas de flux OAuth, pas de refresh token : révoquez une clé compromise en un clic depuis le tableau de bord.

Authorization: Bearer iw_live_<prefix>_<secret>

L’organisation est embarquée dans la clé : vous n’avez pas besoin d’envoyer x-workspace-id ni d’autres en-têtes de contexte.

Scopes

Chaque clé porte un ensemble de scopes au moment de la création. Un endpoint refusé renvoie 403 si le scope requis est absent.

Bundle par défaut à la création : lecture/écriture RDV et clients, lecture catalogue et équipe.

URL de base

Tous les endpoints vivent sous le préfixe PRO :

https://<votre-domaine>/api/v1/pro

Les exemples ci-dessous omettent ce préfixe pour la lisibilité.

Vérifier votre clé

{
  "orgId": "org_…",
  "actor": { "type": "api_key", "id": "key_…" },
  "permissions": ["appointment:read", "appointment:write", …],
  "locale": "fr",
  "timezone": "Europe/Paris"
}

Rendez-vous

CRUD sur les rendez-vous de type APPOINTMENT uniquement (pas les blocs d’indisponibilité). La source est automatiquement marquée API lors d’un appel par clé.

Corps de création

{
  "serviceId": "svc_…",
  "clientId": "cli_…",
  "startAt": "2026-08-10T09:00:00.000Z",
  "endAt": "2026-08-10T10:00:00.000Z",
  "memberIds": ["mem_…"],
  "customFields": { "crmDealId": "42" },
  "internalNotes": "Synchronisé depuis le CRM"
}

Clients

Gérez la fiche client pour alimenter vos rendez-vous et garder le CRM aligné.

Exemple de création

{
  "firstName": "Marie",
  "lastName": "Dupont",
  "email": "marie@exemple.fr",
  "phone": "+33612345678",
  "customFields": { "hubspotId": "12345" }
}

Catalogue & équipe

Données de référence en lecture seule — utiles pour mapper vos IDs avant de créer des rendez-vous.

Mapping IDs externes

Pour une synchronisation CRM idempotente, stockez la correspondance entre vos IDs et ceux d’Iwana. Évite les doublons quand le même contact est reçu plusieurs fois.

PUT /external-refs
{
  "provider": "hubspot",
  "entityType": "client",
  "localId": "cli_…",
  "externalId": "12345"
}

Webhooks sortants

Abonnez une URL HTTPS depuis Paramètres → Développeurs. Iwana envoie un POST JSON à chaque événement métier, signé pour que vous puissiez vérifier l’authenticité.

Événements disponibles

En-têtes de livraison

Iwana-Signature: sha256=<hmac-sha256 du corps brut>
Iwana-Event: appointment.created
Iwana-Delivery: <uuid unique par tentative>

Corps de l’événement

{
  "event": "appointment.created",
  "orgId": "org_…",
  "data": {
    "id": "apt_…",
    "startAt": "2026-08-10T09:00:00.000Z",
    "status": "PENDING"
  },
  "occurredAt": "2026-08-07T12:00:00.000Z"
}

Erreurs

Les réponses d’erreur sont en JSON avec un code machine lisible quand c’est pertinent.

Versioning

Version actuelle : v1 (/api/v1/pro/…). Les changements incompatibles seront publiés sous /v2/ avec une période de chevauchement d’au moins 12 mois sur v1.

Les ajouts rétro-compatibles (nouveaux champs optionnels, nouveaux endpoints) peuvent arriver sans bump de version majeure.