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

# Estándares de API

> Convenciones de diseño y requisitos para las APIs de plugins en el ecosistema Lerian.

Todos los plugins que exponen APIs deben adherirse a los estándares de API de Lerian para asegurar consistencia, interoperabilidad y una experiencia de desarrollador predecible en todo el ecosistema. Las APIs deben seguir principios RESTful y estar descritas usando la especificación **OpenAPI 3.1**. GraphQL es opcional pero está permitido como interfaz complementaria.

Esta página define las convenciones que aplican a cada API de plugin de Lerian — desde la nomenclatura de parámetros hasta el formato de errores.

## Parámetros de encabezado

***

### Authorization

Todos los plugins soportan integración opcional con [Access Manager](/es/platform/access-manager/access-manager). El encabezado `Authorization` debe documentarse como **opcional** en el esquema de tu API. Es requerido solo cuando el entorno tiene el plugin Access Manager habilitado.

Usa el campo de descripción para comunicar esta condicionalidad — no establezcas el flag `required` como `true`.

Texto de descripción recomendado:

> *The authorization token. This header is required only if your environment has the Access Manager plugin enabled.*

### Encabezados personalizados

Los encabezados específicos de servicio siguen el patrón `X-{Service}-{Name}` usando PascalCase. Por ejemplo: `X-Account-ID`.

## Parámetros de consulta

***

Todos los parámetros de consulta deben usar `snake_case`.

Lerian define un conjunto de parámetros de consulta estándar que deben soportarse en todos los endpoints de listado:

| Parámetro    | Tipo    | Descripción                                                       | Valor por defecto |
| ------------ | ------- | ----------------------------------------------------------------- | ----------------- |
| `metadata`   | string  | Cadena JSON para filtrar por campos de metadatos                  | —                 |
| `limit`      | integer | Número máximo de registros por página (1–100)                     | 10                |
| `page`       | integer | Número de página para paginación (mínimo 1)                       | 1                 |
| `start_date` | string  | Filtrar elementos creados en o después de esta fecha (YYYY-MM-DD) | —                 |
| `end_date`   | string  | Filtrar elementos creados en o antes de esta fecha (YYYY-MM-DD)   | —                 |
| `sort_order` | string  | Dirección de ordenamiento: `asc` o `desc`                         | —                 |

## Parámetros de cuerpo

***

Los campos en los cuerpos de solicitud y respuesta deben usar `lowerCamelCase`.

No uses `snake_case`, `kebab-case` o `PascalCase` en payloads JSON. Esta convención aplica a todos los nombres de campo en cada nivel de anidamiento.

## Códigos de estado de respuesta

***

Las APIs de Lerian usan un conjunto mínimo de códigos de estado HTTP:

| Código           | Uso                                              |
| ---------------- | ------------------------------------------------ |
| `200 OK`         | Solicitud procesada exitosamente (síncrona)      |
| `201 Created`    | Recurso creado exitosamente                      |
| `202 Accepted`   | Aceptado para procesamiento asíncrono            |
| `204 No Content` | Éxito sin cuerpo de respuesta (ej., soft-delete) |

## Formato de fecha y hora

***

Todos los campos de fecha-hora deben seguir **ISO 8601** en **UTC** con el sufijo `Z`. No devuelvas fechas sin el sufijo `Z` o en zonas horarias locales.

```json theme={null}
{
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}
```

Los campos de solo fecha (como parámetros de consulta) usan el formato `YYYY-MM-DD`.

## Formato de errores

***

Todas las respuestas de error deben seguir la estructura estándar de errores de Lerian:

```json theme={null}
{
  "code": "XXX-0000",
  "title": "Error title",
  "message": "Error message."
}
```

Cuando el error se relaciona con campos específicos (ej., fallas de validación), incluye un objeto `fields` con detalles por campo:

```json theme={null}
{
  "code": "XXX-0000",
  "title": "Bad Request",
  "message": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
  "fields": {
    "legalName": "legalName is a required field.",
    "parentOrganizationId": "parentOrganizationId must be a valid UUID"
  }
}
```

### Convenciones de códigos de error

Los códigos de error siguen el patrón: **prefijo de 3 letras del plugin** + **4 dígitos**.

* Cada plugin tiene su propio prefijo (ej., `MDZ` para Midaz, `PIX` para Pix, `TRC` para Tracer)
* Los códigos en el rango `0001`–`0999` son errores internos del plugin
* Los códigos que comienzan con `1` (ej., `XXX-1000`) indican errores de integraciones externas

<Warning>
  Las respuestas de error deben cumplir con el formato estándar de Lerian según la guía del [Modelo de errores](/es/partners-hub/error-model).
</Warning>

## Comportamiento de PATCH

***

Todos los endpoints PATCH siguen **RFC 7386 — JSON Merge Patch**.

* **Content-Type**: `application/merge-patch+json`
* **Propiedades omitidas**: permanecen sin cambios
* **Propiedades con valor `null`**: se eliminan o restablecen al valor por defecto
* **Objetos**: se fusionan recursivamente
* **Arrays**: se reemplazan completamente (sin fusión por elemento)

Esto significa que una solicitud PATCH solo necesita incluir los campos que se están modificando. Cualquier campo no presente en el cuerpo de la solicitud permanece como está.

## Patrón de soft-delete

***

Las operaciones de eliminación siguen el patrón de **soft-delete**:

* Devuelven `204 No Content`
* Establecen el campo `deletedAt` con la marca de tiempo UTC actual en formato ISO 8601
* Excluyen los registros eliminados de los listados por defecto (a menos que se aplique un filtro explícito)
* La operación es **idempotente** — llamar DELETE sobre un recurso ya eliminado devuelve el mismo `204`

Los recursos eliminados se preservan para fines de auditoría y cumplimiento. El hard-delete no se usa a menos que esté explícitamente justificado.

## Objetos de metadatos

***

Las APIs de Lerian soportan un objeto `metadata` para almacenar pares clave-valor arbitrarios en los recursos. Esto permite a los clientes adjuntar datos personalizados sin cambios en el esquema.

Convenciones para metadatos:

* Las claves deben usar `lowerCamelCase`
* Los valores pueden ser primitivos JSON u objetos anidados
* Las claves desconocidas deben ser **preservadas textualmente** — nunca transformes, renombres o elimines campos de metadatos
* Los metadatos pueden filtrarse a través del parámetro de consulta `metadata` como cadena JSON

## Referencia rápida

***

| Convención                 | Estándar                        |
| -------------------------- | ------------------------------- |
| Parámetros de consulta     | `snake_case`                    |
| Campos del cuerpo JSON     | `lowerCamelCase`                |
| Encabezados personalizados | `X-Service-Name` (PascalCase)   |
| Fechas                     | ISO 8601 UTC con sufijo `Z`     |
| PATCH                      | RFC 7386 JSON Merge Patch       |
| DELETE                     | Soft-delete, `204 No Content`   |
| Códigos de error           | Prefijo de 3 letras + 4 dígitos |
| OpenAPI                    | 3.1                             |