Registrar número en la Cloud API: PIN y errores comunes

Actualizado el 28/10/2026

Para registrar el número en la Cloud API, haces POST /{phone-number-id}/register con messaging_product: "whatsapp" y un pin de 6 dígitos. Si el número todavía no tiene verificación en dos pasos, ese PIN pasa a ser el suyo; si ya la tiene, debes enviar el PIN actual o recibirás el error 133005. Sin este registro, el número existe en tu cuenta, pero no envía ni recibe mensajes por la API.

Esta guía muestra el orden correcto (verificar, registrar, revisar), qué hace el PIN, los límites de intentos, el deregister y una tabla con los errores de registro de la documentación de Meta.

Dónde entra el registro

Poner un número en la Cloud API tiene tres etapas que se suelen confundir:

Etapa	Qué demuestra	Llamada
Agregar el número	Que pertenece a tu cuenta de WhatsApp Business	Se hace en el WhatsApp Manager o en el registro insertado (Embedded Signup)
Verificar el número	Que tienes acceso al teléfono (código por SMS o llamada)	`POST /{id}/request_code` y `POST /{id}/verify_code`
Registrar el número	Que debe operar en la Cloud API, con PIN de dos pasos	`POST /{id}/register`

Si usas el registro insertado de un proveedor, parte de estas etapas ocurre en la propia pantalla de alta; aun así, conviene saber qué hace cada una para entender los errores de este artículo. Antes de empezar, revisa los requisitos del número en cómo liberar un número que ya está en WhatsApp.

Paso 1: verificar el número (si aún no lo está)

Según la página de números de teléfono de Meta, primero consulta el estado de verificación:

curl "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID?fields=code_verification_status,display_phone_number,verified_name" \
  -H "Authorization: Bearer $TOKEN"

Si code_verification_status no está como VERIFIED, pide el código. code_method acepta SMS o VOICE:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/request_code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code_method": "SMS", "language": "es" }'

Y confírmalo con el código recibido:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/verify_code" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Si el número ya está verificado, request_code devuelve HTTP 400 con el error 136024. Por eso conviene revisar el estado antes.

¿Quieres probar mientras lees? Crea tu cuenta en Vectalk y envía el primer mensaje por la API oficial. Crear cuenta gratis →

Paso 2: registrar con el PIN

La llamada de registro, según la documentación de registro de Meta:

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/register" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messaging_product": "whatsapp",
    "pin": "482915"
  }'

Parámetros:

messaging_product (obligatorio): siempre "whatsapp".
pin (obligatorio): 6 dígitos. Si la verificación en dos pasos ya está activa, usa el PIN existente. Si no, el valor enviado se convierte en el PIN del número.
data_localization_region (opcional): código de país ISO 3166 de 2 letras para activar el almacenamiento local de datos. No se puede desactivar ni cambiar directamente después: hay que cancelar el registro y registrar de nuevo.

El token necesita los permisos whatsapp_business_management y whatsapp_business_messaging. Para producción, usa un token permanente de usuario del sistema.

Qué es el PIN de dos pasos

El PIN de verificación en dos pasos es una capa extra de seguridad: una vez definido, todo nuevo registro del número exige el PIN actual. No es lo mismo que el código de 6 dígitos que llega por SMS. El código de SMS demuestra que tienes la SIM; el PIN demuestra que eres el dueño del registro.

Según la página de verificación en dos pasos, también puedes definir el PIN con POST /{phone-number-id} y el cuerpo {"pin": "123456"}. No existe un endpoint para desactivar la verificación en dos pasos. Para cambiar el PIN en el WhatsApp Manager, abre la configuración del número, pestaña Verificación en dos pasos, y haz clic en Cambiar PIN.

Guarda el PIN en el gestor de contraseñas de la empresa, no en la memoria de quien hizo el alta. Te lo pedirán en cualquier nuevo registro, incluso al cambiar de proveedor. Más sobre el tema en seguridad de la cuenta de WhatsApp Business.

Un cambio en curso: Meta informa que está retirando gradualmente el PIN de 6 dígitos para los números elegibles de la Cloud API. En los números elegibles, la pestaña de verificación en dos pasos desaparece del WhatsApp Manager; si todavía la ves, el número aún no es elegible. Revisa la página oficial antes de automatizar este paso.

Paso 3: revisar el estado

Después del registro, consulta el número:

curl "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID?fields=status,code_verification_status,name_status,quality_rating" \
  -H "Authorization: Bearer $TOKEN"

Qué mirar:

status: debe estar en CONNECTED para enviar y recibir por la API.
code_verification_status: VERIFIED.
name_status: estado del nombre visible (APPROVED, AVAILABLE_WITHOUT_REVIEW, DECLINED, EXPIRED, PENDING_REVIEW o NONE).
quality_rating: calidad del número.

Límites de intentos

El registro y la cancelación del registro tienen límite: 10 solicitudes de cada uno por número en una ventana móvil de 72 horas. Si lo superas, la API devuelve 133016 y bloquea la acción durante las 72 horas siguientes. Por eso, no pongas el register dentro de un bucle de reintentos automáticos. Si falla, lee el error, corrige la causa y solo entonces vuelve a intentarlo.

Errores de registro y cómo resolverlos

Los códigos de abajo están en la tabla de errores de la Cloud API, salvo el 136024, que viene de la página de números de teléfono:

Código	Significado	Qué hacer
`133000`	Falló un intento anterior de cancelar el registro	Cancela el registro de nuevo antes de registrar
`133004`	Servidor no disponible temporalmente	Revisa la página de estado de la plataforma y el campo `details` antes de reintentar
`133005`	PIN de dos pasos incorrecto	Usa el PIN actual o cámbialo en el WhatsApp Manager y registra con el nuevo
`133006`	El número debe verificarse antes del registro	Ejecuta `request_code` y `verify_code`
`133008`	Demasiados intentos de PIN para este número	Espera el tiempo indicado en `details`
`133009`	PIN ingresado demasiado rápido	Revisa `details` antes de reintentar
`133010`	Número no registrado en la plataforma	Registra el número antes de enviar mensajes
`133015`	El número se eliminó hace poco y la eliminación no terminó	Espera 5 minutos y reintenta
`133016`	Demasiados intentos de registro o cancelación en poco tiempo	Espera el fin del bloqueo de 72 horas
`136024`	El número ya está verificado (en `request_code`)	Pasa directo al registro

Los casos más frecuentes en la práctica:

133010 al enviar un mensaje. El número se agregó e incluso se verificó, pero nunca se llamó al register. Es común en números conectados manualmente o en pruebas. La solución es registrarlo.

133005 al cambiar de proveedor. El número viene de otra plataforma con verificación en dos pasos activa y nadie conoce el PIN. Pide el PIN al proveedor anterior o cámbialo en el WhatsApp Manager, si tienes acceso a la cuenta, y registra con el nuevo valor. Consulta cómo cambiar de proveedor sin perder el número.

131031 durante el registro. Este código suele indicar una cuenta restringida por infringir políticas, pero Meta también menciona como causa datos de la solicitud que no coinciden con la cuenta, como un PIN de dos pasos incorrecto. Si la cuenta no tiene restricciones, revisa el PIN.

Cuándo registrar de nuevo

Según la documentación de registro, el registro no ocurre una sola vez:

Al implementar la API por primera vez, cuando Meta exige la verificación en dos pasos.
Después de cambiar el nombre visible: cuando el nuevo nombre se aprueba (el webhook phone_number_name_update lo confirma), registra el número de nuevo. Registrar antes de la aprobación no tiene efecto.
Para cambiar o desactivar el almacenamiento local (data_localization_region): cancela el registro y registra otra vez.
En la migración de On-Premises a la Cloud API, que tiene pasos adicionales antes del registro.

Cancelar el registro (deregister)

curl -X POST "https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/deregister" \
  -H "Authorization: Bearer $TOKEN"

Qué pasa, según Meta: el número deja de funcionar en la Cloud API y el almacenamiento local se desactiva, si estaba activo. El número y el historial de mensajes no se eliminan. Dos restricciones importantes: no se puede cancelar el registro de un número que se usa a la vez en la Cloud API y en la app WhatsApp Business (coexistencia), y sin el permiso whatsapp_business_management la llamada devuelve el error 200. Recuerda que la cancelación también tiene su propio límite de 10 solicitudes por número en 72 horas.

Cómo hacerlo con Vectalk

En Vectalk, las rutas de números usan el token de instancia, que ya identifica el número, así que no necesitas indicar el phone-number-id. La API de Vectalk ofrece POST https://apis.vectalk.com.br/api/phone-numbers/register con el pin en el cuerpo, POST /phone-numbers/deregister, POST /phone-numbers/request-code, POST /phone-numbers/verify-code y GET /phone-numbers para consultar estado, calidad y nivel de throughput. Vectalk también ofrece coexistencia, para que el número siga en la app WhatsApp Business mientras usa la API. Crea tu cuenta en apps.vectalk.com.br/register.

Con el número registrado, los siguientes pasos son validar la firma del webhook y respetar el throughput y el rate limit. El panorama completo de la plataforma está en nuestra guía de WhatsApp Cloud API.

Preguntas frecuentes

¿El PIN de dos pasos es el mismo código que llega por SMS?

No. El código de SMS o llamada verifica que tienes acceso al teléfono. El PIN de 6 dígitos lo defines tú y se exige en cada nuevo registro del número.

Olvidé el PIN. ¿Cómo registro el número?

Cambia el PIN en el WhatsApp Manager, en la pestaña de verificación en dos pasos del número, y registra con el nuevo valor. No existe un endpoint para desactivar la verificación en dos pasos.

¿Cuántas veces puedo intentar registrar?

Hasta 10 registros y 10 cancelaciones por número en 72 horas. Por encima de eso, la API devuelve 133016 y bloquea la acción durante 72 horas.

¿Cancelar el registro borra el número o los mensajes?

No. El número solo deja de funcionar en la Cloud API. El número y el historial se mantienen, y puedes registrarlo de nuevo después.

¿Tengo que registrar de nuevo después de cambiar el nombre visible?

Sí. Una vez aprobado el nuevo nombre, llama otra vez al register. Registrar antes de la aprobación no tiene efecto.

Fuentes oficiales consultadas el 28/10/2026: Register a phone number (Meta), Two-step verification (Meta), Phone numbers (Meta), Códigos de error (Meta), Registrar número en la API de Vectalk.

Prueba hoy la API oficial de WhatsApp

Crea tu cuenta, genera el token y envía el primer mensaje con la guía de la documentación. Los mismos payloads y webhooks de la Cloud API de Meta.

Crear cuenta gratis

Leer la documentación

Cómo registrar el número en la Cloud API: PIN de dos pasos y errores comunes