Sandbox e Dados de Teste

O sandbox é uma cópia completa do pipeline de verificação com suas próprias credenciais e seus próprios dados. Use-o para construir e validar sua integração antes que qualquer cliente real a utilize.

Acesso

Credenciais de sandbox e de produção nunca são intercambiáveis, e uma verificação em sandbox nunca é uma base válida para uma decisão real de onboarding.

O Sandbox Executa Verificação Real

O sandbox realiza análise real de documentos — o mesmo pipeline de extração, autenticidade, prova de vida e correspondência facial da produção. Nenhum número de documento de teste produz um resultado de verificação pré-definido como funcionam os números de cartão de teste em pagamentos: aprovação, recusa e revisão vêm todos das imagens que você envia.

A única exceção é a checagem de formato do número do documento, que aceita valores reservados — veja Números de Documento de Teste Reservados. Ela verifica o formato de um número declarado e nunca olha uma imagem, portanto é uma superfície separada do pipeline de verificação descrito aqui.

A consequência prática: teste com documentos reais que você pessoalmente controla, ou com documentos emitidos para testes. Uma verificação falhará genuinamente se a imagem estiver borrada, o documento estiver vencido ou a selfie não corresponder — o que é exatamente o que torna o sandbox útil para validar seu tratamento de erros.

Todo resultado carrega um campo provider. "inyo" significa que uma análise real o produziu. "inyo-mock" significa que um simulador o produziu — o que nunca acontece em produção, e indica de forma inequívoca que um resultado não veio de uma verificação real.

Produzindo Cada Resultado

Peça um tenant de sandbox separado se você precisar de configurações conflitantes. O roteamento de revisão e as rejeições retidas são configurações no nível do tenant, então exercitar tanto uma recusa normal quanto uma recusa retida significa alterar a configuração entre execuções — ou ter dois tenants de sandbox.

Testando Sem Câmera

O validador de formato de número de documento não precisa de imagens e não consome nenhuma verificação, o que o torna a coisa mais rápida para integrar primeiro:

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"documentType": "drivers_license", "number": "not-a-number", "issuingCountry": "USA", "issuingState": "PA"}'

{
  "documentType": "drivers_license",
  "issuingCountry": "USA",
  "issuingState": "PA",
  "valid": false,
  "rule": "dl:USA:PA",
  "detail": "document number does not match the PA license format"
}

Use-o para confirmar seu tratamento dos três estados — true, false e null para uma jurisdição desconhecida. Veja Validador de Número de Documento.

Números de Documento de Teste Reservados

A checagem de formato do número do documento aceita um pequeno conjunto de valores reservados que retornam o veredito escolhido sob demanda. Use-os quando precisar de um resultado valid específico — mais comumente a partir da criação de remetente de remessas, que executa essa checagem em todo documento declarado — sem antes ter de aprender o formato real de numeração de uma jurisdição.

Somente no sandbox. Esses valores são habilitados por ambiente; se os valores abaixo retornarem um veredito comum, peça ao seu contato Inyo para habilitá-los no seu tenant de sandbox.

Todo tipo capturável publica os três estados de valid, então você pode exercitar seu próprio tratamento por tipo sem precisar aprender o formato real de numeração de uma jurisdição. ssn e itin trazem apenas um valor de aprovação — veja abaixo.

As linhas de identity_card são mexicanas porque não existe regra para carteiras de identidade dos EUA — um valor americano seria um caso de teste para uma verificação que não existe. A CURP codifica o nome e a data de nascimento do titular, então o campo de nome todo em X é estruturalmente válido e não pode colidir com uma pessoa real.

Envie cada número com o issuingCountry e o issuingState indicados. Um valor reservado é reconhecido por esse par exato, portanto o mesmo número em qualquer outra jurisdição é validado pelas regras comuns.

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"documentType": "drivers_license", "number": "99900002", "issuingCountry": "USA", "issuingState": "PA"}'

{
  "documentType": "drivers_license",
  "issuingCountry": "USA",
  "issuingState": "PA",
  "valid": false,
  "rule": "reserved:drivers_license:PA:invalid",
  "detail": "reserved sandbox test value — simulated invalid verdict"
}

Um resultado simulado carrega o cabeçalho de resposta X-Inyo-Simulated: true. Ele está presente apenas quando um valor reservado produziu o resultado, e ausente caso contrário — inclusive em produção, onde nunca aparece.

Os valores reservados são números reais e válidos no formato da sua jurisdição. Isso é deliberado: significa que uma regra de formato anterior — como a que a criação de remetente de remessas aplica antes de chamar essa checagem — deixa o valor passar em vez de rejeitá-lo antes, o que é justamente o que permite que 99900002 chegue até nós e volte como false.

A consequência é que onde os valores reservados não estão habilitados, eles retornam o veredito que as regras reais de formato lhes dão — valid: true para todos os valores, exceto o ITIN, que retorna false. Um valor reservado nunca produz um resultado mais restritivo do que um número comum produziria, então deixar um no código não é um risco de segurança — mas ele deixa silenciosamente de simular, portanto não leve nenhum para produção.

912891234 é o único valor que retorna false com a simulação desligada. Não existe um espécime de ITIN anulado como 078-05-1120 é para SSNs, então ele vem de um grupo que o IRS reserva para outros programas — a única forma de garantir que nunca pertencerá a uma pessoa real. O custo é que uma regra de formato anterior mais estrita pode rejeitá-lo antes que ele chegue a essa checagem. Se isso acontecer do seu lado, use-o diretamente contra este endpoint em vez de passar por um chamador que pré-valida.

Testando a Entrega de Resultados

A entrega vale a pena ser testada por si só, independentemente dos resultados de verificação:

1. Verificação de assinatura — capture um corpo real de webhook do sandbox e sua X-Inyo-Signature, e faça um teste unitário do seu verificador contra esses bytes exatos. Adicione um caso que altera um byte do corpo e afirma a rejeição, e um caso que re-serializa o JSON parseado e afirma a rejeição. Esses dois casos capturam o erro que quebra a maioria das integrações. Depois adicione três que capturam os que você só vai encontrar mais tarde: um t= vencido, fora da sua tolerância; um cabeçalho carregando um v2= extra que seu código não implementa (ele ainda deve validar no v1); e um cabeçalho repetindo v1= duas vezes (ele deve ser rejeitado de imediato, não resolvido escolhendo um dos dois).
2. Comportamento de retry — retorne 500 do seu endpoint e confirme que você vê até três tentativas, e depois nada.
3. Ordenação — reproduza duas notificações armazenadas de uma sessão fora de ordem e afirme que seu handler mantém a que tem o notifiedAt mais alto.
4. Idempotência — entregue o mesmo resultado duas vezes e afirme que seu sistema não o processa em duplicidade.

Os passos 1, 3 e 4 não precisam de nenhuma chamada ao sandbox depois que você capturou um payload real.

Antes de Entrar em Produção

Próximos Passos

• Primeiros Passos — o passo a passo de ponta a ponta
• Recebendo Resultados — assinaturas, retries e ordenação