Verify Guía de migración
La siguiente guía le ayudará a migrar desde Verify Legado a Verify. Para ello, debe actualizar las URL de sus puntos finales para llamar a la nueva versión y modificar la configuración de su aplicación; no es necesario rellenar ningún formulario de registro previo para empezar a utilizar Verify.
Resumen
La API Verify de Vonage es un servicio que permite a los desarrolladores implementar la autenticación de dos factores (2FA) para protegerse contra el fraude y garantizar la autenticidad del usuario. Vonage ofrece dos versiones de esta API: Legacy y la actual Verify. Si bien ambas versiones cumplen la misma función principal, existen diferencias significativas en sus características, funcionalidades y uso.
Principales diferencias
- Flexibilidad y personalización: Verify ofrece ahora una creación de flujos de trabajo más flexible y opciones de personalización mejoradas, como un sistema de gestión de plantillas personalizadas con más funciones en comparación con Legacy.
- Canal de asistencia: Verify ahora incluye soporte adicional para la verificación a través de varios canales nuevos como Silent Auth, RCS, WhatsApp y Email, mientras que Legacy se limita a SMS y voz.
- Seguridad: Verify incluye ahora funciones de seguridad mejoradas y el cumplimiento de las normas más recientes.
- Protección contra el fraude: Los clientes que migran de Verify Legacy a la nueva API de Verify tienen protección y acceso a Vonage Fraud Defender avanzado sin coste adicional.
- Tratamiento de errores: Verify proporciona ahora mensajes de error más detallados y una gestión mejorada, así como mecanismos más avanzados de limitación de velocidad y reintento automático.
- Diseño e integración de API: Verify admite patrones de integración síncronos y asíncronos.
Comparación de funciones
| Función | Verify (heredado) | Verify |
|---|---|---|
| Verificación básica | SMS, Voz | Autenticación silenciosa, RCS, SMS, voz, correo electrónico, WhatsApp |
| Gestión de ID de solicitud | Sistema básico de identificación de solicitudes | Seguimiento mejorado del ID de solicitud con más metadatos |
| Configuración personalizada del flujo de trabajo | Limitado | Amplia, incluidas configuraciones de canales múltiples |
| Gestión de la caducidad del PIN | Configurable pero limitado (de 60 a 3600 segundos) | Control más detallado de la caducidad del PIN y de los tiempos de los eventos |
| Cumplimiento de las normas de seguridad | Básico, conforme a normas más antiguas | Avanzado, cumple las últimas normas de seguridad |
| Tratamiento de errores | Mensajes de error básicos | Mensajes de error detallados con códigos de error extensos |
| Limitación de velocidad | Limitación de tarifa básica | Mejora de los mecanismos de limitación de velocidad |
| Mecanismo de reintento | Reintento básico en caso de fallo | Lógica de reintento avanzada con flujos de trabajo de reintento personalizables |
| Análisis e informes | Capacidad limitada de elaboración de informes | Análisis mejorados e informes detallados |
| Apoyo a la localización | Localización básica (idiomas limitados) | Localización mejorada con más idiomas y mensajes personalizados |
| Documentación y asistencia de la API | Documentación completa pero antigua | Documentación moderna, detallada y más fácil de usar |
Llamadas a la API
Importante: Verify v2 utiliza autenticación JWT Bearer (no api_key / api_secret). Antes de realizar cualquier llamada a la API v2, crea una aplicación de Vonage en la aplicación Cuadro de mandosgenerar application ID y private keyy utilizarlos para firmar JWTs. Véase el Guía de autenticación.
Se ha introducido el modo asíncrono en Verify, lo que permite recibir mensajes y estados de llamada mediante webhook, recibiendo tanto eventos (en el caso de whatsapp_interactive) y devoluciones de llamada de resumen. También se puede utilizar de forma sincrónica con redirect_url y check_url.
Debe configurar sus webhooks para las retrollamadas Verify en la sección Application del módulo Cuadro de mando de clientes:
Encontrará más documentación sobre los webhooks en aquí.
Puntos finales
Todas las llamadas a la API de Verify deben actualizarse para utilizar el nuevo punto final:
| Función | Verify (heredado) | Verify |
|---|---|---|
| Enviar solicitud de verificación | POST https://api.nexmo.com/verify/ | POST https://api.nexmo.com/v2/verify |
| Solicitud de verificación de cheques | POST https://api.nexmo.com/verify/check/:format | POST https://api.nexmo.com/v2/verify/:request_id |
| Verify Búsqueda | https://api.nexmo.com/verify/search/:format | No disponible actualmente. Utilice los estados enviados a sus webhooks para supervisar las solicitudes pasadas o actuales mientras tanto. Véase Devoluciones de llamada resumidas y Webhooks. |
| Cancelar solicitud | POST https://api.nexmo.com/verify/control/:format con cmd = cancel | DELETE https://api.nexmo.com/v2/verify/:request_id |
| Activar el siguiente evento en el flujo de trabajo | POST https://api.nexmo.com/verify/control/:format con cmd = trigger_next_event | POST https://api.nexmo.com/v2/verify/:request_id/next-workflow |
| Plantillas personalizadas | POST https://api.nexmo.com/verify/templates | GET https://api.nexmo.com/v2/verify/templatesPOST https://api.nexmo.com/v2/verify/templatesGET https://api.nexmo.com/v2/verify/templates/:template_idPATCH https://api.nexmo.com/v2/verify/templates/:template_idDELETE https://api.nexmo.com/v2/verify/templates/:template_id |
| PSD2 | POST https://api.nexmo.com/verify/psd2/:format | Obsoleto |
| Desbloqueo de la red | POST https://api.nexmo.com/verify/network-unblock | POST https://api.nexmo.com/v2/verify/network-unblock |
Flujos de trabajo
Verify le ofrece la flexibilidad de definir su propio flujo de trabajo, a diferencia de los flujos de trabajo fijos de Legacy. Puede especificar cualquier combinación de canales de soporte de su elección en el flujo de trabajo, hasta un máximo de tres canales.
Encontrará más documentación sobre los flujos de trabajo aquí.
Canales
Ya están disponibles nuevos canales en Verify:
- SMS
- Voz (antes TTS en Legacy)
- Correo electrónico
- Autenticación silenciosa
- RCS
Para obtener información más detallada sobre estos canales, consulte el Especificación API.
Encontrará documentación específica sobre la autenticación silenciosa aquí.
Devoluciones de llamada resumidas
Las devoluciones de llamada se devuelven a su webhook con el estado del evento, correspondiente request_id y canal. Los siguientes diagramas de secuencia muestran cómo funciona esto cuando se utiliza un solo canal, o el uso de múltiples canales en su flujo de trabajo.
Canal único
Canales múltiples
Códigos de respuesta
Además de cambiar sus puntos finales, también es necesario actualizar sus aplicaciones para que comprendan los códigos de respuesta recibidos al utilizar Verify:
| Código HTTP | Definición |
|---|---|
Creación de una solicitud: POST /v2/verify | |
| 202 | Solicitud aceptada. Entrega en curso. |
| 409 | Hay una solicitud en curso a este número. |
| 422 | Error al procesar la solicitud. |
Validación de una solicitud: POST /v2/verify/{request_id} | |
| 200 | Acierto. Se ha proporcionado el código correcto. |
| 400 | Se ha proporcionado un código incorrecto. |
| 404 | No se ha encontrado la solicitud. |
| 409 | La acción actual no admite la comprobación de pines. |
| 410 | Muchas veces se proporcionó un código incorrecto. |
| 422 | No se puede validar la solicitud. |
Solicitud de anulación
| Verify (heredado) | Verify |
|---|---|
| Verify Control puede utilizarse para cancelar una solicitud de verificación en curso. No se puede cancelar en los primeros 30 segundos de la solicitud. | Enviar un solicitud de anulación - si la solicitud de verificación está activa, aborta el flujo de trabajo. |
Plantillas
| Verify (heredado) | Verify |
|---|---|
| Los clientes pueden utilizar una plantilla personalizada para enviar mensajes de Verify (documentación) | Verify admite tanto plantillas predefinidas como plantillas personalizadas. Gestione las plantillas mediante la función Guía de gestión de plantillas. |
Cumplimiento de la PSD2
| Verify (heredado) | Verify |
|---|---|
| Cumple la PSD2 | Obsoleto |
Solicitud de verificación de búsqueda
| Verify (heredado) | Verify |
|---|---|
| Utilice Verify Búsqueda para comprobar el estado de las solicitudes de verificación pasadas o en curso. | Utilice los estados enviados a sus webhooks para supervisar las solicitudes pasadas o actuales. Consulte Devoluciones de llamada resumidas y Webhooks. |
Gestión del fraude
Tenga en cuenta que los bloqueos de red sólo se aplican a los canales SMS y Voice en la API Verify.
| Verify (heredado) | Verify |
|---|---|
| Los bloques activados por reglas de velocidad se responden con Error 7 | Los bloques activados por reglas de velocidad se muestran con el estado blocked y la razón Fraudulent traffic detected for your account on network [23415]. en la devolución de llamada de resumen |
| Los desbloqueos de red pueden realizarse mediante la función API de desbloqueo de red. | Utiliza la misma API para los desbloqueos. |
| Más documentación: Sistema antifraude heredado | Más documentación: Sistema antifraude |
Verify Diagramas de secuencia
Verify Flow
Verify Request with Summary Callbacks (Verificar solicitud con devoluciones de llamada de resumen)
Diagrama de secuencia de autenticación silenciosa
Verify Payload Parameter Analysis for V1 vs V2
Autenticación (Verify v2): Verify v2 utiliza la autenticación JWT Bearer. Genera un JWT utilizando tu ID de aplicación de Vonage y tu clave privada, y envíalo en el campo Authorization (más información en la sección Guía de autenticación). api_key y api_secret no se incluyen en la carga útil de la solicitud v2.
Enviar solicitud de verificación
| Parámetro | Verify (heredado) | Verify (V2) | Notas |
|---|---|---|---|
| Clave API | api_key | N/A | |
| Secreto API | api_secret | N/A | |
| Numbers de téléphone | number | to | |
| Marca | brand | Incluido en workflow.channels.template | |
| ID del remitente | sender_id | from | Aplicable a channel = SMS & Email en V2 |
| Código Longitud | code_length | code_length | |
| Idioma | lg | locale | |
| Expiración del pin | pin_expiry | channel_timeout | |
| Próximo evento Esperar | next_event_wait | N/A | |
| Identificador de flujo de trabajo | workflow_id | Flujo de trabajo personalizado en workflow.channels | Configuración flexible de los canales en el flujo de trabajo |
| Código personalizado | pin_code | code | |
| Plantilla | N/A | template_id | Gestión de plantillas documentación para V2 |
| Correo electrónico | N/A | workflow.channels.email | |
| N/A | workflow.channels.whatsapp | ||
| Autenticación silenciosa | N/A | workflow.channels.silent_auth | |
| Entidad ID | N/A | entity_id | Aplicable a channel = SMS en V2 |
| ID de contenido | N/A | content_id | Aplicable a channel = SMS en V2 |
| Identificador de Applications | N/A | app_hash | Aplicable a channel = SMS en V2 |
Solicitud de verificación de cheques
| Parámetro | Verify (heredado) | Verify (V2) |
|---|---|---|
| Clave API | api_key | N/A |
| Secreto API | api_secret | N/A |
| Solicitar ID | request_id | request_id |
| Código | code | code |
Solicitud de verificación de búsqueda
| Parámetro | Verify (heredado) | Verify (V2) |
|---|---|---|
| Clave API | api_key | N/A |
| Secreto API | api_secret | N/A |
| Solicitar ID | request_id | N/A |
Cancelar solicitud de verificación
| Parámetro | Verify (heredado) | Verify (V2) | Notas |
|---|---|---|---|
| Clave API | api_key | N/A | |
| Secreto API | api_secret | N/A | |
| Solicitar ID | request_id | request_id | |
| Comando | cmd=cancel | N/A | V2 utiliza un punto final dedicado para la cancelación. |
Activar el siguiente proceso de verificación
| Parámetro | Verify (heredado) | Verify (V2) | Notas |
|---|---|---|---|
| Clave API | api_key | N/A | |
| Secreto API | api_secret | N/A | |
| Solicitar ID | request_id | request_id | |
| Comando | cmd=trigger_next_event | N/A | V2 utiliza un punto final específico para activar la siguiente acción. |
Plantillas personalizadas
| Parámetro | Verify (heredado) | Verify (V2) |
|---|---|---|
| Clave API | api_key | N/A |
| Secreto API | api_secret | N/A |
| Canal | action_type | channel |
| Idioma | lg | locale |
| Texto de la plantilla | template | text |
| Tipo de texto para SMS | type | N/A |
| URL del archivo multimedia | digit_n | N/A |
| Inicio del mensaje | welcome_message | N/A |
| Fin del mensaje | bye_message | N/A |
| Ticket de Zendesk | contact_email | N/A |
| Nombre de la plantilla | N/A | name |
| Indicador de plantilla por defecto | N/A | is_default |
| Plantilla de referencia | N/A | template_id |
Cumplimiento de la PSD2
| Parámetro | Verify (heredado) | Verify (V2) |
|---|---|---|
| Clave API | api_key | N/A |
| Secreto API | api_secret | N/A |
| Numbers de téléphone | number | N/A |
| Código del país | country | N/A |
| Nombre del destinatario | payee | N/A |
| Importe del pago | amount | N/A |
| Longitud del código | code_length | N/A |
| Idioma | lg | N/A |
| Expiración del pin | pin_expiry | N/A |
| Próximo evento Esperar | next_event_wait | N/A |
| Identificador de flujo de trabajo | workflow_id | N/A |
Asignación de flujos de trabajo de Verify V1 frente a Verify V2
Flujo de trabajo 1 (predeterminado)
Patrón: SMS → TTS → TTS
Verify V1
Verify V2
Flujo de trabajo 2
Patrón: SMS → SMS → TTS
Verify V1
Verify V2
Flujo de trabajo 3
Patrón: TTS → TTS
Verify V1
Verify V2
Flujo de trabajo 4
Patrón: SMS → SMS
Verify V1
Verify V2
Flujo de trabajo 5
Patrón: SMS → TTS
Verify V1
Verify V2
Flujo de trabajo 6
Patrón: SMS
Verify V1
Verify V2
Flujo de trabajo 7
Patrón: TTS
Verify V1
Verify V2