Templates de referência de API

Esta página fornece os templates oficiais para toda documentação de referência de API no ecossistema Lerian: páginas de endpoints, schemas de request/response, tratamento de erros e especificações OpenAPI. A documentação de referência de API é técnica, seca e precisa. Sem narrativa, sem contextualização, sem “porquê” — declare fatos. Descreva inputs, outputs e comportamento. Para documentação orientada a tarefas ou contextual, consulte Templates de guias. Aplique as regras de voz e tom e capitalização a todo conteúdo de referência de API.

Página de endpoint

Cada endpoint de API tem sua própria página. A estrutura é rígida — toda página segue o mesmo formato para que desenvolvedores possam escanear de forma previsível.

Título

Use um título curto e claro que caiba em uma linha no sumário. Siga o padrão de verbos baseado no método HTTP:

Método	Verbo	Exemplo
`POST`	Create	Create an account
`GET`	List	List accounts
`GET` (by ID)	Retrieve	Retrieve an account
`PATCH`	Update	Update an account
`DELETE`	Delete / Deactivate	Delete an account

Descrição

Uma a duas frases. O que o endpoint faz e quando usá-lo. Sem contexto, sem motivação.

Creates a new account in the specified ledger. The account is linked to a single asset
and follows double-entry accounting rules.

Pré-requisitos

Liste o que é necessário para usar o endpoint:

Método de autenticação
Permissões ou papéis necessários
Entidades que devem existir previamente (ex.: “Requer uma organização e ledger existentes”)

Parâmetros

Agrupe por localização. Use uma tabela separada para cada grupo:Parâmetros de header

Parâmetro	Tipo	Obrigatório	Descrição
`Authorization`	string	Sim	Bearer token

Parâmetros de path

Parâmetro	Tipo	Obrigatório	Descrição
`organization_id`	string	Sim	UUID da organização
`ledger_id`	string	Sim	UUID do ledger

Parâmetros de query (quando aplicável)

Parâmetro	Tipo	Obrigatório	Descrição	Padrão
`limit`	integer	Não	Número máximo de resultados	10
`cursor`	string	Não	Cursor de paginação	—

Corpo da requisição

Documente todos os campos em uma única tabela com estas colunas:

Campo	Tipo	Obrigatório	Descrição	Valores possíveis	Padrão	Restrições	Exemplo
`name`	string	Sim	Nome da conta	—	—	MaxLength: 100	`"Main Account"`
`type`	string	Sim	Tipo da conta	`deposit`, `savings`, `external`	—	—	`"deposit"`
`assetCode`	string	Sim	Código da moeda ou ativo	—	—	ISO 4217 ou customizado	`"BRL"`
`alias`	string	Não	Identificador legível por humanos	—	—	Deve começar com `@`	`"@revenue"`

Para objetos aninhados, use uma subseção (H4) com sua própria tabela:

Objeto `status`

Campo	Tipo	Obrigatório	Descrição	Valores possíveis
`code`	string	Sim	Código de status	`ACTIVE`, `INACTIVE`, `BLOCKED`
`description`	string	Não	Razão do status	—

Exemplo de requisição

Um comando curl completo e realista. Use placeholders apenas para IDs ({organization_id}), nunca para valores de campos.

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "name": "Revenue Account",
    "assetCode": "BRL",
    "type": "deposit",
    "status": {
      "code": "ACTIVE"
    },
    "alias": "@revenue"
  }'

Resposta de sucesso

Inclua o código de status HTTP e um corpo de resposta completo.201 Created

{
  "id": "01fbc1e4-5678-9abc-def0-123456789abc",
  "name": "Revenue Account",
  "assetCode": "BRL",
  "type": "deposit",
  "status": {
    "code": "ACTIVE"
  },
  "alias": "@revenue",
  "createdAt": "2026-03-27T12:00:00Z",
  "updatedAt": "2026-03-27T12:00:00Z"
}

Para respostas 204 No Content, declare explicitamente que nenhum corpo é retornado.

Respostas de erro

Liste todos os erros possíveis que o endpoint pode retornar. Todos os erros seguem o formato padrão de erros da Lerian.

Status	Código	Descrição
`400`	`INVALID_REQUEST`	Campo obrigatório ausente ou inválido
`404`	`LEDGER_NOT_FOUND`	Ledger não existe
`409`	`ALIAS_ALREADY_EXISTS`	Uma conta com este alias já existe no ledger
`422`	`ASSET_NOT_FOUND`	O código de ativo especificado não existe neste ledger

Inclua um exemplo de corpo de resposta de erro:

{
  "code": "ALIAS_ALREADY_EXISTS",
  "message": "An account with alias @revenue already exists in this ledger.",
  "details": {
    "field": "alias",
    "value": "@revenue"
  }
}

Especificação OpenAPI

Inclua a especificação OpenAPI 3.1 para este endpoint sempre que possível. Use uma seção colapsável:

<Accordion title="OpenAPI spec (YAML)">

  ```yaml
    /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts:
      post:
        summary: Create an account
        operationId: createAccount
        ...
  ```
</Accordion>

Modelo de erros

Todas as APIs da Lerian seguem um formato padrão de erros. Documente-o uma vez e referencie-o em toda página de endpoint.

Resposta padrão de erro

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of what went wrong.",
  "details": {}
}

Campo	Tipo	Descrição
`code`	string	Código de erro legível por máquina (uppercase, snake_case)
`message`	string	Descrição legível por humanos
`details`	object	Contexto adicional (nome do campo, valor, restrições). Opcional.

Convenções de códigos de status HTTP

Status	Significado	Quando usar
`400`	Bad Request	Requisição malformada, campos obrigatórios ausentes, valores inválidos
`401`	Unauthorized	Autenticação ausente ou inválida
`403`	Forbidden	Autenticado mas permissões insuficientes
`404`	Not Found	Recurso não existe
`409`	Conflict	Recurso duplicado (alias, chave de idempotência)
`422`	Unprocessable Entity	Sintaxe válida mas regras de negócio falharam
`429`	Too Many Requests	Limite de taxa excedido
`500`	Internal Server Error	Falha inesperada do servidor

Regras de escrita para referência de API

Essas regras se aplicam a toda documentação de referência de API. Elas complementam as diretrizes gerais de voz e tom.

Faça

Comece descrições com um verbo: “Creates”, “Returns”, “Deletes”
Use formatação de código para todos os nomes de campos, valores, endpoints e métodos HTTP
Documente todos os campos, mesmo os opcionais
Inclua valores de exemplo realistas — nunca "string" ou "example"
Mostre a requisição e resposta completas, não fragmentos
Liste todos os erros possíveis, não apenas os comuns

Não faça

Não explique contexto de negócio ou motivação — isso pertence aos guias
Não use <Tip>, <Note> ou <Warning> em descrições de endpoints — reserve-os apenas para pré-requisitos ou pegadinhas
Não use voz narrativa (“you might want to”, “consider using”)
Não descreva campos com “This field is used to…” — declare o que faz diretamente
Não omita casos de erro porque são “improváveis”

Padrões de componentes

Páginas de referência de API usam um conjunto menor de componentes do que guias.

Componente	Quando usar
`<Accordion>`	Especificações OpenAPI colapsáveis, listas de erros estendidas
`<CodeGroup>`	Múltiplos formatos de request/response (curl + exemplos de SDK)
`<Note>`	Pré-requisitos, comportamento específico de versão
`<Warning>`	Breaking changes, avisos de depreciação
`<Danger>`	Operações irreversíveis (hard delete, perda de dados)
Tabelas	Parâmetros, campos, erros — sempre em tabelas, nunca em prosa

Para mais informações, consulte a documentação oficial do Mintlify.

Introdução

Padrões de codificação

Padrões de escrita

Templates de referência de API

Página de endpoint

Objeto `status`

Modelo de erros

Resposta padrão de erro

Convenções de códigos de status HTTP

Regras de escrita para referência de API

Faça

Não faça

Padrões de componentes

Introdução

Padrões de codificação

Padrões de escrita

​Página de endpoint

​Objeto status

​Modelo de erros

​Resposta padrão de erro

​Convenções de códigos de status HTTP

​Regras de escrita para referência de API

​Faça

​Não faça

​Padrões de componentes

Página de endpoint

Objeto `status`

Modelo de erros

Resposta padrão de erro

Convenções de códigos de status HTTP

Regras de escrita para referência de API

Faça

Não faça

Padrões de componentes