Avanzar estado de guía

Mueve el estado de una guía real al siguiente paso del flujo de entrega. El polling de la empresa integradora detecta el cambio en su siguiente ciclo sin ningún cambio adicional.

Solo empresas sandbox

Este endpoint únicamente acepta guías pertenecientes a las empresas de prueba 6077 y 25505. Cualquier otro id recibe un error 403.

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, "avanzarEstado"
• token* String Token recibido en la Autenticación con vigencia de una hora
• id* Number Identificador de la empresa sandbox (6077 o 25505)
• guia* String Número de guía real perteneciente a la empresa sandbox
• estado String Opcional — fuerza un estado específico. Si se omite, avanza al siguiente en el flujo
• descripcion String Opcional — descripción del evento. Si se omite se usa un texto por defecto
• aclaracion String Opcional — aclaración adicional sobre el estado

Cuándo usar el parámetro estado

Omitir estado avanza automáticamente al siguiente paso del flujo lineal.
Enviarlo es útil para forzar EN NOVEDAD o ENTREGADA directamente desde cualquier estado.

Ejemplo — avance automático

{
  "tipo": "avanzarEstado",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "id": 25505,
  "guia": "212342474354"
}

Ejemplo — forzar EN NOVEDAD

{
  "tipo": "avanzarEstado",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "id": 25505,
  "guia": "212342474354",
  "estado": "EN NOVEDAD",
  "descripcion": "Dirección incorrecta – no se pudo realizar la entrega",
  "aclaracion": "El destinatario no se encontraba en la dirección indicada"
}

Ejemplo — forzar ENTREGADA

{
  "tipo": "avanzarEstado",
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "id": 25505,
  "guia": "212342474354",
  "estado": "ENTREGADA",
  "descripcion": "Entregado a: JUAN PEREZ – C.C 12345678",
  "aclaracion": "Recibido conforme"
}

---

Flujo de estados

Cada llamada sin estado avanza un paso:

Llamada	Estado anterior	Estado nuevo
1ª	(sin estado)	GENERADA
2ª	GENERADA	PRODUCIDA
3ª	PRODUCIDA	EN DESPACHO
4ª	EN DESPACHO	EN REPARTO
5ª	EN REPARTO	ENTREGADA

ENTREGADA y ANULADA son estados terminales. No se puede avanzar desde ellos.

---

Response 📄

Success

• status String "ok"
• message String "Estado avanzado correctamente"
• sandbox Boolean true
• guia String Número de guía procesada
• idempresa Number Empresa sandbox
• estado_anterior String Estado antes del cambio
• estado_nuevo String Estado después del cambio
• siguiente_paso String Próximo estado disponible o "ninguno (estado terminal)"
• id_historial Number ID del registro de historial generado
• fecha String Fecha y hora del cambio
• nota String Recordatorio de que el polling ya detectará el cambio

Ejemplo

{
  "status": "ok",
  "message": "Estado avanzado correctamente",
  "sandbox": true,
  "guia": "212342474354",
  "idempresa": 25505,
  "estado_anterior": "EN DESPACHO",
  "estado_nuevo": "EN REPARTO",
  "siguiente_paso": "ENTREGADA",
  "id_historial": 98765,
  "fecha": "2026-05-26 14:30:00",
  "nota": "El polling con obtenerEstadoAuth en producción ya detectará este cambio."
}

---

Errores

Empresa no autorizada

{
  "status": "error",
  "message": "avanzarEstado solo está habilitado para las empresas sandbox (6077, 25505)"
}

HTTP 403

Guía no encontrada o no pertenece a la empresa

{
  "status": "error",
  "message": "La guía 212342474354 no existe o no pertenece a la empresa 25505"
}

HTTP 404

Estado terminal — no se puede avanzar

{
  "status": "error",
  "message": "La guía ya está en estado terminal: ENTREGADA. No se puede avanzar.",
  "estado_actual": "ENTREGADA"
}

HTTP 409

Estado forzado no válido

{
  "status": "error",
  "message": "Estado 'INVALIDO' no válido. Opciones: GENERADA, PRODUCIDA, EN DESPACHO, EN REPARTO, ENTREGADA, EN NOVEDAD"
}

HTTP 400

Token inválido o expirado

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

HTTP 401

---

¿Cómo lo detecta el polling?

avanzarEstado actualiza el estado de la guía en el sistema de forma inmediata. El endpoint de producción obtenerEstadoAuth refleja ese cambio, por lo que el polling de la empresa integradora lo detecta en el siguiente ciclo sin ningún cambio en su implementación.