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

# Templates de referência de API

> Adote os templates oficiais da Lerian para referência de API — endpoints, schemas, erros e OpenAPI — para manter docs precisos e previsíveis.

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](/pt/partners-hub/guides-template).

Aplique as regras de [voz e tom](/pt/partners-hub/voice-tone) e [capitalização](/pt/partners-hub/capitalization) 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.

<Steps>
  <Step title="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   |
  </Step>

  <Step title="Descrição">
    Uma a duas frases. O que o endpoint faz e quando usá-lo. Sem contexto, sem motivação.

    ```markdown theme={null}
    Creates a new account in the specified ledger. The account is linked to a single asset
    and follows double-entry accounting rules.
    ```
  </Step>

  <Step title="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")
  </Step>

  <Step title="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         | —      |
  </Step>

  <Step title="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  | —                               |
  </Step>

  <Step title="Exemplo de requisição">
    Um comando `curl` completo e realista. Use placeholders apenas para IDs (`{organization_id}`), nunca para valores de campos.

    ```bash theme={null}
    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"
      }'
    ```
  </Step>

  <Step title="Resposta de sucesso">
    Inclua o código de status HTTP e um corpo de resposta completo.

    **`201 Created`**

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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](/pt/partners-hub/error-model).

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

    ```json theme={null}
    {
      "code": "ALIAS_ALREADY_EXISTS",
      "message": "An account with alias @revenue already exists in this ledger.",
      "details": {
        "field": "alias",
        "value": "@revenue"
      }
    }
    ```
  </Step>

  <Step title="Especificação OpenAPI">
    Inclua a especificação OpenAPI 3.1 para este endpoint sempre que possível. Use uma seção colapsável:

    ````json theme={null}
    <Accordion title="OpenAPI spec (YAML)">

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

    ````
  </Step>
</Steps>

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

```json theme={null}
{
  "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](/pt/partners-hub/voice-tone).

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

<Tip>
  Para mais informações, consulte a [documentação oficial do Mintlify](https://www.mintlify.com/docs/components/index).
</Tip>