Skip to main content

​
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

  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. 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)

#ResultadoSignificado
01approvedKYC aprovado. Se você solicitou dupla verificação RENAPER, a resposta inclui RENAPER ok.
02approved_with_renaperIgual a approved; RENAPER na resposta apenas se solicitado na criação.
03cancelledValidação cancelada.
04rejectedRejeição genérica.
05rejected_document_mismatchRejeição por documento não coincidente com a entidade.
06rejected_renaper_tramite_not_matchRejeição: número de trâmite não coincide com o registro.
07rejected_renaper_dni_not_matchRejeição: documento não coincide com o registro.
08rejected_renaper_verification_unavailableRejeição: verificação com o registro indisponível.
09rejected_renaper_dni_missingRejeição: sem documento para verificação com o registro.
10rejectedRejeiçã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 exemploNormalizadoResultado
99.990.001 ou 9999000199990001approved
99.990.002 ou 9999000299990002approved_with_renaper
99.990.00399990003cancelled
99.990.00499990004rejected
99.990.00599990005rejected_document_mismatch
99.990.00699990006rejected_renaper_tramite_not_match
99.990.00799990007rejected_renaper_dni_not_match
99.990.00899990008rejected_renaper_verification_unavailable
99.990.00999990009rejected_renaper_dni_missing
99.990.01099990010rejected

​
Argentina – CUIT (11 dígitos)

Formato: 20-XXXXXXXX-X. Exemplo: 20-99990001-9.
Valor de exemploNormalizadoResultado
20-99990001-920999900019approved
20-99990002-920999900029approved_with_renaper
20-99990003-920999900039cancelled
20-99990004-920999900049rejected
20-99990005-920999900059rejected_document_mismatch
20-99990006-920999900069rejected_renaper_tramite_not_match
20-99990007-920999900079rejected_renaper_dni_not_match
20-99990008-920999900089rejected_renaper_verification_unavailable
20-99990009-920999900099rejected_renaper_dni_missing
20-99990010-920999900109rejected

​
Brasil – CPF (11 dígitos)

Formato: XXX.XXX.XXX-XX. Exemplo: 999.900.001-01.
Valor de exemploNormalizadoResultado
999.900.001-0199990000101approved
999.900.001-0299990000102approved_with_renaper
999.900.001-0399990000103cancelled
999.900.001-0499990000104rejected
999.900.001-0599990000105rejected_document_mismatch
999.900.001-0699990000106rejected_renaper_tramite_not_match
999.900.001-0799990000107rejected_renaper_dni_not_match
999.900.001-0899990000108rejected_renaper_verification_unavailable
999.900.001-0999990000109rejected_renaper_dni_missing
999.900.001-1099990000110rejected

​
Brasil – CNPJ (14 dígitos)

Formato: XX.XXX.XXX/XXXX-XX. Exemplo: 99.990.000/0001-01.
Valor de exemploNormalizadoResultado
99.990.000/0001-0199990000000101approved
99.990.000/0001-0299990000000102approved_with_renaper
99.990.000/0001-0399990000000103cancelled
99.990.000/0001-0499990000000104rejected
99.990.000/0001-0599990000000105rejected_document_mismatch
99.990.000/0001-0699990000000106rejected_renaper_tramite_not_match
99.990.000/0001-0799990000000107rejected_renaper_dni_not_match
99.990.000/0001-0899990000000108rejected_renaper_verification_unavailable
99.990.000/0001-0999990000000109rejected_renaper_dni_missing
99.990.000/0001-1099990000000110rejected

​
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): 
{
  "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", "..." }
      }
    }
  }
}
Quando a dupla verificação RENAPER não é solicitada, metadata.responseDoubleChecks não aparece em aprovado; quando é solicitada, aparece como acima.

​
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 Gueno. Dados mock personalizados para sandbox são gerenciados pela Gueno e não podem ser configurados pelo cliente.

​
Ver também