Padrões de API

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

{
  "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:

{
  "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:

{
  "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

Respostas de erro devem estar em conformidade com o formato padrão da Lerian de acordo com a diretriz do Modelo de erros.

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

Visão geral

Dicionário de campos

Padrões de API

Parâmetros de cabeçalho

Authorization

Cabeçalhos personalizados

Parâmetros de consulta

Parâmetros de corpo

Códigos de status de resposta

Formato de data e hora

Formato de erros

Convenções de códigos de erro

Comportamento do PATCH

Padrão de soft-delete

Objetos de metadados

Referência rápida

​Parâmetros de cabeçalho

​Authorization

​Cabeçalhos personalizados

​Parâmetros de consulta

​Parâmetros de corpo

​Códigos de status de resposta

​Formato de data e hora

​Formato de erros

​Convenções de códigos de erro

​Comportamento do PATCH

​Padrão de soft-delete

​Objetos de metadados

​Referência rápida

Parâmetros de cabeçalho

Authorization

Cabeçalhos personalizados

Parâmetros de consulta

Parâmetros de corpo

Códigos de status de resposta

Formato de data e hora

Formato de erros

Convenções de códigos de erro

Comportamento do PATCH

Padrão de soft-delete

Objetos de metadados

Referência rápida