Datos mock en sandbox

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.

Vista previa sintética de entidad (solo GET)

En sandbox, si consultás un número de documento del catálogo de prueba y no existe una entidad real, Gu1 puede devolver una persona sintética en lugar de 404:

GET /api/entities/by-tax-id/{taxId}
GET /api/entities?taxId={taxId} (filtro exacto, cero coincidencias reales)

La respuesta incluye sandboxMock: true, id: null y metadata.sandboxKycOutcome. No se escribe nada en la base de datos.

La vista previa es para descubrimiento y documentación. Para POST /api/kyc/validations o POST /api/kyc/biometric/sessions con entityTaxId, primero debés crear una entidad persona real (con el mismo taxId de prueba). Los endpoints KYC/biometría resuelven solo filas persistidas.

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
99.990.011	99990011	approved (KYC); mock biométrico por defecto rejected — ver Biometría embebida mock

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
20-99990011-9	20999900119	approved (KYC); mock biométrico por defecto 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",
    "ejemplar": "A",
    "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",
        "comparisonResults": {
          "dni": { "field": "dni", "compared": true, "passed": true, "ocrValue": "99990001", "renaperValue": "99990001" },
          "tramite": { "field": "tramite", "compared": true, "passed": true, "ocrValue": "99990001", "renaperValue": "987654321" },
          "ejemplar": { "field": "ejemplar", "compared": true, "passed": true, "ocrValue": "A", "renaperValue": "A" }
        },
        "renaperData": {
          "id_tramite_principal": "987654321",
          "id_tramite_tarjeta_reimpresa": "112233445",
          "ejemplar": "A",
          "vencimiento": "2030-05-20",
          "emision": "2015-05-20",
          "apellido": "User",
          "nombres": "Sandbox",
          "fecha_nacimiento": "1990-01-15",
          "cuil": "20-99990001-9",
          "calle": "Av. Corrientes",
          "numero": "1234",
          "piso": "5",
          "departamento": "B",
          "codigo_postal": "1043",
          "barrio": "San Nicolás",
          "monoblock": "",
          "ciudad": "Ciudad Autónoma de Buenos Aires",
          "municipio": "Comuna 1",
          "provincia": "Buenos Aires",
          "pais": "Argentina",
          "nacionalidad": "Argentina",
          "codigo_fallecido": "",
          "mensaje_fallecido": "",
          "fecha_fallecimiento": "",
          "id_ciudadano": "99990001",
          "codigo": "",
          "mensaje": ""
        }
      }
    }
  }
}

Cuando no se pide doble chequeo RENAPER, metadata.responseDoubleChecks no aparece en aprobado; cuando sí se pide, aparece como arriba. Para renaperData en rechazos o errores de servicio, ver forma de renaperData.

Biometría embebida (mock sandbox)

Tras un KYC mock aprobado para la misma entidad, podés crear una sesión biométrica embebida (POST /api/kyc/biometric/sessions) también en modo mock en sandbox: sin UI hospedada; Gu1 devuelve el resultado de inmediato.

La biometría mock usa la misma organización sandbox y el mismo mapa de taxId de prueba que el mock de KYC. Las validaciones mock incluyen metadata.sandboxMock: true. Las sesiones biométricas mock incluyen metadata.sandboxMock: true y metadata.sandboxMockOutcome (approved o rejected).

Requisitos

Organización en modo sandbox (igual que KYC mock).
Entidad persona con taxId de prueba cuyo outcome de KYC sea approved o approved_with_renaper (p. ej. 99990001, 99990002, 99990011).
KYC aprobado para esa entidad (crearlo antes con POST /api/kyc/validations).

Outcomes biométricos por documento de prueba

Ejemplo `taxId`	Normalizado	Mock KYC	Mock biometría (default)
99990001 / 20-99990001-9	99990001 / 20999900019	approved	approved (inmediato)
99990002 / 20-99990002-9	99990002 / 20999900029	approved_with_renaper	approved (inmediato)
99990011 / 20-99990011-9	99990011 / 20999900119	approved	rejected (inmediato)

Si el mock de KYC es rejected o cancelled, no podés crear sesión biométrica (NO_KYC).

Forzar outcome en la misma entidad

En cualquier entidad mock elegible, enviá metadata.sandboxMockOutcome en el body:

POST /api/kyc/biometric/sessions
{
  "entityId": "uuid",
  "metadata": {
    "sandboxMockOutcome": "rejected"
  }
}

Valores: approved, rejected. Solo aplica si califica para mock sandbox (org sandbox + KYC mock aprobado, o KYC con metadata.sandboxMock: true).

Ejemplo: mock aprobado

Crear entidad persona con taxId: 99990001.
POST /api/kyc/validations → webhook kyc.validation_approved (o GET hasta approved).
POST /api/kyc/biometric/sessions con { "entityId": "..." }.

Respuesta 201 con "status": "approved", hostedSessionId con prefijo sandbox-mock-bio-, webhook biometric.session_approved. No hace falta iframe.

Ejemplo: mock rechazado

Opción A — documento 99990011 (KYC aprobado, biometría rechazada por defecto). Opción B — misma entidad 99990001 con "metadata": { "sandboxMockOutcome": "rejected" }. Respuesta "status": "rejected"; webhook biometric.session_rejected.

Biometría real (no mock) en sandbox

Si el taxId no está en el mapa de prueba, o la org no es sandbox, el create sigue el flujo de producción: UI de captura hospedada, status: pending, y un hostedSessionId asignado por Gu1. Requiere retrato válido del KYC aprobado.

Reintentos y sesiones activas

Si la última sesión biométrica está pending o in_progress, el create devuelve 409 ACTIVE_SESSION_EXISTS con activeSessionId. Cancelala con POST /api/kyc/biometric/sessions/:id/cancel.
Si un create anterior persistió en Gu1 pero el cliente reintentó, Gu1 reutiliza la fila existente cuando devuelve el mismo hostedSessionId (create idempotente).

Ver también: Sesión biométrica embebida.

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 Gu1. Los datos mock personalizados para sandbox los gestiona Gu1 y no pueden configurarse por el cliente.

Ver también

Crear validación KYC – Cómo llamar a la API
Sesión biométrica embebida – Reautenticación hospedada tras KYC
Integración webhook – Recibir eventos de validación en tiempo real

​Descripción general

​Cómo funciona

​Vista previa sintética de entidad (solo GET)

​Valores de prueba por defecto

​Lista de resultados (qué devuelve cada número)

​Argentina – DNI (8 dígitos)

​Argentina – CUIT (11 dígitos)

​Brasil – CPF (11 dígitos)

​Brasil – CNPJ (14 dígitos)

​Ejemplo: aprobado con RENAPER

​Ejemplo de respuesta (mock aprobado)

​Biometría embebida (mock sandbox)

​Requisitos

​Outcomes biométricos por documento de prueba

​Forzar outcome en la misma entidad

​Ejemplo: mock aprobado

​Ejemplo: mock rechazado

​Biometría real (no mock) en sandbox

​Reintentos y sesiones activas

​Datos mock personalizados

​Ver también

Descripción general

Cómo funciona

Vista previa sintética de entidad (solo GET)

Valores de prueba por defecto

Lista de resultados (qué devuelve cada número)

Argentina – DNI (8 dígitos)

Argentina – CUIT (11 dígitos)

Brasil – CPF (11 dígitos)

Brasil – CNPJ (14 dígitos)

Ejemplo: aprobado con RENAPER

Ejemplo de respuesta (mock aprobado)

Biometría embebida (mock sandbox)

Requisitos

Outcomes biométricos por documento de prueba

Forzar outcome en la misma entidad

Ejemplo: mock aprobado

Ejemplo: mock rechazado

Biometría real (no mock) en sandbox

Reintentos y sesiones activas

Datos mock personalizados

Ver también