Información de integración

Aprenda a configurar la integración con sus sistemas, incluyendo API keys, webhooks, return URLs, skip result page y dynamic fields.

La configuración de información de integración permite la integración de datos en tiempo real con los sistemas del cliente. Puede construir una integración fluida con sistemas de negocio mediante gestión de API keys, configuración de webhooks, configuración de return URL, configuración de dynamic fields, etc.

---

​

API Key

Puede consultar y gestionar la API key del proyecto.

La API key es una clave única utilizada para autenticación al llamar a la ARGOS ID Check API. Debe incluirse en el header x-api-key en todas las solicitudes API.

Seguridad de la API Key

Tenga cuidado de no exponer las API keys externamente. Si una API key se filtra, se pueden acceder a todos los datos del proyecto, por lo que debe gestionarse de forma segura.

Uso de la API Key

Puede usar diversas funciones API como consulta de submissions, procesamiento de aprobación/rechazo, gestión de tokens, etc. usando la API key.

---

​

Configuración de Webhook

La función Webhook permite la integración de datos en tiempo real con sistemas del cliente. Cuando ocurren eventos específicos, envía solicitudes HTTP POST al endpoint (Endpoint URL) configurado por el cliente, permitiendo notificaciones y procesamiento de datos en tiempo real sin llamadas API separadas.

​

Configuración de Webhook URL

Configure la endpoint URL donde el sistema del cliente recibirá los datos del webhook.

Las solicitudes HTTP POST se envían a la URL configurada cuando ocurren eventos de webhook.

Seguridad y estabilidad del Webhook

Los endpoints de webhook deben usar HTTPS para asegurar la transmisión segura de datos. También se recomienda implementar mecanismos de verificación de firma para verificar la autenticidad de las solicitudes de webhook.

Se requiere configuración de firewall

La dirección IP usada por ARGOS al enviar webhooks es 52.78.194.237. Para recibir webhooks normalmente, debe configurar el firewall para permitir solicitudes desde esta dirección IP.

Método de configuración del firewall

Agregue la siguiente dirección IP a la allow list en la configuración del firewall o security group del cliente:

• Webhook IP: 52.78.194.237

Si no se permiten las solicitudes HTTP POST desde esta dirección IP, los webhooks serán bloqueados y no podrán recibirse.

Gestión de IP y URL de Webhook

Las IPs fijas de webhook para cada proyecto solo pueden consultarse en esta página, y el historial de cambios de URL de webhook no se almacena, así que tenga cuidado con la gestión de URLs de webhook.

​

Gestión de usuarios de notificación

Al agregar nombres y emails mediante la gestión de usuarios de notificación, puede recibir información sobre webhooks enviados el día anterior vía email a la mañana siguiente.

Método de configuración:

1. Ingrese nombre y dirección de email.
2. Haga clic en el botón agregar para registrar usuarios de notificación.
3. Los usuarios registrados reciben información de webhooks enviados el día anterior vía email cada mañana.

Reporte diario de Webhook

Un resumen de todos los eventos webhook enviados el día anterior (00:00 ~ 23:59 UTC) se envía vía email a los usuarios de notificación registrados cada mañana. Esto le permite monitorear el estado de transmisión de webhooks.

---

​

Return URL

Los usuarios son redirigidos a la URL configurada cuando se completa el KYC o cuando acceden a una página de error.

Cuando se completa el proceso KYC y el remitente selecciona el botón “Ok” o espera 5 segundos, es redirigido a la return URL con los parámetros de los campos dinámicos seleccionados. A partir de la actualización de 2026-04, incluso después de acceder a una página de error se puede redirigir a la return URL; en este caso, el parámetro errorCode se transmite junto con la URL para que el cliente pueda identificar el motivo del bloqueo.

Ejemplo de Return URL (finalización normal):

https://yourapp.com/verification-complete?userid=user123&email=[e-mail]&kycStatus=approved&submissionId=sub_abc123&cf1=campaign_summer

Ejemplo de Return URL (página de error → Return URL):

https://yourapp.com/verification-complete?kycStatus=rejected&errorCode=DE-20000

​

Cifrado de Return URL

Cuando se activa la función de cifrado de return URL, los parámetros de la return URL se cifran y entregan.

Cuando el cifrado de return URL está activado, los parámetros seleccionados en dynamic fields se cifran e incluyen en el parámetro encrypted.

Ejemplo de Return URL cifrada:

https://yourapp.com/verification-complete?encrypted={encrypted_data}

Uso del cifrado de Return URL

Cuando usa return URLs que contienen información sensible (email, user ID, etc.), puede reforzar la seguridad activando la función de cifrado. Se usa el método AES-256-ECB para el descifrado.

Guía de cifrado

Aprenda a descifrar datos de cifrado de return URL.

Uso de Return URL

Después de completar el KYC, los usuarios pueden ser redirigidos automáticamente a la página de servicio del cliente, proporcionando páginas de guía personalizadas según el estado de aprobación/rechazo.

---

​

Skip Result Page

Puede omitir que los usuarios vean los resultados de KYC y redirigirlos a la URL deseada.

Cuando se activa la función skip result page, se omite la página de resultados de KYC y se mueve directamente a la return URL.

Escenarios de uso:

• Cuando los clientes quieren proporcionar su propia página de resultados
• Cuando desea proporcionar resultados de forma flexible mediante parámetros de dynamic fields en la return URL

Combinación de Skip Result Page y Dynamic Fields

Cuando activa la función skip result page y selecciona parámetros como kycStatus, submissionId en dynamic fields, la información del resultado KYC se incluye en la return URL. Esto permite a los clientes configurar sus propias páginas de resultados.

---

​

Campos Dinámicos

Puede seleccionar los elementos que se transmitirán como parámetros de consulta a la Return URL haciendo clic en las casillas de los Campos Dinámicos. Los valores configurados se reflejan automáticamente en la vista previa de la Return URL final en la parte inferior de la pantalla.

Campo	Clave de parámetro	Descripción
User ID	userid	ID del usuario
Email	email	Dirección de email del usuario
Submission ID	submissionId	ID de submission
Custom Field #1·#2·#3	cf1, cf2, cf3	Campos personalizados
KYC Result	kycStatus	Estado del resultado KYC (approved, pending, rejected)
Error Code Nuevo en 2026-04	errorCode	Código de error transmitido al acceder a una página de error (ej.: DE-20000, TK-10001)

Vista previa de la Return URL final:

https://argosidentity.com?kycStatus={kycStatus}&errorCode={errorCode}

Uso del parámetro Error Code (errorCode)

Al marcar Error Code en los Campos Dinámicos, los usuarios que accedan a una página de error podrán regresar al servicio del cliente a través del botón de Return URL. En ese momento, el valor errorCode se incluirá en el query string de la URL, permitiendo al cliente identificar el motivo del bloqueo (ej.: fallo en Device Verification, token expirado). Consulte el documento Códigos de error y páginas de error para el mapeo completo de códigos de error.

Precauciones de Campos Dinámicos

Los parámetros kycStatus y errorCode siguen camelCase, por lo que las mayúsculas y minúsculas deben distinguirse con precisión. kycStatus devuelve uno de approved, pending o rejected según el resultado.

---

​

Tipos de evento Webhook

Los principales tipos de evento enviados vía webhook son los siguientes:

Evento	Descripción
approved	Ocurre cuando la autenticación KYC es aprobada
rejected	Ocurre cuando la autenticación KYC es rechazada
pending	Ocurre cuando el estado cambia a requerir revisión manual
retry	Ocurre cuando hay un reintento
updated	Ocurre cuando se actualiza la información del submission
delete	Ocurre cuando se elimina un submission
submit	Ocurre cuando se completa un nuevo submission
token	Cuando ocurren eventos relacionados con token
injection	Cuando ocurre inyección de datos
aml	Cuando ocurren resultados de comprobación AML
aml-ongoing	Cuando ocurren resultados de ongoing monitoring AML

---

​

Casos de uso

Automatización del proceso de onboarding de clientes

Cuando se completa la autenticación KYC de un nuevo cliente de una institución financiera, pueden recibir notificaciones inmediatas vía webhook y proceder automáticamente con procesos de seguimiento como apertura de cuenta, emisión de tarjeta y activación de servicio. Usando return URLs y dynamic fields, se pueden proporcionar páginas de guía personalizadas según el estado de aprobación/rechazo.

Monitoreo y respuesta en tiempo real del equipo de operaciones

Cuando los submissions KYC son rechazados o se detectan factores de riesgo específicos, se pueden enviar notificaciones inmediatas al equipo de operaciones vía webhook para respuesta rápida. Puede verificar el estado de transmisión de webhooks del día anterior cada mañana mediante la función de gestión de usuarios de notificación.

Provisión de páginas de resultados personalizadas

Los clientes pueden configurar sus propias páginas de resultados usando la función skip result page y dynamic fields. Como la información del resultado KYC se incluye en la return URL, los resultados pueden procesarse inmediatamente sin llamadas API separadas.

---

​

Documentación relacionada

Información del proyecto

Consulte la configuración de información básica del proyecto.

Descripción general de eventos Webhook

Consulte la descripción general completa de eventos webhook.

Guía de Return URL

Aprenda a usar return URLs en detalle.

Webhook aprobado

Consulte el payload del webhook aprobado.

Webhook rechazado

Consulte el payload del webhook rechazado.

Referencia de API

Aprenda a usar las APIs.