API Documentation

Cotización de envíos

POST /api/quoter Obtiene cotizaciones de envío entre dos códigos postales

Descripción

Retorna una lista de servicios de paquetería disponibles con precios entre un origen y un destino, según el peso del paquete. Acepta tanto POST con body JSON como GET con query parameters.

Códigos de respuesta

200OK

400Bad Request

403Forbidden

Parámetros

Nombre	Tipo	Requerido	Descripción
apikey	string	Sí	Tu clave de API proporcionada por el sistema
from	string	Sí	Código postal de origen (5 dígitos)
to	string	Sí	Código postal de destino (5 dígitos)
weight	number	Sí	Peso del paquete en kg (usar peso volumétrico si es mayor)

// POST /api/quoter
// Content-Type: application/json

{
  "apikey": "tu-api-key-aqui",
  "from":   "01000",
  "to":     "44100",
  "weight": 5
}

// Alternativa GET:
// GET /api/quoter?apikey=xxx&from=01000&to=44100&weight=5

// Array de servicios disponibles
[
  {
    "id": 1,
    "courier": "fedex",
    "courier_name": "FedEx",
    "carrier_id": 3,
    "service": "ground",
    "service_slug": "Terrestre",
    "price": "185.50",
    "extended": "false",
    "service_estimate_date": "3-5 días hábiles"
  },
  ...
]

GET /api/quoter Misma funcionalidad vía query parameters

Descripción

Endpoint alternativo para obtener cotizaciones usando parámetros GET. Ideal para integraciones simples o pruebas desde el navegador. Mismos parámetros que el endpoint POST.

// Ejemplo de URL:
GET /api/quoter?apikey=tu-api-key&from=01000&to=44100&weight=5

Creación de envíos

POST /api/create_order Genera una nueva orden de envío y guía

Descripción

Crea una nueva orden de envío completa, generando la guía con la paquetería seleccionada. Requiere datos de origen, destino, paquete y servicio. El balance del usuario será descontado automáticamente.

Códigos de respuesta

200Orden creada

400JSON inválido

403API Key inválida

500Error interno

Parámetros del body

Nombre	Tipo	Requerido	Descripción
apikey	string	Sí	Tu clave de API
courier	string	Sí	Identificador de la paquetería (ej. `fedex`, `estafeta`)
service	string	Sí	Tipo de servicio (ej. `ground`, `express`)
origin	object	Sí	Objeto con datos del remitente
destination	object	Sí	Objeto con datos del destinatario
package	object	Sí	Objeto con dimensiones y peso del paquete

// POST /api/create_order
// Content-Type: application/json

{
  "apikey": "tu-api-key-aqui",
  "courier": "fedex",
  "service": "ground",
  "origin": {
    "name": "Juan Pérez",
    "company": "Mi Empresa S.A.",
    "phone": "5551234567",
    "email": "juan@ejemplo.com",
    "street": "Av. Insurgentes Sur 1234",
    "number": "Int. 5",
    "neighborhood": "Del Valle",
    "city": "Ciudad de México",
    "state": "CDMX",
    "zip_code": "03100",
    "country": "MX",
    "reference": "Edificio azul"
  },
  "destination": {
    "name": "María López",
    "phone": "3319876543",
    "email": "maria@ejemplo.com",
    "street": "Calle Hidalgo 567",
    "neighborhood": "Centro",
    "city": "Guadalajara",
    "state": "Jalisco",
    "zip_code": "44100",
    "country": "MX",
    "reference": "Frente al parque"
  },
  "package": {
    "weight": 5,
    "length": 30,
    "width": 20,
    "height": 15,
    "content": "Electrónicos"
  }
}

{
  "status": "ok",
  "order_id": 4521,
  "tracking_number": "7940123456789",
  "label_url": "https://...",
  "price": 185.50,
  "courier": "FedEx",
  "service": "Terrestre"
}

{
  "status": "forbidden",
  "message": "API key inválida o sin servicio asignado"
}

Rastreo de envíos

POST /api/tracking Consulta el historial de movimientos de un envío

Descripción

Consulta el estado y movimientos de un envío mediante su número de rastreo. La petición se reenvía al servidor central (core) de forma transparente (proxy). Retorna el historial completo de eventos del paquete.

Códigos de respuesta

200Datos de rastreo

400Campos faltantes

403API Key inválida

502Error upstream

Parámetros

Nombre	Tipo	Requerido	Descripción
apikey	string	Sí	Tu clave de API
tracking_number	string	Sí	Número de guía o rastreo del envío

// POST /api/tracking
// Content-Type: application/json

{
  "apikey": "tu-api-key-aqui",
  "tracking_number": "7940123456789"
}

// Ejemplo de respuesta del servidor central
{
  "status": "ok",
  "tracking_data": {
    "tracking_number": "7940123456789",
    "current_status": "En tránsito",
    "events": [
      {
        "date": "2026-04-23 10:30:00",
        "description": "Paquete en centro de distribución",
        "location": "Guadalajara, Jalisco"
      },
      {
        "date": "2026-04-22 14:00:00",
        "description": "Recolección realizada",
        "location": "CDMX"
      }
    ]
  }
}

{
  "status": "missing_fields",
  "message": "Los campos 'apikey' y 'tracking_number' son obligatorios."
}

Información de cuenta

POST /api/account Obtiene el perfil y saldo del usuario autenticado

Descripción

Retorna la información del perfil de la cuenta asociada a la API Key, incluyendo datos del usuario, saldo disponible, información de facturación y configuración.

Códigos de respuesta

200Perfil obtenido

400JSON inválido

403API Key inválida

Parámetros

Nombre	Tipo	Requerido	Descripción
apikey	string	Sí	Tu clave de API

// POST /api/account
// Content-Type: application/json

{
  "apikey": "tu-api-key-aqui"
}

Recolección de paquetes

POST /api/pickup Solicita una recolección de paquetes a partir de un tracking_number

Descripción

Programa una recolección (pickup) para un envío existente. El sistema localiza la orden mediante el tracking_number, identifica automáticamente el proveedor (carrier) y envía la solicitud de recolección al proveedor correspondiente.

Autenticación

API Key requerida en el campo apikey

Content-Type

application/json

Parámetros del Request

Campo	Tipo	Requerido	Descripción
apikey	string	Requerido	Tu API Key de autenticación
tracking_number	string	Requerido	Número de rastreo del envío para el cual se solicita la recolección. Debe existir en el sistema.
pickupDate	string	Requerido	Fecha de recolección en formato `YYYY-MM-DD`. Debe ser a partir del día siguiente (no se permiten fechas pasadas ni el día de hoy).
startTimeHour	integer	Requerido	Hora de inicio de la ventana de recolección. Valor entre 9 y 18 (9:00 AM – 6:00 PM).
endTimeHour	integer	Requerido	Hora de fin de la ventana de recolección. Valor entre 9 y 18. Debe ser mayor que `startTimeHour`.
startTimeMinute	integer	Opcional	Minutos de la hora de inicio. Valor entre 0 y 59. Por defecto: `0`
endTimeMinute	integer	Opcional	Minutos de la hora de fin. Valor entre 0 y 59. Por defecto: `0`
specialInstructions	string	Opcional	Instrucciones especiales para el repartidor (ej: "Tocar timbre del piso 3").
environment	string	Opcional	Modo de prueba. Valores: `"sandbox"`, `"test"` o `"development"`. En este modo se devuelve una respuesta simulada sin contactar al proveedor.

⏰ Horario disponible

Lunes a Sábado: 9:00 AM – 6:00 PM

Las horas de inicio y fin deben estar dentro del rango 9 a 18 (formato 24h). La hora de inicio debe ser estrictamente menor que la hora de fin.

📅 Restricciones de fecha

Mínimo: día siguiente

La fecha de recolección debe ser a partir de mañana. No se permiten recolecciones para el mismo día ni fechas pasadas. Zona horaria: America/Mexico_City.

// POST /api/pickup
// Content-Type: application/json

{
  "apikey": "tu-api-key",
  "tracking_number": "TRACK123456789",
  "pickupDate": "2026-05-01",
  "startTimeHour": 9,
  "startTimeMinute": 0,
  "endTimeHour": 14,
  "endTimeMinute": 0,
  "specialInstructions": "Tocar el timbre del piso 3."
}

{
  "success": "true",
  "data": {
    "pickupRequestId": "clsn1v2rm0000maxb1k5m3f8q",
    "status": "Pending"
  }
}

// Envía "environment": "sandbox" o "test" para obtener datos simulados

{
  "apikey": "tu-api-key",
  "tracking_number": "TEST123",
  "pickupDate": "2026-05-01",
  "startTimeHour": 10,
  "endTimeHour": 15,
  "environment": "sandbox"
}

// Respuesta simulada:
{
  "success": "true",
  "data": {
    "pickupRequestId": "clsn1v2rm0000maxb1k5m3f8q",
    "status": "Pending"
  }
}

// 401 — API Key inválida
{
  "status": "error",
  "message": "API Key inválida o no encontrada."
}

// 422 — Campo requerido faltante
{
  "status": "error",
  "message": "El campo 'tracking_number' es requerido."
}

// 422 — Fecha inválida (debe ser mañana o posterior)
{
  "status": "error",
  "message": "La fecha de recolección debe ser a partir del día siguiente (2026-04-30)."
}

// 422 — Hora fuera de rango
{
  "status": "error",
  "message": "La hora de inicio (startTimeHour) debe estar entre 9 y 18."
}

// 404 — Tracking no encontrado (devuelto por el CORE)
{
  "status": "error",
  "message": "No se encontró ninguna orden con el tracking_number: TRACK123"
}

Notas importantes

• El tracking_number debe corresponder a una orden existente que tenga un proveedor asignado.
• La recolección solo se puede programar si el envío está en estado PENDING.
• Las horas usan formato 24h (9 = 9:00 AM, 18 = 6:00 PM).
• Zona horaria del sistema: America/Mexico_City (CST/CDT).
• Para pruebas, envía "environment": "sandbox" para obtener una respuesta simulada sin contactar al proveedor.

201Recolección programada

401API Key inválida

422Validación fallida

404Tracking no encontrado

500Error del proveedor

502Error de conexión