> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadados

> Anexe dados chave-valor personalizados às entidades do Midaz para estender o esquema padrão com informações específicas da sua integração.

Nossa plataforma oferece uma maneira flexível de enriquecer entidades com informações definidas pelo usuário por meio de **Metadados**. Este recurso está disponível em todas as entidades da nossa API, permitindo que você anexe dados personalizados como pares de chave-valor dentro de um objeto de metadados.

Metadados são uma ferramenta poderosa para adicionar informações relevantes e definidas pelo usuário às entidades da API, permitindo que elas contenham dados específicos para suas necessidades de integração. Os metadados podem ser adicionados a qualquer momento, tornando as entidades mais adaptáveis a requisitos em constante evolução.

Incentivamos o uso de metadados para aprimorar suas integrações com a API, criando uma experiência alinhada às necessidades da sua aplicação.

## O que são metadados?

***

Os metadados permitem armazenar informações complementares junto ao modelo de dados padrão de uma entidade, adicionando atributos ou anotações personalizadas sem alterar o esquema predefinido da entidade. Essa flexibilidade fornece às entidades um contexto adicional, tornando-as adaptáveis a requisitos específicos.

No Midaz, metadados são um objeto que suporta pares de chave-valor nos seguintes tipos de dados: strings (**até 100 caracteres**), inteiros, floats e booleanos.

<Warning>
  Os metadados **não** suportam valores aninhados.
</Warning>

### Exemplo de metadados

Considere uma entidade Organização conforme mostrado abaixo:

<CodeGroup>
  ```jsonon JSON expandable theme={null}
  {
    "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
    "parentOrganizationId": null,
    "legalName": "Empresa Teste Ltda",
    "doingBusinessAs": "Empresa Teste",
    "legalDocument": "86820799000188",
    "address": {
      "line1": "Rua Botucatu, 10",
      "line2": "Casa B",
      "zipCode": "04023060",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR"
    },
    "metadata": null,
    "status": {
      "code": "ACTIVE",
      "description": null
    },
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
  }
  ```
</CodeGroup>

Para enriquecer esta organização com informações adicionais, como setor da indústria e número de funcionários, você pode incluir um objeto de metadados nas suas requisições `POST`, `PUT` ou `PATCH`:

<CodeGroup>
  ```jsonon JSON theme={null}
  {
    "metadata": {
      "sector": "Fintech",
      "employees": "50-100"
    }
  }
  ```
</CodeGroup>

## Criando entidades com metadados

***

Ao criar uma entidade, você pode enviar metadados por meio dos nossos endpoints `POST`, permitindo adicionar dados personalizados desde o início. Este recurso ajuda a criar uma representação detalhada e completa de cada entidade no seu sistema.

## Atualizando e removendo metadados

***

Nossa API segue a RFC JSON Merge Patch para atualizações de metadados, garantindo que os metadados permaneçam adaptáveis e atualizados:

* **Adicionando ou atualizando valores**: Enviar uma chave com um novo valor em uma requisição `PUT` ou `PATCH` atualiza os metadados existentes.
* **Removendo chaves**: Omitir uma chave previamente incluída em uma requisição `PUT` ou `PATCH` subsequente remove esse par chave-valor dos metadados da entidade.

### Exemplo prático: modificando metadados

Suponha que uma entidade Organização incluiu inicialmente metadados para setor e contagem de funcionários. Para atualizar a contagem de funcionários e remover o setor, envie uma requisição `PATCH` com os seguintes metadados:

<CodeGroup>
  ```jsonon JSON theme={null}
  {
    "metadata": {
      "employees": "100-150"
    }
  }
  ```
</CodeGroup>

Após o processamento da requisição, a chave de setor será removida e a contagem de funcionários será atualizada.