Authentication

Usa tu client_id y client_secret para obtener un token Bearer. Incluye este token en todas las solicitudes posteriores mediante el encabezado Authorization. Los tokens no expiran automáticamente; vuelve a autenticarte si recibes una respuesta 401.

POST /api/v2/partner/auth/token\nContent-Type: application/json\n\n
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

{
  "success": true,
  "token_type": "Bearer",
  "access_token": "1|...",
  "message": "Access token generated successfully."
}

Master Data

Devuelve todas las regiones activas disponibles para cobertura de servicio. Usa el id de región al consultar servicios.

GET https://app.shippea.io/api/v2/partner/regions

{
  "success": true,
  "data": [
    {"id": 1, "name": "Panamá", "iso_code": "PA-8"}
  ]
}

Services & Prices

Devuelve servicios disponibles y precios para una región dada. Filtra por peso para ver solo los servicios que aceptan el paquete.

Solicitud Parameters

GET https://app.shippea.io/api/v2/partner/services?region_id=1&origin_region_id=2&weight=2.5

{
  "success": true,
  "data": [
    {
      "id": 12,
      "rate_name": "Door-to-Door",
      "rate_type": "Door-to-Door",
      "min_weight": 0.0,
      "max_weight": 5.0,
      "price": 4.99,
      "return_charge": 0.0,
      "weight_unit": "lb",
      "min_transit_days": 1,
      "max_transit_days": 3,
      "is_dynamic": false,
      "courier": {"id": 3, "name": "Shippea Express", "logo_url": "https://..."},
      "agency": {"id": 2, "name": "Agency Name", "region_id": 1}
    }
  ]
}

Customers

Crea una cuenta de cliente para la titularidad del envío. Si el email ya existe, devuelve la información del cliente existente y no crea duplicados.

Campos del Cuerpo de la Solicitud

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+50760000000",
  "password": "optionalStrongPassword"
}

{
  "success": true,
  "message": "Customer account created successfully.",
  "data": {"customer_uuid": "...", "email": "john@example.com"}
}

Shipments

Shipment Lifecycle

Shippea soporta listado, creación, pago, seguimiento, recuperación de etiqueta y cancelación. En el flujo estándar, crear un envío debita la billetera inmediatamente y encola la generación asíncrona de etiqueta.

{
  "order_number": "ORDER-1001",
  "service_name": "Door-to-Door",
  "customer": {"name": "John Doe", "email": "john@example.com", "phone": "+50760000000"},
  "sender_details": {"name": "My Store", "address": "Sender Street 45", "city": "Panamá", "country": "Panama", "province_code": "PA-8", "latitude": 8.9824, "longitude": -79.5199},
  "receiver_details": {"name": "John Doe", "address": "Street 123", "city": "Panamá", "country": "Panama", "province_code": "PA-8", "latitude": 8.9943, "longitude": -79.5188},
  "items_information": [{"title": "Shoes", "sku": "SHOE-001", "quantity": 1, "weight": 1.2}]
}

{
  "success": true,
  "message": "Shipment created and payment processed. Label generation has been queued.",
  "data": {
    "shipment_id": 991,
    "tracking_number": "4001234",
    "status": "label_created",
    "is_paid": true,
    "payment_method": "shippea_wallet",
    "total_price": 4.99,
    "currency": "USD",
    "wallet_balance": 195.01,
    "service": {"id": 12, "name": "Door-to-Door", "type": "Door-to-Door"},
    "calculation": {"total_items": 1, "total_weight": 1.2, "final_price": 4.99},
    "items": [{"id": 1, "title": "Shoes", "quantity": 1, "weight": 1.2}]
  }
}

GET https://app.shippea.io/api/v2/partner/shipments/4001234

{
  "success": true,
  "data": {
    "tracking_number": "4001234",
    "order_number": "ORDER-1001",
    "status": "in_transit",
    "is_paid": true,
    "total_price": 4.99,
    "currency": "USD",
    "service": {"id": 12, "name": "Door-to-Door", "type": "Door-to-Door"},
    "sender": {"username": "My Store", "city": "Panamá", "country": "PA", "phone": "+50761110000"},
    "receiver": {"username": "John Doe", "city": "Panamá", "country": "PA", "phone": "+50760000000"},
    "items": [{"id": 1, "title": "Shoes", "quantity": 1, "weight": 1.2}],
    "label_url": "https://app.shippea.io/storage/labels/4001234.pdf",
    "tracking_history": [{"status": "confirmed", "remarks": "Payment confirmed", "timestamp": "2026-06-12 10:00:00"}],
    "proof_of_delivery": {
      "receiver_name": "John Doe",
      "photos": ["https://app.shippea.io/storage/proof_of_delivery/4001234-1.jpg"],
      "signature": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
      "location": {"lat": "8.98240000", "lng": "-79.51990000"},
      "delivered_at": "2026-06-12 18:30:00"
    },
    "created_at": "2026-06-12 09:00:00",
    "updated_at": "2026-06-12 18:00:00"
  }
}

{
  "proof_of_delivery": {
    "receiver_name": "John Doe",
    "note": "Left at front door",
    "photos": ["https://app.shippea.io/storage/proof_of_delivery/4001234-1.jpg"],
    "signature": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
    "location": {"lat": "8.98240000", "lng": "-79.51990000"},
    "delivered_at": "2026-06-12 18:30:00"
  }
}

DELETE https://app.shippea.io/api/v2/partner/shipments/4001234

{"success": true, "message": "Shipment cancelled successfully."}

GET https://app.shippea.io/api/v2/partner/shipments?status=label_created&per_page=20

{
  "success": true,
  "data": [
    {
      "shipment_id": 991,
      "tracking_number": "4001234",
      "order_number": "ORDER-1001",
      "status": "label_created",
      "is_paid": true,
      "total_price": 4.99,
      "currency": "USD",
      "label_url": "https://...",
      "created_at": "2026-06-12 10:00:00"
    }
  ],
  "meta": {"current_page": 1, "per_page": 20, "total": 145, "last_page": 8}
}

POST https://app.shippea.io/api/v2/partner/shipments/4001234/pay

{
  "success": true,
  "message": "Payment successful. Label generation has been queued.",
  "data": {
    "tracking_number": "4001234",
    "status": "label_created",
    "transaction_id": "TXN-...",
    "amount_charged": 4.99,
    "currency": "USD",
    "wallet_balance": 195.01
  }
}

GET https://app.shippea.io/api/v2/partner/shipments/4001234/label

{
  "success": true,
  "data": {
    "tracking_number": "4001234",
    "label_url": "https://.../label.pdf",
    "combined_url": "https://.../combined.pdf"
  }
}

Account & Wallet

Devuelve el perfil de la cuenta partner autenticada, resumen de billetera y detalles del cliente API.

GET https://app.shippea.io/api/v2/partner/account

{
  "success": true,
  "data": {
    "account": {"name": "My Company", "email": "partner@example.com", "phone": "+50760000000", "status": "active"},
    "wallet": {"balance": 195.01, "currency": "USD", "is_active": true},
    "api_client": {"name": "My Integration", "client_id": "clnt_abc123", "webhook_url": "https://myapp.com/webhooks", "last_used_at": "2026-06-12 10:00:00"}
  }
}

Wallet

Devuelve el saldo actual de la billetera, moneda y las últimas 20 transacciones.

GET https://app.shippea.io/api/v2/partner/wallet

{
  "success": true,
  "data": {
    "balance": 195.01,
    "currency": "USD",
    "is_active": true,
    "transactions": [
      {"type": "debit", "amount": 4.99, "balance": 195.01, "reason": "Shipment payment - 4001234", "reference": "SHIPMENT-4001234", "date": "2026-06-12 10:00:00"}
    ]
  }
}

Webhook

Webhook Configuration

Registra una webhook URL para notificaciones de eventos. Verifica los payloads calculando HMAC-SHA256(webhook_secret, raw_body) y comparándolo con el encabezado X-Shippea-Signature.

GET https://app.shippea.io/api/v2/partner/webhook

{
  "success": true,
  "data": {
    "webhook_url": "https://myapp.com/webhooks",
    "webhook_secret": "shp_secret_abc..."
  }
}

{
  "webhook_url": "https://myapp.com/webhooks/shippea"
}

{
  "success": true,
  "message": "Webhook URL registered successfully.",
  "data": {
    "webhook_url": "https://myapp.com/webhooks/shippea",
    "webhook_secret": "shp_secret_abc..."
  }
}

{"success": true, "message": "Webhook URL removed successfully."}

Authentication

Revoca el token de acceso actual. Las solicitudes posteriores con este token devuelven 401. Solo se revoca el token usado para esta solicitud; los demás tokens activos del mismo cliente no se ven afectados.

POST https://app.shippea.io/api/v2/partner/auth/logout

{"success": true, "message": "Token revoked successfully."}

Statuses

Devuelve todos los códigos de estado de envío que usa Shippea, con su nombre en inglés y español. Se lee en vivo del mismo catálogo que administra el panel de administración; los estados nuevos aparecen aquí automáticamente en cuanto se agregan.

GET https://app.shippea.io/api/v2/partner/statuses

{
  "success": true,
  "data": [
    {"id": 6, "code": "pending_payment", "name": {"en": "Pending Payment", "es": "Pago Pendiente"}},
    {"id": 3, "code": "label_created", "name": {"en": "Label Created", "es": "Etiqueta Creada"}}
  ]
}

Pickups

Pickups / Recogidas

GET https://app.shippea.io/api/v2/partner/pickups?per_page=20

{
  "success": true,
  "data": [
    {
      "pickup_number": "PU-2026-0042",
      "status": "pending",
      "pickup_date": "2026-08-20",
      "time_slot": "AM",
      "pickup_address": "Calle 50, Ciudad de Panamá",
      "phone_number": "+50760000000",
      "package_count": 3,
      "courier_provider": "hotexpress",
      "created_at": "2026-08-13 10:00:00"
    }
  ],
  "meta": {"current_page": 1, "per_page": 20, "total": 4, "last_page": 1}
}

{
  "pickup_date": "2026-08-20",
  "time_slot": "AM",
  "pickup_address": "Calle 50, Ciudad de Panamá",
  "phone_number": "+50760000000",
  "package_count": 3,
  "courier_provider": "hotexpress",
  "merchant_notes": "Ring the front desk"
}

{
  "success": true,
  "data": {
    "pickup_number": "PU-2026-0042",
    "status": "pending",
    "pickup_date": "2026-08-20",
    "time_slot": "AM",
    "pickup_address": "Calle 50, Ciudad de Panamá",
    "phone_number": "+50760000000",
    "package_count": 3,
    "courier_provider": "hotexpress",
    "merchant_notes": "Ring the front desk",
    "created_at": "2026-08-13 10:00:00"
  }
}

GET https://app.shippea.io/api/v2/partner/pickups/PU-2026-0042

{
  "success": true,
  "data": {
    "pickup_number": "PU-2026-0042",
    "status": "confirmed",
    "pickup_date": "2026-08-20",
    "time_slot": "AM",
    "pickup_address": "Calle 50, Ciudad de Panamá",
    "phone_number": "+50760000000",
    "package_count": 3,
    "courier_provider": "hotexpress",
    "courier_notes": null,
    "rejected_reason": null,
    "updated_at": "2026-08-13 14:00:00"
  }
}

Reference

Regiones Reference

Panama region IDs and ISO codes to use with region_id, origin_region_id, and province_code. Usa GET /regions para recuperar IDs vivos; pueden diferir entre producción y sandbox.

Códigos de Provincia para Campos de Envío

Reference

Códigos de Error

Todos los errores devuelven success: false y un message legible. El código de estado HTTP indica la categoría del error.

Developer Tools

Colección Postman

Descarga la colección Postman para obtener todos los endpoints v2 preconfigurados con scripts de guardado automático de token.