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.

Se sua integração vinha usando um identificador de operação próprio (do tipo consumerX/op-123) precisa passar a usar o que é devolvido por POST /operation. Um identificador com outro formato é rejeitado com 400.

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

{
  "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04",
  "asset": {
    "context": "TOKEN_FRONT_DOCUMENT",
    "file": "<base64>"
  }
}

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

{
  "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT",
  "timestamp": "2026-06-26T12:00:03.000Z"
}

Reenvie a fileKey exatamente como está. Não adicione o contexto (a chave já o traz, e concatená-lo novamente gera uma chave que não resolve), não coloque nenhum prefixo antes e não a quebre. Se precisar recuperar as chaves de uma operação, peça-as com GET /operation/{operationId}/file-keys, que as devolve indexadas por contexto.

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

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