Contrato objetivo (en convergencia)

Esta documentación describe el estándar al que se apega la API v1: un contrato consistente, alineado con JSON:API y RFC 9457. La plataforma está migrando a este contrato, por lo que algunas respuestas actuales pueden diferir de los ejemplos mientras se completa la unificación. Programa tus integraciones contra este estándar.

URL base y tenant

Cada organización vive en su propio subdominio. Todas las rutas de la v1 cuelgan de /api/v1 sobre tu subdominio:

URL base

https://tu-empresa.chainlink.mx/api/v1

El subdominio identifica al tenant; no existe un dominio compartido para los datos de tu almacén.

Peticiones

Usa HTTPS siempre.
Envía Accept: application/json para recibir JSON (y errores en JSON).
En POST/PUT envía Content-Type: application/json con el cuerpo en JSON.
Autentícate con Authorization: Bearer TU_TOKEN (ver Autenticación).

Cuerpo de las peticiones

En POST y PUT, los campos van directamente en el cuerpo JSON (sin envoltura). Las respuestas, en cambio, sí envuelven el resultado en data (ver abajo).

Cuerpo · POST /products

{
  "item_code": "SKU-001",
  "name": "Producto de ejemplo",
  "barcode": "7501000000017"
}

Estándar de respuestas

Toda respuesta exitosa envuelve el resultado en una clave data. Un recurso individual es un objeto; una colección es un arreglo, acompañado de meta y links.

Recurso individual

{
  "data": { "id": 9, "item_code": "DEMO-009", "name": "Aceite Vegetal 1L" }
}

Paginación

Las colecciones se paginan. Controla el tamaño con per_page (entre 1 y 100, por defecto 25) y navega con page. La respuesta incluye meta (posición) y links (navegación):

Colección paginada

{
  "data": [ { "id": 9, "item_code": "DEMO-009", "name": "Aceite Vegetal 1L" } ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "from": 1,
    "to": 25,
    "last_page": 6,
    "total": 138
  },
  "links": {
    "first": "https://tu-empresa.chainlink.mx/api/v1/products?page=1",
    "last":  "https://tu-empresa.chainlink.mx/api/v1/products?page=6",
    "prev":  null,
    "next":  "https://tu-empresa.chainlink.mx/api/v1/products?page=2"
  }
}

Errores

Los errores siguen un formato consistente basado en un arreglo errors. El detalle completo, con los códigos y ejemplos por estatus, está en Errores.

Headers de respuesta

Cada respuesta incluye headers estándar para trazabilidad y control de tasa:

Headers

X-Request-Id: req_01HXX8Z9K3M7QRVT2E4B6N0R
X-Api-Version: v1
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119

X-Request-Id — identificador único de la petición. Inclúyelo cuando reportes un problema: nos permite rastrear tu llamada exacta.
X-Api-Version — versión de la API que atendió la petición.
X-RateLimit-Limit / X-RateLimit-Remaining — límite de tasa y solicitudes restantes en la ventana.

Límites de tasa

La API aplica un límite por minuto (por usuario o IP, dentro de cada tenant). El valor por defecto es 120 solicitudes/minuto y puede variar según el plan de tu organización. Al superarlo, la API responde 429 Too Many Requests con un header Retry-After.

Fechas

Las marcas de tiempo se devuelven en ISO 8601 en UTC (por ejemplo 2026-07-20T18:00:00.000000Z).

Versionado

La versión actual y recomendada es v1 (/api/v1). Los cambios se anuncian en el Changelog. Los endpoints heredados bajo /api se mantienen para integraciones antiguas pero no reciben nuevas funciones.