API de reducción de inventario

Esta API permite descontar stock en la bodega asociada a una tienda autorizada en tu API key. Cada operación registra movimientos con el tipo indicado por ítem (por defecto Consumo) y documento API_INVENTORY_REDUCTION.

Actualmente existe un único endpoint: la reducción se identifica siempre por código externo del producto (external_code).

Casos de uso típicos

Antes de llamar a este endpoint, tu organización debe tener configurado en el panel del sistema:

1. 1

   API key de tipo OPERATIVE — una key GENERAL no sirve para esta ruta.

2. 2

   El módulo inventory_reduction asignado a esa key.

3. 3

   Productos dados de alta en la tienda (tienda / productos) con código externo configurado desde el dashboard, y stock en la bodega configurada.

4. 4

   external_id configurado en las tiendas que uses en la integración.

5. 5

   El tenant (identificador de tu instancia) para enviarlo en el header X-Tenant en cada petición.

Todas las rutas viven bajo la URL base de la API:

El tenant ya no se resuelve por subdominio del host. Se resuelve a partir del header X-Tenant, cuyo valor es el identificador (slug) de tu tenant en Smart Order:

Incluye el tenant y la API key en cada petición:

Flujo de validación (en orden)

1. 1

   TenantMiddleware

   Resuelve el tenant por el header X-Tenant. 401 si no especificado, no encontrado o inactivo.

2. 2

   ValidateApiKeyMiddleware

   Verifica que la key exista, sea válida y no esté revocada. 401 si está ausente, inválida o revocada.

3. 3

   RequireOperativeKey

   La key debe ser de tipo OPERATIVE. 403 si no lo es.

4. 4

   HasApiKeyModule (inventory_reduction)

   La key debe tener asignado el módulo de reducción. 403 si falta.

5. ✓

   Validar tienda, productos y stock → descontar

   Responde 200 {"ok": true} o un error 4xx.

Descuenta inventario identificando cada ítem por código externo en la tienda indicada.

Body

{
  "store_id": "TIENDA-CENTRO-01",
  "reference": "venta-pos-2026-05-15-0042",
  "items": [
    { "external_code": "PROD-001", "quantity": 2.5, "movement_type": "sale" },
    { "external_code": "PROD-002", "quantity": 1 }
  ]
}

Tipos de movimiento

Respuesta exitosa

200 OK

{
  "ok": true
}

El campo reference es obligatorio en cada petición. Evita descontar stock dos veces si reenvías la misma operación (timeouts, reintentos de red, etc.).

Comportamiento

Antes de descontar, el servidor busca un movimiento previo con la misma combinación: (reference, API_INVENTORY_REDUCTION, api-key:<id>).

• Si ya existe → 200 con {"ok": true} sin volver a descontar.
• Si no existe → se procesa la reducción y se registra con esa reference.

Alcance de la idempotencia

La clave es única por: valor de reference, tipo de documento API_INVENTORY_REDUCTION y la API key que realiza la operación (api-key:<uuid>). Dos keys distintas pueden usar la misma reference sin conflicto entre sí.

{
  "reference": "mi-sistema:orden-12345",
  "store_id": "...",
  "items": [ /* ... */ ]
}

Todos los IDs que envías en el body de este endpoint son IDs externos de tu sistema, mapeados en Smart Order mediante external_id.

Tienda

Producto

Además de autenticación y permisos, el servidor valida los datos de cada ítem antes de descontar. Todas estas devuelven 400.

Las respuestas de error son un array JSON. El campo param solo aparece en errores de validación de entrada (HTTP 400).

[
  {
    "message": "Descripción del error",
    "param": "nombre_campo"
  }
]

Tabla de códigos HTTP

Mensajes frecuentes de validación (400, con param)

[
  {
    "param": "store_id",
    "message": "store_id inválido"
  }
]

[
  {
    "message": "La tienda no está autorizada para esta API key"
  }
]

Seguridad

• Nunca expongas la API key en el frontend ni en repositorios públicos.
• Rota o desactiva keys comprometidas desde el dashboard.
• Usa HTTPS en producción.

Diseño de integración

1. 1

   Siempre envía reference con un identificador estable de tu operación.

2. 2

   Agrupa ítems en una sola petición cuando una venta u operación afecta varios productos (menos latencia, un solo documento de referencia).

3. 3

   Usa external_code para identificar productos de forma consistente con tu catálogo.

4. 4

   No asumas el warehouse_id: depende de la configuración de la key; solo controlas la tienda mediante store_id.

5. 5

   Mapea tiendas autorizadas en tu sistema con los external_id configurados en Smart Order y asociados a la key.

Manejo de errores y reintentos

Pruebas

1. 1

   Crear una API key OPERATIVE con módulo inventory_reduction y una tienda de prueba.

2. 2

   Probar reducción con reference fija dos veces → la segunda llamada debe devolver 200 sin cambiar stock adicional.

3. 3

   Probar tienda no autorizada → 403.

4. 4

   Probar cantidad mayor al stock → 400 con mensaje de stock disponible.

5. 5

   Probar petición sin reference → 400.

Sustituye {TENANT} por el slug de tu tenant (ej. mi-empresa), {API_KEY} por tu key operativa, y los IDs externos y códigos por valores reales de tu entorno.

Reducir por código externo

curl -X POST "https://api-demo-dev.smart-order.io/api/v1/managed/inventory/reduce-by-sku" \
  -H "X-Tenant: {TENANT}" \
  -H "X-Api-Key: {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "SUCURSAL-NORTE",
    "reference": "pos-ticket-10042",
    "items": [
      { "external_code": "BEB-001", "quantity": 2, "movement_type": "sale" },
      { "external_code": "SNK-010", "quantity": 1.5 }
    ]
  }'

Respuesta exitosa

{
  "ok": true
}

Ejemplo de error de validación · 400

[
  {
    "param": "store_id",
    "message": "store_id inválido"
  }
]

Ejemplo de error de permisos · 403

[
  {
    "message": "La tienda no está autorizada para esta API key"
  }
]