Skip to main content
POST
cURL

Quando usar

Use este endpoint para anexar um documento (RG, CNH, comprovante de residência etc.) a um cliente já cadastrado — via POST /customers ou pelo portal de onboarding. Ideal para integrações que fazem o cadastro e a captura de documentos em etapas separadas, sem depender do cliente final preencher o formulário web.

Corpo da requisição

O corpo é multipart/form-data, não JSON — evita o overhead de ~33% de um payload base64 e mantém POST /customers livre de mudança de contrato.

Limite de arquivo: 4MB

Serverless Functions da Vercel têm um teto de 4.5MB de tamanho de request, fixo em nível de infraestrutura. Arquivos maiores que 4MB são rejeitados com 400 file_too_large antes de chegar no Storage.

Catálogo de type

Tipos base, aceitos em qualquer tenant:
Tenants com tipos de documento customizados configurados também podem enviar esses tipos adicionais. Um type fora desse conjunto retorna 400 invalid_document_type.

Reenvio do mesmo tipo

Enviar o mesmo type novamente para o mesmo cliente substitui o documento anterior (desde que não esteja rejeitado) — só um documento ativo por tipo. Se o documento existente desse type estiver rejeitado, o comportamento é diferente: o antigo não é removido, e o novo upload passa a coexistir com ele — os dois aparecem em documents[] de GET /customers/, um rejeitado e um pendente. Não é possível, via API, apagar o documento rejeitado antigo depois disso.

Exemplo

O que este endpoint não faz

  • Não retorna o arquivo nem gera signed URL — baixar o documento continua exclusivo do dashboard.
  • Não aprova nem rejeita documentos — todo documento entra como pendente; a revisão manual é feita no dashboard.
  • Não lista documentos em volume — use o campo documents de GET /customers/ para confirmar recebimento e status.

Erros

Formato completo do envelope e estratégia de retry em Tratamento de erros. Os códigos deste endpoint: missing_api_key, invalid_api_key, insufficient_scope, channel_disabled, invalid_id ({id} da URL ausente ou inválido), invalid_multipart, invalid_file, invalid_document_type, file_too_large, customer_not_found, storage_failed, db_failed.

Authorizations

x-api-key
string
header
required

API key no header x-api-key (recomendado)

Headers

x-kycert-api-version
string
Example:

"2026-06-03"

Path Parameters

id
string<uuid>
required

ID do cliente retornado pelo POST /customers

Body

multipart/form-data
file
file
required

Arquivo do documento (máx. 4MB)

type
string
required

Tipo do documento. Catálogo base: identidade_frente, identidade_verso, cnh_frente, cnh_verso, passaporte, comprovante_endereco, selfie, contrato_social, comprovante_cnpj, procuracao, balanco, outro. Tenants com tipos customizados configurados também são aceitos.

Example:

"comprovante_endereco"

Response

Documento anexado com sucesso

document_id
string<uuid>
object
enum<string>
Available options:
document
type
string
status
enum<string>

Todo documento entra como pendente — aprovação/rejeição é exclusiva do dashboard

Available options:
pendente
file_name
string
mime_type
string
created_at
string<date-time>
livemode
boolean