Saltar al contenido principal
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. 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ámetroTipoDescripciónValor por defecto
metadatastringCadena JSON para filtrar por campos de metadatos—
limitintegerNúmero máximo de registros por página (1–100)10
pageintegerNúmero de página para paginación (mínimo 1)1
start_datestringFiltrar elementos creados en o después de esta fecha (YYYY-MM-DD)—
end_datestringFiltrar elementos creados en o antes de esta fecha (YYYY-MM-DD)—
sort_orderstringDirecció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ódigoUso
200 OKSolicitud procesada exitosamente (síncrona)
201 CreatedRecurso creado exitosamente
202 AcceptedAceptado 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. 
{
  "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: 
{
  "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: 
{
  "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
Las respuestas de error deben cumplir con el formato estándar de Lerian según la guía del Modelo de errores.

​
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ónEstándar
Parámetros de consultasnake_case
Campos del cuerpo JSONlowerCamelCase
Encabezados personalizadosX-Service-Name (PascalCase)
FechasISO 8601 UTC con sufijo Z
PATCHRFC 7386 JSON Merge Patch
DELETESoft-delete, 204 No Content
Códigos de errorPrefijo de 3 letras + 4 dígitos
OpenAPI3.1