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://www.iwana.site/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://www.iwana.site/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" }
}

Sites & équipements

Un site est une adresse où le travail a lieu : un contact en a généralement plusieurs, et c’est le site — pas le contact — qui porte le code de portail, les coordonnées GPS et les personnes à joindre sur place. Un équipement est ce qui y est installé.

Les sites suivent les scopes clients:* : un site appartient à un contact, et qui peut lire l’un peut lire l’autre. Les équipements ont leur propre paire de scopes — ajouter une ressource à un scope existant élargirait en silence les clés déjà en circulation.

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

Toute erreur a la même forme, et porte l’identifiant de la requête qui l’a produite. Citez requestId quand vous nous écrivez au sujet d’un appel : il est aussi renvoyé en en-tête X-Request-Id sur toutes les réponses, succès compris.

{
  "error": {
    "code": "site_not_found",
    "message": "site_not_found",
    "requestId": "70b0b670-ecb1-4ceb-b8a0-9096b8b56ee3"
  }
}

code est stable et destiné au code appelant ; message est pour un humain et peut changer sans préavis. Ne faites pas de logique sur le message.

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. Traitez les champs inconnus comme normaux : votre client ne doit pas échouer parce que nous en avons ajouté un.

OpenAPI

Toute cette page existe aussi sous forme lisible par une machine. Collez cette URL dans Postman, Insomnia, Swagger UI ou un générateur de SDK — vous n’avez pas à recopier les schémas à la main.

curl https://www.iwana.site/api/v1/openapi.json

Ouvrir openapi.json

Le document est servi sans authentification : une spécification qu’il faut une clé pour lire est une spécification que personne n’évalue avant de s’inscrire. Il ne décrit que des formes — aucune donnée d’espace de travail n’y transite.