Descripción general
En sandbox, cuando creas una validación KYC para una entidad persona, la API puede devolver un resultado mock inmediato según el taxId (documento) de la entidad. No se realiza ninguna verificación externa; la respuesta y los webhooks coinciden con el resultado asociado a ese documento en nuestro set de prueba.
Así puedes probar todos los flujos (aprobado, rechazado, cancelado, doble chequeo RENAPER, etc.) sin pasar por una verificación real.
¡Configura un webhook para recibir las respuestas!En sandbox, el resultado de KYC se actualiza de forma asíncrona (igual que en producción). Aunque la API devuelve 201 inmediatamente después de crear la validación, el resultado final (aprobado, rechazado, etc.) se envía a través de webhooks momentos después.Debes configurar un endpoint webhook en tu organización para recibir las notificaciones de validación. Sin un webhook configurado, no recibirás las actualizaciones de estado.📚 Aprende a configurar webhooks: Integración webhook El formato no importa. El taxId de la entidad puede enviarse con o sin formato (p. ej. 99.990.001 o 99990001). La API lo normaliza antes de comparar, por lo que ambos funcionan igual.
Cómo funciona
- La entidad persona pertenece a una organización en modo sandbox.
- Llamas a POST /api/kyc/validations con el
entityId de esa entidad.
- La API busca el taxId de la entidad en el mapa de prueba de sandbox (tras normalizar: solo dígitos y letras).
- Si hay coincidencia, se crea una validación mock con estado
pending (201 Created) y momentos después se actualiza al estado final (p. ej. approved, rejected, cancelled).
- Se envían los webhooks correspondientes a tu endpoint configurado con el resultado final.
- Si no hay coincidencia, la API sigue el flujo normal (crea una sesión de verificación real y devuelve
providerSessionUrl).
Flujo asíncrono: El comportamiento en sandbox replica exactamente el flujo de producción, que es asíncrono. La validación se crea en estado pending, y luego se actualiza y se notifica vía webhook. No intentes hacer polling inmediato al endpoint GET después de crear la validación - usa webhooks para recibir el resultado.
RENAPER en sandbox: Si envías doubleCheckRenaper: true al crear la validación y el resultado es aprobado (o un rechazo relacionado con RENAPER), la respuesta y el payload del webhook incluirán metadata.responseDoubleChecks.renaper con la misma estructura que en producción.
Valores de prueba por defecto
Ofrecemos un set fijo de números de documento de prueba en cuatro formatos. Cada número corresponde a un resultado. La clave de búsqueda es el valor normalizado (sin puntos, guiones ni espacios).
Lista de resultados (qué devuelve cada número)
| # | Resultado | Significado |
|---|
| 01 | approved | KYC aprobado. Si pediste doble chequeo RENAPER, la respuesta incluye RENAPER correcto. |
| 02 | approved_with_renaper | Igual que approved; RENAPER en la respuesta solo si se pidió en la creación. |
| 03 | cancelled | Validación cancelada. |
| 04 | rejected | Rechazo genérico. |
| 05 | rejected_document_mismatch | Rechazo por documento no coincidente con la entidad. |
| 06 | rejected_renaper_tramite_not_match | Rechazo: número de trámite no coincide con el registro. |
| 07 | rejected_renaper_dni_not_match | Rechazo: documento no coincide con el registro. |
| 08 | rejected_renaper_verification_unavailable | Rechazo: verificación con el registro no disponible. |
| 09 | rejected_renaper_dni_missing | Rechazo: sin documento para verificación con el registro. |
| 10 | rejected | Rechazo genérico (segundo número para pruebas). |
Argentina – DNI (8 dígitos)
Usa cualquiera de estos como taxId de la entidad (con o sin puntos). El valor normalizado es el que se usa para el match.
| Valor de ejemplo | Normalizado | Resultado |
|---|
| 99.990.001 o 99990001 | 99990001 | approved |
| 99.990.002 o 99990002 | 99990002 | approved_with_renaper |
| 99.990.003 | 99990003 | cancelled |
| 99.990.004 | 99990004 | rejected |
| 99.990.005 | 99990005 | rejected_document_mismatch |
| 99.990.006 | 99990006 | rejected_renaper_tramite_not_match |
| 99.990.007 | 99990007 | rejected_renaper_dni_not_match |
| 99.990.008 | 99990008 | rejected_renaper_verification_unavailable |
| 99.990.009 | 99990009 | rejected_renaper_dni_missing |
| 99.990.010 | 99990010 | rejected |
Argentina – CUIT (11 dígitos)
Formato: 20-XXXXXXXX-X. Ejemplo: 20-99990001-9.
| Valor de ejemplo | Normalizado | Resultado |
|---|
| 20-99990001-9 | 20999900019 | approved |
| 20-99990002-9 | 20999900029 | approved_with_renaper |
| 20-99990003-9 | 20999900039 | cancelled |
| 20-99990004-9 | 20999900049 | rejected |
| 20-99990005-9 | 20999900059 | rejected_document_mismatch |
| 20-99990006-9 | 20999900069 | rejected_renaper_tramite_not_match |
| 20-99990007-9 | 20999900079 | rejected_renaper_dni_not_match |
| 20-99990008-9 | 20999900089 | rejected_renaper_verification_unavailable |
| 20-99990009-9 | 20999900099 | rejected_renaper_dni_missing |
| 20-99990010-9 | 20999900109 | rejected |
Brasil – CPF (11 dígitos)
Formato: XXX.XXX.XXX-XX. Ejemplo: 999.900.001-01.
| Valor de ejemplo | Normalizado | Resultado |
|---|
| 999.900.001-01 | 99990000101 | approved |
| 999.900.001-02 | 99990000102 | approved_with_renaper |
| 999.900.001-03 | 99990000103 | cancelled |
| 999.900.001-04 | 99990000104 | rejected |
| 999.900.001-05 | 99990000105 | rejected_document_mismatch |
| 999.900.001-06 | 99990000106 | rejected_renaper_tramite_not_match |
| 999.900.001-07 | 99990000107 | rejected_renaper_dni_not_match |
| 999.900.001-08 | 99990000108 | rejected_renaper_verification_unavailable |
| 999.900.001-09 | 99990000109 | rejected_renaper_dni_missing |
| 999.900.001-10 | 99990000110 | rejected |
Brasil – CNPJ (14 dígitos)
Formato: XX.XXX.XXX/XXXX-XX. Ejemplo: 99.990.000/0001-01.
| Valor de ejemplo | Normalizado | Resultado |
|---|
| 99.990.000/0001-01 | 99990000000101 | approved |
| 99.990.000/0001-02 | 99990000000102 | approved_with_renaper |
| 99.990.000/0001-03 | 99990000000103 | cancelled |
| 99.990.000/0001-04 | 99990000000104 | rejected |
| 99.990.000/0001-05 | 99990000000105 | rejected_document_mismatch |
| 99.990.000/0001-06 | 99990000000106 | rejected_renaper_tramite_not_match |
| 99.990.000/0001-07 | 99990000000107 | rejected_renaper_dni_not_match |
| 99.990.000/0001-08 | 99990000000108 | rejected_renaper_verification_unavailable |
| 99.990.000/0001-09 | 99990000000109 | rejected_renaper_dni_missing |
| 99.990.000/0001-10 | 99990000000110 | rejected |
Ejemplo: aprobado con RENAPER
- Crea una entidad persona en sandbox con
taxId: 99990001 (o 99.990.001).
- Llama a POST /api/kyc/validations con
entityId y doubleCheckRenaper: true (body o query).
- La API devuelve 201 con la validación; poco después el estado es approved y se envía el webhook
kyc.validation_approved.
- El payload del webhook incluye el objeto completo de la validación, incluido
metadata.responseDoubleChecks.renaper con verified: true, matchResult: "match", personalNumber, idTramitePrincipal y renaperData (respuesta mock del registro).
Ejemplo de respuesta (mock aprobado)
El body de la respuesta y el payload del webhook siguen la misma estructura que una validación real. Ejemplo de forma para un mock aprobado (campos relevantes):
{
"id": "uuid",
"entityId": "uuid",
"status": "approved",
"verifiedAt": "2026-02-21T12:00:00.000Z",
"extractedData": {
"firstName": "Sandbox",
"lastName": "User",
"fullName": "Sandbox User",
"dateOfBirth": "1990-01-15",
"documentNumber": "99990001",
"documentType": "Identity Card",
"nationality": "AR",
"gender": "M",
"age": 34
},
"verifiedFields": ["identity_document", "liveness_check", "face_match"],
"warnings": [],
"metadata": {
"doubleChecks": { "renaper": true },
"responseDoubleChecks": {
"renaper": {
"verified": true,
"matchResult": "match",
"personalNumber": "99990001",
"idTramitePrincipal": "987654321",
"verifiedAt": "2026-02-21T12:00:00.000Z",
"renaperData": { "id_tramite_principal": "987654321", "apellido": "User", "nombres": "Sandbox", "fecha_nacimiento": "1990-01-15", "dni": "99990001", "..." }
}
}
}
}
metadata.responseDoubleChecks no aparece en aprobado; cuando sí se pide, aparece como arriba.
Datos mock personalizados
El set por defecto anterior está disponible para todas las organizaciones sandbox sin configuración.
Añadir o cambiar números de documento mock en tu sandbox:
Si necesitas documentos de prueba adicionales o resultados distintos para números concretos, contacta al equipo de Gueno. Los datos mock personalizados para sandbox los gestiona Gueno y no pueden configurarse por el cliente.
Ver también
