Envio de assets

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

Endpoint

POST /storage

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
Authorization	string	Sim	Token de consumer no formato Bearer <token> (ver Autenticação).
consumer-id	string	Sim	Identificador do consumer.

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

{
  "operationId": "<operationId>",
  "asset": {
    "context": "TOKEN_FRONT_DOCUMENT",
    "file": "<base64>"
  }
}

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
fileKey	string	Chave do asset com a forma <consumerId>/<operationId>.
timestamp	string	Marca temporal da resposta no formato ISO 8601.

Exemplo de resposta

{
  "fileKey": "<consumerId>/<operationId>",
  "timestamp": "2026-06-26T12:00:00.000Z"
}

409 Conflict

Já existe um asset do mesmo tipo para esse operationId. Não pode existir mais de um asset do mesmo type para o mesmo operationId.

Tipos de asset relevantes para o DAF

type	Conteúdo	Obrigatoriedade
TOKEN_FRONT_DOCUMENT	Token RAW do anverso do documento de identidade (p. ex. tokenRawFrontDocument gerado pelo SDK de captura).	Obrigatório
TOKEN_BACK_DOCUMENT	Token RAW do verso do documento de identidade (p. ex. tokenRawBackDocument gerado pelo SDK de captura).	Opcional
TOKEN_FACE_IMAGE	Selfie do titular.	Opcional

Importante: os assets do documento devem ser os tokens RAW do anverso/verso, não os tokens processados. Se for enviado um token não RAW, a validação não pode ser executada e a transação termina em FAILED.

Se não for fornecido TOKEN_FACE_IMAGE, o DAF 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

• O DAF valida documentos de identidade (ID) e passaportes.

• Em passaportes, não é necessário 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 a sua integração.

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

Requisitos e qualidade da 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 proporção de cartão padrão.

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

• Não pode existir mais de um asset do mesmo type para o mesmo operationId (um segundo envio do mesmo tipo retorna 409 Conflict).

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