> ## 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.
# Dados mock no sandbox
> Números de documento de teste e resultados esperados para KYC no sandbox — na API KYC da gu1 para fluxos de verificação de identidade.
## Visão geral
No **sandbox**, quando você cria uma validação KYC para uma **entidade pessoa**, a API pode retornar um **resultado mock imediato** com base no **taxId** (documento) da entidade. Nenhuma verificação externa é realizada; a resposta e os webhooks correspondem ao resultado associado a esse documento em nosso conjunto de teste.
Isso permite testar todos os fluxos (aprovado, rejeitado, cancelado, dupla verificação RENAPER, etc.) sem passar por uma verificação real.
**Configure um webhook para receber as respostas!**
No sandbox, os resultados de KYC são atualizados **de forma assíncrona** (igual à produção). Embora a API retorne 201 imediatamente após criar a validação, o resultado final (aprovado, rejeitado, etc.) é enviado via **webhooks** momentos depois.
**Você deve configurar um endpoint webhook em sua organização** para receber as notificações de validação. Sem um webhook configurado, você não receberá as atualizações de status.
📚 **Aprenda a configurar webhooks:** [Integração webhook](/pt/use-cases/kyc/webhook-integration)
**O formato não importa.** O `taxId` da entidade pode ser enviado com ou sem formatação (ex.: `99.990.001` ou `99990001`). A API normaliza antes de comparar, então ambos funcionam igual.
## Como funciona
1. A entidade pessoa pertence a uma organização em modo **sandbox**.
2. Você chama **POST /api/kyc/validations** com o `entityId` dessa entidade.
3. A API consulta o **taxId** da entidade no mapa de teste do sandbox (após normalizar: apenas dígitos e letras).
4. Se houver correspondência, uma **validação mock** é criada com status `pending` (201 Created) e momentos depois é atualizada para o **status final** (ex.: `approved`, `rejected`, `cancelled`).
5. **Os webhooks são enviados** para seu endpoint configurado com o resultado final.
6. Se não houver correspondência, a API segue o fluxo normal (cria uma sessão de verificação real e retorna `providerSessionUrl`).
**Fluxo assíncrono:** O comportamento no sandbox **replica exatamente o fluxo de produção**, que é assíncrono. A validação é criada no estado `pending`, depois atualizada e notificada via webhook. **Não tente fazer polling imediato** ao endpoint GET após criar a validação - use webhooks para receber o resultado.
## Prévia sintética de entidade (somente GET)
No **sandbox**, ao consultar um **número de documento do catálogo de teste** e **não existir entidade real**, a Gu1 pode retornar uma **pessoa sintética** em vez de `404`:
* `GET /api/entities/by-tax-id/{taxId}`
* `GET /api/entities?taxId={taxId}` (filtro exato, zero correspondências reais)
A resposta inclui `sandboxMock: true`, `id: null` e `metadata.sandboxKycOutcome`. **Nada é gravado no banco.**
A prévia é para **descoberta e documentação**. Para `POST /api/kyc/validations` ou `POST /api/kyc/biometric/sessions` com `entityTaxId`, você deve **criar uma entidade pessoa real** primeiro (com o mesmo `taxId` de teste). Endpoints KYC/biometria resolvem apenas linhas persistidas.
**RENAPER no sandbox:** Se você enviar `doubleCheckRenaper: true` ao criar a validação e o resultado for aprovado (ou rejeição relacionada ao RENAPER), a resposta e o payload do webhook incluirão `metadata.responseDoubleChecks.renaper` com a mesma estrutura que em produção.
## Valores de teste padrão
Oferecemos um conjunto fixo de números de documento de teste em quatro formatos. Cada número corresponde a um **resultado**. A chave de busca é o valor **normalizado** (sem pontos, traços ou espaços).
### Lista de resultados (o que cada número retorna)
| # | Resultado | Significado |
| -- | ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| 01 | `approved` | KYC aprovado. Se você solicitou dupla verificação RENAPER, a resposta inclui RENAPER ok. |
| 02 | `approved_with_renaper` | Igual a approved; RENAPER na resposta apenas se solicitado na criação. |
| 03 | `cancelled` | Validação cancelada. |
| 04 | `rejected` | Rejeição genérica. |
| 05 | `rejected_document_mismatch` | Rejeição por documento não coincidente com a entidade. |
| 06 | `rejected_renaper_tramite_not_match` | Rejeição: número de trâmite não coincide com o registro. |
| 07 | `rejected_renaper_dni_not_match` | Rejeição: documento não coincide com o registro. |
| 08 | `rejected_renaper_verification_unavailable` | Rejeição: verificação com o registro indisponível. |
| 09 | `rejected_renaper_dni_missing` | Rejeição: sem documento para verificação com o registro. |
| 10 | `rejected` | Rejeição genérica (segundo número para testes). |
### Argentina – DNI (8 dígitos)
Use qualquer um destes como `taxId` da entidade (com ou sem pontos). O valor normalizado é usado para o match.
| Valor de exemplo | Normalizado | Resultado |
| ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
| 99.990.001 ou 99990001 | 99990001 | approved |
| 99.990.002 ou 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 padrão **rejected** — ver [Biometria incorporada mock](#biometria-incorporada-mock-sandbox) |
### Argentina – CUIT (11 dígitos)
Formato: `20-XXXXXXXX-X`. Exemplo: `20-99990001-9`.
| Valor de exemplo | 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 padrão **rejected** |
### Brasil – CPF (11 dígitos)
Formato: `XXX.XXX.XXX-XX`. Exemplo: `999.900.001-01`.
| Valor de exemplo | 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`. Exemplo: `99.990.000/0001-01`.
| Valor de exemplo | 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 |
## Exemplo: aprovado com RENAPER
1. Crie uma entidade **pessoa** no sandbox com `taxId`: `99990001` (ou `99.990.001`).
2. Chame **POST /api/kyc/validations** com `entityId` e `doubleCheckRenaper: true` (body ou query).
3. A API retorna **201** com a validação; em seguida o status é **approved** e o webhook `kyc.validation_approved` é enviado.
4. O payload do webhook inclui o objeto completo da validação, incluindo **`metadata.responseDoubleChecks.renaper`** com `verified: true`, `matchResult: "match"`, `personalNumber`, `idTramitePrincipal` e `renaperData` (resposta mock do registro).
## Exemplo de resposta (mock aprovado)
O body da resposta e o payload do webhook seguem a mesma estrutura de uma validação real. Exemplo de forma para um mock aprovado (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": ""
}
}
}
}
}
```
Quando a dupla verificação RENAPER não é solicitada, `metadata.responseDoubleChecks` não aparece em aprovado; quando é solicitada, aparece como acima. Para `renaperData` em rejeições ou erros de serviço, ver [forma de `renaperData`](/pt/use-cases/kyc/create-validation#forma-de-renaperdata).
## Biometria incorporada (mock sandbox)
Após um **KYC mock aprovado** para a mesma entidade, você pode criar uma **sessão biométrica incorporada** (`POST /api/kyc/biometric/sessions`) também em **modo mock** no sandbox — sem UI hospedada; a Gu1 retorna o resultado imediatamente.
A biometria mock usa a **mesma organização sandbox** e o **mesmo mapa de `taxId` de teste** do mock de KYC. Validações mock incluem `metadata.sandboxMock: true`. Sessões biométricas mock incluem `metadata.sandboxMock: true` e `metadata.sandboxMockOutcome` (`approved` ou `rejected`).
### Pré-requisitos
1. Organização em modo **sandbox** (igual ao mock de KYC).
2. Entidade pessoa com **`taxId` de teste** cujo outcome de KYC seja **`approved`** ou **`approved_with_renaper`** (ex.: `99990001`, `99990002`, `99990011`).
3. **KYC aprovado** para essa entidade (crie antes com `POST /api/kyc/validations`).
### Outcomes biométricos por documento de teste
| Exemplo `taxId` | Normalizado | Mock KYC | Mock biometria (padrão) |
| ------------------------ | ---------------------- | ----------------------- | ----------------------- |
| 99990001 / 20-99990001-9 | 99990001 / 20999900019 | approved | **approved** (imediato) |
| 99990002 / 20-99990002-9 | 99990002 / 20999900029 | approved\_with\_renaper | **approved** (imediato) |
| 99990011 / 20-99990011-9 | 99990011 / 20999900119 | approved | **rejected** (imediato) |
Se o mock de KYC for `rejected` ou `cancelled`, não é possível criar sessão biométrica (`NO_KYC`).
### Forçar outcome na mesma entidade
Em qualquer entidade mock elegível, envie `metadata.sandboxMockOutcome` no body:
```json theme={null}
POST /api/kyc/biometric/sessions
{
"entityId": "uuid",
"metadata": {
"sandboxMockOutcome": "rejected"
}
}
```
Valores: `approved`, `rejected`. Aplica-se apenas quando qualifica para mock sandbox (org sandbox + KYC mock aprovado, ou KYC com `metadata.sandboxMock: true`).
### Exemplo: mock aprovado
1. Criar entidade pessoa com `taxId`: `99990001`.
2. `POST /api/kyc/validations` → webhook `kyc.validation_approved` (ou GET até `approved`).
3. `POST /api/kyc/biometric/sessions` com `{ "entityId": "..." }`.
Resposta `201` com `"status": "approved"`, `hostedSessionId` com prefixo `sandbox-mock-bio-`, webhook `biometric.session_approved`. Iframe não é necessário.
### Exemplo: mock rejeitado
**Opção A** — documento `99990011` (KYC aprovado, biometria rejeitada por padrão).
**Opção B** — mesma entidade `99990001` com `"metadata": { "sandboxMockOutcome": "rejected" }`.
Resposta `"status": "rejected"`; webhook `biometric.session_rejected`.
### Biometria real (não mock) no sandbox
Se o `taxId` **não** estiver no mapa de teste, ou a org não for sandbox, o create segue o **fluxo de produção**: UI de captura hospedada, `status: pending`, `hostedSessionId` atribuído pela Gu1. Exige retrato válido do KYC aprovado.
### Retentativas e sessões ativas
* Se a última sessão biométrica estiver `pending` ou `in_progress`, o create retorna **`409 ACTIVE_SESSION_EXISTS`** com `activeSessionId`. Cancele com `POST /api/kyc/biometric/sessions/:id/cancel`.
* Se um create anterior persistiu na Gu1 mas o cliente repetiu a chamada, a Gu1 reutiliza a linha existente quando o mesmo `hostedSessionId` é retornado (create idempotente).
Ver também: [Sessão biométrica incorporada](/pt/use-cases/kyc/embedded-biometric).
## Dados mock personalizados
O conjunto padrão acima está disponível para todas as organizações sandbox sem configuração.
**Adicionar ou alterar números de documento mock no seu sandbox:**\
Se você precisar de documentos de teste adicionais ou resultados diferentes para números específicos, entre em contato com a **equipe Gu1**. Dados mock personalizados para sandbox são gerenciados pela Gu1 e não podem ser configurados pelo cliente.
## Ver também
* [Criar validação KYC](/pt/use-cases/kyc/create-validation) – Como chamar a API
* [Sessão biométrica incorporada](/pt/use-cases/kyc/embedded-biometric) – Reautenticação hospedada após KYC
* [Integração webhook](/pt/use-cases/kyc/webhook-integration) – Receber eventos de validação em tempo real