Documentación de API

API RESTful moderna para integrar envíos multi-carrier en minutos

Ver Endpoints Solicitar Acceso

Autenticación

Todas las peticiones requieren un API Key en el header de autorización:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
X-API-Version: v1

Base URL: https://api.shipphub.com

Endpoints Principales

POST /v1/rates

Cotizar tarifas de envío

Obtén cotizaciones en tiempo real de múltiples carriers con una sola llamada.

Request Body:

{
  "origin": {
    "country": "MX",
    "state": "Jalisco",
    "city": "Guadalajara",
    "postal_code": "44100",
    "address": "Av. Americas 1500"
  },
  "destination": {
    "country": "MX",
    "state": "CDMX",
    "city": "Ciudad de México",
    "postal_code": "06600",
    "address": "Av. Reforma 100"
  },
  "parcels": [
    {
      "weight": 2.5,
      "weight_unit": "kg",
      "length": 30,
      "width": 20,
      "height": 15,
      "distance_unit": "cm"
    }
  ],
  "insurance": {
    "enabled": true,
    "amount": 1500.00,
    "currency": "MXN"
  }
}
📖 Ver descripción de campos
origin (object, requerido)

Dirección de origen del envío.

  • country - Código ISO del país (MX, US, etc.)
  • state - Estado o provincia
  • city - Ciudad
  • postal_code - Código postal
  • address - Dirección completa
destination (object, requerido)

Dirección de destino del envío. Misma estructura que origin.

parcels (array, requerido)

Lista de paquetes a enviar.

  • weight - Peso del paquete (número decimal)
  • weight_unit - Unidad de peso (kg, lb)
  • length - Largo en centímetros
  • width - Ancho en centímetros
  • height - Alto en centímetros
  • distance_unit - Unidad de distancia (cm, in)
insurance (object, opcional)

Configuración de seguro para el envío.

  • enabled - Si se requiere seguro (boolean)
  • amount - Valor asegurado (número)
  • currency - Moneda (MXN, USD, etc.)

Response (200 OK):

{
  "status": "success",
  "data": {
    "rates": [
      {
        "carrier": "fedex",
        "service": "FEDEX_GROUND",
        "service_name": "FedEx Terrestre",
        "total_price": 185.50,
        "currency": "MXN",
        "estimated_days": 3,
        "insurance_cost": 15.00
      },
      {
        "carrier": "dhl",
        "service": "DHL_EXPRESS",
        "service_name": "DHL Express",
        "total_price": 245.00,
        "currency": "MXN",
        "estimated_days": 1,
        "insurance_cost": 18.00
      }
    ]
  },
  "meta": {
    "trace_id": "req_abc123xyz",
    "timestamp": "2026-02-20T10:30:00Z"
  }
}
📖 Ver descripción de respuesta
rates (array)

Lista de cotizaciones disponibles de diferentes carriers.

  • carrier - Identificador del carrier (fedex, dhl, ups)
  • service - Código del servicio
  • service_name - Nombre legible del servicio
  • total_price - Precio total incluyendo seguro
  • currency - Moneda del precio
  • estimated_days - Días estimados de entrega
  • insurance_cost - Costo del seguro
POST /v1/shipments

Crear envío y generar etiqueta

Crea un envío, genera la guía y obtén el número de rastreo instantáneamente.

Request Body:

{
  "rate_id": "rate_fedex_abc123",
  "shipper": {
    "name": "Mi Empresa SA",
    "company": "Mi Empresa",
    "email": "envios@miempresa.com",
    "phone": "+52 33 1234 5678",
    "address": {
      "street": "Av. Americas 1500",
      "city": "Guadalajara",
      "state": "Jalisco",
      "postal_code": "44100",
      "country": "MX"
    }
  },
  "recipient": {
    "name": "Juan Pérez",
    "email": "juan@example.com",
    "phone": "+52 55 9876 5432",
    "address": {
      "street": "Av. Reforma 100",
      "city": "Ciudad de México",
      "state": "CDMX",
      "postal_code": "06600",
      "country": "MX"
    }
  },
  "parcels": [
    {
      "weight": 2.5,
      "weight_unit": "kg",
      "length": 30,
      "width": 20,
      "height": 15,
      "distance_unit": "cm",
      "description": "Electrónicos"
    }
  ],
  "customs": {
    "content_type": "merchandise",
    "content_description": "Productos electrónicos",
    "incoterm": "DAP",
    "items": [
      {
        "description": "Laptop",
        "quantity": 1,
        "value": 15000.00,
        "currency": "MXN",
        "weight": 2.5,
        "weight_unit": "kg",
        "origin_country": "MX"
      }
    ]
  },
  "options": {
    "signature_required": true,
    "saturday_delivery": false,
    "insurance": {
      "enabled": true,
      "amount": 15000.00,
      "currency": "MXN"
    }
  },
  "metadata": {
    "order_id": "ORD-12345",
    "customer_reference": "REF-ABC"
  }
}
📖 Ver descripción de campos
rate_id (string, opcional)

ID de la tarifa obtenida previamente del endpoint /v1/rates.

shipper (object, requerido)

Información del remitente.

  • name - Nombre completo o razón social
  • company - Nombre de la empresa
  • email - Email de contacto
  • phone - Teléfono con código de país
  • address - Objeto con dirección completa
recipient (object, requerido)

Información del destinatario. Misma estructura que shipper.

parcels (array, requerido)

Lista de paquetes. Similar a /v1/rates pero incluye description.

customs (object, requerido para envíos internacionales)

Información aduanal para envíos internacionales.

  • content_type - Tipo de contenido (merchandise, documents, gift, etc.)
  • incoterm - Término comercial internacional (DAP, DDP, etc.)
  • items - Lista detallada de productos
options (object, opcional)

Opciones adicionales del envío (firma requerida, entrega en sábado, seguro).

metadata (object, opcional)

Datos adicionales para tu referencia (no se envían al carrier).

Response (201 Created):

{
  "status": "success",
  "data": {
    "shipment_id": "shp_xyz789",
    "tracking_number": "1234567890",
    "carrier": "fedex",
    "service": "FEDEX_GROUND",
    "label_url": "https://api.shipphub.com/labels/shp_xyz789.pdf",
    "status": "created",
    "estimated_delivery": "2026-02-23T18:00:00Z",
    "total_cost": 185.50,
    "currency": "MXN"
  },
  "meta": {
    "trace_id": "req_def456uvw",
    "timestamp": "2026-02-20T10:35:00Z"
  }
}
📖 Ver descripción de respuesta
data (object)

Información del envío creado.

  • shipment_id - ID único del envío en ShippHub
  • tracking_number - Número de rastreo del carrier
  • carrier - Carrier seleccionado
  • label_url - URL para descargar la etiqueta en PDF
  • status - Estado actual del envío
  • estimated_delivery - Fecha estimada de entrega (ISO 8601)
  • total_cost - Costo total del envío
GET /v1/tracking/:tracking_number

Rastrear envío en tiempo real

Consulta el estado actual de cualquier envío con eventos detallados de tránsito.

Request Example:

GET /v1/tracking/1234567890
Authorization: Bearer YOUR_API_KEY
📖 Ver descripción de parámetros
tracking_number (path parameter, requerido)

Número de rastreo del envío obtenido al crear el shipment.

Response (200 OK):

{
  "status": "success",
  "data": {
    "tracking_number": "1234567890",
    "carrier": "fedex",
    "status": "in_transit",
    "status_detail": "En ruta hacia destino",
    "estimated_delivery": "2026-02-23T18:00:00Z",
    "origin": {
      "city": "Guadalajara",
      "state": "Jalisco",
      "country": "MX"
    },
    "destination": {
      "city": "Ciudad de México",
      "state": "CDMX",
      "country": "MX"
    },
    "events": [
      {
        "timestamp": "2026-02-20T10:35:00Z",
        "status": "created",
        "description": "Etiqueta creada",
        "location": {
          "city": "Guadalajara",
          "state": "Jalisco",
          "country": "MX"
        }
      },
      {
        "timestamp": "2026-02-20T14:20:00Z",
        "status": "picked_up",
        "description": "Paquete recolectado",
        "location": {
          "city": "Guadalajara",
          "state": "Jalisco",
          "country": "MX"
        }
      },
      {
        "timestamp": "2026-02-21T08:15:00Z",
        "status": "in_transit",
        "description": "En ruta hacia destino",
        "location": {
          "city": "Querétaro",
          "state": "Querétaro",
          "country": "MX"
        }
      }
    ]
  },
  "meta": {
    "trace_id": "req_ghi789rst",
    "timestamp": "2026-02-21T10:00:00Z"
  }
}
📖 Ver descripción de respuesta
data (object)

Información del rastreo del envío.

  • tracking_number - Número de rastreo
  • carrier - Carrier del envío
  • status - Estado actual (created, picked_up, in_transit, delivered, etc.)
  • status_detail - Descripción detallada del estado
  • estimated_delivery - Fecha estimada de entrega
  • events - Historial completo de eventos del envío
events (array)

Lista cronológica de eventos del envío.

  • timestamp - Fecha y hora del evento (ISO 8601)
  • status - Estado del evento
  • description - Descripción del evento
  • location - Ubicación donde ocurrió el evento
GET /v1/shipments

Listar envíos con filtros

Obtén un listado paginado de tus envíos con opciones de filtrado.

Query Parameters:

  • page - Número de página (default: 1)
  • per_page - Registros por página (default: 20, max: 100)
  • status - Filtrar por estado (created, in_transit, delivered, etc.)
  • carrier - Filtrar por carrier (fedex, dhl, ups, etc.)
  • from_date - Fecha desde (ISO 8601)
  • to_date - Fecha hasta (ISO 8601)

Request Example:

GET /v1/shipments?page=1&per_page=10&status=in_transit&carrier=fedex
Authorization: Bearer YOUR_API_KEY

Response (200 OK):

{
  "status": "success",
  "data": {
    "shipments": [
      {
        "shipment_id": "shp_xyz789",
        "tracking_number": "1234567890",
        "carrier": "fedex",
        "service": "FEDEX_GROUND",
        "status": "in_transit",
        "created_at": "2026-02-20T10:35:00Z",
        "estimated_delivery": "2026-02-23T18:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 10,
      "total": 45,
      "total_pages": 5,
      "has_more": true
    }
  },
  "meta": {
    "trace_id": "req_jkl012mno",
    "timestamp": "2026-02-21T11:00:00Z"
  }
}

Respuestas de Error

Todos los errores siguen el mismo formato estándar:

400 Bad Request:

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Datos de entrada inválidos",
    "details": {
      "origin.postal_code": ["El código postal es requerido"],
      "parcels.0.weight": ["El peso debe ser mayor a 0"]
    }
  },
  "meta": {
    "trace_id": "req_error123",
    "timestamp": "2026-02-20T10:40:00Z"
  }
}

401 Unauthorized:

{
  "status": "error",
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API Key inválida o expirada"
  }
}

429 Too Many Requests:

{
  "status": "error",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Límite de peticiones excedido",
    "retry_after": 60
  }
}

Límites de Uso

60
Peticiones por minuto
5,000
Peticiones por día
99.9%
Disponibilidad garantizada

¿Listo para comenzar?

Solicita acceso a la API y recibe tus credenciales en menos de 24 horas

Solicitar Acceso Ahora