Pular para o conteúdo principal
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âmetroTipoDescriçãoValor padrão
metadatastringString JSON para filtrar por campos de metadados—
limitintegerNúmero máximo de registros por página (1–100)10
pageintegerNúmero da página para paginação (mínimo 1)1
start_datestringFiltrar itens criados em ou após esta data (YYYY-MM-DD)—
end_datestringFiltrar itens criados em ou antes desta data (YYYY-MM-DD)—
sort_orderstringDireçã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ódigoUso
200 OKRequisição processada com sucesso (síncrona)
201 CreatedRecurso criado com sucesso
202 AcceptedAceito para processamento assíncrono
204 No ContentSucesso 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çãoPadrão
Parâmetros de consultasnake_case
Campos do corpo JSONlowerCamelCase
Cabeçalhos personalizadosX-Service-Name (PascalCase)
DatasISO 8601 UTC com sufixo Z
PATCHRFC 7386 JSON Merge Patch
DELETESoft-delete, 204 No Content
Códigos de erroPrefixo de 3 letras + 4 dígitos
OpenAPI3.1