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

# Padrões de API

> Convenções de design e requisitos para APIs de plugins no ecossistema Lerian.

Todos os plugins que expõem APIs devem aderir aos padrões de API da Lerian para garantir consistência, interoperabilidade e uma experiência de desenvolvedor previsível em todo o ecossistema. As APIs devem seguir princípios RESTful e ser descritas usando a especificação **OpenAPI 3.1**. GraphQL é opcional, mas permitido como interface complementar.

Esta página define as convenções que se aplicam a toda API de plugin da Lerian — desde nomenclatura de parâmetros até formatação de erros.

## Parâmetros de cabeçalho

***

### Authorization

Todos os plugins suportam integração opcional com o [Access Manager](/pt/platform/access-manager/access-manager). O cabeçalho `Authorization` deve ser documentado como **opcional** no esquema da sua API. Ele é obrigatório apenas quando o ambiente tem o plugin Access Manager habilitado.

Use o campo de descrição para comunicar essa condicionalidade — não defina o flag `required` como `true`.

Texto de descrição recomendado:

> *The authorization token. This header is required only if your environment has the Access Manager plugin enabled.*

### Cabeçalhos personalizados

Cabeçalhos específicos de serviço seguem o padrão `X-{Service}-{Name}` usando PascalCase. Por exemplo: `X-Account-ID`.

## Parâmetros de consulta

***

Todos os parâmetros de consulta devem usar `snake_case`.

A Lerian define um conjunto de parâmetros de consulta padrão que devem ser suportados em todos os endpoints de listagem:

| Parâmetro    | Tipo    | Descrição                                                 | Valor padrão |
| ------------ | ------- | --------------------------------------------------------- | ------------ |
| `metadata`   | string  | String JSON para filtrar por campos de metadados          | —            |
| `limit`      | integer | Número máximo de registros por página (1–100)             | 10           |
| `page`       | integer | Número da página para paginação (mínimo 1)                | 1            |
| `start_date` | string  | Filtrar itens criados em ou após esta data (YYYY-MM-DD)   | —            |
| `end_date`   | string  | Filtrar itens criados em ou antes desta data (YYYY-MM-DD) | —            |
| `sort_order` | string  | Direção de ordenação: `asc` ou `desc`                     | —            |

## Parâmetros de corpo

***

Os campos nos corpos de requisição e resposta devem usar `lowerCamelCase`.

Não use `snake_case`, `kebab-case` ou `PascalCase` em payloads JSON. Essa convenção se aplica a todos os nomes de campo em todos os níveis de aninhamento.

## Códigos de status de resposta

***

As APIs da Lerian usam um conjunto mínimo de códigos de status HTTP:

| Código           | Uso                                              |
| ---------------- | ------------------------------------------------ |
| `200 OK`         | Requisição processada com sucesso (síncrona)     |
| `201 Created`    | Recurso criado com sucesso                       |
| `202 Accepted`   | Aceito para processamento assíncrono             |
| `204 No Content` | Sucesso sem corpo de resposta (ex.: soft-delete) |

## Formato de data e hora

***

Todos os campos de data-hora devem seguir **ISO 8601** em **UTC** com o sufixo `Z`. Não retorne datas sem o sufixo `Z` ou em fusos horários locais.

```json theme={null}
{
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}
```

Campos somente de data (como parâmetros de consulta) usam o formato `YYYY-MM-DD`.

## Formato de erros

***

Todas as respostas de erro devem seguir a estrutura padrão de erros da Lerian:

```json theme={null}
{
  "code": "XXX-0000",
  "title": "Error title",
  "message": "Error message."
}
```

Quando o erro se relaciona a campos específicos (ex.: falhas de validação), inclua um objeto `fields` com detalhes por campo:

```json theme={null}
{
  "code": "XXX-0000",
  "title": "Bad Request",
  "message": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
  "fields": {
    "legalName": "legalName is a required field.",
    "parentOrganizationId": "parentOrganizationId must be a valid UUID"
  }
}
```

### Convenções de códigos de erro

Os códigos de erro seguem o padrão: **prefixo de 3 letras do plugin** + **4 dígitos**.

* Cada plugin tem seu próprio prefixo (ex.: `MDZ` para Midaz, `PIX` para Pix, `TRC` para Tracer)
* Códigos no intervalo `0001`–`0999` são erros internos do plugin
* Códigos que começam com `1` (ex.: `XXX-1000`) indicam erros de integrações externas

<Warning>
  Respostas de erro devem estar em conformidade com o formato padrão da Lerian de acordo com a diretriz do [Modelo de erros](/pt/partners-hub/error-model).
</Warning>

## Comportamento do PATCH

***

Todos os endpoints PATCH seguem **RFC 7386 — JSON Merge Patch**.

* **Content-Type**: `application/merge-patch+json`
* **Propriedades omitidas**: permanecem inalteradas
* **Propriedades com valor `null`**: são removidas ou redefinidas para o valor padrão
* **Objetos**: são mesclados recursivamente
* **Arrays**: são substituídos inteiramente (sem mesclagem por elemento)

Isso significa que uma requisição PATCH só precisa incluir os campos que estão sendo alterados. Qualquer campo não presente no corpo da requisição permanece como está.

## Padrão de soft-delete

***

As operações de exclusão seguem o padrão de **soft-delete**:

* Retornam `204 No Content`
* Definem o campo `deletedAt` com o timestamp UTC atual em formato ISO 8601
* Excluem registros deletados das listagens padrão (a menos que um filtro explícito seja aplicado)
* A operação é **idempotente** — chamar DELETE em um recurso já deletado retorna o mesmo `204`

Recursos deletados são preservados para fins de auditoria e conformidade. O hard-delete não é utilizado a menos que seja explicitamente justificado.

## Objetos de metadados

***

As APIs da Lerian suportam um objeto `metadata` para armazenar pares chave-valor arbitrários nos recursos. Isso permite que os clientes anexem dados personalizados sem alterações no schema.

Convenções para metadados:

* As chaves devem usar `lowerCamelCase`
* Os valores podem ser primitivos JSON ou objetos aninhados
* Chaves desconhecidas devem ser **preservadas textualmente** — nunca transforme, renomeie ou remova campos de metadados
* Metadados podem ser filtrados através do parâmetro de consulta `metadata` como string JSON

## Referência rápida

***

| Convenção                 | Padrão                          |
| ------------------------- | ------------------------------- |
| Parâmetros de consulta    | `snake_case`                    |
| Campos do corpo JSON      | `lowerCamelCase`                |
| Cabeçalhos personalizados | `X-Service-Name` (PascalCase)   |
| Datas                     | ISO 8601 UTC com sufixo `Z`     |
| PATCH                     | RFC 7386 JSON Merge Patch       |
| DELETE                    | Soft-delete, `204 No Content`   |
| Códigos de erro           | Prefixo de 3 letras + 4 dígitos |
| OpenAPI                   | 3.1                             |