Enviando Documentos

Para avançar um remetente para níveis de conformidade mais altos (Nível 2 e acima), pode ser necessário enviar documentos de identidade e comprovante de origem dos fundos. Os documentos são verificados automaticamente (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, driverLicense, nationalId, ...) quanto o formato canônico em maiúsculas (PASSPORT, DRIVER_LICENSE, ...) são aceitos. Tipos comuns:

Tipo	Descrição
`PASSPORT`	Passaporte
`DRIVER_LICENSE`	Carteira de motorista
`ID`	Documento de identidade nacional / estadual
`CONSULAR_ID`	Identidade consular
`VOTER_ID`	Título de eleitor
`OTHER`	Outro documento emitido pelo governo

Um subtype desconhecido retorna 422 com a lista de valores permitidos.

Campos do Formulário

Campo	Tipo	Obrigatório	Descrição
`file`	file	Sim	A imagem do documento — `pdf`, `jpg`, `jpeg` ou `png`, máx. 10 MB
`idNumber`	string	Não	O número impresso no documento
`issuer`	string	Não	Autoridade emissora ou estado
`expirationDate`	string	Não	Formato `YYYY-MM-DD`

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

Status	Descrição
`PENDING`	Documento enviado, aguardando verificação
`VERIFIED`	Documento aceito — o nível de conformidade pode ser elevado
`REJECTED`	Documento rejeitado — verifique o `reason` e reenvie

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