> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/metadata.md).

# Metadados

## Visão geral

Metadados são quaisquer dados opcionais que você possa precisar adicionar a um [objeto do sistema](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/system-objects.md). Na `meta_data` seção, você pode incluir qualquer informação que quiser, simplesmente fornecendo qualquer número de campos com seus valores:

```json
…
meta_data:
{
  "field1": "value1",
  "field2": "value2"
}
…
```

## Objetos e métodos

Metadados estão disponíveis para a maioria dos objetos de sistema do Oz. Veja abaixo a lista desses objetos com os métodos da API necessários para adicionar metadados. Observe: também é possível adicionar metadados a esses objetos durante a criação deles.

| **Objeto** | **Método da API**                                                                                                                                                                                                 |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usuário    | `PATCH /api/users/{{user_id}}`                                                                                                                                                                                    |
| Pasta      | `PATCH /api/folders/{{folder_id}}/meta_data/`                                                                                                                                                                     |
| Mídia      | `PATCH /api/media/{{media_id}}/meta_data`                                                                                                                                                                         |
| Análise    | `PATCH /api/analyses/{{analyse_id}}/meta_data`                                                                                                                                                                    |
| COLLECTION | <p><code>PATCH /api/collections/{{collection\_id}}/meta\_data/</code></p><p>e, para uma pessoa em uma coleção,</p><p><code>PATCH /api/collections/{{collection\_id}}/persons/{{person\_id}}/meta\_data</code></p> |

Também é possível alterar ou excluir metadados. Consulte nossa [documentação da API](https://apidoc.ozforensics.com/).

## Exemplos de uso

Talvez seja útil usar metadados para agrupar pastas por uma pessoa ou lead. Por exemplo, se quiser calcular a conversão quando um único lead fizer várias tentativas de Liveness, basta adicionar o identificador da pessoa/lead aos metadados da pasta.

Veja como adicionar o ID do cliente `iin` a um objeto de pasta.

No corpo da requisição, adicione:

```json
{
  "iin": "123123123"
}
```

{% hint style="info" %}
É possível passar o ID de uma pessoa neste campo e usar esse ID para combinar requisições com a mesma pessoa e contar pessoas únicas (mesmo ID = mesma pessoa, IDs diferentes = pessoas diferentes). Esse ID pode ser um número de telefone, um IIN, um SSN ou qualquer outro tipo de ID exclusivo. O ID será exibido no relatório como uma coluna adicional.
{% endhint %}

Outro caso é a segurança: quando for necessário processar o resultado das análises no back-end, mas não se quiser fazer isso usando o ID da pasta. Adicione um ID (`transaction_id`) a esta pasta e use esse ID para buscar as informações necessárias. Este caso é explicado em detalhes [aqui](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/sdk/oz-liveness-websdk/web-plugin/security-recommendations.md#retrieve-the-analysis-response-and-process-it-on-the-back-end).

Se você armazenar PII em metadados, certifique-se de que isso esteja em conformidade com os requisitos regulatórios aplicáveis.

Também é possível adicionar metadados via SDK para processar as informações posteriormente usando métodos da API. Consulte as seções correspondentes do SDK:

* [iOS](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/sdk/oz-mobile-sdk/ios/checking-liveness-and-face-biometry.md#adding-metadata)
* [Android](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/sdk/oz-mobile-sdk/android/checking-liveness-and-face-biometry.md#adding-metadata)
* [Web](https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/sdk/oz-liveness-websdk/web-plugin/launching-the-plugin.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://doc.ozforensics.com/oz-knowledge/oz-knowledge/pt-br/guias/developer-guide/api/oz-api/metadata.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
