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

# Plantillas de referencia de API

> Adopta las plantillas oficiales de Lerian para referencia de API — endpoints, esquemas, errores y OpenAPI — para mantener docs precisos y predecibles.

Esta página proporciona las plantillas oficiales para toda la documentación de referencia de API en el ecosistema de Lerian: páginas de endpoints, esquemas de solicitud/respuesta, manejo de errores y especificaciones OpenAPI.

La documentación de referencia de API es técnica, seca y precisa. Sin narrativa, sin establecer contexto, sin "por qué" -- declara hechos. Describe entradas, salidas y comportamiento. Para documentación orientada a tareas o contextual, consulta las [Plantillas de guías](/es/partners-hub/guides-template).

Aplica las reglas de [voz y tono](/es/partners-hub/voice-tone) y [capitalización](/es/partners-hub/capitalization) a todo el contenido de referencia de API.

## Página de endpoint

***

Cada endpoint de API tiene su propia página. La estructura es estricta -- cada página sigue el mismo formato para que los desarrolladores puedan escanear de manera predecible.

<Steps>
  <Step title="Título">
    Usa un título corto y claro que quepa en una línea en la tabla de contenidos. Sigue el patrón de verbos estándar basado en el método HTTP:

    | Method        | Verb                | Example             |
    | :------------ | :------------------ | :------------------ |
    | `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="Descripción">
    Una a dos oraciones. Qué hace el endpoint y cuándo usarlo. Sin contexto, sin motivación.

    ```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="Prerrequisitos">
    Lista lo que se requiere para usar el endpoint:

    * Método de autenticación
    * Permisos o roles requeridos
    * Entidades que deben existir primero (ej., "Requires an existing organization and ledger")
  </Step>

  <Step title="Parámetros">
    Agrupa por ubicación. Usa una tabla separada para cada grupo:

    **Header parameters**

    | Parameter       | Type   | Required | Description  |
    | :-------------- | :----- | :------- | :----------- |
    | `Authorization` | string | Yes      | Bearer token |

    **Path parameters**

    | Parameter         | Type   | Required | Description              |
    | :---------------- | :----- | :------- | :----------------------- |
    | `organization_id` | string | Yes      | UUID of the organization |
    | `ledger_id`       | string | Yes      | UUID of the ledger       |

    **Query parameters** (cuando aplique)

    | Parameter | Type    | Required | Description               | Default |
    | :-------- | :------ | :------- | :------------------------ | :------ |
    | `limit`   | integer | No       | Maximum number of results | 10      |
    | `cursor`  | string  | No       | Pagination cursor         | —       |
  </Step>

  <Step title="Cuerpo de la solicitud">
    Documenta todos los campos en una sola tabla con estas columnas:

    | Field       | Type   | Required | Description               | Possible values                  | Default | Constraints         | Example          |
    | :---------- | :----- | :------- | :------------------------ | :------------------------------- | :------ | :------------------ | :--------------- |
    | `name`      | string | Yes      | Name of the account       | —                                | —       | MaxLength: 100      | `"Main Account"` |
    | `type`      | string | Yes      | Account type              | `deposit`, `savings`, `external` | —       | —                   | `"deposit"`      |
    | `assetCode` | string | Yes      | Currency or asset code    | —                                | —       | ISO 4217 or custom  | `"BRL"`          |
    | `alias`     | string | No       | Human-readable identifier | —                                | —       | Must start with `@` | `"@revenue"`     |

    Para objetos anidados, usa una subsección (H4) con su propia tabla:

    #### `status` object

    | Field         | Type   | Required | Description           | Possible values                 |
    | :------------ | :----- | :------- | :-------------------- | :------------------------------ |
    | `code`        | string | Yes      | Status code           | `ACTIVE`, `INACTIVE`, `BLOCKED` |
    | `description` | string | No       | Reason for the status | —                               |
  </Step>

  <Step title="Ejemplo de solicitud">
    Un comando `curl` completo y realista. Usa placeholders solo 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="Respuesta exitosa">
    Incluye el código de estado HTTP y un cuerpo de respuesta 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 respuestas `204 No Content`, indica explícitamente que no se devuelve cuerpo.
  </Step>

  <Step title="Respuestas de error">
    Lista cada error posible que el endpoint puede devolver. Todos los errores siguen el [formato estándar de errores de Lerian](/es/partners-hub/error-model).

    | Status | Code                   | Description                                             |
    | :----- | :--------------------- | :------------------------------------------------------ |
    | `400`  | `INVALID_REQUEST`      | Missing or invalid required field                       |
    | `404`  | `LEDGER_NOT_FOUND`     | Ledger does not exist                                   |
    | `409`  | `ALIAS_ALREADY_EXISTS` | An account with this alias already exists in the ledger |
    | `422`  | `ASSET_NOT_FOUND`      | The specified asset code does not exist in this ledger  |

    Incluye un ejemplo de cuerpo de respuesta de error:

    ```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="Especificación OpenAPI">
    Incluye la especificación OpenAPI 3.1 para este endpoint siempre que sea posible. Usa una sección colapsable:

    ````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 errores

***

Todas las APIs de Lerian siguen un formato estándar de errores. Documéntalo una vez y referéncialo desde cada página de endpoint.

### Respuesta estándar de error

```json theme={null}
{
  "code": "ERROR_CODE",
  "message": "Human-readable description of what went wrong.",
  "details": {}
}
```

| Field     | Type   | Description                                                    |
| :-------- | :----- | :------------------------------------------------------------- |
| `code`    | string | Machine-readable error code (uppercase, snake\_case)           |
| `message` | string | Human-readable description                                     |
| `details` | object | Additional context (field name, value, constraints). Optional. |

### Convenciones de códigos de estado HTTP

| Status | Meaning               | When to use                                                |
| :----- | :-------------------- | :--------------------------------------------------------- |
| `400`  | Bad Request           | Malformed request, missing required fields, invalid values |
| `401`  | Unauthorized          | Missing or invalid authentication                          |
| `403`  | Forbidden             | Authenticated but insufficient permissions                 |
| `404`  | Not Found             | Resource does not exist                                    |
| `409`  | Conflict              | Duplicate resource (alias, idempotency key)                |
| `422`  | Unprocessable Entity  | Valid syntax but failed business rules                     |
| `429`  | Too Many Requests     | Rate limit exceeded                                        |
| `500`  | Internal Server Error | Unexpected server failure                                  |

## Reglas de escritura para referencia de API

***

Estas reglas aplican a toda la documentación de referencia de API. Complementan las directrices generales de [voz y tono](/es/partners-hub/voice-tone).

### Hacer

* Comienza las descripciones con un verbo: "Creates", "Returns", "Deletes"
* Usa `formato de código` para todos los nombres de campo, valores, endpoints y métodos HTTP
* Documenta cada campo, incluso los opcionales
* Incluye valores de ejemplo realistas -- nunca `"string"` o `"example"`
* Muestra la solicitud y respuesta completas, no fragmentos
* Lista cada error posible, no solo los comunes

### No hacer

* No expliques contexto de negocio o motivación -- eso pertenece a las guías
* No uses `<Tip>`, `<Note>` o `<Warning>` en descripciones de endpoints -- resérvalos solo para prerrequisitos o detalles importantes
* No uses voz narrativa ("you might want to", "consider using")
* No describas campos con "This field is used to..." -- indica directamente lo que hace
* No omitas casos de error porque son "improbables"

## Patrones de componentes

***

Las páginas de referencia de API usan un conjunto más reducido de componentes que las guías.

| Componente    | Cuándo usarlo                                                      |
| ------------- | ------------------------------------------------------------------ |
| `<Accordion>` | Especificaciones OpenAPI colapsables, listas extendidas de errores |
| `<CodeGroup>` | Múltiples formatos de solicitud/respuesta (curl + ejemplos de SDK) |
| `<Note>`      | Prerrequisitos, comportamiento específico de versión               |
| `<Warning>`   | Cambios incompatibles, avisos de deprecación                       |
| `<Danger>`    | Operaciones irreversibles (hard delete, pérdida de datos)          |
| Tablas        | Parámetros, campos, errores -- siempre en tablas, nunca en prosa   |

<Tip>
  Para más información, consulta la [documentación oficial de Mintlify](https://www.mintlify.com/docs/components/index).
</Tip>