Guía de uso de UltimaMilla

UltimaMilla es la plataforma de entregas de última milla en La Habana: las empresas cliente crean envíos, el operador los organiza y asigna, y los transportistas los recogen y entregan con camionetas (refrigeradas o no). Todo envío nace de una cotización con precio cerrado por zona, y el destinatario final puede seguir su pedido con un enlace público, sin registrarse.

Esta guía explica cada panel según tu rol. Si vas a integrar tu sistema por API, ve directo a la sección de integración o a la documentación interactiva.

🎛 Guía del Operador

El operador es quien dirige la operación diaria: recibe las órdenes de todas las empresas, decide qué transportista lleva cada una, vigila las entregas y gestiona tarifas, flota, locales y empresas. Tu página principal es el Dispatch.

Dispatch: asignar órdenes

  1. 1Las órdenes nuevas llegan en estado Confirmada (azul). Cada una muestra empresa, zona, precio y si requiere frío ❄️.
  2. 2El selector de cada fila trae un ⭐ recomendado con el motivo (p. ej. «va en el mismo viaje: misma recogida y misma zona»). Junto a cada nombre ves su situación: 🚚 en ruta (N) si ya está repartiendo — puedes asignarle igual, pero implica esperar su regreso.
  3. 3Pulsa Asignar. El transportista recibe la orden al instante en su panel y en Telegram.
  4. 4Para órdenes frías ❄️ el selector solo ofrece transportistas con vehículo refrigerado.

Rutas multi-entrega 🧭

  1. 1Cuando hay 2+ órdenes confirmadas aparecen casillas ☑ a la izquierda. Marca las que deban salir en el mismo viaje (típicamente misma recogida).
  2. 2Elige transportista en la barra verde y pulsa «Asignar como ruta». El sistema ordena las paradas automáticamente por cercanía (con el mapa real de La Habana).
  3. 3Cada orden muestra su badge 🧭 parada N — haz clic para ver la ruta en el mapa con la traza por carretera, km y minutos.
  4. 4Las rutas ahorran combustible: el regreso a base se reparte entre las órdenes del viaje (lo verás en Costes).

Seguimiento y problemas

En la ficha de cada orden tienes el timeline completo (quién hizo qué y cuándo), la prueba de entrega, el coste interno frente al precio, y el enlace público de seguimiento por si el cliente final lo pide. Desde ahí puedes desasignar (la orden vuelve al dispatch), cancelar (solo antes de la recogida) o marcarla fallida. En Flota ves la situación de cada transportista y su última posición GPS («📍 hace X min»).

Tarifas y combustible 💰

  1. 1En Tarifas gestionas dos tarifarios: base por zona (primera regla que casa, el orden importa) y suplementos (suman todos los que casan: refrigerado, peso, nocturno…).
  2. 2Para cambiar precios crea un tarifario nuevo con fecha de vigencia — clona las reglas del vigente y editas. El historial nunca se pierde: cada cotización usa el tarifario de su día.
  3. 3El precio del combustible también se versiona: añade el precio nuevo con su fecha; solo afecta al coste interno de cotizaciones futuras.
  4. 4En Costes ves el margen real por orden y por transportista, con el combustible de ida y regreso. Si la columna «coste a litro de hoy» sale en ámbar, tus tarifas se están quedando cortas.

Altas: flota, empresas y locales

En Flota creas vehículos (matrícula, consumo km/L, ❄️) y transportistas — con su email y contraseña de acceso. En Empresas das de alta una empresa cliente: se crea su usuario del panel y su primera API key (⚠️ se muestra una sola vez, cópiala en el momento). En Locales registras los puntos de consignación, marcando la ubicación exacta con un clic en el mapa.

🏪 Guía de la Empresa Cliente

Como empresa cliente creas envíos, sigues su estado, gestionas tus almacenes de recogida y conectas tu sistema por API. Entras con el usuario que te dio el operador.

Crear un envío

  1. 1Nueva orden → elige el punto de recogida: un local de consignación de la operadora (donde ya dejaste mercancía) o uno de tus almacenes.
  2. 2Escribe la dirección de entrega tal como se dice en Cuba: «Calle 23 e/ A y B, Vedado». El mapa se centra solo; si la dirección es nueva, marca el punto exacto con un clic (el pin rellena la dirección si el campo está vacío). Las direcciones ya usadas no piden pin.
  3. 3Indica contacto, peso, bultos y si necesita cadena de frío ❄️.
  4. 4Pulsa Cotizar: verás el precio con su desglose (tarifa de zona + suplementos), km y tiempo estimado. La cotización vale 15 minutos.
  5. 5Confirma añadiendo tu referencia (tu nº de venta), notas para el transportista y qué prueba de entrega exiges (firma, notas).
💡 En el detalle de cada orden tienes el «Enlace de seguimiento para tu cliente»: mándaselo por WhatsApp y podrá ver el progreso (Confirmado → Asignado → Recogido → En camino → Entregado) identificado con TU referencia de venta, sin necesidad de cuenta.

Tus almacenes

En Mis almacenes registras tus propios puntos de recogida (nombre, dirección y pin en el mapa). Quedan disponibles al instante en «Nueva orden». Puedes desactivarlos cuando quieras.

Integraciones

En Integraciones creas y revocas API keys (la clave completa solo se muestra al crearla) y configuras webhooks para recibir los cambios de estado en tu sistema, con su registro de entregas. Detalles técnicos en la sección de API.

🚚 Guía del Transportista

Tienes dos formas de trabajar, y puedes combinarlas: el panel web desde el navegador del móvil, o el bot de Telegram — recomendado en el día a día porque gasta muchos menos datos.

Conectar Telegram (una sola vez)

  1. 1Entra al panel web → pestaña Telegram → «Conectar Telegram».
  2. 2Se abre el chat del bot: pulsa Iniciar. Verás «✅ Telegram conectado».
  3. 3Desde entonces, cada orden o ruta que te asignen te llega al chat al momento.

El día a día por Telegram

  1. 1Te llega «🚚 Nueva orden asignada» (o «🧭 Nueva entrega en tu ruta — parada 2 de 3», con enlace al mapa del recorrido).
  2. 2Gestiona todo con los botones: Aceptar → 📍 Llegué a la recogida → 📦 Recogido → 📍 Llegué a la entrega → ✅ Entregado. Si no puedes entregar, «⚠️ No pude entregar».
  3. 3Si la orden exige prueba de entrega, el bot te la pide al marcar Entregado: escribe el nombre de quien recibe y/o envía una foto.
  4. 4Comando útil: /ordenes lista tus entregas activas. Enviar tu ubicación 📎→Ubicación la registra para el dispatch.

El panel web

En Hoy ves tus entregas: las rutas aparecen agrupadas con su mapa de paradas en orden y el botón «Aceptar ruta completa». Cada parada tiene botones grandes (Llegué / Recogido / Entregado) y el formulario de firma cuando se exige. En Historial tienes tus entregas terminadas con contadores de entregas y km de hoy, la semana y el total.

💡 Sigue siempre el orden de paradas de la ruta — está calculado sobre el mapa real para minimizar el recorrido. Acepta la ruta antes de salir y marca cada paso en el momento: el historial de tiempos te protege ante cualquier reclamación.

🔌 Guía de Integración por API

Para conectar tu tienda, ERP o e-commerce. Referencia completa e interactiva en /docs (puedes probar las llamadas desde el propio navegador).

Autenticación y límites

Todas las llamadas llevan Authorization: Bearer lm_live_…. La key identifica tu empresa: solo ves tus datos. Límite: 120 peticiones/minuto por key (al superarlo, 429 con Retry-After).

El flujo en 3 llamadas

# 1. Cotizar (la cotización vale 15 minutos)
curl -X POST $BASE/api/v1/quotes \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "pickup":  { "facility_id": "…" },
    "dropoff": { "address": { "text": "Calle 23 e/ A y B, Vedado" } },
    "weight_kg": 5
  }'
# → { "quote_id": "…", "price": { "amount": "6.50" }, "breakdown": [...], "expires_at": "…" }

# 2. Confirmar la orden (idempotente con tu propia clave)
curl -X POST $BASE/api/v1/orders \
  -H "Authorization: Bearer $API_KEY" -H "Idempotency-Key: venta-4471" \
  -d '{ "quote_id": "…", "external_ref": "PED-4471", "requirements": { "signature": true } }'
# → { "order_number": "HAB-2026-000123", "status": "confirmed", "tracking_url": "/t/…" }

# 3. Recibir estados por webhook (recomendado) o consultar
curl $BASE/api/v1/orders/{id} -H "Authorization: Bearer $API_KEY"

Webhooks: recibe los estados en tu sistema

  1. 1Crea la suscripción (POST /webhooks o desde el panel). Guarda el secret: solo se muestra una vez.
  2. 2Cada envío llega firmado: cabecera X-Ultimamilla-Signature: t=<unix>,v1=<hmac> donde v1 = HMAC_SHA256(secret, t + "." + body). Verifica la firma y descarta si t difiere más de 5 minutos.
  3. 3La entrega es at-least-once con reintentos (1m→5m→30m→2h→12h): deduplica por event_id y responde 2xx rápido.
  4. 4Valida tu endpoint con POST /webhooks/{id}/test (evento ping firmado).
💡 ¿Tu sistema ya captura coordenadas con su propio mapa? Puedes cotizar enviando solo lat/lng, sin texto: la plataforma resuelve sola un nombre legible para el transportista. Enviar texto y coordenadas juntos sigue siendo lo más preciso.

Errores que debes manejar