API de Socio de Envíos de Pigee

Inicio rápido

Desde la creación de la cuenta hasta tu primer envío en producción en menos de una hora. Sigue estos cinco pasos:

1. Crea una cuenta gratuita de Pigee en account.pigeepost.com y selecciona Shipping Partner como tipo de cuenta.
2. Ve a Dashboard → Developer → API Keys y genera una clave de producción y una clave de prueba.
3. Elige tu modo de pago: Pigee Pay o Pigee Account Balance.
4. Configura tu tarifa de servicio en Dashboard → Fees.
5. Importa la colección de Postman para el desarrollo en el entorno de pruebas.

Autenticación

Cada solicitud debe incluir tu clave API en la cabecera Authorization como un Bearer token. Las claves están vinculadas a tu cuenta de socio y llevan asociada tu configuración de tarifas y tu modo de pago.

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

Tipos de clave

Entornos y URL base

El sandbox es una réplica exacta y completa del entorno de producción. Cambia de entorno sustituyendo el prefijo de tu clave, o usa la URL explícita del sandbox para mayor claridad.

SDKs y bibliotecas

Los SDK oficiales encapsulan la API REST con modelos tipados, reintentos automáticos y herramientas de sandbox.

Validar clave de API

Llama a este endpoint para confirmar que tu clave de API está activa y correctamente configurada antes de pasar a producción.

POST /api/v1/store/valid
Authorization: Bearer pgk_live_…
Content-Type: application/json

{
  "store_type": 2,
  "api_key": "pgk_live_YOUR_KEY"
}

{
  "valid": true,
  "account": {
    "id": "acc_7H4K",
    "type": "shipping_partner",
    "payment_mode": "pigee_pay",
    "service_fee_pct": 8.5,
    "balance_gbp": 240.00
  }
}

Obtener tarifas de envío

Consulta tarifas de transportistas en tiempo real para un envío. Devuelve todos los servicios disponibles ordenados por precio, incluyendo tiempo de tránsito, cobertura de seguro y coste total de importación.

{
  "shop_url": "https://your-store.com",
  "currency": "GBP",
  "parcel": {
    "type": "Box",
    "boxsize": 4
  },
  "weight": { "value": 4, "units": "kg" },
  "dimension": {
    "length": 40,
    "width": 30,
    "height": 20,
    "units": "cms"
  },
  "address": {
    "pickup": {
      "address_line1": "10 High Street",
      "town": "London",
      "post_code": "SW1A 1AA",
      "country": "United Kingdom"
    },
    "destination": {
      "address_line1": "123 Ocean Drive",
      "town": "Miami",
      "post_code": "33101",
      "country": "United States"
    }
  }
}

{
  "rates": [
    {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE",
      "method_title": "DHL Express Worldwide",
      "price": 125.50,
      "currency": "GBP",
      "transit_days": 2,
      "insurance_available": true,
      "customs_included": true
    }
  ],
  "currency": "GBP",
  "request_id": "req_7H4K2026"
}

Parámetros de la solicitud

Crear pedido

Crea un pedido de Pigee usando un carrier_request_id del endpoint de tarifas. Pigee genera la etiqueta, la factura comercial y, si usas Pigee Pay, un enlace de pago alojado.

{
  "order_from": "api",
  "shop_url": "https://your-store.com",
  "order_id": "ORDER-10001",
  "currency": "GBP",
  "items": [
    {
      "name": "Vintage leather jacket",
      "quantity": 1,
      "value": 600.00,
      "currency": "GBP",
      "hs_code": "4203100090"
    }
  ],
  "shippingData": {
    "method_title": "DHL Express Worldwide",
    "cost": 125.50,
    "currency": "GBP",
    "meta_data": {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE"
    }
  }
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "pending_payment",
  "payment_url": "https://pay.pigee.com/c/abc123",
  "label_url": null,
  "tracking_number": null
}

Completar pedido

Envía los datos finales de cumplimiento una vez confirmado el pago. Pigee genera la etiqueta de envío, reserva el transportista y devuelve un número de seguimiento.

{
  "order_id": "po_78910",
  "status": "processing",
  "shop_id": "https://your-store.com",
  "currency": "GBP",
  "total": 725.50,
  "shipping_total": 125.50
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "booked",
  "label_url": "https://labels.pigeepost.com/PGE-7H4K-2026-0042.pdf",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "estimated_delivery": "2026-05-08"
}

Seguimiento

Consulta eventos de seguimiento en tiempo real para cualquier envío creado a través de la API.

{
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "status": "in_transit",
  "estimated_delivery": "2026-05-08",
  "events": [
    {
      "timestamp": "2026-05-06T08:14:00Z",
      "status": "in_transit",
      "location": "DHL Hub, Leipzig",
      "description": "Shipment in transit"
    }
  ]
}

Métodos de pago

Pigee admite dos modos de pago. El modo activo se configura en tu panel de socio y se aplica a todos los pedidos.

Tarifas de servicio

Como Socio de Envíos, puedes añadir tu propia tarifa sobre las tarifas base del transportista de Pigee. Las tarifas se configuran en tu panel y se aplican automáticamente antes de devolver los precios.

• Tarifa porcentual: Se aplica como un porcentaje del coste base del transportista.
• Tarifa fija: Un importe fijo añadido por envío.
• Excepciones por ruta: Anula la tarifa global para pares específicos de origen/destino.

Liquidaciones y cambio de divisas

Pigee Pay cobra a los clientes finales en más de 135 divisas y liquida en tu cuenta bancaria en tu moneda local.

• El ciclo de liquidación suele ser T+2 días hábiles tras la confirmación de entrega del envío.
• Retira fondos de tu saldo Pigee a través del panel.
• Los registros detallados de transacciones están disponibles en Finanzas → Liquidaciones.
• Las facturas de las transacciones liquidadas se generan automáticamente y están disponibles en PDF.

Webhooks

Pigee envía eventos en tiempo real a tu endpoint HTTPS en formato JSON POST solicitudes. Configura la URL de tu webhook en Panel → Desarrollador → Webhooks.

{
  "event": "parcel.delivered",
  "created_at": "2026-05-08T14:22:07Z",
  "api_version": "v1",
  "data": {
    "pigee_order_id": "PGE-7H4K-2026-0042",
    "order_id": "ORDER-10001",
    "carrier": "DHL",
    "tracking_number": "1234567890",
    "delivered_at": "2026-05-08T14:18:00Z"
  }
}

Referencia de eventos de webhook

Firmas de Webhook

Cada solicitud de webhook incluye un encabezado X-Pigee-Signature , un resumen HMAC-SHA256 del cuerpo bruto de la solicitud. Verifícalo siempre antes de procesarlo.

// Node.js
const crypto = require('crypto');

function verifyPigeeWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

Errores

Todos los errores devuelven JSON con un objeto error que contiene un code legible por máquina y un message.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your Pigee partner balance is not sufficient to create this shipment.",
    "request_id": "req_7H4K2026"
  }
}

Límites de solicitudes

Los límites de solicitudes se aplican por clave de API y varían según el nivel de tu cuenta.

Cuando se alcanza un límite de solicitudes, la API devuelve HTTP 429 con un encabezado Retry-After .

Tipos de datos y convenciones

• Fechas y horas - ISO 8601 UTC, p. ej. 2026-05-06T14:22:07Z
• Divisas - Códigos de tres letras ISO 4217, p. ej. GBP, USD, NGN
• Valores monetarios - number con dos decimales, siempre acompañados de un campo currency campo
• Nombres de países - Nombres completos en inglés, p. ej. "United Kingdom", "United States"
• Números de teléfono - Se recomienda el formato E.164, p. ej. +447700900123
• Pesos - kg o lbs especificados por solicitud
• IDs - Los IDs generados por Pigee usan un formato con prefijo, p. ej. po_78910, cr_abc123

Referencia de IDs de transportistas

Usa una pigee_carrier_id valores de la respuesta de tarifas al crear pedidos.

Registro de cambios

v1.3 - mayo de 2026

• Se añadieron los indicadores insurance_available y customs_included a la respuesta de tarifas.
• La verificación de firma de los webhooks ahora utiliza HMAC-SHA256.
• Nuevo código de error RATE_EXPIRED.
• Endpoint de seguimiento añadido: GET /api/v1/tracking/{pigee_order_id}.

v1.2 - febrero de 2026

• Se añadieron anulaciones de tarifas de servicio por ruta en el panel.
• Los enlaces de pago de Pigee Pay ahora incluyen un campo expires_at campo.
• Nuevos eventos de webhook añadidos para aduanas y liquidaciones.

v1.1 - octubre de 2025

• Publicación de la colección inicial de Postman.
• Lanzamiento del entorno sandbox.
• Lanzamiento del modo de pago con Saldo de Cuenta.

v1.0 - junio de 2025

• Lanzamiento público inicial: Validar, Obtener Tarifas, Crear Pedido, Procesar Pedido.