Cómo construir tu propio Uber Eats con la API de Hawky

Este es un recorrido rápido para levantar una app de delivery tipo Uber Eats encima de Hawky en un fin de semana.

Qué te da Hawky gratis

• Dispositivos + conductores: tu courier con su teléfono o un rastreador GPS. Hawky ya maneja posición en tiempo real, velocidad, estado y alertas.
• Tareas (/tasks): representan una entrega individual. Incluyen dirección de entrega, cliente, asignación y estado.
• Geocercas: zonas de recogida (restaurantes) y zonas de entrega (barrios / edificios).
• Share links: URLs públicas para que el cliente siga el pedido sin registrarse.
• Webhooks: entrada/salida de geocerca, SOS, apagado dispara notificaciones automáticas a tu backend.

El flujo mínimo viable

1. Cliente hace un pedido en tu app
   → hawky_add_task { address, lat, lng, customer_name, customer_phone }

2. Auto-asignación (tu algoritmo)
   → hawky_get_drivers online + hawky_get_devices_latest
   → calcular distancia al punto de recogida
   → hawky_assign_task al más cercano

3. Conductor acepta
   → hawky_update_task_status status="on_the_way"
   → hawky_create_share { device_id, expire_at: +2h }
   → SMS con el link al cliente

4. Llega a la entrega (geocerca dispara evento)
   → hawky_update_task_status status="arrived"
   → push al cliente

5. Entrega confirmada
   → hawky_update_task_status status="delivered" + nota con URL de foto

ETA, proof-of-delivery y anti-fraude

El ETA lo calculas tú: distancia al drop-off dividida entre la velocidad promedio del conductor (lo sacas de hawky_get_device_history de los últimos 7 días). Para proof-of-delivery, Hawky guarda metadatos pero las fotos/firmas las subes a tu propio bucket S3/R2 y pones la URL en la nota de la tarea.

Tres reglas anti-fraude que deberías siempre tener:

1. Si el punto donde se marca "entregado" está a > 50 m de lat,lng del pedido, pedir override del supervisor.
2. Si el estado es delivered pero la velocidad del dispositivo es != 0 por 60 segundos, marcar como sospechoso.
3. Pedidos fuera del horario operativo se auto-cancelan.

Costos reales

El plan Personal cuesta $90 MXN/mes por unidad (el conductor trae su dispositivo o usa el teléfono). 100 couriers ≈ $9,000 MXN/mes. Agrega tu propia data móvil si el dispositivo no es un smartphone.

Qué NO necesitas construir

• Broadcast de posición en tiempo real (ya está)
• Evaluación de geocercas (edge-evaluated cada ping)
• Alertas SOS / apagón / manejo agresivo (incluidas)
• Reconstrucción histórica de rutas (hawky_get_device_history)

Arquitectura de referencia

Así se conectan las piezas para un MVP de 100-200 pedidos/día:

┌───────────────┐      POST /api/tasks       ┌───────────────┐
│ App del       │ ─────────────────────────▶ │  Hawky API    │
│ cliente       │                            │ (GPS + tareas)│
└──────┬────────┘ ◀──── share URL ────────── └──────┬────────┘
       │                                             │ webhook
       ▼                                             ▼
┌───────────────┐   geofence_in / delivered   ┌───────────────┐
│ Backend tuyo  │ ◀────────────────────────── │   Webhook     │
│ (Node/Python) │                             │  (firmado)    │
└───────────────┘                             └───────────────┘

Tu backend es muy fino: recibe pedidos del cliente, los convierte en tareas Hawky, y escucha webhooks de eventos para actualizar el estado en tu DB.

Código real — auto-asignación de conductor más cercano

// Node.js con fetch nativo
async function assignNearestCourier(taskId, pickupLat, pickupLng) {
  const drivers = await hawky.get("/get_drivers", { status: "online" });
  const devices = await hawky.get("/get_devices_latest");
  const deviceById = Object.fromEntries(devices.items.map(d => [d.id, d]));

  const ranked = drivers
    .filter(d => d.device_id && deviceById[d.device_id])
    .map(d => {
      const dev = deviceById[d.device_id];
      const dist = haversine(pickupLat, pickupLng, dev.lat, dev.lng);
      return { driver: d, distance_m: dist };
    })
    .sort((a, b) => a.distance_m - b.distance_m);

  const winner = ranked.find(r => r.distance_m < 3000); // 3 km cap
  if (!winner) throw new Error("NO_COURIER_AVAILABLE");

  await hawky.post("/tasks/" + taskId + "/assign", { driver_id: winner.driver.id });
  return winner;
}

Costos reales — desglose para 100 couriers activos

Concepto	MXN / mes	Notas
100 × Plan Personal	$9,000	Cada courier trae su teléfono
Datos móviles (opcional)	$0 – $15,000	Solo si provees SIM
Hosting backend (CF Workers + D1)	~$0 – $150	Gratis hasta 100K req/día
Gateway SMS (opcional)	$500 – $2,000	Notificaciones al cliente
Comisión de pago (si aplica)	3% - 4% GMV	Stripe / MercadoPago / Clip

El 80% del costo operativo típicamente son los conductores mismos (pago por entrega), no la infraestructura.

Preguntas frecuentes

¿Hawky provee el courier?

No. Hawky es la capa de rastreo + dispatch. Los conductores los contratas tú, directamente o como 1099. Muchos clientes usan la app móvil de Hawky como la app del conductor.

¿Cómo manejo pago al courier?

Por fuera de Hawky. Usa Stripe Connect, Dwolla, o pagos directos. Hawky tiene reportes de tareas completadas por conductor que usas como input para pagarles.

¿Puedo escalar a 1,000 couriers?

Sí — el plan Empresarial tiene rate limits más altos y cuentas maestras. Escribe a hello@hawky.tech con tu volumen proyectado.

Siguiente paso

Instala el MCP de Hawky en Claude Code o Cursor y prueba construir tu primera tarea de delivery vía lenguaje natural. O revisa la documentación completa de la API.