> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/subida-de-assets.md). # Upload 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 ``` ```json { "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](/docs.facephi-pt-br/api-rest/midapi-v2/operations.md). {% hint style="warning" %} 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`. {% endhint %} ### Endpoint ``` POST /storage ``` ### Cabeçalhos | Nome | Tipo | Obrigatório | Descrição | | ----------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Authorization** | string | **Sim** | Token de consumer no formato `Bearer ` (veja [Autenticação](/docs.facephi-pt-br/api-rest/midapi-v2/autenticacion.md)). | | **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 ```json { "operationId": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04", "asset": { "context": "TOKEN_FRONT_DOCUMENT", "file": "" } } ``` ### 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 ```json { "fileKey": "0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT", "timestamp": "2026-06-26T12:00:03.000Z" } ``` {% hint style="warning" %} 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. {% endhint %} #### 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 | {% hint style="warning" %} **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`. {% endhint %} {% hint style="info" %} 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. {% endhint %} ### 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](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md)). ### 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. {% hint style="info" %} 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](/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/respuesta-de-resultado.md#rechazo-por-calidad-vs-deteccion-de-fraude)). Nesses casos, repetir a captura com melhor qualidade costuma resolver a ocorrência. {% endhint %}