Verificação de Documentos

Para avançar um remetente para níveis de conformidade mais altos (Nível 2 e acima), seus documentos de identidade precisam ser verificados. Há duas formas de fazer isso:

• Sessão de Verificação KYC (recomendado) — crie uma sessão e entregue ao seu usuário a URL de um widget hospedado. O widget captura as fotos do documento e uma selfie, verifica tudo, e o resultado flui automaticamente para o registro do remetente.
• Envio direto de documentos (obsoleto) — envie você mesmo os arquivos de imagem do documento e aguarde a revisão por OCR/manual.

⚠️ Os endpoints de envio direto estão obsoletos. Novas integrações devem usar Sessões de Verificação KYC. As integrações de envio existentes continuam funcionando, mas o fluxo de sessão adiciona prova de vida com selfie, comparação facial com o retrato do documento e defesa contra ataques de apresentação, algo que o simples envio de arquivos não oferece.

Sessões de Verificação KYC (Recomendado)

Endpoint: POST /organizations/{tenant}/v2/people/{personId}/kycSession
Autenticação: Nível de tenant (x-api-key)

Cria uma sessão de Verificação de Identidade Inyo360 para a pessoa. Você fornece apenas parâmetros de apresentação do widget — o documento a verificar é resolvido automaticamente a partir dos documentos declarados da pessoa, e a sessão é pré-preenchida com os dados do registro (nome, data de nascimento, número do documento, estado emissor, nacionalidade), de modo que o usuário só precisa capturar o documento e a selfie.

Declare o documento primeiro. A pessoa precisa ter no registro um documento verificável por KYC e não vencido (adicionado via POST /v2/people documents[]) antes de abrir uma sessão — caso contrário a requisição retorna 422 NO_VERIFIABLE_DOCUMENT.

Corpo da Requisição

Ambos os campos são obrigatórios:

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/v2/people/$PERSON_ID/kycSession \
  --header 'Content-Type: application/json' \
  --header "x-api-key: $API_KEY" \
  --data '{
  "language": "pt-BR",
  "redirectUrl": "https://your-app.example/kyc/done"
}'

Como o Documento É Selecionado

A Inyo percorre os documentos declarados da pessoa em ordem de prioridade e verifica o primeiro elegível:

1. drivers_license
2. passport
3. A família de documentos de identidade, do mais específico ao mais genérico: dni, cc, cpf, consular_id, voter_id, id

Documentos com data de validade no passado são ignorados (uma pessoa com carteira de motorista vencida e passaporte válido usa o passaporte); documentos sem data de validade registrada são aceitos. ssn, itin e other nunca são selecionados — não correspondem ao vocabulário de documentos do KYC.

A checagem cruzada de dados está sempre ativa: a camada KYC compara os dados extraídos do documento capturado com o registro pré-preenchido da pessoa.

Resposta (201):

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widgetUrl": "https://{FQDN}/verify/8Kd2mQ..."
}

O Fluxo

1. Crie a sessão e abra a widgetUrl para o seu usuário (link, redirecionamento ou webview — veja Entrega do widget).
2. O usuário fotografa o documento e tira uma selfie no widget.
3. A Inyo recebe diretamente o resultado de verificação assinado — você não manipula nenhuma imagem de documento.
4. Com um resultado verificado, os registros de documentos da pessoa são criados/atualizados automaticamente com o veredito de verificação, e o webhook DocumentUpdatedEvents (webhooks) é disparado.
5. Consulte o novo nível do remetente via GET /participants/{id}/complianceLevels.

As sessões passam por estes estados no lado da Inyo: PENDING → VERIFIED, REJECTED, PENDING_REVIEW (revisão manual na camada KYC) ou EXPIRED.

Erros

Legado: Envio Direto de Documentos (Obsoleto)

⚠️ Obsoleto. Use as Sessões de Verificação KYC no lugar. Estes endpoints permanecem disponíveis para integrações existentes. Os documentos enviados são verificados por OCR com IA (quando habilitado para o seu tenant) ou pela equipe de conformidade da Inyo.

Documentos de Identidade

Endpoint: POST /organizations/{tenant}/people/{personId}/documents/documentId/{subtype}/upload
Autenticação: Nível de tenant (x-api-key)
Content-Type: multipart/form-data

O segmento de caminho {subtype} é o tipo do documento. Tanto o formato wire (passport, driversLicense, ...) quanto o formato canônico em maiúsculas (PASSPORT, DRIVER_LICENSE, ...) são aceitos. O conjunto completo:

As três variantes de documento nacional (DNI, CC, ID) são agrupadas no único valor wire nationalId, para que os clientes não precisem lidar com nomes específicos por país.

Um subtype desconhecido retorna 422 INVALID_SUBTYPE com a lista allowed na resposta. PROOF_OF_FUNDS deliberadamente não é aceito aqui — use o endpoint dedicado de origem de fundos.

Campos do Formulário

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID/documents/documentId/PASSPORT/upload \
  --header "x-api-key: $API_KEY" \
  --form "file=@/path/to/passport.jpg" \
  --form "idNumber=AB1234567" \
  --form "expirationDate=2030-12-31"

Resposta (201):

{
  "id": "4ec66735-216b-4ab4-b1d7-00558baa6d85",
  "subtype": "PASSPORT",
  "fileName": "passport.jpg",
  "verificationStatus": "PENDING",
  "createdAt": "2026-08-04T12:00:00+00:00",
  "idNumber": "AB1234567",
  "issuer": null,
  "expirationDate": "2030-12-31"
}

Origem dos Fundos

Comprovante da origem dos fundos do remetente (extrato bancário, contracheque), exigido para tiers de conformidade mais altos.

Endpoint: POST /organizations/{tenant}/people/{personId}/documents/sourceOfFunds/upload
Autenticação: Nível de tenant (x-api-key)
Content-Type: multipart/form-data

curl --request POST \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID/documents/sourceOfFunds/upload \
  --header "x-api-key: $API_KEY" \
  --form "file=@/path/to/bank-statement.pdf"

Mesmas regras de arquivo dos documentos de identidade (pdf/jpg/jpeg/png, máx. 10 MB). O envio é armazenado sob o tipo PROOF_OF_FUNDS.

Status de Verificação de Documentos

Após o envio, os documentos são verificados de forma assíncrona — por OCR com IA (se habilitado para o seu tenant) em minutos, ou então pela equipe de conformidade.

Consultar o Status de Verificação Atual

Endpoint: GET /organizations/{tenant}/documents/{documentId}/verificationStatus/current
Autenticação: Nível de tenant

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/documents/$DOCUMENT_ID/verificationStatus/current \
  --header "x-api-key: $API_KEY"

Consultar o Histórico de Status de Verificação

Endpoint: GET /organizations/{tenant}/documents/{documentId}/verificationStatus
Autenticação: Nível de tenant

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/documents/$DOCUMENT_ID/verificationStatus \
  --header "x-api-key: $API_KEY"

Retorna entradas com status, reason, verifiedBy e createdAt — o campo reason explica as rejeições, para que você possa orientar o usuário a reenviar.

Listar os Documentos de uma Pessoa

Endpoint: GET /organizations/{tenant}/people/{personId}/documents
Autenticação: Nível de tenant

curl --request GET \
  --url https://{FQDN}/organizations/$TENANT/people/$PERSON_ID/documents \
  --header "x-api-key: $API_KEY"

Status de Verificação

Notificações por Webhook

Registre-se no webhook DocumentUpdatedEvents para ser notificado quando o status de verificação de um documento mudar — um evento no envio (PENDING) e outro quando a verificação for concluída (VERIFIED/REJECTED). Veja Webhooks para a referência do payload.

Boas Práticas

• Envie imagens de alta qualidade — imagens borradas ou cortadas serão rejeitadas.
• Passe idNumber e expirationDate quando os tiver — eles enriquecem o registro de conformidade e aceleram a análise.
• Verifique o nível de conformidade após a verificação — quando um documento estiver VERIFIED, chame GET /participants/{id}/complianceLevels para ver se o remetente foi elevado de nível.
• Trate rejeições com cuidado — exiba o reason da rejeição e solicite ao usuário que reenvie.
• Use webhooks em vez de polling — registre-se em DocumentUpdatedEvents para ser notificado imediatamente.

Dados de Teste

Para testes em sandbox, veja Dados de Teste e Testes em Sandbox — certas combinações de nome/endereço disparam comportamentos específicos de conformidade (aprovação, retenção, rejeição).