> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Datos mock en sandbox
> Números de documento de prueba y resultados esperados para KYC en sandbox — en la API KYC de gu1 para flujos de verificación de identidad.
## 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](/es/use-cases/kyc/webhook-integration)
**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
1. La entidad persona pertenece a una organización en modo **sandbox**.
2. Llamas a **POST /api/kyc/validations** con el `entityId` de esa entidad.
3. La API busca el **taxId** de la entidad en el mapa de prueba de sandbox (tras normalizar: solo dígitos y letras).
4. 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`).
5. **Se envían los webhooks** correspondientes a tu endpoint configurado con el resultado final.
6. 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](#biometría-embebida-mock-sandbox) |
### 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
1. Crea una entidad **persona** en sandbox con `taxId`: `99990001` (o `99.990.001`).
2. Llama a **POST /api/kyc/validations** con `entityId` y `doubleCheckRenaper: true` (body o query).
3. La API devuelve **201** con la validación; poco después el estado es **approved** y se envía el webhook `kyc.validation_approved`.
4. 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):
```json theme={null}
{
"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`](/es/use-cases/kyc/create-validation#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
1. Organización en modo **sandbox** (igual que KYC mock).
2. Entidad persona con **`taxId` de prueba** cuyo outcome de KYC sea **`approved`** o **`approved_with_renaper`** (p. ej. `99990001`, `99990002`, `99990011`).
3. **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:
```json theme={null}
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
1. Crear entidad persona con `taxId`: `99990001`.
2. `POST /api/kyc/validations` → webhook `kyc.validation_approved` (o GET hasta `approved`).
3. `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](/es/use-cases/kyc/embedded-biometric).
## 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](/es/use-cases/kyc/create-validation) – Cómo llamar a la API
* [Sesión biométrica embebida](/es/use-cases/kyc/embedded-biometric) – Reautenticación hospedada tras KYC
* [Integración webhook](/es/use-cases/kyc/webhook-integration) – Recibir eventos de validación en tiempo real