Dados mock no sandbox

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

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

A entidade pessoa pertence a uma organização em modo sandbox.
Você chama POST /api/kyc/validations com o entityId dessa entidade.
A API consulta o taxId da entidade no mapa de teste do sandbox (após normalizar: apenas dígitos e letras).
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).
Os webhooks são enviados para seu endpoint configurado com o resultado final.
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

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

Crie uma entidade pessoa no sandbox com taxId: 99990001 (ou 99.990.001).
Chame POST /api/kyc/validations com entityId e doubleCheckRenaper: true (body ou query).
A API retorna 201 com a validação; em seguida o status é approved e o webhook kyc.validation_approved é enviado.
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):

{
  "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.

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

Organização em modo sandbox (igual ao mock de KYC).
Entidade pessoa com taxId de teste cujo outcome de KYC seja approved ou approved_with_renaper (ex.: 99990001, 99990002, 99990011).
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:

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

Criar entidade pessoa com taxId: 99990001.
POST /api/kyc/validations → webhook kyc.validation_approved (ou GET até approved).
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.

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 – Como chamar a API
Sessão biométrica incorporada – Reautenticação hospedada após KYC
Integração webhook – Receber eventos de validação em tempo real

​Visão geral

​Como funciona

​Prévia sintética de entidade (somente GET)

​Valores de teste padrão

​Lista de resultados (o que cada número retorna)

​Argentina – DNI (8 dígitos)

​Argentina – CUIT (11 dígitos)

​Brasil – CPF (11 dígitos)

​Brasil – CNPJ (14 dígitos)

​Exemplo: aprovado com RENAPER

​Exemplo de resposta (mock aprovado)

​Biometria incorporada (mock sandbox)

​Pré-requisitos

​Outcomes biométricos por documento de teste

​Forçar outcome na mesma entidade

​Exemplo: mock aprovado

​Exemplo: mock rejeitado

​Biometria real (não mock) no sandbox

​Retentativas e sessões ativas

​Dados mock personalizados

​Ver também

Visão geral

Como funciona

Prévia sintética de entidade (somente GET)

Valores de teste padrão

Lista de resultados (o que cada número retorna)

Argentina – DNI (8 dígitos)

Argentina – CUIT (11 dígitos)

Brasil – CPF (11 dígitos)

Brasil – CNPJ (14 dígitos)

Exemplo: aprovado com RENAPER

Exemplo de resposta (mock aprovado)

Biometria incorporada (mock sandbox)

Pré-requisitos

Outcomes biométricos por documento de teste

Forçar outcome na mesma entidade

Exemplo: mock aprovado

Exemplo: mock rejeitado

Biometria real (não mock) no sandbox

Retentativas e sessões ativas

Dados mock personalizados

Ver também