Code d'appairage et QR

Le QR change toutes les 20 secondes. Proposez les deux méthodes, car une intégration sur un seul appareil ne peut pas photographier son propre écran.

L'appairage concerne les connexions qr. Un numéro cloud_api ne scanne jamais rien et répond 409 not_supported_for_provider.

La méthode par QR

POST /connections renvoie un premier QR sous forme de PNG en data-URI.

Régénérez le QR à chaque interrogation

WhatsApp renouvelle le code d'appairage environ toutes les 20 secondes. Le qr de la réponse de création est périmé quelques secondes après son affichage, et l'échec est silencieux : le téléphone ne s'appaire jamais et rien à l'écran n'explique pourquoi.

Interrogez GET /connections/{id} toutes les 3 à 5 s et régénérez l'image du qr à partir de chaque réponse, jusqu'à ce que status vaille "connected". Ne le mettez pas en cache et ne cachez pas l'actualisation derrière un bouton que l'utilisateur doit presser.

La même règle s'applique à un rejeu idempotent : lorsque POST /connections renvoie 200 avec Idempotency-Replayed: true, le qr de cette réponse a été récupéré à nouveau, et non rejoué depuis le stockage — précisément parce qu'un code stocké ne pourrait plus être scanné.

La méthode par code d'appairage

Un QR demande deux appareils : un écran qui l'affiche et un téléphone qui le photographie. Une bonne part des intégrations réelles se déroulent sur un seul appareil : le client termine votre parcours sur le téléphone même où tourne WhatsApp, et ne peut pas photographier son propre écran. Pour lui, la méthode par QR n'est pas pénible, elle est impossible.

POST /connections/{id}/pairing-code

curl -X POST https://developers.wasync.app/api/v1/connections/conn_8f3a21/pairing-code \
  -H "Authorization: Bearer $WASYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"40740267964"}'

200 response

{
  "code": "7S59-1KZP"
}

Le client ouvre WhatsApp → Paramètres → Appareils connectés → Connecter avec le numéro de téléphone et saisit le code.

phoneNumber est au format E.164 sans le + initial : uniquement des chiffres. Toute autre valeur est rejetée avec 400 { "error": "invalid_phone_number" } au lieu d'être corrigée à votre place : réécrire silencieusement le numéro envoyé, c'est ainsi qu'un client finit par appairer un compte que personne n'a demandé. Utilise whatsapp.manage, comme la création de la connexion.

Un code d'appairage n'est pas toujours disponible — gardez le QR en secours

Le moteur peut refuser d'en émettre un. C'est un cas ordinaire, pas une panne, et il répond 502 { "error": "pairing_code_unavailable" } plutôt qu'une erreur 500 générique, justement pour que vous puissiez distinguer les deux et renvoyer l'utilisateur vers le QR. Une intégration qui ne propose que le code d'appairage finira tôt ou tard par montrer à un client un écran sans issue. Affichez les deux, côte à côte.

Demander un autre code

Vous pouvez demander un autre code sur la même connexion : cela renvoie un nouveau code sans reconstruire la session, de sorte qu'un bouton « Envoyez-moi un autre code » est sans danger.

La limite est de 5 par connexion et par tranche de 15 minutes ; au-delà, vous recevez 429 { "error": "rate_limited" } avec un en-tête Retry-After à respecter. Cette limite n'est pas de la bureaucratie : demander des codes à répétition pour un même numéro est exactement ce que les systèmes anti-abus de WhatsApp sanctionnent, et le numéro en danger est celui de votre client.

Rien de plus n'est consommé

L'appairage par code utilise le même emplacement payant et démarre le même essai gratuit de 7 jours que le scan d'un QR : la licence est réclamée quand le numéro s'appaire réellement, quelle que soit la méthode utilisée.

Le suivi de la réussite ne change pas non plus. Il n'existe pas d'événement « code accepté » : interrogez donc GET /connections/{id} jusqu'à ce que status vaille "connected" et/ou écoutez le webhook connection.connected.

Deux refus méritent d'être gérés dans votre code :

409 already_connected : la session est active, il n'y a rien à appairer.
409 not_supported_for_provider : un numéro cloud_api. Les codes d'appairage sont propres aux connexions qr et ne s'appliquent jamais ici ; ne réessayez donc pas.

Réappairer plus tard

Une session qr peut se rompre d'elle-même. connection.disconnected vous en informe, et needs_reconnect est le champ à utiliser pour piloter votre interface. Le QR ne figure volontairement pas dans cette charge utile : c'est un identifiant de connexion par scan. Récupérez-le donc via GET /connections/{id} et présentez-le au propriétaire du numéro exactement comme lors de la première configuration. Voir Webhooks.

Cette page vous a-t-elle été utile ?