API de Inventarios

La API de Inventarios de Fenicia gestiona el stock de tus productos por ubicación: consulta y actualización de existencias, transferencias entre ubicaciones, ajustes manuales y conteos cíclicos/físicos.

Lee esta página completa antes de integrar

Esta API tiene comportamientos que difieren entre recursos (formato de paginación, nombres de campo, códigos de error). No son inconsistencias cosméticas — afectan directamente cómo debes parsear las respuestas. Están documentadas explícitamente abajo.

¿Qué puedes hacer?

Consultar el stock de un SKU en una ubicación, o el listado completo con filtros.
Actualizar el stock de un SKU en una ubicación (PUT) o en lote (bulk-update).
Transferir stock entre ubicaciones (creación, aprobación y recepción).
Ajustar el stock manualmente con una razón auditable (merma, daño, corrección de conteo, etc.).
Ejecutar conteos cíclicos o físicos y aplicar la varianza resultante como ajuste.

Base URL

https://api.fenicia.io

Todos los endpoints de este dominio viven bajo /inventory/*. El dominio relacionado de Ubicaciones (/locations/*) administra las ubicaciones y zonas a las que apunta el locationId de cada registro de inventario, pero no forma parte de esta referencia.

Modelo de datos

Un registro de inventario (Inventory) representa el stock de un SKU en una ubicación. La clave compuesta {tenantId, sku, locationId} es única: existe un solo documento por combinación de SKU y ubicación.

{
  "tenantId": "69db07c8bce4d49b18c42a49",
  "sku": "CAM-ROJO-M",
  "productSku": "CAM-ROJO",
  "locationId": "loc_abc123",
  "stock": 42,
  "compromised": 0,
  "handler": null,
  "handlerType": "manual",
  "createdAt": "2026-01-10T12:00:00.000Z",
  "updatedAt": "2026-06-01T09:15:00.000Z"
}

Campo	Tipo	Descripción
`sku`	string	SKU de la variante.
`productSku`	string	SKU del producto padre (opcional).
`locationId`	string	Ubicación a la que pertenece este registro.
`stock`	number	Existencias actuales.
`compromised`	number	Stock reservado/comprometido. Ver advertencia abajo.
`handler`	string \| null	Identificador de la integración/canal que controla este registro, si aplica.
`handlerType`	`manual` \| `integration` \| `channel`	Origen del control de stock.

No existe un endpoint de 'stock disponible' en este dominio

El campo compromised (stock reservado/comprometido) existe en el esquema, pero ningún endpoint de la API de Inventarios lo lee, escribe o calcula. No hay un endpoint que devuelva disponible = stock − compromised. Ese cálculo lo resuelven los dominios de Productos y Órdenes en sus propias vistas — si tu integración necesita "disponible vs. comprometido", no lo busques aquí.

Formato de respuesta

Esta API no usa un envelope único {data, meta}. Cada recurso devuelve la forma que su endpoint define, y esas formas no son iguales entre sí:

Recurso	Forma de la respuesta de listado
`/inventory`, `/inventory/location/:id`	`{ items: Inventory[], pagination: { page, limit, total, pages } }`
`/inventory/transfers`	`{ transfers: InventoryTransfer[], pagination }`
`/inventory/adjustments`	`{ adjustments: InventoryAdjustment[], pagination }`
`/inventory/counts`	`{ counts: InventoryCount[], pagination }`

Los endpoints de detalle (GET .../:id) devuelven el documento crudo, sin envolver (por ejemplo, GET /inventory/transfers/:id devuelve el objeto InventoryTransfer directamente, no { transfer: {...} }).

Paginación — advertencia importante

La paginación NO usa el mismo índice en todos los endpoints

Los endpoints bajo /inventory (listado de stock, transferencias, ajustes, conteos) son 1-indexados: page por defecto es 1. Si integras un solo helper de paginación reutilizado en todo tu cliente, verifica siempre el valor por defecto de page para el endpoint específico que estás llamando — usar el mismo helper sin ajustar produce off-by-one silencioso.

Endpoint	`page` por defecto
`GET /inventory`	`1`
`GET /inventory/location/:id`	`1`
`GET /inventory/transfers`	`1`
`GET /inventory/adjustments`	`1`
`GET /inventory/counts`	`1`

Autenticación

Todas las peticiones requieren el header Authorization con tu API key:

Authorization: Bearer fkapi_tu_api_key

Consulta Autenticación para el proceso completo de creación y rotación de llaves.

Tip

Cada endpoint documenta el permiso (scope) exacto que requiere, por ejemplo inventory:read o inventory:update. Una API key sin ese scope recibe 403.

Inicio rápido

curl 'https://api.fenicia.io/inventory?limit=10' \
  -H 'Authorization: Bearer fkapi_tu_api_key'