API de verificación de edad para webs y aplicaciones

Paso uno, verificar el número. Llamas a POST /start-verification con flow=age y muestras el enlace profundo de WhatsApp que devuelve, como código QR en escritorio o como botón en móvil. El visitante envía un mensaje ya escrito desde su propia cuenta de WhatsApp, así que el control del número queda demostrado por el propio acto de enviarlo y no por un código que tú le hayas mandado.

Paso dos, fijar el umbral. La misma llamada acepta un min_age opcional. Si lo omites se aplica el umbral configurado en tu cuenta, que es 18 mientras no lo cambies. min_age solo se acepta en flow=age y tiene que ser un entero positivo; cualquier otra cosa vuelve como un 400.

Paso tres, completar el control de edad. En cuanto se demuestra la mitad del teléfono, la respuesta trae un bloque age con status pending y una age_verification_url. Al visitante se le envía ese mismo enlace de un solo uso por WhatsApp, y tú puedes usarlo para que siga en el navegador en el que ya está. Responde en el proveedor de edad y vuelve a tu callback_url con token y age=verified, denied o failed añadidos.

Paso cuatro, recibir el resultado. Un segundo webhook, age_verification_result, se dispara cuando el proveedor responde, y GET /check-verification-status informa de lo mismo. El bloque age lleva status, verified, required — el umbral realmente comprobado —, verified_at y provider.

Conviene conocer una trampa antes de escribir el bucle de sondeo. El estado de la propia sesión llega a verified en cuanto se demuestra el número, mientras age.status sigue en pending. Toma el bloque age como señal del paso de edad, nunca el estado de la sesión.

Los dos pasos responden a preguntas distintas, y el flujo los mantiene separados a propósito. Enviar un mensaje de WhatsApp demuestra que el visitante controla ese número. No dice absolutamente nada de su edad: un número de teléfono no es prueba de edad, y ninguna parte de este flujo lo trata como tal.

Lo que te aporta el paso del teléfono es un sitio donde poner la respuesta. Un resultado de edad por sí solo es un hecho sin anclaje — alguien, en algún sitio, superó un umbral. Ligado a un número que el visitante acaba de usar de forma demostrable, se convierte en algo que sabrás reconocer en la siguiente visita.

Eso también abarata al visitante recurrente. Un resultado positivo se guarda un año asociado al número, así que quien ya superó el mismo umbral vuelve a demostrar el número y arrastra la respuesta anterior en lugar de volver al proveedor. Terminar el mensaje de WhatsApp con #reset se salta esa caché cuando necesitas una respuesta nueva.

La pregunta que hace un control de edad es un booleano. La mayoría de los datos que suelen recogerse para responderla no lo son, y eso es lo que hace que el archivo de documentos sea tan mal negocio: acabas guardando pasaportes y carnés de conducir para almacenar un sí.

Lo que tu aplicación necesita es poco. El resultado — verified, denied, failed o todavía pending. El umbral comprobado. Cuándo se respondió y qué proveedor respondió. El identificador de sesión y el número verificado que atan la respuesta al visitante que tienes delante. Eso es todo el bloque age, más lo que el flujo del teléfono ya devuelve.

Lo que tu aplicación no necesita es una fecha de nacimiento ni un documento de identidad, y la API no devuelve ninguno de los dos, así que no hay campo que registrar por accidente. Una respuesta positiva se guarda junto al número como la respuesta, el umbral y la fecha. Las credenciales del proveedor viven en secretos del lado del servidor, y lo que el proveedor tuviera que mirar para decidir no se te pasa a ti.

Nada de esto dice nada sobre tus propias obligaciones. Qué tienes que comprobar, durante cuánto tiempo debes poder acreditar que lo comprobaste y qué cuenta como método aceptable son preguntas para tu asesoría jurídica y tu regulador, no para un proveedor de API.

La verificación de edad responde a una pregunta: ¿este visitante alcanza el umbral de edad que has fijado? La verificación de identidad responde a otra: ¿quién es esta persona? Se venden juntas a menudo y mueven cantidades de datos muy distintas.

flow=age es del primer tipo. No devuelve nombre, ni fecha de nacimiento, ni nada procedente de un documento. No es KYC, y un resultado positivo no es una afirmación de identidad en la que apoyarte en otro sitio. Si tu obligación es saber quién es un cliente, esta no es la herramienta para esa parte.

También hereda el supuesto que hay debajo de todo control basado en el teléfono: que el número pertenece a quien lo está usando. Demostrar el control enviando un mensaje es terreno más firme que recibir un SMS, pero un adolescente con acceso al teléfono de un adulto es un escenario que ningún control remoto cierra del todo. El artículo sobre controles de edad que no acaban en una base de documentos, enlazado más abajo, entra en la arquitectura, los cuatro estados y los límites.