Skip to main content
Version: Latest

Sumar unidades al inventario

Ingresa unidades al inventario de una bodega. Pensado para recepciones de mercancía desde un sistema externo.

Request 🚀​

url​

https://app.aveonline.co/avestock/api/inventoryAddUnits.php

Method​

POST

Content-Type: application/json
Authorization: {data.token}

El data.token se obtiene en la Autenticación.

Params JSON​

  • tipo* String Enrutador de la API, "authave"
  • empresa* Number Identificador de la empresa dentro de AVEONLINE
  • idempotency_key* String Llave única de la operación. Máximo 120 caracteres
  • items* Array Referencias y cantidades a ingresar
  • items[].reference* String Referencia del producto
  • items[].quantity* Number Unidades a sumar. Debe ser mayor a 0
  • warehouse_id Number Bodega. Si se omite, se usa la bodega principal activa de la empresa
  • reason String Motivo del movimiento. Queda guardado en el detalle de la entrada

Ejemplo​

{
  "tipo": "authave",
  "empresa": 6077,
  "idempotency_key": "recepcion-2026-11-05-001",
  "warehouse_id": 1203,
  "reason": "Recepción de mercancía proveedor",
  "items": [
    { "reference": "REF-0001", "quantity": 50 },
    { "reference": "REF-0002", "quantity": 10 }
  ]
}
La llave de idempotencia es obligatoria

Si se pierde la respuesta por un corte de red o un tiempo de espera agotado, al reintentar con la misma llave el servicio devuelve el resultado original sin volver a sumar.

Sin esta llave, un reintento ingresaría las unidades dos veces, y esa diferencia solo aparecería semanas después en un conteo físico.

Reutilizar la misma llave con un contenido distinto devuelve 409.

Response 📄​

Success​

  • replayed Bool true cuando la respuesta corresponde a un reintento
  • warehouse_id Number Bodega sobre la que se aplicó
  • items[].before Number Saldo antes del movimiento
  • items[].after Number Saldo después del movimiento
  • items[].units Number Unidades movidas
  • items[].shopify Object Resultado de la sincronización de stock, si la cuenta la tiene activa

Ejemplo​

{
  "success": true,
  "messages": "Inventario actualizado",
  "status": 200,
  "data": {
    "idempotency_key": "recepcion-2026-11-05-001",
    "replayed": false,
    "warehouse_id": 1203,
    "shopify_sync": true,
    "items": [
      {
        "reference": "REF-0001",
        "product_id": 225321,
        "before": 120,
        "after": 170,
        "units": 50,
        "movement": "entrada",
        "shopify": { "ok": true, "action": "updated", "reason": "" }
      }
    ]
  }
}

Reintento con la misma llave​

{
  "success": true,
  "messages": "Reintento: el movimiento ya se habia aplicado.",
  "status": 200,
  "data": { "replayed": true }
}

Falta la llave de idempotencia​

{
  "success": false,
  "messages": "Errores de validacion",
  "status": 422,
  "errors": [
    {
      "attribute": "idempotency_key",
      "detail": "Es obligatoria: sin ella un reintento duplicaria las unidades."
    }
  ]
}

Una referencia no existe​

El lote no se aplica: ni siquiera los items correctos.

{
  "success": false,
  "messages": "El lote no se aplico: revise los errores.",
  "status": 409,
  "errors": [
    {
      "attribute": "items.1.reference",
      "detail": "No existe un producto con la referencia REF-0002."
    }
  ]
}

La bodega no es de la empresa​

{
  "success": false,
  "messages": "Bodega invalida",
  "status": 409,
  "errors": [
    { "attribute": "warehouse_id", "detail": "La bodega 999 no existe o no es de esta empresa." }
  ]
}

Notas Importantes 📝​

  1. El lote es todo o nada. Primero se valida completo y solo si todo pasa se aplica. Un lote aplicado a medias es peor que uno rechazado: no se sabe por dónde iba y al reintentar se duplica lo que ya entró.
  2. Se registran los movimientos tanto del saldo disponible como del saldo físico.
  3. Si la cuenta tiene activa la sincronización con Shopify, el stock se actualiza allá después de aplicar el movimiento. Si Shopify falla, el movimiento en AveCRM se mantiene y el detalle del error viaja en items[].shopify.