Veez App Icon

Documentación API VeezDelivery

Integra servicios de despacho express, cotización en tiempo real y asignación de repartidores GPS.

BASE URL: https://api.veez.cl/api/v1

🌐 Visión General

La API REST de VeezDelivery permite conectar tiendas e-commerce, sistemas ERP y aplicaciones móviles para cotizar, solicitar y monitorear envíos urbanos automatizados.

Todas las solicitudes deben realizarse a través de HTTPS. Las respuestas se entregan estrictamente en formato JSON utilizando la codificación UTF-8.

💡
Estructura Estándar de Respuesta:
Todas las respuestas exitosas devuelven "success": true. En caso de error, devuelven un código HTTP acorde (400, 401, 500) junto con un objeto descriptivo en el campo error.

🔑 Autenticación & API Keys

La API utiliza llaves de autenticación (API Keys) basadas en Bearer Tokens para validar el acceso.

Debes enviar tu API Key en cada solicitud mediante el encabezado HTTP Authorization o X-API-Key:

Authorization: Bearer vz_live_a1b2c3d4e5f6...
X-API-Key: vz_live_a1b2c3d4e5f6...

Modos de Entorno (Producción vs Sandbox)

Entorno Prefijo de API Key Encabezado Opcional Comportamiento
Producción vz_live_... - Crea despachos reales con cobro a la cuenta del comercio.
Sandbox (Pruebas) vz_test_... X-Test-Mode: true Simula rutas y conductores sin generar cobros reales ni despachar repartidores.

⏱️ Tiempo de Preparación (`prep_time_mins`)

Permite a los comercios indicar cuántos minutos requiere la cocina o el almacén para empaquetar el pedido antes del arribo del repartidor.

El sistema de VeezDelivery utiliza prep_time_mins para recalcular automáticamente las ventanas de recolección y entrega (ETAs):

Jerarquía de Prioridad:

  1. Valor especificado en el payload JSON de la solicitud (prep_time_mins).
  2. Configuración predeterminada del comercio guardada en su perfil (/merchants/settings).
  3. Valor por defecto: 0 minutos (Despacho inmediato).

⚡ SDKs Oficiales & Especificación OpenAPI

Librerías de código oficiales y especificación OpenAPI 3.1.0 para rápida integración y generación de SDKs.

📄 Especificación OpenAPI 3.1.0 (Swagger)

Puedes descargar o consultar el contrato unificado OpenAPI 3.1.0 para explorar los endpoints o generar SDKs automáticos en PHP, Python, Go o Dart usando herramientas como Fern o Liblab.

⬇️ Descargar openapi.yaml (3.1.0)
🚀 Monorrepo JavaScript / TypeScript (@veez)
🐙 GitHub: veez-js-sdk

Suite modular en TypeScript para Node.js, Express, Next.js, React y React Native.

1. @veez/core (TypeScript Base)

Ver en NPM ↗
npm install @veez/core

2. @veez/node (Servidores Node.js)

Ver en NPM ↗
npm install @veez/node

3. @veez/react (React & React Native Hooks)

Ver en NPM ↗
npm install @veez/react
🐘 SDK Oficial de PHP (veezdelivery/veez-sdk)
🐙 GitHub: veez-php-sdk

Cliente PHP nativo ultraligero sin dependencias para integración en PHP 7.4 / 8.x.

composer require veezdelivery/veez-sdk

📦 Guías de Instalación e Integración

Instrucciones detalladas para instalar los plugins oficiales o conectar tu sistema personalizado.

🛒 WordPress / WooCommerce
  1. Descarga el paquete oficial del plugin:
    ⬇️ Descargar plugin WooCommerce (.zip)
  2. Ingresa al panel de administración de WordPress > Plugins > Añadir Nuevo.
  3. Haz clic en Subir Plugin, selecciona el archivo woocommerce-veezdelivery.zip y presiona Instalar Ahora.
  4. Activa el plugin VeezDelivery Shipping Method.
  5. Ve a WooCommerce > Ajustes > Envío > Zonas de Envío y añade el método VeezDelivery Express.
  6. Ingresa tu API Key (vz_live_...) y define el Tiempo de Preparación (minutos) por defecto para tu cocina/almacén. Guarda los cambios.
🛍️ Shopify Integration
  1. Solicita tus credenciales de Shopify Admin API en el panel de tu tienda (o usa la aplicación privada VeezDelivery).
  2. Ejecuta el script de registro automático para vincular el servicio de tarifas de envío (CarrierService):
    node setup-carrier.js --shop=tu-tienda.myshopify.com --token=shpat_xxx --prep-time-mins=15
  3. El script registrará la URL callback https://api.veez.cl/api/v1/shopify/carrier-service y el webhook de creación de despacho automático en pedidos pagados (orders/paid).
📦 Odoo ERP Addon (v14, v15, v16, v17, v18)
  1. Descarga el conector oficial de Odoo:
    ⬇️ Descargar Addon Odoo (.zip)
  2. Descomprime la carpeta delivery_veezdelivery dentro del directorio de addons personalizados de tu servidor (custom_addons/).
  3. Activa el Modo Desarrollador en Odoo, ve a Aplicaciones > Actualizar Lista de Aplicaciones.
  4. Busca e instala el módulo VeezDelivery Shipping Carrier.
  5. Dirígete a Inventario > Configuración > Métodos de Entrega y crea un nuevo método de envío.
  6. Selecciona como proveedor VeezDelivery, pega tu API Key (vz_live_...) e ingresa el Tiempo de Preparación (Minutos).
⚡ Integración Personalizada (Custom REST API)

Para sistemas propios desarrollados en React, Node.js, Python, PHP, Laravel, Flutter, iOS, Android, etc.:

  1. Obtén tu API Key desde el Dashboard Admin de VeezDelivery.
  2. En el checkout de tu sitio/app, realiza un POST a https://api.veez.cl/api/v1/shipping/quote enviando la dirección de entrega y peso.
  3. Muestra las tarifas devueltas y el tiempo estimado de entrega al cliente.
  4. Al confirmar el pago del cliente, envía un POST a https://api.veez.cl/api/v1/orders con los datos del destinatario para solicitar el repartidor automáticamente.
POST /shipping/quote
Cotizar Tarifas en Tiempo Real

Calcula las opciones de tarifa, tiempos de viaje y estimaciones de entrega según la distancia y peso.

Parámetros del Body (JSON)
Campo Tipo Descripción
destination string / object * Dirección completa de entrega o coordenadas {lat, lng}.
origin string / object opcional Dirección de origen (si se omite, se usa la dirección del perfil de comercio).
total_weight number opcional Peso total del paquete en kilogramos (ej: 1.5).
prep_time_mins integer opcional Tiempo de preparación en minutos (ej: 25). O override del comercio. 
curl -X POST https://api.veez.cl/api/v1/shipping/quote \
  -H "Authorization: Bearer vz_live_83f9102" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "Av. Providencia 1234, Providencia, Santiago",
    "total_weight": 2.5,
    "prep_time_mins": 20
  }'
200 OK 
{
  "success": true,
  "prep_time_minutes": 20,
  "travel_time_minutes": 18,
  "total_estimated_minutes": 38,
  "estimated_pickup_time": "2026-08-21T04:00:00.000Z",
  "estimated_delivery_time": "2026-08-21T04:18:00.000Z",
  "rates": [
    {
      "id": "express_motorcycle",
      "name": "Express Moto",
      "cost": 2900,
      "estimated_minutes": 18,
      "recommended": true
    }
  ]
}
POST /orders
Crear Pedido / Solicitar Repartidor

Genera una solicitud de envío en firme para ser asignada inmediatamente o según el tiempo de preparación configurado.

Parámetros Requeridos
Campo Tipo Descripción
customer_name string * Nombre completo del destinatario.
customer_phone string * Teléfono móvil de contacto (ej: +56912345678).
dropoff_address string / object * Dirección física exacta de entrega.
payment_mode string * prepaid (pagado) o cash_on_delivery (cobro al entregar).
prep_time_mins integer opcional Minutos de preparación requeridos antes del pickup. 
curl -X POST https://api.veez.cl/api/v1/orders \
  -H "Authorization: Bearer vz_live_83f9102" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "María González",
    "customer_phone": "+56987654321",
    "dropoff_address": "Av. Apoquindo 4500, Las Condes",
    "payment_mode": "prepaid",
    "prep_time_mins": 15,
    "order_notes": "Dejar en recepción"
  }'
200 OK 
{
  "success": true,
  "booking_id": "vz_bk_98127341",
  "status": "new",
  "tracking_number": "VZ-98127341",
  "tracking_url": "https://veez.web.app/booking-details/vz_bk_98127341",
  "estimated_pickup_time": "2026-08-21T03:50:00.000Z",
  "estimated_delivery_time": "2026-08-21T04:12:00.000Z"
}
GET /orders/:id
Consultar Estado del Pedido

Obtiene el estado actual del envío, información del repartidor asignado y coordenadas GPS en tiempo real.

Estados Posibles (`status`)
  • new: Creado, buscando repartidor cercano.
  • assigned: Repartidor asignado y en camino al retiro.
  • arrived_pickup: Repartidor en el local comercial.
  • picked_up: Paquete retirado, en camino al cliente.
  • arrived_dropoff: Repartidor en domicilio del cliente.
  • completed: Entregado con éxito.
  • cancelled: Cancelado.
curl -X GET https://api.veez.cl/api/v1/orders/vz_bk_98127341 \
  -H "Authorization: Bearer vz_live_83f9102"
200 OK 
{
  "success": true,
  "booking_id": "vz_bk_98127341",
  "status": "assigned",
  "driver": {
    "name": "Carlos Mamani",
    "phone": "+56911223344",
    "vehicle_plate": "KL-9082",
    "current_location": { "lat": -33.425, "lng": -70.612 }
  },
  "tracking_url": "https://veez.web.app/booking-details/vz_bk_98127341"
}
POST /orders/:id/cancel
Cancelar Pedido

Permite cancelar una solicitud de envío que aún no ha sido retirada por el repartidor.

Body JSON Opcional
Campo Tipo Descripción
reason string opcional Motivo descriptivo de la cancelación del envío. 
curl -X POST https://api.veez.cl/api/v1/orders/vz_bk_98127341/cancel \
  -H "Authorization: Bearer vz_live_83f9102" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Cliente reprogramó la fecha de entrega"
  }'
200 OK 
{
  "success": true,
  "message": "Order cancelled successfully",
  "booking_id": "vz_bk_98127341",
  "status": "cancelled"
}
GET /merchants/me
Perfil de Comercio

Obtiene la información general del comercio asociado a la API Key, estado de revisión y configuración activa.

curl -X GET https://api.veez.cl/api/v1/merchants/me \
  -H "Authorization: Bearer vz_live_83f9102"
200 OK 
{
  "success": true,
  "merchant": {
    "id": "m_812938",
    "name": "Pizzería Don Carlos",
    "status": "active",
    "prep_time_mins": 15,
    "address": "Av. Italia 1234, Providencia",
    "integration_platform": "woocommerce"
  }
}
PATCH /merchants/settings
Actualizar Ajustes del Comercio

Permite actualizar la configuración predeterminada del comercio, como el tiempo habitual de preparación en minutos.

Body JSON
Campo Tipo Descripción
prep_time_mins integer * Minutos de preparación por defecto para todas las órdenes futuras. 
curl -X PATCH https://api.veez.cl/api/v1/merchants/settings \
  -H "Authorization: Bearer vz_live_83f9102" \
  -H "Content-Type: application/json" \
  -d '{
    "prep_time_mins": 25
  }'
200 OK 
{
  "success": true,
  "message": "Merchant settings updated successfully",
  "prep_time_mins": 25
}
POST /woocommerce/shipping-quote
WooCommerce API Endpoint

Endpoint consumido de forma transparente por el plugin de WooCommerce para calcular las tarifas de envío en tiempo real durante el checkout del carrito.

Características
  • Soporta cálculo de tarifas según dirección del comprador y código postal.
  • Incluye parámetro de tiempo de preparación de cocina/almacén (prep_time_mins).
  • Registra automáticamente la telemetría del comercio para moderación administrativa.
curl -X POST https://api.veez.cl/api/v1/woocommerce/shipping-quote \
  -H "Authorization: Bearer vz_live_83f9102" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "address": "Av. Providencia 1234", "city": "Santiago" },
    "contents": [{ "name": "Pizza Familiar", "quantity": 1 }],
    "prep_time_mins": 20
  }'
200 OK 
{
  "rates": [
    {
      "id": "veezdelivery_express",
      "label": "VeezDelivery Express (Entrega en 38 min)",
      "cost": "2900"
    }
  ]
}
POST /shopify/carrier-service
Shopify CarrierService

Endpoint compatible con el protocolo nativo de Shopify CarrierService API para retornar cotizaciones dinámicas.

Parámetros Query

Se puede pasar opcionalmente el parámetro ?prep_time_mins=15 en la URL de callback registrada en Shopify.

curl -X POST "https://api.veez.cl/api/v1/shopify/carrier-service?prep_time_mins=15" \
  -H "Authorization: Bearer vz_live_83f9102" \
  -H "Content-Type: application/json" \
  -d '{
    "rate": {
      "origin": { "country": "CL", "city": "Santiago" },
      "destination": { "country": "CL", "address1": "Av. Apoquindo 4500" },
      "items": [{ "name": "Producto X", "quantity": 1, "grams": 1000 }]
    }
  }'
200 OK 
{
  "rates": [
    {
      "service_name": "VeezDelivery Express",
      "service_code": "express",
      "total_price": "2900",
      "currency": "CLP"
    }
  ]
}
POST /odoo/rate-shipment
Odoo Delivery Connector

Endpoint de tarifa para el addon de Odoo Delivery Carrier en presupuestos y ordenes de venta.

Campos Payload

Procesa prep_time_mins configurado en las opciones de despacho del modelo delivery.carrier de Odoo.

curl -X POST https://api.veez.cl/api/v1/odoo/rate-shipment \
  -H "Authorization: Bearer vz_live_83f9102" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_address": "Av. Las Condes 1000",
    "weight_kg": 2.0,
    "prep_time_mins": 15
  }'
200 OK 
{
  "success": true,
  "price": 2900,
  "estimated_days": 0,
  "prep_time_mins": 15
}

⚡ Webhooks en Tiempo Real

Recibe notificaciones automáticas en tu servidor cuando ocurran cambios de estado o movimiento GPS de tus pedidos.

Configura tu URL de Webhooks desde el panel de administración. Cada notificación enviará un evento con la siguiente estructura:

{
  "event": "order.status_changed",
  "booking_id": "vz_bk_98127341",
  "status": "picked_up",
  "timestamp": "2026-08-21T04:05:00.000Z",
  "driver": {
    "name": "Carlos Mamani",
    "phone": "+56911223344"
  }
}

⚠️ Códigos de Estado y Errores HTTP

La API de VeezDelivery utiliza códigos HTTP estándar para responder.

Código HTTP Significado Causa Habitual
200 OK Éxito La solicitud fue procesada correctamente.
400 Bad Request Solicitud Inválida Faltan parámetros obligatorios o la dirección no pudo ser geocodificada.
401 Unauthorized No Autorizado La API Key proporcionada es errónea, no existe o fue revocada.
403 Forbidden Cuenta Suspendida / Límite Aprobación La integración está en revisión o no se ha completado la moderación admin.
429 Too Many Requests Límite Superado Se ha superado el rate limit de solicitudes por minuto.
500 Server Error Error Interno Ocurrió un inconveniente temporal en la plataforma.