Plantillas de referencia de API

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. Aplica las reglas de voz y tono y capitalización 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.

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

Descripción

Una a dos oraciones. Qué hace el endpoint y cuándo usarlo. Sin contexto, sin motivación.

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

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”)

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	—

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	—

Ejemplo de solicitud

Un comando curl completo y realista. Usa placeholders solo 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"
  }'

Respuesta exitosa

Incluye el código de estado HTTP y un cuerpo de respuesta 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 respuestas 204 No Content, indica explícitamente que no se devuelve cuerpo.

Respuestas de error

Lista cada error posible que el endpoint puede devolver. Todos los errores siguen el formato estándar de errores de Lerian.

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:

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

Especificación OpenAPI

Incluye la especificación OpenAPI 3.1 para este endpoint siempre que sea posible. Usa una sección colapsable:

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

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

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

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

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

Para más información, consulta la documentación oficial de Mintlify.

Resumen

Diccionario de campos

Plantillas de referencia de API

Página de endpoint

`status` object

Modelo de errores

Respuesta estándar de error

Convenciones de códigos de estado HTTP

Reglas de escritura para referencia de API

Hacer

No hacer

Patrones de componentes

​Página de endpoint

​status object

​Modelo de errores

​Respuesta estándar de error

​Convenciones de códigos de estado HTTP

​Reglas de escritura para referencia de API

​Hacer

​No hacer

​Patrones de componentes

Página de endpoint

`status` object

Modelo de errores

Respuesta estándar de error

Convenciones de códigos de estado HTTP

Reglas de escritura para referencia de API

Hacer

No hacer

Patrones de componentes