Consultar estados de ejemplo

Retorna un ejemplo de cada estado posible que puede tener una guía. Los datos son de ejemplo, no corresponden a guías reales. Útil para que la empresa integradora comprenda la estructura de la respuesta antes de conectar su polling.

info

La autenticación es real: el token e id deben ser válidos. Solo los datos de las guías son de ejemplo.

Request 🚀

url

https://aveonline.co/api/nal/v1.0/sandbox/guia.php

Method

POST

Header

Content-Type: application/json

Params JSON

• tipo* String Enrutador de la API, "obtenerEstadoAuth"
• token* String Token recibido en la Autenticación con vigencia de una hora
• id* Number Identificador del usuario dentro de AVEONLINE, se obtiene en la Autenticación
• guia String Número de guía (referencia de contexto, no filtra datos)
• ordencompra String Orden de compra (referencia de contexto, no filtra datos)
• referencia String Referencia del cliente (referencia de contexto, no filtra datos)

Ejemplo

{
  "tipo": "obtenerEstadoAuth",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "id": 25505,
  "guia": "212342474354",
  "ordencompra": "",
  "referencia": ""
}

---

Response 📄

Success

• status String "ok"
• message String "registros encontrados"
• sandbox Boolean true — indica que es una respuesta de ejemplo
• parametros Object Parámetros recibidos en el request
  • guia String
  • ordencompra String
  • referencia String
• guias Array Object -> [{}] Un registro por cada estado posible
  • pkid Number Identificador interno
  • idtransportadora Number Identificador de la transportadora
  • dsconsec String Número de guía de ejemplo (prefijo SBX-)
  • destinatario String Nombre del destinatario
  • telefono String Teléfono del destinatario
  • direccion String Dirección del destinatario
  • estado String Estado actual de la guía
  • rutadigitalizada String URL de la guía en la transportadora
  • origen String Ciudad de origen
  • destino String Ciudad de destino
  • dsreferencia String Referencia del cliente
  • dsordencompra String Orden de compra
  • idagente Number Identificador del agente
  • idempresa Number Identificador de la empresa
  • idcliente Number Identificador del cliente
  • dsfechaentrega String Fecha de entrega (aplica en estado ENTREGADA)
  • dsfecha String Fecha de creación de la guía
  • dsflete Number Costo del flete
  • manejo Number Costo por manejo
  • contraentrega Number Valor de contraentrega
  • dscostorecaudo Number Costo por recaudo
  • totalflete Number Costo total
  • transportadora String Nombre de la transportadora
  • agente String Nombre del agente
  • totalUnidades Number Total de unidades
  • totalkilos Number Kilogramos
  • kilosvol Number Kilogramos volumétricos
  • nombreRemitente String Nombre del remitente
  • direccionRemitente String Dirección del remitente
  • diceContener String Contenido declarado
  • numfacturacliente String Número de factura del cliente
  • factura_ave_tn String Factura AVE transporte nacional
  • factura_ave_tn_fecha String Fecha de la factura
  • recibo_caja String Número de recibo de caja
  • recibo_caja_fecha String Fecha del recibo de caja
  • numero_reembolso String Número de nota crédito (reembolso)
  • historicos Array Object -> [{}] Historial de estados en orden descendente
    • id Number Identificador del registro de historial
    • estado String Nombre del estado
    • fechamostrar String Fecha del estado
    • descripcion String Descripción del evento
    • aclaracion String Aclaración adicional
    • novedad Number Identificador de novedad (0 si no aplica)
  • rutave String URL de seguimiento en AVE
  • tipo String Tipo de guía (Transporte / Contraentrega / Recaudo)
  • rotulo String URL de impresión del rótulo
  • ruta guia String URL del PDF de la guía
  • ruta sticker String URL del sticker

Ejemplo

{
  "status": "ok",
  "message": "registros encontrados",
  "sandbox": true,
  "parametros": {
    "guia": "212342474354",
    "ordencompra": "",
    "referencia": ""
  },
  "guias": [
    {
      "pkid": 901001,
      "idtransportadora": 33,
      "dsconsec": "SBX-GEN-001",
      "destinatario": "CLIENTE EJEMPLO SANDBOX",
      "telefono": "3001234567",
      "direccion": "CRA 10 # 20-30 APTO 501",
      "estado": "GENERADA",
      "origen": "BOGOTA",
      "destino": "MEDELLIN",
      "dsfecha": "2026-05-21",
      "dsflete": 15000,
      "manejo": 1000,
      "totalflete": 16000,
      "transportadora": "SERVIENTREGA",
      "historicos": [
        {
          "id": 1001,
          "estado": "GENERADA",
          "fechamostrar": "2026-05-21 08:00:00",
          "descripcion": "Guía generada en el sistema",
          "aclaracion": "",
          "novedad": 0
        }
      ],
      "tipo": "Transporte"
    },
    {
      "pkid": 901005,
      "dsconsec": "SBX-ENT-005",
      "estado": "ENTREGADA",
      "dsfechaentrega": "2026-05-25",
      "factura_ave_tn": "FE 98765",
      "historicos": [
        {
          "id": 1005,
          "estado": "ENTREGADA",
          "fechamostrar": "2026-05-25 14:30:00",
          "descripcion": "Entregado a: JUAN PEREZ – C.C 12345678",
          "aclaracion": "Recibido conforme",
          "novedad": 0
        },
        {
          "id": 1004,
          "estado": "EN REPARTO",
          "fechamostrar": "2026-05-24 09:00:00",
          "descripcion": "Mensajero en camino al destinatario",
          "aclaracion": "",
          "novedad": 0
        }
      ]
    },
    {
      "pkid": 901006,
      "dsconsec": "SBX-NOV-006",
      "estado": "EN NOVEDAD",
      "historicos": [
        {
          "id": 1010,
          "estado": "EN NOVEDAD",
          "fechamostrar": "2026-05-25 11:00:00",
          "descripcion": "Dirección incorrecta – no se pudo realizar la entrega",
          "aclaracion": "El destinatario no se encontraba. Se realizará nuevo intento.",
          "novedad": 5
        }
      ]
    }
  ]
}

note

La respuesta incluye 7 guías, una por cada estado posible: GENERADA, PRODUCIDA, EN DESPACHO, EN REPARTO, ENTREGADA, EN NOVEDAD y ANULADA.

---

Error

Token inválido o expirado

{
  "status": "error",
  "message": "autenticacion fallida"
}

Tipo de operación incorrecto

{
  "status": "error",
  "message": "Tipo no soportado. Use: obtenerEstadoAuth | avanzarEstado"
}