Confirmar recibo de devolución

Registra que la mercancía de una guía en devolución volvió a la bodega, y la reingresa al inventario.

Request 🚀

url

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

Method

POST

Header

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
• guide_number* String Número de la guía. Admite con o sin ceros a la izquierda
• items Array Qué volvió. Si se omite, se asume la devolución completa del pedido
• items[].reference* String Referencia del producto
• items[].quantity* Number Unidades que volvieron
• warehouse_id Number Bodega de ingreso. Si se omite, la bodega del pedido
• observation String Observación. Queda en el detalle de la entrada
• force Bool Confirma la advertencia de que la guía no está en devolución. Por defecto false
• force_duplicate Bool Confirma la advertencia de que esa guía ya ingresó ese producto. Por defecto false

Ejemplo

{
  "tipo": "authave",
  "empresa": 6077,
  "idempotency_key": "devolucion-4410",
  "guide_number": "240064570238",
  "observation": "Caja completa, sin daños",
  "items": [
    { "reference": "REF-0001", "quantity": 2 }
  ]
}

Devolución parcial

Si de una guía con 5 unidades solo regresaron 2, se envían 2. El servicio registra exactamente lo que se le indica.

Ingresar la guía completa cuando solo volvió parte de la mercancía deja inventario que no existe en el estante, y esa diferencia aparece después en el conteo físico.

Response 📄

Success

• replayed Bool true cuando la respuesta corresponde a un reintento
• order_id String Pedido al que pertenece la guía
• full_return Bool true si se asumió la devolución completa
• description String Texto con el que quedó registrada la entrada
• items[].before / after / units Number Saldos y unidades ingresadas

Ejemplo

{
  "success": true,
  "messages": "Devolucion registrada",
  "status": 200,
  "data": {
    "idempotency_key": "devolucion-4410",
    "replayed": false,
    "guide_number": "240064570238",
    "order_id": "43129108328094224",
    "warehouse_id": 1203,
    "full_return": false,
    "forced": false,
    "description": "DEV 240064570238 - Caja completa, sin daños",
    "shopify_sync": true,
    "items": [
      {
        "reference": "REF-0001",
        "product_id": 225321,
        "before": 118,
        "after": 120,
        "units": 2,
        "movement": "entrada"
      }
    ]
  }
}

La guía no existe o no es de la empresa

{
  "success": false,
  "messages": "La guia 240064570238 no existe o no pertenece a esta empresa.",
  "status": 404
}

Las dos advertencias

Hay dos 409 que no son rechazos definitivos: traen requires_confirmation en true y una persona puede aceptarlos. Cada uno tiene su propio permiso, y la respuesta dice cuál en confirm_with.

No comparten bandera a propósito. La primera advertencia salta casi siempre, porque la transportadora actualiza el estado tarde y la bodega sabe antes que el sistema que la caja volvió; si el mismo permiso cubriera las dos, quien acepta la de rutina estaría aceptando de paso la única que protege el inventario.

Advertencia	Permiso para continuar
La guía no está en devolución	"force": true
Esa guía ya ingresó ese producto	"force_duplicate": true

La guía no está en devolución

{
  "success": false,
  "messages": "La guia 240064570238 no figura en devolucion (estado actual: Solicitada). ¿Confirma que la mercancia volvio a la bodega?",
  "status": 409,
  "data": {
    "guide_number": "240064570238",
    "requires_confirmation": true,
    "confirm_with": "force"
  }
}

Esa guía ya ingresó ese producto

Esta es la que evita contar la mercancía dos veces. Antes de aceptarla hay que mirar quién registró la entrada anterior y cuándo: el mensaje lo dice.

{
  "success": false,
  "messages": "Esta guia ya tiene entradas por devolucion de alguno de estos productos. Si aun asi la mercancia volvio otra vez, reenvie con force_duplicate.",
  "status": 409,
  "data": {
    "guide_number": "240064570238",
    "requires_confirmation": true,
    "confirm_with": "force_duplicate",
    "duplicates": [
      {
        "reference": "REF-0001",
        "message": "La guia 240064570238 ya tiene una entrada por devolucion de este producto: 2 unidad(es) el 2026-11-04 por Juan Perez. Si continua, la mercancia quedara contada dos veces. ¿Desea continuar?"
      }
    ]
  }
}

Notas Importantes 📝

1. La guía admite ceros a la izquierda o no. 034059439873 y 34059439873 resuelven a la misma guía.
2. La entrada se registra con el formato DEV <guía> - <observación>, que es el que leen el panel de devoluciones pendientes y los informes de AveCRM. No se debe construir ese texto por fuera.
3. El control de duplicados busca por la guía, no por el pedido. Así detecta también las devoluciones que se hayan registrado manualmente desde la pantalla.
4. Se registran los movimientos tanto del saldo disponible como del saldo físico.
5. Las dos banderas son independientes. force no abre la puerta del duplicado ni al revés. Si el caso necesita las dos, se mandan las dos — pero esa combinación debería ser rarísima, y conviene que la autorice una persona mirando el mensaje, no un proceso automático.