Código de emparejamiento y QR

El QR rota cada 20 segundos. Ofrezca ambas vías, porque una incorporación desde un solo dispositivo no puede fotografiar su propia pantalla.

El emparejamiento se aplica a las conexiones qr. Un número cloud_api nunca escanea nada y responde 409 not_supported_for_provider.

La vía del QR

POST /connections devuelve un QR inicial como PNG en data-URI.

Vuelva a generar el QR en cada consulta

WhatsApp rota el código de emparejamiento aproximadamente cada 20 segundos. El qr de la respuesta de creación queda obsoleto a los pocos segundos de mostrarse, y esto falla en silencio: el teléfono nunca se empareja y nada en pantalla explica por qué.

Consulte GET /connections/{id} cada 3–5 s y vuelva a generar el qr con cada respuesta hasta que status sea "connected". No lo guarde en caché ni oculte la actualización detrás de un botón que el usuario deba pulsar.

La misma regla se aplica a una repetición idempotente: cuando POST /connections devuelve 200 con Idempotency-Replayed: true, el qr de esa respuesta se ha obtenido de nuevo en ese momento, en lugar de reutilizarse desde el almacenamiento, justamente porque un código guardado ya no se podría escanear.

La vía del código de emparejamiento

Un QR necesita dos dispositivos: una pantalla que lo muestre y un teléfono que lo fotografíe. Una gran parte de las incorporaciones reales ocurre en un solo dispositivo: el cliente termina su flujo en el mismo teléfono que ejecuta WhatsApp y no puede fotografiar su propia pantalla. Para ellos la vía del QR no es incómoda, es imposible.

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

El cliente abre WhatsApp → Configuración → Dispositivos vinculados → Vincular con el número de teléfono e introduce el código.

phoneNumber está en formato E.164 sin el + inicial: solo dígitos. Cualquier otro formato se rechaza con 400 { "error": "invalid_phone_number" } en lugar de corregirse por usted: reescribir en silencio el número que envió es la forma en que un cliente acaba emparejando una cuenta que nadie pidió. Usa whatsapp.manage, igual que la creación de la conexión.

Un código de emparejamiento no siempre está disponible: mantenga el QR como alternativa

El motor puede negarse a emitir uno. Es un resultado normal, no una caída, y responde 502 { "error": "pairing_code_unavailable" } en lugar de un 500 genérico precisamente para que usted pueda distinguirlos y devolver al usuario al QR. Una integración que ofrezca solo la vía del código de emparejamiento, tarde o temprano mostrará a un cliente una pantalla sin salida. Muestre ambas, una junto a la otra.

Pedir otro código

Puede solicitar otro código en la misma conexión: devuelve un código nuevo y no reconstruye la sesión, así que un botón de «enviarme otro código» es seguro.

Tiene un límite de 5 por conexión cada 15 minutos; al superarlo recibirá 429 { "error": "rate_limited" } con un encabezado Retry-After que debe respetar. El límite no es burocracia: pedir códigos repetidamente para un mismo número es justo lo que activa los sistemas antiabuso de WhatsApp, y el número en riesgo es el de su cliente.

No se consume nada adicional

El emparejamiento por código usa el mismo cupo de pago e inicia la misma prueba gratuita de 7 días que escanear un QR: la licencia se reclama cuando el número realmente se empareja, sea cual sea la vía.

Vigilar el éxito tampoco cambia. No existe un evento de «código aceptado», así que consulte GET /connections/{id} hasta que status sea "connected" o escuche el webhook connection.connected (o ambas cosas).

Conviene prever dos rechazos:

409 already_connected: la sesión está activa, no hay nada que emparejar.
409 not_supported_for_provider: un número cloud_api. Los códigos de emparejamiento son un concepto de qr y nunca se aplican, así que no reintente.

Volver a emparejar más adelante

Una sesión qr puede romperse por sí sola. connection.disconnected se lo indica, y needs_reconnect es el campo a partir del cual debe dirigir su interfaz. El QR no está en esa carga a propósito, porque es una credencial de inicio de sesión por escaneo: obténgalo de GET /connections/{id} y muéstrelo al titular del número exactamente como en la configuración inicial. Consulte Webhooks.

¿Le resultó útil esta página?