Saltar al contenido principal
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.
1

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:
MethodVerbExample
POSTCreateCreate an account
GETListList accounts
GET (by ID)RetrieveRetrieve an account
PATCHUpdateUpdate an account
DELETEDelete / DeactivateDelete an account
2

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

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

Parámetros

Agrupa por ubicación. Usa una tabla separada para cada grupo:Header parameters
ParameterTypeRequiredDescription
AuthorizationstringYesBearer token
Path parameters
ParameterTypeRequiredDescription
organization_idstringYesUUID of the organization
ledger_idstringYesUUID of the ledger
Query parameters (cuando aplique)
ParameterTypeRequiredDescriptionDefault
limitintegerNoMaximum number of results10
cursorstringNoPagination cursor—
5

Cuerpo de la solicitud

Documenta todos los campos en una sola tabla con estas columnas:
FieldTypeRequiredDescriptionPossible valuesDefaultConstraintsExample
namestringYesName of the account——MaxLength: 100"Main Account"
typestringYesAccount typedeposit, savings, external——"deposit"
assetCodestringYesCurrency or asset code——ISO 4217 or custom"BRL"
aliasstringNoHuman-readable identifier——Must start with @"@revenue"
Para objetos anidados, usa una subsección (H4) con su propia tabla:

​
status object

FieldTypeRequiredDescriptionPossible values
codestringYesStatus codeACTIVE, INACTIVE, BLOCKED
descriptionstringNoReason for the status—
6

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"
  }'
7

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

Respuestas de error

Lista cada error posible que el endpoint puede devolver. Todos los errores siguen el formato estándar de errores de Lerian.
StatusCodeDescription
400INVALID_REQUESTMissing or invalid required field
404LEDGER_NOT_FOUNDLedger does not exist
409ALIAS_ALREADY_EXISTSAn account with this alias already exists in the ledger
422ASSET_NOT_FOUNDThe 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"
  }
}
9

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": {}
}
FieldTypeDescription
codestringMachine-readable error code (uppercase, snake_case)
messagestringHuman-readable description
detailsobjectAdditional context (field name, value, constraints). Optional.

​
Convenciones de códigos de estado HTTP

StatusMeaningWhen to use
400Bad RequestMalformed request, missing required fields, invalid values
401UnauthorizedMissing or invalid authentication
403ForbiddenAuthenticated but insufficient permissions
404Not FoundResource does not exist
409ConflictDuplicate resource (alias, idempotency key)
422Unprocessable EntityValid syntax but failed business rules
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnexpected 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.
ComponenteCuá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)
TablasParámetros, campos, errores — siempre en tablas, nunca en prosa
Para más información, consulta la documentación oficial de Mintlify.