NUEVO 🚀 API v2 - Guía para ajustes de inventario (consumo y recepción)

1. Requisitos antes de empezar

• Scope inventory:write para registrar recepciones y consumos, e inventory:read para consultarlos.

• El header Idempotency-Key es obligatorio en ambos endpoints. Si no lo envías, la API responde 422 con idempotency_key_missing.
• Genera un UUID nuevo por cada movimiento real. Reutiliza la misma clave solo al reintentar ese mismo movimiento. Así evitas registrar stock duplicado.
  
  

Para esto existen dos endpoints separados:

2. Ajuste de entrada

POST /api/v2/inventario/recepcion

Body de ejemplo:

json

{ "ware_house_id": 3, "document": "Ajuste de entrada API", "note": "Ingreso manual por regularización", "items": [ { "product_id": 15, "quantity": 10, "unit_cost": 990 } ] }

Campos principales:

• ware_house_id: bodega donde se aplicará el movimiento.
• items[]: lista de productos a ajustar.
  • product_id: ID del producto.
  • quantity: cantidad a ingresar.
  • unit_cost: costo unitario, opcional pero recomendado en recepciones.
  • document y note: referencia y comentario del ajuste (opcionales).
  • provider_id: proveedor asociado a la recepción (opcional).
  • Por cada ítem, también puedes enviar de forma opcional: location (ubicación dentro de la bodega), lot_serial_number (lote o número de serie) y expiration_date (fecha de vencimiento).
    
    

3. Ajuste de salida

POST /api/v2/inventario/consumo

Body de ejemplo:

json

{  "ware_house_id": 3,  "document": "Ajuste de salida API",  "note": "Salida manual por regularización",  "items": [  {  "product_id": 15,  "quantity": 4  }  ] }

Campos principales:

• ware_house_id: bodega desde donde se descuenta stock.
• items[]: lista de productos a consumir.
  • product_id: ID del producto.
  • quantity: cantidad a descontar.
  • document y note: referencia y comentario del ajuste (opcionales).
  • Por cada ítem, también puedes enviar de forma opcional: location (ubicación dentro de la bodega), lot_serial_number (lote o número de serie) y expiration_date (fecha de vencimiento).
    
    

4. Sincronización con integraciones e-commerce

Si quieres que el ajuste se refleje en tus integraciones nativas (MercadoLibre, Shopify, etc.), envía "sync_integrations": true en el body de la recepción o del consumo.

Esto requiere tener contratado el addon “Sincronización de integraciones vía API”. Sin el addon, el ajuste se registra igual en relBase pero no se propaga a tus canales, y la respuesta indica el motivo en sync_integrations.reason.

5. Respuesta de la API

Si el ajuste se registra correctamente, la API responde así:

json

{   "data": {     "ajuste": { "id": 120, "type_stock": "in" },     "sync_integrations": { "requested": false, "applied": false }   },   "meta": { "code": 201, "message": "success" } }

En un consumo, type_stock será "out". El bloque sync_integrations indica si solicitaste la sincronización (requested) y si efectivamente se aplicó (applied).

Errores frecuentes

• 422 idempotency_key_missing: no enviaste el header Idempotency-Key.
• 422 con mensaje en meta.message: error de validación, por ejemplo un producto o una bodega inválidos, o stock insuficiente al registrar un consumo.

6. Recomendaciones

• Envía un Idempotency-Key único por cada movimiento, idealmente un UUID, y reutilízalo solo al reintentar ese mismo movimiento.
• Si necesitas hacer una transferencia interna completa entre bodegas, debes ejecutar dos movimientos: una recepción y un consumo.
• Para consultar los ajustes ya creados, usa GET /api/v2/inventario/ajustes con scope inventory:read. Puedes filtrar por tipo con status_query (0 recepciones, 1 consumos, all todos) y por fecha con range_date (formato 01-01-2026 / 31-01-2026).
• Para verificar el stock resultante, usa GET /api/v2/inventario/stock-actual.