Documentos

Os documentos são anexados a uma solicitação, não diretamente a um solicitante. Cada envio aproxima a solicitação principal de estar "pronta para envio" — quando pendingDocTypes estiver vazio, você pode enviar a solicitação para processamento.

Enviar um documento

POST /api/v1/kyc/requests/:requestId/documents    Escopo: kyc:write

Envio multipart. Passe documentType (e side, se aplicável) como parâmetros de consulta, e o arquivo em um campo de formulário file.

Parâmetros de consulta

Corpo do formulário

Tipos de documento

Exemplo

# Upload the front of a driver's license
curl -X POST "https://app.certivant.com/api/v1/kyc/requests/req_01J.../documents?documentType=GOVERNMENT_ID&side=front" \
  -H "Authorization: Bearer ck_live_..." \
  -F "file=@/path/to/license-front.jpg"

Resposta (201)

{
  "id": "doc_01J...",
  "documentType": "GOVERNMENT_ID",
  "side": "front",
  "status": "pending",
  "fileSize": 412938,
  "mimeType": "image/jpeg",
  "requestStatus": "PENDING_UPLOAD",
  "pendingDocTypes": ["GOVERNMENT_ID", "SELFIE"],
  "message": "Document uploaded. Front of GOVERNMENT_ID received; back of GOVERNMENT_ID still required."
}

A resposta sempre informa o que ainda falta por meio de pendingDocTypes. Quando essa lista estiver vazia, sua próxima chamada deve ser POST /requests/:id/submit.

Valores de status do documento

• pending — enviado, ainda não processado (só ocorre antes do envio da solicitação).
• verified — aprovado em todas as verificações de autenticidade após o envio da solicitação.
• failed — reprovado em uma verificação de autenticidade. Consulte os registros de verificação vinculados em GET /requests/:id para ver o motivo específico.
• corrupted — o arquivo não pôde ser decodificado. Envie novamente.

Erros

• 400 BAD_REQUEST:
  • Arquivo maior que 10 MB.
  • Tipo MIME não suportado.
  • side ausente para GOVERNMENT_ID.
  • documentType não permitido pelas configurações de KYC da organização.
• 404 NOT_FOUND — a solicitação principal não existe nesta organização.
• 409 CONFLICT — a solicitação não está em PENDING_UPLOAD. Não é possível adicionar documentos a uma solicitação que já foi enviada.

Obter uma URL de download

GET /api/v1/kyc/requests/:requestId/documents/:docId/url    Escopo: kyc:read

Os documentos são armazenados em um armazenamento de objetos privado. Para visualizar ou baixar um deles, busque uma URL assinada de curta duração.

Resposta

{
  "url": "https://storage.certivant.com/kyc/org_.../req_.../doc_....jpg?X-Amz-Signature=...",
  "expiresIn": 900
}

expiresIn está em segundos — a URL é válida por 15 minutos. Gere uma nova sempre que precisar exibir um documento; não armazene essas URLs em cache.

A url retornada é uma URL de armazenamento pré-assinada (S3 / Azure Blob / GCS). Ela abre diretamente em uma aba do navegador e é exibida sem cabeçalho Authorization:

• Imagens (image/jpeg, image/png, image/webp) → <img src="{url}" />
• PDFs (application/pdf) → <iframe src="{url}" /> ou <object data="{url}" type="application/pdf" />

Verifique o mimeType de cada documento (em GET /requests/:id) para decidir qual renderizar.

Baixar os bytes brutos

GET /api/v1/kyc/requests/:requestId/documents/:docId/download    Escopo: kyc:read

Transmite os bytes do arquivo diretamente, com o Content-Type armazenado (image/jpeg, image/png, image/webp ou application/pdf) e Content-Disposition: inline. Sem URL assinada, sem redirecionamento.

curl -L "https://app.certivant.com/api/v1/kyc/requests/req_01J.../documents/doc_01J.../download" \
  -H "Authorization: Bearer ck_live_..." \
  -o government_id_front.jpg

Prefira essa opção à rota de URL assinada quando exibir documentos dentro do seu próprio painel:

• Funciona com todos os backends de armazenamento, inclusive o disco local — cuja URL assinada /uploads/… só é acessível de dentro do host da Certivant e retorna 404 a partir de outra origem.
• Faça o proxy pelo seu backend e sirva-o na mesma origem (<img src="/your-proxy/doc"> para imagens, <iframe> para PDFs). A chave Authorization: Bearer permanece no servidor e nunca chega ao navegador.
• Nenhuma URL de armazenamento é exposta, então não há nada a vazar ou expirar.

Substituindo documentos

Você não pode editar um documento no lugar. Se o solicitante enviou uma foto borrada e você quer uma nova captura:

1. A solicitação deve estar em PENDING_UPLOAD (ou você deve reenviar antes uma solicitação rejeitada para limpar os documentos anteriores).
2. Envie um novo documento com o mesmo documentType e side. O anterior é substituído — apenas a versão mais recente é usada no processamento.

Essa regra existe por integridade de auditoria: um histórico imutável de cada envio permanece no registro de auditoria, mesmo quando o documento ativo muda.

Listar documentos de uma solicitação

Não há um endpoint separado para listar documentos. A lista completa vem incluída na resposta de GET /api/v1/kyc/requests/:id:

{
  "id": "req_...",
  "documents": [
    { "id": "doc_a", "documentType": "GOVERNMENT_ID", "side": "front", "status": "verified", ... },
    { "id": "doc_b", "documentType": "GOVERNMENT_ID", "side": "back", "status": "verified", ... },
    { "id": "doc_c", "documentType": "SELFIE", "status": "verified", ... }
  ]
}

Itere sobre documents e chame /download (para repassar os bytes) ou /url (para um link assinado) em qualquer documento específico que você queira exibir.

Relacionados

• Solicitações KYC — o endpoint principal ao qual seus documentos são anexados.
• Sessões hospedadas — permita que a Certivant colete os documentos diretamente do solicitante.
• Esquemas — enumeração completa de documentType, status e valores relacionados.