For the complete documentation index, see llms.txt. This page is also available as Markdown.

Envio de assets

Document Validation não recebe arquivos diretamente: consome os assets já carregados no serviço de armazenamento da Facephi, referenciados por sua fileKey. Antes de iniciar uma validação, envie cada asset (documento e, opcionalmente, selfie) com o endpoint de armazenamento.

Antes de fazer upload: criar a operação

Os assets pertencem a uma operação, que é seu contêiner e seu ciclo de vida. O identificador de operação não é um dado de negócio livre: é o que é emitido por POST /operation, e é o primeiro segmento de toda chave de asset.

POST /operation
{
  "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04",
  "timestamp": "2026-06-26T12:00:00Z",
  "expiresAt": "2026-06-26T12:15:00Z"
}

A operação expira no momento indicado por expiresAt. Ao expirar, não é possível fazer upload de assets sob ela nem referenciá-los: é preciso criar uma nova operação e fazer upload dos assets novamente. Veja Operações.

Endpoint

POST /storage

Cabeçalhos

Nome
Tipo
Obrigatório
Descrição

Authorization

string

Sim

Token de consumer no formato Bearer <token> (veja Autenticação).

consumer-id

string

Sim

Identificador do consumer.

Este endpoint não leva cabeçalho operation-id: a operação vai no corpo, em operationId.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro
Tipo
Obrigatório
Descrição

operationId

string

Sim

Identificador da operação à qual o asset pertence, tal como devolvido por POST /operation.

asset

object

Sim

Asset a ser salvo.

asset.context

string

Sim

Tipo de asset (ver tabela de tipos mais abaixo).

asset.file

string

Sim

Conteúdo do asset (Token do documento ou selfie), codificado em Base64. Para TOKEN_FRONT_DOCUMENT e TOKEN_BACK_DOCUMENT deve ser o token RAW do documento gerado pelo SDK de captura.

Exemplo de solicitação

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro
Tipo
Descrição

fileKey

string

Chave do asset, na forma {operationId}/{CONTEXTO}. É o valor que é reenviado sem modificar ao iniciar a validação.

timestamp

string

Marca temporal da resposta no formato ISO 8601.

Exemplo de resposta

Outras respostas

Código
Significado

400

operationId não tem o formato esperado, o conteúdo não corresponde ao contexto declarado, ou o asset está vazio ou excede o tamanho máximo.

403

O consumer não está provisionado com o serviço STORAGE.

404

A operação não existe ou pertence a outro consumer.

409

Já existe um asset desse contexto na operação: não pode haver mais de um por contexto e operação.

410

A operação expirou.

Contextos de asset relevantes para o serviço

Contexto
Conteúdo
Obrigatoriedade

TOKEN_FRONT_DOCUMENT

Token RAW do anverso do Documento de identidade (por ex. tokenRawFrontDocument gerado pelo SDK de captura).

Obrigatório

TOKEN_BACK_DOCUMENT

Token RAW do verso do Documento de identidade (por ex. tokenRawBackDocument gerado pelo SDK de captura).

Opcional

TOKEN_FACE_IMAGE

Selfie do titular.

Opcional

Se não for fornecido TOKEN_FACE_IMAGE, o serviço valida apenas o documento: perdem-se os sinais derivados da selfie (comparação facial) e o diagnóstico se baseia apenas nas validações documentais.

Documentos suportados

  • Document Validation valida documentos de identidade (ID) e passaportes.

  • Em passaportes não se exige o verso: basta o anverso (TOKEN_FRONT_DOCUMENT).

  • O conjunto específico de tipos de documento e países/emissores suportados é definido no cadastro do serviço; consulte-o com a Facephi para sua integração.

  • Se o documento não for suportado ou sua versão não puder ser validada, a transação é resolvida como DECLINED com o código de motivo correspondente (veja Resposta de resultado).

Requisitos e qualidade de imagem

A qualidade da captura determina se o documento pode ser validado. Para maximizar a taxa de aprovação:

  • Resolução mínima recomendada: HD (≥ 720×1080 px).

  • Tamanho máximo por arquivo: 10 MB. Evite compressão agressiva; use os valores padrão de um fluxo de captura guiada.

  • Enquadramento: o documento deve aparecer completo e sem cortes, ocupando a maior parte do enquadramento e com uma relação de aspecto padrão de cartão.

  • Nitidez e iluminação: sem desfoque, sem reflexos ou brilhos que ocultem dados e sem rotação excessiva.

  • Não pode existir mais de um asset do mesmo contexto para a mesma operação (um segundo upload do mesmo contexto retorna 409 Conflict). Se precisar repetir uma captura já enviada, crie uma nova operação.

Se uma captura não atender a esses requisitos, a validação a sinaliza como um problema de qualidade/captura (não como fraude): são os códigos das categorias input e integrity (por ex. 100/101/104/105 e 102/103/106-111/500/501, veja Resposta de resultado). Nesses casos, repetir a captura com melhor qualidade costuma resolver a ocorrência.

Atualizado