Generar pedido

Permite generar un pedido en AveCRM con validación automática de inventario, cálculo de envío y generación de guía. El sistema soporta dropshipping, fulfillment y múltiples formas de envío. Los productos deben estar previamente registrados. Si no se especifica el operador logístico, el sistema selecciona automáticamente el más económico.

Request 🚀

url

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

Method

POST

Header

Content-Type: application/json

Params JSON

Autenticación (requeridos)

• tipo* String Enrutador de la API: "authave"
• token* String Token recibido en la [Autenticación](./autenticacion) con vigencia de una hora
• empresa* Number Identificador de la empresa dentro de AVEONLINE

Identificación del Pedido

• numeropedidoExterno String Número de pedido asociado a tienda, POS, ERP, etc. Validado contra duplicados
• lucidsalesOrderId String ID de orden de LucidSales (si aplica)

Origen del Pedido

• bodegaName Number ID de la bodega desde donde se realiza el envío. Si no se envía, se selecciona automáticamente
• idAgente Number ID del canal de venta o agente. Si no se envía, el sistema resuelve bodega según reglas internas. [Listado de canales de ventas](./listadocanalesVentas)
• proveedorName Number ID del proveedor para pedidos de dropshipping

Productos - Opción 1: Array de items (payload preferido)

• items Array<Object> Lista de productos del pedido
  • productRef* String Código/referencia del producto
  • quantity* Number Cantidad del producto
  • rateValue Number Valor unitario. Si no se envía, se toma del sistema
  • ivaValue Number Valor del IVA unitario
  • peso Number Peso unitario (Kg). Si no se envía, se toma del sistema
  • vol Number Volumen unitario. Si no se envía, se toma del sistema
  • declarado Number Valor declarado unitario. Si no se envía, se toma del sistema
  • totalValue Number Valor total del ítem. Si no se envía, se calcula automáticamente
  • descuentoValue Number Valor de descuento del producto
  • descuento Float Porcentaje de descuento (ej: 10.50)
  • numerodescuento Number Descuento en valor absoluto

Productos - Opción 2: Arrays paralelos (para formularios / legacy)

• productName Array<String> Array de nombres/IDs de productos
• quantity Array<Number> Array de cantidades (debe coincidir con productName)
• rateValue Array<Number> Array de valores unitarios
• ivaValue Array<Number> Array de valores de IVA
• peso Array<Number> Array de pesos
• vol Array<Number> Array de volúmenes
• declarado Array<Number> Array de valores declarados

Recomendación: usa siempre items (array de objetos) cuando consumas la API en JSON. Es el formato preferido para integraciones backend/backend y evita desalineaciones entre arrays.

Usa arrays paralelos solo cuando tu origen de datos venga de formularios o estructuras legacy que ya entregan campos separados por columna.

Totales del Pedido (si no se envían, se calculan automáticamente)

• subTotalValue Number Subtotal antes de impuestos
• vatValue Number Total de impuestos
• totalAmountValue Number Total del pedido sin envío
• grandTotalValue Number Total general del pedido
• grandTotalPeso Number Peso total (Kg)
• grandTotalVol Number Volumen total
• grandTotalUnit Number Total de unidades
• grandTotalDeclarado Number Valor declarado total
• grandDescuentoValue Number Total de descuentos
• orderDiscount Number Descuento aplicado sobre todo el pedido antes del IVA

Datos del Cliente Destinatario

• clientDestino* String Ciudad de destino: 'CIUDAD(DEPARTAMENTO)' o código DANE de 5+ dígitos
• clientContact* String Nombre del destinatario
• clientId String Identificación del destinatario. Requerido cuando recaudo o recaudoValue es mayor a 0
• clientDir String Dirección del destinatario. Si está vacía, el pedido queda en novedad
• clientTel String Teléfono del destinatario
• clientEmail String Correo electrónico del destinatario
• clientName Number ID del cliente (uso interno)

Configuración del Envío

• seloperadorEnvio Number ID del operador logístico. Si es 0, se selecciona el más económico automáticamente
• valorEnvio Number Valor del envío (si ya fue cotizado previamente)
• valorEnvioValue Number Alias de valorEnvio
• cadenaEnvio String Datos adicionales del envío (JSON string)
• diasEntrega Number Días de entrega estimados

Configuración de Pago y Recaudo

• paymentCliente Number ¿Cliente paga el transporte? (1=SI, 2=NO)
• recaudo Number Valor a recaudar del pedido. Si es mayor a 0, pagado se marca como 2
• recaudoValue Number Alias de recaudo
• paymentAsumecosto Number ¿Cliente asume costo del recaudo? (1=SI, 2=NO)
• pagado Number Estado de pago: 1=Pagado desde canal de venta, 2=No pagado
• metodo_pago Number ID del método de pago utilizado
• plazo_pago Number Plazo de pago en días

Configuración del Proceso

• noGenerarEnvio Number 1=No genera guía automáticamente. Se debe generar después manualmente
• revisarCE String "1"=Pedido requiere confirmación (contraentrega). No genera guía hasta confirmar
• enviopropio Boolean Indica envío propio
• plugin String Identificador del método de acceso. Por defecto "aveonline"

Comportamiento validado del endpoint

• Si tipo = "authave", el endpoint entra en modo API y registra trazas en order_api_logs.
• El payload preferido para API es items como array de objetos.
• El formato de arrays paralelos (productName, quantity, etc.) se mantiene para formularios/legacy.
• Para recaudo > 0, pagado siempre se normaliza a no pagado en backend.
• Si existe numeropedidoExterno en proceso reciente (1 minuto), responde conflicto.
• Si numeropedidoExterno ya existe para la empresa (y agente cuando aplica), responde conflicto.
• Si la orden queda con novedad (dirección, ciudad, sin producto, sin stock), no genera guía automática.
• revisarCE = 1 fuerza que no se genere guía hasta confirmar.

Datos Adicionales

• obs String Observaciones del envío ("dice contener"). Si está vacío, se genera automáticamente con los productos
• observacion String Alias de obs
• notas String Notas internas del pedido
• nroFactura String Número de factura interna
• calificacion Array<Object> Calificaciones asociadas al pedido
• otros_items Array<Object> Items adicionales (ej: costos de empaque)

Configuración Avanzada

• debug Number 1=Modo debug (registra información adicional)
• noSocket Boolean true=No envía notificación por socket
• extra_data Object Datos extra como reputación IA
  • ia_dir_reputation Object Datos de reputación de dirección por IA

Ejemplos de Payload

Payload preferido (JSON con items)

{
  "tipo": "authave",
  "obs": null,
  "idAgente": 17154,
  "numeropedidoExterno": "#196551",
  "empresa": 25505,
  "items": [
    {
      "vol": null,
      "peso": null,
      "ivaValue": null,
      "quantity": 1,
      "declarado": null,
      "rateValue": 0,
      "productRef": "2550549248",
      "totalValue": null,
      "pordescuento": 0
    }
  ],
  "plugin": "aveonline",
  "recaudo": 0,
  "clientId": "71889000",
  "vatValue": null,
  "clientDir": "CR 47 # 35 SUR 20 El Portal",
  "clientTel": "573002001513",
  "revisarCE": 1,
  "bodegaName": null,
  "nroFactura": null,
  "valorEnvio": null,
  "cadenaEnvio": null,
  "clientEmail": "jsgil@lagilco.com",
  "recaudoValue": 0,
  "clientContact": "Juan Sebastian Gil",
  "clientDestino": "MEDELLIN(ANTIOQUIA)",
  "grandTotalVol": null,
  "subTotalValue": null,
  "grandTotalPeso": null,
  "grandTotalUnit": null,
  "noGenerarEnvio": 1,
  "paymentCliente": 2,
  "grandTotalValue": null,
  "valorEnvioValue": null,
  "seloperadorEnvio": null,
  "totalAmountValue": null,
  "paymentAsumecosto": 2,
  "grandTotalDeclarado": null,
  "grandTotalDeclaradoValue": null,
  "pagado": true
}

Payload alternativo (arrays paralelos para formularios)

{
  "empresa": 6077,
  "idAgente": 10961,
  "numeropedidoExterno": "TEST-GUIA-ATADA-177446041543",
  "productRef": [
    "2"
  ],
  "productName": [
    "2"
  ],
  "quantity": [
    "1"
  ],
  "rateValue": [
    "18000"
  ],
  "ivaValue": [
    "3420"
  ],
  "peso": [
    "1"
  ],
  "vol": [
    "0"
  ],
  "declarado": [
    "21420"
  ],
  "subTotalValue": 18000,
  "vatValue": 3420,
  "totalAmountValue": 21420,
  "grandTotalValue": 21420,
  "grandTotalPeso": 1,
  "grandTotalUnit": 1,
  "grandTotalDeclarado": 21420,
  "clientDestino": "BOGOTA(CUNDINAMARCA)",
  "clientContact": "Test Guia Atada",
  "clientId": "900000003",
  "clientDir": "Cra 10 # 10-10",
  "clientTel": "3001234570",
  "clientEmail": "test@test.com",
  "seloperadorEnvio": 33,
  "noGenerarEnvio": 0
}

Response 📄

Success

Datos Principales

• success Boolean true si el pedido se creó exitosamente
• order_id String Número consecutivo de la orden generada
• id Number ID único de la orden en la base de datos
• messages String Mensaje descriptivo del resultado

Información del Transporte

• valortransporte Number Valor estimado del transporte (puede cambiar al confirmar)
• diasEntrega Number Días de entrega estimados
• kilosenvios Number Peso (Kg) utilizado para calcular el costo de transporte
• operador String Nombre del operador logístico seleccionado. Vacío si enviopropio=true

Información de la Bodega

• bodegaContact String Nombre de la bodega
• bodegaId String NIT de la bodega
• bodegaTel String Teléfono de la bodega
• bodegaDir String Dirección de la bodega
• bodegaEmail String Email de la bodega
• bodega_usuario Number ID del usuario asociado a la bodega
• bodega_id Number ID de la bodega en el sistema
• bodegaOrigen String Ciudad origen de la bodega

Operadores Disponibles

• dataoperadores Array<Object> Lista de operadores cotizados (vacío si enviopropio=true)
  • status Number Estado de la cotización (1=exitoso)
  • message String Mensaje de la cotización
  • flete Number Valor del flete
  • variable Number Costo de manejo
  • comision Number Costo del recaudo
  • total Number Valor total del operador
  • campo Number ID del operador
  • transportadora String Nombre del operador
  • diasentrega Number Días de entrega
  • stringdata String Cadena con datos completos de la cotización

Estado del Pedido

• order_status Number ID del estado del pedido
• order_status_name String Nombre del estado del pedido
• log String Registro del log de estado creado

Novedades (si existen)

• novelties Array<Object> Lista de novedades detectadas
  • status Number ID del estado de novedad
  • message String Descripción de la novedad
  • priority Number Prioridad de la novedad
• novelties_count Number Cantidad de novedades detectadas
• all_novelty_logs Array<String> Logs de todas las novedades registradas

Generación de Guía

• guide Object Resultado del proceso de generación de guía (si aplica)
  • success Boolean true si la guía se generó exitosamente
  • Otros campos según el operador

Totales Calculados

• totalAmount Number Total del pedido calculado

Integraciones

• linea_estandar_message Object Resultado del envío de mensaje WhatsApp
  • status String success|error
  • message String Mensaje de resultado
  • result Object Respuesta completa del servicio (cuando aplica)

Ejemplo

{
  "success": true,
  "order_id": "0000000",
  "messages": "Pedido 0000000 Agregado exitosamente.",
  "valortransporte": 00000,
  "id": 116056,
  "diasEntrega": 3,
  "kilosenvios": 1,
  "operador": "DOMINA",
  "bodegaContact": "",
  "bodegaId": "",
  "bodegaTel": "",
  "bodegaDir": "",
  "bodegaEmail": "",
  "bodega_usuario": "",
  "bodega_id": "",
  "bodegaOrigen": "",
  "databodegas": [
    {
      "bodega_id": "0000",
      "bodega_nombre": "BODEGA PRUEBA",
       "dataoperadores": [
        {
          "status": 1,
          "message": "Datos recibidos",
          "flete": 10820,
          "variable": 0,
          "comision": 1946,
          "total": 12766,
          "campo": 1026,
          "transportadora": "DOMINA",
          "diasentrega": 3,
          "stringdata": "numbererror=-0-|dataerror=|codigotransportadora=1026|transportadora=Domina|logotransportadora={ruta}|logotransportadora2={ruta}|origen=BOGOTA(CUNDINAMARCA)|destino=CALI(VALLE DEL CAUCA)|unidades=1|kilosacobrar=1|pesovolumen=0|valoracion=44950|porvaloracion=0.5|trayecto=Nacional|codtrayecto=96|tipoenvio=Mensajeria|fletexkilo=10820|fletexund=10820|fletetotal=10820|diasentrega=3|flete=10820|costomanejo=0|valortotal=10820|valorotros=1946|grantotal=12766|codmostrartransportadora=1026|topemaximo=0|dscontraentrega=0|alto=0|largo=0|ancho=0",
          "bodegaId": "",
          "bodegaTel": "",
          "bodegaDir": "",
          "bodegaEmail": "",
          "bodega_usuario": "",
          "bodega_id": "",
          "bodegaOrigen": ""
        }
      ],
    }
  ],  
}

Si esta pendiente de confirmar el pedido o no se genera guia de envio

{
    "success": true,
    "order_id": "0000000",
    "messages": "Pedido 0000000 Agregado exitosamente. No se genera el envío. Lo puede hacer de manera posterior en la opción '<strong>Gestionar pedidos<\/strong> y\/o confirmando el proceso de pedido cuando el cliente asume el costo o se debe recaudar el valor.",
    "valortransporte": 00000,
    "id": 116056,
    "diasEntrega": 3,
    "operador": "DOMINA",
    "bodegaContact": "",
    "bodegaId": "",
    "bodegaTel": "",
    "bodegaDir": "",
    "bodegaEmail": "",
    "bodega_usuario": "",
    "bodega_id": "",
    "bodegaOrigen": "",
    "databodegas": [
        {
          "bodega_id": "0000",
          "bodega_nombre": "BODEGA PRUEBA",
          "dataoperadores": [
            {
                "status": 1,
                "message": "Datos recibidos",
                "flete": 10820,
                "variable": 0,
                "comision": 1946,
                "total": 12766,
                "campo": 1026,
                "transportadora": "DOMINA",
                "stringdata": "numbererror=-0-|dataerror=|codigotransportadora=1026|transportadora=Domina|logotransportadora={ruta}|logotransportadora2={ruta}|origen=BOGOTA(CUNDINAMARCA)|destino=CALI(VALLE DEL CAUCA)|unidades=1|kilosacobrar=1|pesovolumen=0|valoracion=44950|porvaloracion=0.5|trayecto=Nacional|codtrayecto=96|tipoenvio=Mensajeria|fletexkilo=10820|fletexund=10820|fletetotal=10820|diasentrega=3|flete=10820|costomanejo=0|valortotal=10820|valorotros=1946|grantotal=12766|codmostrartransportadora=1026|topemaximo=0|dscontraentrega=0|alto=0|largo=0|ancho=0",
                "bodegaContact": "",
                "bodegaId": "",
                "bodegaTel": "",
                "bodegaDir": "",
                "bodegaEmail": "",
                "bodega_usuario": "",
                "bodega_id": "",
                "bodegaOrigen": "",

            }
         ],
      }
    ],  
  
}

Errores de Validación

Método no permitido (405)

{
  "status": "error",
  "message": "Error de solicitud, el método no está permitido."
}

Producto no encontrado (400)

{
  "success": false,
  "order_id": "",
  "messages": "El producto referencia REF-123 no se encuentra en el inventario"
}

Sin inventario disponible (400)

{
  "success": false,
  "order_id": "",
  "messages": "El producto referencia REF-123 no posee unidades disponibles en el inventario."
}

Cantidad insuficiente en inventario (400)

{
  "success": false,
  "order_id": "",
  "messages": "El total de las unidades solicitadas no están disponibles en los inventarios"
}

Bodega no válida (404)

{
  "status": "error",
  "message": "La bodega con código 12345 no pertenece a la empresa."
}

Pedido en proceso (409)

{
  "status": "error",
  "message": "Pedido en proceso de creación con el número de pedido externo: TEST-123"
}

Pedido duplicado (409)

{
  "status": "error",
  "message": "Ya existe un pedido con el número de pedido externo: TEST-123"
}

Múltiples proveedores en items (400)

{
  "status": "error",
  "message": "Los productos no pertenecen al mismo proveedor."
}

Múltiples bodegas en items (400)

{
  "status": "error",
  "message": "Los productos no pertenecen a la misma bodega."
}

Arrays de productos no coinciden (400)

{
  "success": false,
  "order_id": "",
  "messages": "La cantidad de productos no coincide con las unidades especificadas."
}

Recaudo sin identificación (422)

{
  "status": "error",
  "message": "El número de identificación del cliente es requerido cuando hay recaudo."
}

Identificación inválida para recaudo (422)

{
  "status": "error",
  "message": "El número de identificación debe tener mínimo 5 dígitos."
}

Identificación iniciando en cero (422)

{
  "status": "error",
  "message": "El número de identificación no puede empezar con cero."
}

Error al registrar cliente (400)

{
  "status": "error",
  "message": "Error al registrar el cliente: [detalle del error]"
}

Error al crear pedido (400)

{
  "success": false,
  "messages": "Error al crear el pedido: [detalle del error SQL]"
}

Error al validar duplicados (400)

{
  "status": "error",
  "message": "Error en la validación de pedidos duplicados"
}

Error al registrar log (400)

{
  "status": "error",
  "message": "Error al registrar log del pedido"
}

Empresa inválida o ausente (400)

{
  "status": "error",
  "message": "El identificador de empresa es incorrecto o se ha producido un error inesperado."
}

Totales no válidos para crear pedido (422)

{
  "status": "error",
  "message": "No se puede generar el pedido porque no existe un valor total. Verifique la configuración de los pedidos."
}

Error después de creación (500)

{
  "status": "error",
  "message": "Error al crear la orden. Por favor, inténtelo nuevamente."
}

Notas Importantes 📝

• El campo order_consec se genera automáticamente: {empresa}{random(4)}{timestamp}
• Si recaudo > 0, el campo pagado se establece en 2 (no pagado)
• Si revisarCE = 1, no se genera guía hasta confirmar el pedido
• El sistema soporta duplicación intencional pero lo registra en logs
• Las ciudades deben enviarse en formato 'CIUDAD(DEPARTAMENTO)' o código DANE
• El peso mínimo es 1 Kg (se ajusta automáticamente)
• El payload preferido es items (array de objetos) y debe ser la primera opción en integraciones JSON
• Los arrays paralelos se mantienen para formularios y compatibilidad legacy
• pagado se interpreta en backend como entero: solo valor 1 se toma como pagado
• En la versión actual del endpoint, enviopropio no está afectando el flujo como se esperaría por una normalización interna
• Se valida inventario en tiempo real antes de crear el pedido
• Las novedades se registran todas, pero el estado final es el de mayor prioridad
• Si la ciudad o dirección tiene problema, normalmente se registra como novedad en order_status en lugar de devolver error inmediato
• La generación de guía es asíncrona para mejorar performance
• Se envía notificación WhatsApp automática si hay configuración de Línea Estándar
• El método HTTP debe ser POST, de lo contrario retorna error 405
• Todos los totales se redondean automáticamente
• Si hay múltiples novedades, se crean logs separados para cada una