Codice di abbinamento e QR

Il QR cambia ogni 20 secondi. Offra entrambi i percorsi, perché un onboarding da un solo dispositivo non può fotografare il proprio schermo.

L'abbinamento riguarda le connessioni qr. Un numero cloud_api non scansiona mai nulla e risponde 409 not_supported_for_provider.

Il percorso con il QR

POST /connections restituisce un QR iniziale come PNG in formato data-URI.

Rigeneri il QR a ogni polling

WhatsApp cambia il codice di abbinamento circa ogni 20 secondi. Il qr nella risposta di creazione risulta scaduto pochi secondi dopo la visualizzazione, e l'errore è silenzioso: il telefono non si abbina e nulla sullo schermo ne spiega il motivo.

Interroghi GET /connections/{id} ogni 3–5 s e rigeneri il qr da ogni risposta finché status non diventa "connected". Non lo memorizzi in cache e non nasconda l'aggiornamento dietro un pulsante che l'utente deve premere.

La stessa regola vale per una ripetizione idempotente: quando POST /connections restituisce 200 con Idempotency-Replayed: true, il qr di quella risposta è stato richiesto di nuovo e non riproposto dall'archivio — proprio perché un codice memorizzato non sarebbe più scansionabile.

Il percorso con il codice di abbinamento

Un QR richiede due dispositivi: uno schermo che lo mostra e un telefono che lo fotografa. Una buona parte degli onboarding reali avviene su un solo dispositivo: il cliente completa il Suo flusso sullo stesso telefono su cui è installato WhatsApp e non può fotografare il proprio schermo. Per questi utenti il percorso con il QR non è scomodo, è impossibile.

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"
}

Il cliente apre WhatsApp → Impostazioni → Dispositivi collegati → Collega con numero di telefono e inserisce il codice.

phoneNumber è in formato E.164 senza il + iniziale: solo cifre. Qualsiasi altro formato viene rifiutato con 400 { "error": "invalid_phone_number" } invece di essere corretto automaticamente: riscrivere in silenzio il numero inviato è il modo in cui un cliente finisce per abbinare un account che nessuno aveva richiesto. Usa whatsapp.manage, come la creazione della connessione.

Il codice di abbinamento non è sempre disponibile: mantenga il QR come alternativa

Il motore può rifiutarsi di emetterne uno. È un esito normale, non un'interruzione del servizio, e risponde 502 { "error": "pairing_code_unavailable" } invece di un generico 500 proprio perché Lei possa distinguere i due casi e rimandare l'utente al QR. Un'integrazione che offre solo il percorso con il codice di abbinamento prima o poi mostrerà a un cliente una schermata senza via d'uscita. Mostri entrambi, affiancati.

Richiedere un altro codice

Può richiedere un altro codice sulla stessa connessione: restituisce un nuovo codice e non ricrea la sessione, quindi un pulsante «Inviami un altro codice» è sicuro.

Il limite è di 5 per connessione ogni 15 minuti; oltre questa soglia riceve 429 { "error": "rate_limited" } con un'intestazione Retry-After da rispettare. Il limite non è burocrazia: richiedere ripetutamente codici per uno stesso numero è esattamente ciò su cui intervengono i sistemi antiabuso di WhatsApp, e il numero a rischio è quello del Suo cliente.

Nessun consumo aggiuntivo

L'abbinamento con il codice usa lo stesso slot a pagamento e avvia la stessa prova gratuita di 7 giorni della scansione di un QR: la licenza viene associata quando il numero si abbina effettivamente, in qualunque modo sia avvenuto l'abbinamento.

Anche il controllo dell'esito non cambia. Non esiste un evento «codice accettato», quindi interroghi GET /connections/{id} finché status non diventa "connected" e/o resti in ascolto del webhook connection.connected.

Due rifiuti meritano di essere gestiti nel codice:

409 already_connected: la sessione è attiva, non c'è nulla da abbinare.
409 not_supported_for_provider: un numero cloud_api. I codici di abbinamento sono un concetto delle connessioni qr e non si applicano mai, quindi non riprovi.

Riabbinare in seguito

Una sessione qr può interrompersi da sola. Lo segnala connection.disconnected, e needs_reconnect è il campo da cui far dipendere la Sua interfaccia. Il QR non è volutamente presente in quel payload — è una credenziale di accesso tramite scansione — quindi lo recuperi da GET /connections/{id} e lo mostri al titolare del numero esattamente come durante la prima configurazione. Vedere Webhook.

Questa pagina è stata utile?