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. Vous publiez un produit que plusieurs entreprises installeront ? Passez par OAuth, ci-dessous.
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://iwana.fr/v3/api/v1/pro/integrations/me \
  -H "Authorization: Bearer iw_live_xxxxxxxx_your_secret_here"

Authentification

Deux façons d’atteindre un espace de travail, qui arrivent sur la même API, les mêmes routes /pro/* et les mêmes contrôles de permission. Une clé API nomme l’espace de travail ; un jeton OAuth nomme l’utilisateur, l’espace de travail et votre application. Ni l’un ni l’autre ne gère les identifiants (clés API, webhooks, plugins) ni n’invoque l’IA : ces actions restent dans l’application.

Authorization: Bearer iw_live_<prefix>_<secret>

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

OAuth 2.0 — Sign in with IWANA

Authorization Code avec secret client. PKCE (S256) est honoré quand le client l’envoie, sans être obligatoire. Les jetons sont opaques : pas d’OpenID Connect, pas de JWKS, pas d’id_token — l’identité vient de GET /oauth/userinfo. Le jeton ouvre toute l’API décrite ici, dans la limite du rôle de l’utilisateur : le jeton d’un VIEWER ne peut pas écrire.

1. Enregistrer votre application

L’équipe Iwana crée l’application : nom, logo, jusqu’à cinq redirect_uri comparées à l’identique (http ou https, sans fragment). Vous recevez un client_id (iwa_…) et un client_secret (iwa_cs_…) — le secret n’est affiché qu’une fois et stocké haché. Toutes les applications sont confidentielles : le secret est requis au token endpoint, PKCE s’y ajoute mais ne le remplace pas.

Écrivez à [email protected] avec le nom de l’application, un logo et vos URL de retour.

2. Envoyer l’utilisateur vers Iwana

GET https://iwana.fr/v3/oauth/authorize
    ?client_id=iwa_…
    &redirect_uri=https://crm.example/auth/iwana/callback
    &response_type=code
    &state=<random>
    &code_challenge=<S256>&code_challenge_method=S256

Pas de paramètre scope : le jeton couvre toute l’API. Un client_id inconnu ou une redirect_uri non enregistrée affiche une page sans issue et ne redirige jamais. Un utilisateur sans espace PRO voit « réservé aux professionnels » ; avec plusieurs espaces, il choisit lequel autoriser. Un consentement déjà accordé saute la carte.

Le navigateur revient sur redirect_uri?code=iwa_ac_…&state=…, ou ?error=access_denied&state=… si l’utilisateur a refusé. Le code vit 60 secondes et ne sert qu’une fois.

3. Échanger le code

POST https://iwana.fr/v3/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=iwa_ac_…&redirect_uri=<same as step 2>
&client_id=iwa_…&client_secret=iwa_cs_…&code_verifier=…

{
  "access_token": "iwa_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "iwa_rt_…",
  "scope": "…"
}

Envoyez code_verifier seulement si vous avez envoyé un code_challenge à l’étape 2. Le client peut s’authentifier dans le corps ou en HTTP Basic.

4. Appeler l’API

GET https://iwana.fr/v3/api/v1/pro/clients
Authorization: Bearer iwa_at_…

Pas d’en-tête x-workspace-id : le jeton porte l’espace de travail. Les écritures faites ainsi sont attribuées à votre application dans le journal d’audit, et un rendez-vous créé ainsi porte source: API.

5. Rafraîchir

grant_type=refresh_token&refresh_token=iwa_rt_…&client_id=iwa_…&client_secret=iwa_cs_…

Renvoie un nouvel access_token ; le refresh_token reste le même. Après trois ans, ou une fois le grant révoqué, la réponse est invalid_grant et l’utilisateur doit se reconnecter. Rafraîchissez à l’heure, pas à chaque requête : le token endpoint a sa propre limite, bien plus basse.

Qui est connecté

GET https://iwana.fr/v3/api/v1/oauth/userinfo
Authorization: Bearer iwa_at_…

{
  "sub": "<user id>", "email": "…", "email_verified": true, "name": "…", "picture": null,
  "org_id": "<workspace id>", "org_name": "Plomberie Dupont", "role": "OWNER",
  "scope": "…"
}

sub + org_id est la paire à lier à votre propre fiche utilisateur.

Erreurs OAuth

Le token endpoint parle RFC 6749 : { "error": "invalid_grant", "error_description": "…" } avec invalid_request, invalid_client (401, avec WWW-Authenticate), invalid_grant, unsupported_grant_type. Un bearer refusé sur une route PRO est un 401 avec l’enveloppe habituelle { "error": { "code": "invalid_token" } }.

Durées de vie

Révocation

Il n’y a pas d’endpoint de révocation : l’admin de l’espace coupe votre application depuis Paramètres → Développeurs → Applications connectées, et l’équipe Iwana peut désactiver l’application partout. Dans les deux cas, chaque jeton est refusé dès la requête suivante, y compris un access token fraîchement rafraîchi. Un membre retiré ou suspendu perd ses jetons de la même manière.

Avec une librairie générique

Tout client OAuth 2.0 standard fonctionne. Deux configurations prêtes à coller :

Passport (passport-oauth2)

new OAuth2Strategy({
  authorizationURL: 'https://iwana.fr/v3/oauth/authorize',
  tokenURL: 'https://iwana.fr/v3/api/v1/oauth/token',
  clientID, clientSecret, callbackURL,
  pkce: true, state: true,
}, async (accessToken, refreshToken, _profile, done) => {
  const me = await fetch('https://iwana.fr/v3/api/v1/oauth/userinfo', {
    headers: { authorization: `Bearer ${accessToken}` },
  }).then((r) => r.json());
  done(null, { id: me.sub, orgId: me.org_id, accessToken, refreshToken });
});

NextAuth / Auth.js

{
  id: 'iwana', name: 'IWANA', type: 'oauth',
  authorization: 'https://iwana.fr/v3/oauth/authorize',
  token: 'https://iwana.fr/v3/api/v1/oauth/token',
  userinfo: 'https://iwana.fr/v3/api/v1/oauth/userinfo',
  clientId, clientSecret, checks: ['pkce', 'state'],
  profile: (p) => ({ id: p.sub, email: p.email, name: p.name, image: p.picture }),
}

URL de base

Tous les endpoints vivent sous le préfixe PRO :

https://iwana.fr/v3/api/v1/pro

Les exemples ci-dessous omettent ce préfixe pour la lisibilité. Les identifiants (`id`, `clientId`, `orgId`…) sont des chaînes opaques sans préfixe : stockez-les tels quels, ne les analysez pas.

Vérifier votre clé

{
  "orgId": "<workspace id>",
  "actor": { "kind": "api_key", "id": "<key id>" },
  "permissions": ["appointment:read", "appointment:write", …],
  "locale": "fr",
  "timezone": "Europe/Paris"
}

Règles communes

Ce qui vaut pour toutes les routes, et que la spécification OpenAPI décrit opération par opération.

Listes et pagination

Une liste sans kind sur /clients ne renvoie que les particuliers : envoyez kind=ALL pour les entreprises aussi. Le schéma de réponse de chaque opération dit laquelle de ces formes elle renvoie.

Équipe

Membres de l’espace et équipes : l’identifiant d’adhésion d’un membre est ce qu’attendent les memberIds d’un rendez-vous. Une clé peut aussi inviter et organiser l’équipe.

Rendez-vous

Les rendez-vous (type=APPOINTMENT) et les créneaux bloqués (type=UNAVAILABILITY, y compris ceux importés de Google ou Outlook) passent par les mêmes routes ; les listes renvoient les rendez-vous sauf si vous demandez type=UNAVAILABILITY. La source est marquée API lors d’un appel par clé ou par jeton, sauf si le corps envoie la sienne.

Corps de création

{
  "serviceId": "<service id>",
  "clientId": "<client id>",
  "startAt": "2026-08-10T09:00:00.000Z",
  "endAt": "2026-08-10T10:00:00.000Z",
  "memberIds": ["<member id>"],
  "customFields": { "crmDealId": "42" },
  "internalNotes": "Synced from CRM"
}

Clients

Le carnet d’adresses. /clients porte les particuliers (kind=INDIVIDUAL) et les entreprises (kind=COMPANY) ; /companies en est la vue entreprise, /contacts les personnes rattachées à un compte. Un client n’est pas un membre de l’équipe : pour un collègue, voir POST /team/members/invite.

Exemple de création

{
  "firstName": "Marie",
  "lastName": "Dupont",
  "email": "[email protected]",
  "phone": "+33612345678",
  "customFields": { "hubspotId": "12345" }
}

Sites, équipements & contrats

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é, un contrat d’entretien ce qui le couvre.

Un site appartient à un contact ou à une entreprise, et un équipement à un client et éventuellement à l’un de ses sites : créez le contact avant le site, et filtrez les équipements par ?siteId= pour retrouver ceux d’une adresse. Équipements et contrats demandent les modules ERP.

Chantiers & tâches

Un chantier regroupe phases, ouvrages, pièces, réserves, métrés, documents, intervenants et entreprises partenaires. Les tâches de /tasks sont la liste de choses à faire de l’espace, distincte des ouvrages d’un chantier.

Une quarantaine d’opérations au total sur les chantiers : la spécification OpenAPI les liste toutes, groupe « Chantiers ».

Configuration, catalogue, workflows & communications

Catalogue (prestations, lieux, catégories, spécialités — à lire pour mapper vos IDs avant de créer des rendez-vous, et modifiable par une clé), règles métier, champs personnalisés, automatisations et messages envoyés aux clients.

La rédaction de workflows par l’IA n’est pas ouverte aux clés. Les envois de test de /communications/notifications/…/test partent réellement (un SMS est facturé) : envoyez to, une clé n’a pas d’adresse de compte.

Statistiques, journal & géo

Indicateurs du tableau de bord, journal d’activité de l’espace et outils d’adresse.

Les chiffres sont ceux du tableau de bord, recalculés à chaque appel : mettez-les en cache plutôt que de les relire en boucle.

Mapping IDs externes

Iwana ne dédoublonne pas à votre place : POST /clients sans id crée toujours. Pour une synchronisation idempotente, stockez la correspondance entre vos IDs et ceux d’Iwana, et consultez-la avant de créer.

PUT /external-refs
{
  "provider": "hubspot",
  "entityType": "client",
  "localId": "<client id>",
  "externalId": "12345"
}

provider et entityType sont du texte libre (hubspot, client…) : choisissez des valeurs et gardez-les.

Webhooks sortants

Abonnez une URL HTTPS depuis Paramètres → Développeurs. Iwana envoie un POST JSON à chaque événement, signé pour que vous puissiez vérifier l’authenticité. Le corps est toujours { event, orgId, data, occurredAt }. data reste court : l’id de l’enregistrement, les ids liés, le statut, des dates ISO et des montants en centimes — pas de nom, de note ni d’adresse, sauf l’email et le nom d’un contact dans client.created / client.updated. Relisez l’enregistrement par GET si vous avez besoin de tout.

Événements disponibles

En-têtes de livraison

Iwana-Signature: sha256=<hex hmac-sha256 of the raw body>
Iwana-Event: appointment.created
Iwana-Delivery: <uuid, unique per attempt>

Corps de l’événement

{
  "event": "appointment.created",
  "orgId": "<workspace id>",
  "data": {
    "id": "<appointment id>",
    "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.

Limites de débit

Le budget appartient à l’espace de travail, et toutes ses clés API et jetons OAuth dépensent le même. Les personnes qui utilisent le tableau de bord ont chacune le leur : une intégration qui boucle ne peut pas bloquer son propre client.

Ce sont les valeurs par défaut ; l’équipe Iwana peut les changer pour toute la plateforme, lisez donc les en-têtes X-RateLimit-Limit* plutôt que de coder les nombres en dur. Au-delà de l’une des fenêtres, la réponse est 429 avec l’enveloppe habituelle, error.code = "rate_limited", et un en-tête Retry-After en secondes. Un plancher par IP de 1 000 requêtes/minute s’applique aussi avant authentification, sous les mêmes noms d’en-têtes sans suffixe : un appel refusé par le contrôle de la clé ou des permissions (401, un 403 comme test_key_read_only, un 402) ne porte que ces en-têtes par IP — aucun -Day — et ne consomme pas le budget de l’espace.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 12

{ "error": { "code": "rate_limited", "message": "…", "requestId": "…" } }

Rythmez-vous sur X-RateLimit-Remaining et reculez sur 429. Rafraîchissez les access tokens à l’heure, pas à chaque requête.

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 d’une réponse comme normaux : votre client ne doit pas échouer parce que nous en avons ajouté un. Dans une requête, c’est l’inverse : un champ non déclaré est refusé en 400 validation_failed.

OpenAPI

Toute cette page existe aussi sous forme lisible par une machine, et en plus complet : la spécification liste chaque opération qu’une clé peut appeler — près de 300 —, avec ses paramètres, son corps et sa réponse. 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://iwana.fr/v3/api/v1/openapi.json

Référence interactive (Swagger) 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.

Prompts pour agents IA

Vous construisez l’intégration avec Claude, Cursor, Copilot ou un autre agent de code ? Ces prompts lui donnent le contrat exact de l’API pour qu’il n’ait pas à le deviner. Copiez, remplacez ce qui est entre chevrons, collez.

Commencez toujours par la fiche de contexte : elle tient dans un message système ou en tête de conversation, et chaque prompt de tâche s’appuie dessus.

Tu vas m'aider à intégrer l'API REST d'Iwana (SaaS de prise de rendez-vous pour artisans, France/UE). Voici le contrat ; ne suppose rien qui n'y figure pas — lis d'abord la spécification OpenAPI.

- Spécification OpenAPI (source de vérité pour chaque schéma) : https://iwana.fr/v3/api/v1/openapi.json
- Documentation humaine : https://iwana.fr/developers/api
- URL de base : https://iwana.fr/v3/api/v1/pro — toutes les routes ci-dessous sont relatives à ce préfixe.
- Authentification : en-tête "Authorization: Bearer <jeton>". Deux formes de jeton, mêmes routes, mêmes permissions :
  - clé API d'espace de travail "iw_live_…", créée dans Paramètres → Développeurs ; une clé de test "iw_test_…" lit le même espace réel et se voit refuser toute écriture (403 test_key_read_only, avant la validation du corps) — il n'existe pas d'espace de démonstration ;
  - access token OAuth 2.0 "iwa_at_…" obtenu par Authorization Code (autorisation : https://iwana.fr/v3/oauth/authorize ; token : POST https://iwana.fr/v3/api/v1/oauth/token en form-urlencoded ; identité : GET https://iwana.fr/v3/api/v1/oauth/userinfo). Access token 1 h, refresh token 3 ans et inchangé au refresh, PKCE S256 optionnel.
- Aucun en-tête x-workspace-id : le jeton porte l'espace de travail.
- Health-check : GET /integrations/me renvoie orgId, acteur, permissions, locale, fuseau.
- Une clé ou un jeton donne accès à toute l'API de la spécification (rendez-vous, clients, sites, équipements, contrats, catalogue, équipe, devis, factures, interventions, chantiers, tâches, workflows, réglages). Un 403 signifie que le rôle de l'utilisateur (jeton OAuth) ou une clé de test (lecture seule) refuse l'action. Une clé n'appelle jamais l'IA. Un 402 erp_required signifie que l'offre de l'espace n'a pas les modules ERP ; un 403 offer_disabled signifie que l'offre est désactivée sur toute la plateforme.
- Erreurs : toujours { "error": { "code": "…", "message": "…", "requestId": "…" } }. "code" est stable, "message" ne l'est pas : ne jamais brancher de logique sur "message". X-Request-Id est présent sur toutes les réponses.
- Limites : 600 requêtes/minute et 50 000/jour par espace de travail, partagées entre toutes ses clés et jetons. Lire X-RateLimit-Remaining et X-RateLimit-Remaining-Day ; sur 429, respecter Retry-After (secondes). Un 401/403 refusé avant le décompte du budget de l'espace ne porte que les en-têtes X-RateLimit-* par IP, sans les -Day.
- Nouvelles tentatives : envoyer un en-tête Idempotency-Key (8 à 128 caractères) sur les POST de création (rendez-vous, clients, contacts, entreprises, sites, équipements, contrats, devis, factures, paiements, interventions, chantiers, tâches) ; la même clé sur la même route dans les 48 h renvoie la première réponse au lieu de créer un doublon.
- Doublons : POST /clients sans id crée toujours, il ne rapproche jamais par email ou téléphone. Stocker la correspondance entre mes IDs et ceux d'Iwana via PUT /external-refs { provider, entityType, localId, externalId } et la résoudre avec GET /external-refs?provider=&entityType=&externalId= avant de créer ; sans correspondance la réponse est { "item": null } (200, pas 404).
- Listes : chaque opération a sa taille de page et sa forme ({ items, total } avec ou sans limit/offset, { items } ou tableau) : la lire dans la spécification, ne pas supposer.
- Dates en ISO 8601 UTC ; montants "…Cents" en centimes. Champ non déclaré dans un corps de requête : 400 validation_failed, donc n'envoyer que les champs du schéma. Champs inconnus dans une réponse : les ignorer, jamais échouer.
- Webhooks entrants : POST JSON signé ; en-têtes Iwana-Signature (sha256=<HMAC-SHA256 du corps brut>), Iwana-Event, Iwana-Delivery. Vérifier la signature sur le corps BRUT, répondre 2xx en moins de 15 s, traiter en asynchrone. Une seule tentative de livraison, sans nouvelle tentative automatique : prévoir une réconciliation périodique via les endpoints de liste.
- Ne jamais logger une clé, un secret client ou un jeton.

Mon système à connecter : <CRM / ERP / outil>.

En t'appuyant sur la fiche de contexte Iwana ci-dessus, implémente une synchronisation bidirectionnelle entre <mon système> et Iwana avec une clé API d'espace de travail.

Exigences :
1. Au démarrage, appelle GET /integrations/me et arrête-toi avec un message clair si les permissions ne contiennent pas ce dont la synchro a besoin.
2. Lis le catalogue (GET /catalog/services) et l'équipe (GET /team) une fois et mets-les en cache pour mapper mes IDs de prestations et d'intervenants.
3. Pour chaque contact de <mon système> : résous d'abord GET /external-refs?provider=<mon-provider>&entityType=client&externalId=<id> ; si item est null, POST /clients (avec un Idempotency-Key dérivé de mon id) puis PUT /external-refs ; sinon POST /clients avec l'id Iwana pour mettre à jour. Iwana ne rapproche pas par email : ne crée jamais deux fois le même contact.
4. Même schéma pour les rendez-vous (POST /appointments avec serviceId, clientId, startAt/endAt en ISO 8601 UTC, memberIds, customFields.<monId>, et Idempotency-Key). Pour une modification, renvoie toujours startAt et endAt.
5. Respecte le budget : lis X-RateLimit-Remaining, ralentis quand il descend sous 10 %, et sur 429 attends Retry-After avant de réessayer. Ne réessaie jamais un 400 ou un 403.
6. Journalise requestId de chaque erreur, jamais la clé.

Commence par lister les endpoints que tu vas appeler et dans quel ordre, puis implémente.

En t'appuyant sur la fiche de contexte Iwana ci-dessus, implémente « Sign in with IWANA » (Authorization Code avec secret client, PKCE S256 activé).

Contrat :
- Redirige l'utilisateur vers https://iwana.fr/v3/oauth/authorize?client_id=<CLIENT_ID>&redirect_uri=<URI enregistrée à l'identique>&response_type=code&state=<aléatoire>&code_challenge=<S256>&code_challenge_method=S256
- Au retour sur redirect_uri : vérifie state ; si ?error=access_denied, affiche un message et n'échange rien. Le code (iwa_ac_…) vit 60 s et ne sert qu'une fois.
- Échange : POST https://iwana.fr/v3/api/v1/oauth/token, Content-Type application/x-www-form-urlencoded, grant_type=authorization_code&code=…&redirect_uri=<même valeur>&client_id=…&client_secret=…&code_verifier=…
  Réponse : { access_token: "iwa_at_…", token_type: "Bearer", expires_in: 3600, refresh_token: "iwa_rt_…", scope: "…" }
- Identité : GET https://iwana.fr/v3/api/v1/oauth/userinfo avec le bearer → { sub, email, name, org_id, org_name, role, scope }. Lie mon compte utilisateur à la paire (sub, org_id).
- Refresh : grant_type=refresh_token&refresh_token=…&client_id=…&client_secret=… → nouvel access_token, le refresh_token reste le même. Rafraîchis à l'expiration (1 h), pas à chaque requête.
- Erreurs du token endpoint : { error, error_description } avec invalid_request, invalid_client (401), invalid_grant, unsupported_grant_type. Sur invalid_grant au refresh, le grant a été révoqué ou a expiré : marque la connexion comme à refaire et renvoie l'utilisateur vers l'autorisation.
- Un 401 invalid_token sur une route de l'API avec un access token non expiré signifie que l'espace de travail a révoqué l'application : même traitement.
- Conserve access_token, refresh_token, expires_at, sub et org_id par connexion ; ne logge jamais un jeton ni le secret client.

Gère chaque cas ci-dessus : state invalide, access_denied, expiration du code, expiration du jeton et révocation.

En t'appuyant sur la fiche de contexte Iwana ci-dessus, implémente un récepteur de webhooks Iwana.

Contrat de livraison :
- POST JSON sur mon URL HTTPS. En-têtes : Iwana-Signature: sha256=<HMAC-SHA256 hex du corps brut avec mon secret d'abonnement>, Iwana-Event: <type>, Iwana-Delivery: <uuid unique par tentative>.
- Corps : { "event": "appointment.created", "orgId": "…", "data": { "id": "…", "startAt": "…", "status": "…" }, "occurredAt": "…" }
- Événements : la liste à jour est dans x-iwana-webhook-events de https://iwana.fr/v3/api/v1/openapi.json (par exemple appointment.created, appointment.cancelled, client.updated) ; data porte toujours l'id de l'enregistrement, avec des ids liés, le statut, des dates ISO et des montants en centimes.
- Une seule tentative par événement, timeout 15 s, pas de nouvelle tentative automatique : un événement manqué doit être rattrapé par réconciliation.

Exigences :
1. Lis le corps BRUT (avant tout parsing JSON) et compare le HMAC en temps constant ; réponds 401 si la signature ne correspond pas.
2. Réponds 2xx immédiatement après avoir mis l'événement en file ; traite en asynchrone.
3. Traite chaque Iwana-Delivery une seule fois (stocke les IDs traités) par précaution.
4. Pour chaque événement, recharge l'objet complet via le GET correspondant (GET /appointments/{id}, GET /clients/{id}…) plutôt que de faire confiance au payload partiel ; ignore les types d'événement que tu ne traites pas.
5. Ne logge jamais le secret d'abonnement.
6. Ajoute une réconciliation périodique (GET /appointments?from=&to=, GET /clients) pour rattraper les événements manqués.

En t'appuyant sur la fiche de contexte Iwana ci-dessus, construis un client pour l'API PRO d'Iwana à partir de sa spécification OpenAPI.

1. Télécharge https://iwana.fr/v3/api/v1/openapi.json et ne garde que les chemins qui commencent par /pro/ : ils sont relatifs à l'URL de base https://iwana.fr/v3/api/v1 (les routes OAuth https://iwana.fr/v3/api/v1/oauth/token et https://iwana.fr/v3/api/v1/oauth/userinfo n'y figurent pas, elles sont décrites plus haut).
2. Dérive chaque type de requête et de réponse de la spécification plutôt que de les écrire à la main, pour pouvoir régénérer le client quand la spécification change.
3. Le client doit : injecter "Authorization: Bearer <jeton>", lire X-RateLimit-Remaining et attendre Retry-After sur 429, transformer l'enveloppe { error: { code, message, requestId } } en une erreur typée portant code et requestId, et ignorer les champs inconnus.
4. Vérifie le client contre l'API réelle avec GET /integrations/me et une clé iw_test_ que je te fournis.

Montre-moi d'abord la liste des opérations retenues, puis le client.