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 {BASE_URL}/auth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

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

cURL Example

curl --request POST '{BASE_URL}/auth/token' \
    --header 'Content-Type: application/json' \
    --data '{
        "client_id": "your_client_id",
        "client_secret": "your_client_secret"
    }'

Master Data

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

GET {BASE_URL}/regions

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

cURL Example

curl --request GET '{BASE_URL}/regions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Services & Prices

Devuelve servicios disponibles y precios para una región dada. Filtra por peso para ver solo los servicios que aceptan el paquete. También soporta coordenadas para cotización dinámica/ASAP.

Solicitud Parameters

GET {BASE_URL}/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}
    }
  ]
}

cURL Example

curl --request GET '{BASE_URL}/services?region_id=1&origin_region_id=2&weight=2.5' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Customers

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

Request Body Fields

{
  "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"}
}

cURL Example

curl --request POST '{BASE_URL}/customers' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "phone": "+50760000000",
        "password": "optionalStrongPassword"
    }'

Shipments

Shipment Lifecycle

Shippea soporta creación, pago, listado, tracking, consulta de etiquetas y cancelación. En el flujo estándar, la creación del envío debita la billetera automáticamente y encola la generación de etiqueta de forma asíncrona.

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

{
  "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, "total_declared_value": 35, "base_price": 4.99, "return_fee": 0, "final_price": 4.99},
    "items": [{"id": 1, "title": "Shoes", "sku": "SHOE-001", "quantity": 1, "weight": 1.2, "length": 12, "width": 8, "height": 5, "package_type": "Box", "declared_value": 35, "description": null, "category": null}]
  }
}

curl --request POST '{BASE_URL}/shipments' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
        "order_number": "ORDER-1001",
        "service_name": "Door-to-Door",
        "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": {"address":"Street 123","city":"Panamá","country":"Panama","province_code":"PA-8","latitude":8.9943,"longitude":-79.5188},
        "items_information": [{"title":"Shoes","quantity":1,"weight":1.2}]
    }'

GET {BASE_URL}/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", "address": "Sender Street 45", "city": "Panamá", "country": "PA", "phone": "+50761110000"},
    "receiver": {"username": "John Doe", "address": "Street 123", "city": "Panamá", "country": "PA", "phone": "+50760000000"},
    "items": [{"id": 1, "title": "Shoes", "sku": "SHOE-001", "quantity": 1, "weight": 1.2, "length": 12, "width": 8, "height": 5, "package_type": "Box", "declared_value": 35, "description": null, "category": null}],
    "label_url": "https://app.shippea.io/storage/labels/4001234.pdf",
    "tracking_history": [
      {"status": "confirmed", "remarks": "Payment confirmed", "location": null, "timestamp": "2026-06-12 10:00:00"},
      {"status": "picked_up", "remarks": "Picked up by courier", "location": "Panamá", "timestamp": "2026-06-12 14:30:00"},
      {"status": "in_transit", "remarks": "In transit", "location": "Penonomé", "timestamp": "2026-06-12 18:00:00"}
    ],
    "created_at": "2026-06-12 09:00:00",
    "updated_at": "2026-06-12 18:00:00"
  }
}

curl --request GET '{BASE_URL}/shipments/4001234' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

DELETE {BASE_URL}/shipments/4001234

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

curl --request DELETE '{BASE_URL}/shipments/4001234' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

GET {BASE_URL}/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}
}

curl --request GET '{BASE_URL}/shipments?per_page=20' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

POST {BASE_URL}/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
  }
}

curl --request POST '{BASE_URL}/shipments/4001234/pay' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

GET {BASE_URL}/shipments/4001234/label

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

curl --request GET '{BASE_URL}/shipments/4001234/label' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Account & Wallet

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

GET {BASE_URL}/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"}
  }
}

cURL Example

curl --request GET '{BASE_URL}/account' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Wallet

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

GET {BASE_URL}/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"}
    ]
  }
}

cURL Example

curl --request GET '{BASE_URL}/wallet' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Webhook

Webhook Configuration

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

GET {BASE_URL}/webhook

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

PUT {BASE_URL}/webhook
Content-Type: application/json

{
  "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..."}
}

DELETE {BASE_URL}/webhook

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

Authentication

Revoca el token de acceso actual. Las solicitudes posteriores con este token devuelven 401.

POST {BASE_URL}/auth/logout

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

cURL Example

curl --request POST '{BASE_URL}/auth/logout' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Reference

Regiones Reference

Panama region IDs and ISO codes to use with the region_id and origin_region_id query parameters on the /services endpoint, and the province_code fields in shipment creation. Use the /regions endpoint to retrieve live IDs.

Province Codes for Shipment Fields

Use the province_code ISO value in sender_details.province_code and receiver_details.province_code when creating shipments.

Errors

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.

Standard Error Shape

{
  "success": false,
  "message": "Human-readable error message."
}

Reference

Colección Postman

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