🚀 Zeus Colecta API

Sistema integral de gestión de colectas y entregas para Home Delivery. Integra webhooks en tiempo real, tracking de visitas y más.

⚡ Inicio Rápido

Las dos opciones más usadas de Zeus Colecta API:

🔔 ¿Qué son Webhooks?

Los webhooks son notificaciones HTTP en tiempo real que enviamos a tu servidor cuando algo importante sucede en Zeus Colecta.

Polling vs Webhooks

Ejemplo de Webhook

Cuando una visita se marca como completada, recibis este JSON:

{
  "event": "visita_estado_cambio",
  "timestamp": "2026-06-01T14:30:45.123456",
  "data": {
    "visita_id": 12345,
    "tracking_id": "REF-001-2026",
    "estado_anterior": "pendiente",
    "estado_nuevo": "completada",
    "conductor": {
      "id": 5,
      "nombre": "Juan Pérez García"
    },
    "contacto": {
      "nombre": "María García López",
      "telefono": "+51 987 654 321"
    },
    "ubicacion": {
      "latitud": "-12.0456",
      "longitud": "-77.0456"
    }
  }
}

💻 Implementación (Python)

Aquí está el código mínimo para comenzar:

from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_TOKEN = "tu_token_aqui"

@app.route('/webhooks/estado-cambios', methods=['POST'])
def handle_webhook():
    # Validar token
    token = request.headers.get('Authorization', '').replace('Bearer ', '')
    if token != WEBHOOK_TOKEN:
        return jsonify({"error": "No autorizado"}), 401

    # Procesar webhook
    data = request.get_json()
    visita = data['data']

    if visita['estado_nuevo'] == 'completada':
        print(f"✅ Visita {visita['visita_id']} completada")
        # Tu lógica aquí...

    elif visita['estado_nuevo'] == 'falso_flete':
        print(f"❌ Falso flete: {visita['visita_id']}")
        # Tu lógica aquí...

    # Responder con éxito
    return jsonify({"status": "ok"}), 200

if __name__ == '__main__':
    app.run(port=5000)

Ver ejemplos en Node.js, PHP, Go →

✨ Características Principales

🔔 Sistema de Webhooks

• ✅ Notificaciones en tiempo real
• ✅ Autenticación con Bearer token JWT
• ✅ Reintentos automáticos (hasta 3 intentos)
• ✅ Información completa de cada visita
• ✅ Logging y auditoría completa
• ✅ Ejemplos en múltiples lenguajes

📊 Datos Incluidos

Cada webhook trae información completa:

• Identificadores: visita_id, tracking_id
• Estados: anterior y nuevo
• Operacional: conductor, ruta, fecha
• Contacto: nombre, teléfono, email
• Ubicación: coordenadas GPS
• Evidencia: URLs de fotos

🔒 Seguridad

• ✅ HTTPS obligatorio
• ✅ Bearer token en header
• ✅ Validación de payload
• ✅ Logging de intentos

🧪 Testing

Antes de ir a producción, prueba tu implementación:

Opción 1: Webhook.site (Recomendado)

1. Ve a https://webhook.site
2. Obtén tu URL pública única
3. Comunícanos la URL para testing
4. Verifica que recibes webhooks en tiempo real

Opción 2: ngrok (Servidor Local)

ngrok http 5000
# Obtendrás: https://abc123.ngrok.io/webhooks/estado-cambios

Opción 3: Script de Testing

Ver script de testing →

📞 Soporte & Contacto

Nuestro equipo técnico está disponible para ayudarte:

✅ Checklist de Implementación

• Endpoint HTTPS configurado
• Token validado en header Authorization
• Payload JSON parseado correctamente
• Respuesta HTTP 200-204 enviada
• Datos guardados en base de datos
• Idempotencia implementada (visita_id + timestamp)
• Logs configurados para auditoría
• Probado en ambiente de desarrollo
• URL comunicada a nuestro equipo técnico