> 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/storage.md).

# Armazenamento

O armazenamento guarda as capturas de uma [operação](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/operations.md) antes de validá-las. Cada asset é armazenado uma vez, fica associado a um **contexto** dentro da operação e, a partir daí, é referenciado pela chave nos serviços de validação sem que o binário precise ser enviado novamente. O fluxo completo, do token até a chamada de validação, está em [Fluxo comum](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/flujo-comun.md).

#### Modos de asset

Os serviços de validação recebem os assets de duas formas, com a mesma estrutura de requisição. O modo é declarado pelo campo `source`:

| Valor de `source` | Conteúdo dos campos de asset               |
| ----------------- | ------------------------------------------ |
| `FILE`            | Conteúdo da captura, codificado em Base64. |
| `FILE_KEY`        | Chave de um asset já armazenado.           |

`source` é único por requisição, não por asset: uma requisição não pode combinar conteúdo em linha e referências. Quando a requisição referencia algum asset por chave, o cabeçalho `operation-id` é obrigatório e declara a operação à qual todas as chaves pertencem.

{% hint style="info" %}
**A forma recomendada é a referência por chave.** Os serviços de validação de identidade também aceitam receber o asset tokenizado em Base64 na própria chamada (`source: FILE`), mas essa não é a forma recomendada de integrá-los: o conteúdo é enviado por completo a cada validação, não é reutilizado entre chamadas nem entre serviços, aumenta o tamanho da requisição e a aproxima do limite permitido, e a captura fica sem a operação que permite rastreá-la. Armazene cada asset uma vez e depois faça referência a ele pela chave (`source: FILE_KEY`).

Os serviços que só aceitam conteúdo em linha, listados abaixo em [Exceções](#excepciones), ficam fora desta recomendação: nesses casos, não há outra forma de enviar o asset.
{% endhint %}

#### Contextos de asset

O **contexto** identifica qual captura o asset representa e determina em quais campos de quais serviços ele pode ser usado. Cada serviço declara, na descrição de seus parâmetros, o contexto aceito em cada campo.

| Contexto               | Conteúdo                                              | Formato de `asset.file`                                |
| ---------------------- | ----------------------------------------------------- | ------------------------------------------------------ |
| `TOKEN_FRONT_DOCUMENT` | **Token RAW** da frente do documento de identidade.   | Token do buffer gerado pelo SDK de captura, em Base64. |
| `TOKEN_BACK_DOCUMENT`  | **Token RAW** do verso do documento de identidade.    | Token do buffer gerado pelo SDK de captura, em Base64. |
| `TOKEN_FACE_IMAGE`     | Rosto recortado do documento de identidade.           | Token do buffer gerado pelo SDK de captura, em Base64. |
| `TOKEN_BEST_IMAGE`     | Melhor imagem da captura de selfie.                   | Token do buffer gerado pelo SDK de captura, em Base64. |
| `TOKEN_BIN_IAD`        | Binário da captura de Detecção de Ataques de Injeção. | Binário em Base64.                                     |
| `RAW_IMAGE`            | Imagem facial em aberto, sem tokenização.             | JPEG ou PNG em aberto, em Base64.                      |
| `TOKEN_RAW_IMAGE`      | Token de uma imagem facial enviada em aberto.         | Não é aceito no envio: é obtido ao enviar `RAW_IMAGE`. |

O par (operação, contexto) identifica exatamente um asset: um segundo envio do mesmo contexto na mesma operação retorna `409`. Se for necessário repetir uma captura já armazenada, cria-se uma nova operação.

`RAW_IMAGE` nomeia o conteúdo como ele chega, não como fica armazenado, e é o único contexto com essa assimetria. A imagem em aberto é tokenizada ao ser recebida e não é armazenada: a operação conserva o token, e a chave retornada por [Save Asset](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/storage/save-asset.md) leva o contexto `TOKEN_RAW_IMAGE`, que é referenciado posteriormente e a única forma de ler o conteúdo novamente. Declarar `TOKEN_RAW_IMAGE` no envio é rejeitado com `400`. Está previsto para o rosto fornecido por um registro civil e é referenciado como `sourceImage` em [Facial Matching](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/biometric-services/facial-matching.md).

#### Formato da chave

```
{operationId}/{CONTEXTO}

0192a3f4-7b21-7c44-9e1a-3f5b8c2d1e04/TOKEN_FRONT_DOCUMENT
```

É o valor retornado por [Save Asset](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/storage/save-asset.md) em `fileKey` e o retornado por [Get File Keys](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/operations/get-file-keys.md) em cada entrada de `fileKeys`.

{% hint style="warning" %}
A chave é encaminhada exatamente como recebida. Ela não deve ser composta nem interpretada: adicionar o contexto a ela o duplica, e o asset não é resolvido.
{% endhint %}

#### Limites de uso de um asset

Uma captura é armazenada uma única vez. No envio, seu conteúdo é verificado: se esse mesmo conteúdo já estiver armazenado, o envio retorna `409` e nada é salvo, mesmo que outra operação ou outro contexto seja declarado. Portanto, não adianta enviar novamente a mesma captura para validá-la outra vez.

Um asset já armazenado também tem um limite de invocações por endpoint. Quando esse limite é atingido, a resposta é `429`. O limite é independente para cada asset e endpoint, de modo que consumir o limite de um endpoint não consome o de outro, e seu valor é definido na contratação do serviço.

| Situação                                                      | Resposta |
| ------------------------------------------------------------- | -------- |
| O conteúdo enviado para `POST /storage` já está armazenado    | `409`    |
| Um asset atingiu o número máximo de invocações nesse endpoint | `429`    |

Uma invocação é contabilizada quando o asset é lido do armazenamento, o que ocorre antes da invocação do serviço subjacente. Ela é contabilizada independentemente do resultado da chamada: um resultado negativo, um erro do serviço subjacente ou uma falha posterior também consomem a invocação.

#### Exceções

Por padrão, os serviços de validação de identidade aceitam os dois modos de asset: conteúdo em linha e referência por chave. Estas são as exceções:

| Serviço                                                                                                                                                                                                                                              | Modos aceitos                                |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [Form OCR](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/document-services/form-ocr.md)                                                                                                                                             | Somente `FILE`                               |
| [Cadastro de voz](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/voice-services/voice-enrollment.md) e [Autenticação por voz](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/voice-services/voice-authentication.md) | Apenas conteúdo em linha, sem campo `source` |
| [Validação de documentos](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/document-services/document-validation/iniciar-validacion.md)                                                                                                | Apenas referência, sem campo `source`        |

Nos serviços exclusivamente em linha, o conteúdo é enviado na própria chamada e não há cabeçalho `operation-id`.

#### Serviços disponíveis

* [**Salvar ativo**](https://docs.facephi.com/docs.facephi-pt-br/api-rest/midapi-v2/storage/save-asset.md): Armazena um ativo no contexto de uma operação e retorna sua chave.
