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.
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"}'{
"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 numerocloud_api. I codici di abbinamento sono un concetto delle connessioniqre 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.
Webhooks
Un unico endpoint firmato per account. Verifica della firma, catalogo degli eventi, policy di retry e rotazione del secret.
Portare un numero da un altro provider
Sposti su WASync un numero WhatsApp Business API che gestisce già presso un altro provider, con la procedura guidata nell'app, e mantenga la reputazione presso Meta.