Conectar tu tienda en línea con Vaelo

Para cuentas de empresa. Tu tienda (Shopify, WooCommerce, una página propia o una hoja de cálculo con Zapier o Make) puede crear envíos en Vaelo y recibir un aviso cada vez que cambian de estado. Esta página es para quien programa tu tienda.

1. Crea tu clave

Entra a tu cuenta en Mis envíos > Mis datos > Conectar tu tienda en línea, y toca Crear clave. Cópiala: solo se muestra una vez. Si alguien más la ve, crea una nueva y la anterior deja de funcionar.

2. Crea un envío

La recogida puede ser una dirección guardada con su ubicación (direccion_id) o un punto (origen_lat y origen_lng). Quien recibe comparte su ubicación con el enlace que te devolvemos: mándaselo a tu comprador por WhatsApp o correo.

POST https://vaelomensajeria.com/api/v1/envios
Authorization: Bearer vaelo_tu_clave
Content-Type: application/json

{
  "direccion_id": 12,
  "destino_nombre": "Ana López",
  "destino_telefono": "55551234",
  "destino_direccion": "Casa verde, frente al parque",
  "destino_zona": "Zona 16",
  "peso": 2,
  "descripcion": "Pedido 1045",
  "metodo_pago": "credito",
  "cobro_destinatario": 150
}

Respuesta: guia, estado, precio, enlace_receptor (para quien recibe), rastreo y codigo_entrega. Si la zona no es de tarifa fija, el precio queda "desde" hasta que quien recibe comparta su ubicación.

Campos opcionales: vehiculo_id (1 = moto, por defecto), fragil (true), valor_declarado y asegurar (true), notas, programado_para (hora de Guatemala, "2026-11-20T09:00").

3. Consulta un envío

GET https://vaelomensajeria.com/api/v1/envios/VA-7K3M9QX2
Authorization: Bearer vaelo_tu_clave

4. Recibe avisos de estado

En la misma sección de tu cuenta escribe la dirección (https) donde quieres recibir los avisos. Cada cambio llega como POST con este cuerpo:

{ "evento": "entregado", "envio": { "guia": "VA-...", "estado": "entregado", "recibio": "Ana López", ... }, "enviado": "2026-11-20T15:04:05Z" }

Para comprobar que viene de Vaelo, calcula el HMAC-SHA256 del cuerpo con tu secreto y compáralo con la cabecera X-Vaelo-Firma (formato sha256=...).

Eventos: aceptado, recogido, en_camino, entregado, fallido, devolviendo, devuelto, a_sede, en_sede, reenviado, cancelado y precio (cuando cambia el precio).

Límites

Hasta 120 peticiones por minuto por clave. Los errores vienen con un mensaje en error que explica qué corregir.