Tabla de contenidos

Documentación de la API Pública de ShaQ Express

Bienvenido a la API Pública de ShaQ Express. Esta documentación proporciona a los socios y desarrolladores los endpoints necesarios para gestionar paquetes, envíos y recibir actualizaciones de seguimiento.

Info	Valor
versión	1.0
URL base (Desa.)	`https://test-partner.shaqexpress.com/api/v1`

Cabeceras Estándar

Todas las solicitudes a la API deben contener las siguientes cabeceras HTTP estándar:

Cabecera	Tipo	Descripción
`Content-Type`	`application/json`	Requiere cuerpos de solicitud en JSON
`Accept`	`application/json`	Espera cuerpos de respuesta en JSON

(Nota: Los endpoints protegidos también requerirán una cabecera Authorization: Bearer <token>, que se obtiene al iniciar sesión).

Estados de Paquetes

Nuestro sistema utiliza varios estados para rastrear el ciclo de vida de un paquete. A continuación se muestra la lista completa de estados que puede recibir:

📦 Pendiente & Recolección

pending : El paquete aún no ha sido recibido del Socio
received : El paquete ha sido recibido del Socio
warehouse_received : El paquete ha sido recibido en un almacén regional
collected : El paquete ha sido recogido del Socio por ShaQ Express
ready_for_pickup : El paquete está listo para ser recogido por el cliente

🚚 Tránsito & Despacho

shipped : El paquete ha sido enviado por el Socio
assigned : El paquete ha sido asignado a un Repartidor
in_transit : El paquete está en tránsito hacia el almacén más cercano
dispatched : El paquete está en camino para ser entregado

✅ Resultados de Entrega

confirmed : Se ha llamado al cliente y la entrega ha sido confirmada
delivered : El paquete fue entregado exitosamente al cliente

⚠️ Problemas & Excepciones

not_delivered : Se intentó la entrega pero no se pudo completar
rescheduled : La entrega del paquete fue reprogramada para un nuevo intento
customer_hold : La entrega está en espera por solicitud del cliente
customer_unreachable : La entrega está en espera porque el cliente no es localizable
suspected_scam : La entrega está en espera debido a una sospecha de fraude

🔙 Devoluciones

return_picked : El paquete ha sido recogido del cliente para devolución al socio
return_in_progress : El paquete está siendo preparado para ser devuelto al Socio
returned_to_sender : El paquete ha sido devuelto al Socio
return_to_central : El paquete está siendo devuelto al almacén central de ShaQ Express tras múltiples intentos fallidos de entrega, en preparación para ser devuelto al socio

Endpoints de la API

Inicio de Sesión

POST /auth/login

Obtener un token de autenticación para solicitudes posteriores. Como medida de seguridad, el token es válido por 7 días, tras los cuales deberá generarse uno nuevo usando la ruta /auth/login.

Solicitud

Parámetro	Tipo	Descripción
`identifier`	`string`	requerido.
`secret`	`string`	requerido.

Respuesta

200

{
  "message": "Request successful",
  "data": {
    "token": "UtXdU9HODhjdmtTNkRtUWNsVlM4OWI1d2Z2TXVIanlkRk"
  }
}

Obtener Paquetes

GET /packages?page=1&limit=1

Obtener todos los paquetes

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Respuesta

200

{
  "message": "Request successful",
  "data": {
    "list": [
      {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceCountry": "Ghana",
        "sourceAddressLine1": "Accra Spintex",
        "sourceAddressLine2": null,
        "destinationCountry": "Ghana",
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "units": 1,
        "type": "box",
        "value": "300.00",
        "amountToCollect": "300.00",
        "paymentCollector": "shaq",
        "handling": "normal",
        "specialInstructions": null,
        "status": "delivered",
        "statusDescription": "Package was successfully delivered to customer",
        "latitude": null,
        "longitude": null,
        "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "dateCreated": "2025-04-10 11:15",
        "eta": "2026-04-20 - 2026-04-22",
        "items": [
          {
            "name": "iPhone 6",
            "quantity": 1
          },
          {
            "name": "iPhone 14 Pro",
            "quantity": 2
          }
        ]
      },
      {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceCountry": "Ghana",
        "sourceAddressLine1": "Accra Spintex",
        "sourceAddressLine2": null,
        "destinationCountry": "Ghana",
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "units": 1,
        "type": "box",
        "value": "300.00",
        "amountToCollect": "300.00",
        "paymentCollector": "shaq",
        "handling": "normal",
        "specialInstructions": null,
        "status": "pending",
        "statusDescription": "Package is yet to be received from Partner.",
        "latitude": null,
        "longitude": null,
        "proofPhotoUrl": null,
        "dateCreated": "2025-04-10 11:15",
        "eta": "2026-04-20 - 2026-04-22",
        "items": [
          {
            "name": "iPhone 6",
            "quantity": 1
          }
        ]
      }
    ],
    "meta": {
      "total": 2,
      "perPage": 15,
      "currentPage": 1,
      "lastPage": 1
    }
  }
}

Obtener un Paquete Específico

GET /packages/{partnerRef}

Obtener detalles de un paquete

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Respuesta

200

{
  "message": "Request successful",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "sourceCountry": "Ghana",
    "sourceAddressLine1": "Accra Spintex",
    "sourceAddressLine2": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "units": 1,
    "type": "box",
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "handling": "normal",
    "specialInstructions": null,
    "status": "not_delivered",
    "statusDescription": "Attempted delivery but couldn't complete it.",
    "latitude": null,
    "longitude": null,
    "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "dateCreated": "2025-04-10 11:15",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "trackingHistory": [
      {
        "name": "not_delivered",
        "description": "Attempted delivery but couldn't complete it.",
        "date": "2025-07-16 09:00",
        "comment": "Customer was unreachable upon arrival. Package rescheduled for 2nd delivery attempt."
      },
      {
        "name": "dispatched",
        "description": "Package is en-route to deliver.",
        "date": "2025-07-15 15:45",
        "comment": null
      },
      {
        "name": "confirmed",
        "description": "Customer has been called and delivery confirmed.",
        "date": "2025-07-15 15:45",
        "comment": null
      },
      {
        "name": "received",
        "description": "Package has been received from Partner.",
        "date": "2025-07-15 15:38",
        "comment": null
      },
      {
        "name": "pending",
        "description": "Package is yet to be received by Partner.",
        "date": "2025-07-14 10:38",
        "comment": null
      }
    ]
  }
}

Eliminar un Paquete Pendiente

DELETE /packages/{partnerRef}

Eliminar un paquete. Solo se pueden eliminar paquetes pendientes.

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Respuesta

200

{
  "message": "Package deleted",
  "data": null
}

Cancelar Orden

POST /packages/{partnerRef}/cancel

Cancelar una orden de fulfillment.

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Respuesta

200

{
  "message": "Order cancelled successfully",
  "data": null
}

400

{
  "message": "Order cannot be cancelled. Order cancellation failed",
  "data": null
}

404

{
  "message": "Order not found",
  "data": null
}

Crear Paquete Individual

POST /packages

Crear un solo paquete

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Solicitud

Parámetro	Tipo	Descripción
`tracking_number`	`string`	opcional.
`partner_ref`	`string`	requerido. Debe ser único.
`customer_name`	`string`	requerido.
`customer_phone_1`	`string`	requerido.
`customer_phone_2`	`string`	opcional.
`source_country_iso2`	`string`	requerido.
`source_address_line_1`	`string`	requerido.
`source_address_line_2`	`string`	opcional.
`destination_region`	`string`	requerido si `region_id` está vacío.
`destination_city`	`string`	requerido.
`destination_address_line_1`	`string`	requerido.
`destination_address_line_2`	`string`	opcional.
`destination_postal_code`	`string`	opcional.
`length`	`decimal`	opcional.
`height`	`decimal`	opcional.
`weight`	`decimal`	opcional.
`description`	`string`	requerido.
`units`	`string`	requerido.
`type`	`string`	requerido . entre `parcel`, `box`
`handling`	`string`	requerido . entre `normal`, `fragile`
`special_instructions`	`string`	opcional.
`latitude`	`decimal`	opcional.
`longitude`	`decimal`	opcional.
`value`	`decimal`	requerido.
`amount_to_collect`	`decimal`	opcional. Por defecto, igual al `value` del paquete.
`payment_collector`	`string`	opcional. entre `shaq`, `partner` (Este parámetro solo puede enviarse cuando ShaQ Express es el cobrador de pagos. Especifica quién es responsable de cobrar el pago al cliente por el paquete y está destinado a casos especiales donde el socio gestiona el cobro. Si no se proporciona, se utilizará la configuración predeterminada acordada de cobrador de pagos.)
`items`	`array`	requerido. `{name, quantity}`
`region_id`	`integer`	requerido si `destination_region` está vacío.

Respuesta

200

{
  "message": "Package created successfully",
  "data": {
    "partnerRef": "UNIQUE-REF-001",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "altPhone": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "units": 1,
    "type": "box",
    "handling": "normal",
    "specialInstructions": null,
    "status": "pending",
    "statusDescription": "Package is yet to be received by Partner",
    "landmark": null,
    "proofPhotoUrl": null,
    "partner": "Demo Partner",
    "scheduleDate": null,
    "deliveryFee": null,
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "paymentStatus": null,
    "date": "2025-04-10 11:15",
    "deliveredAt": null,
    "eta": "2026-04-20 - 2026-04-22",
    "deliveryAttempts": 0,
    "items": [
      { "name": "iPhone 6", "quantity": 1 },
      { "name": "iPhone 14 Pro", "quantity": 2 }
    ]
  }
}

404

{
  "message": "No Region with name {destination_region} found",
  "data": null
}

Crear Paquetes en Masa

POST /packages/bulk

Crear múltiples paquetes

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Solicitud

Parámetro	Tipo	Descripción
`packages`	`array`	requerido.
`packages.*.tracking_number`	`string`	opcional.
`packages.*.partner_ref`	`string`	requerido.
`packages.*.customer_name`	`string`	requerido.
`packages.*.customer_phone_1`	`string`	requerido.
`packages.*.customer_phone_2`	`string`	opcional.
`packages.*.source_country_iso2`	`string`	requerido.
`packages.*.source_address_line_1`	`string`	requerido.
`packages.*.source_address_line_2`	`string`	opcional.
`packages.*.destination_region`	`string`	requerido si `region_id` está vacío.
`packages.*.destination_city`	`string`	requerido.
`packages.*.destination_address_line_1`	`string`	requerido.
`packages.*.destination_address_line_2`	`string`	opcional.
`packages.*.destination_postal_code`	`string`	opcional.
`packages.*.length`	`decimal`	opcional.
`packages.*.height`	`decimal`	opcional.
`packages.*.weight`	`decimal`	opcional.
`packages.*.description`	`string`	requerido.
`packages.*.units`	`string`	requerido.
`packages.*.type`	`string`	requerido . entre `parcel`, `box`
`packages.*.handling`	`string`	requerido . entre `normal`, `fragile`
`packages.*.special_instructions`	`string`	opcional.
`packages.*.latitude`	`decimal`	opcional.
`packages.*.longitude`	`decimal`	opcional.
`packages.*.value`	`decimal`	requerido.
`packages.*.amount_to_collect`	`decimal`	opcional. Por defecto, igual al `value` del paquete.
`packages.*.payment_collector`	`string`	opcional. entre `shaq`, `partner` (Este parámetro solo puede enviarse cuando ShaQ Express es el cobrador de pagos. Especifica quién es responsable de cobrar el pago al cliente por el paquete y está destinado a casos especiales donde el socio gestiona el cobro. Si no se proporciona, se utilizará la configuración predeterminada acordada de cobrador de pagos.)
`packages.*.items`	`array`	requerido. `{name, quantity}`
`packages.*.region_id`	`integer`	requerido si `destination_region` está vacío.

Respuesta

200

{
  "message": "Packages created successfully",
  "data": null
}

Crear Envío

POST /shipments

Crear un envío que representa el envío físico de paquetes que serán enviados a ShaQ Express.

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Solicitud

Parámetro	Tipo	Descripción
`packages`	`array`	requerido.
`packages.*.tracking_number`	`string`	opcional.
`packages.*.partner_ref`	`string`	requerido.
`packages.*.customer_name`	`string`	requerido.
`packages.*.customer_phone_1`	`string`	requerido.
`packages.*.customer_phone_2`	`string`	opcional.
`packages.*.source_country_iso2`	`string`	requerido.
`packages.*.source_address_line_1`	`string`	requerido.
`packages.*.source_address_line_2`	`string`	opcional.
`packages.*.destination_region`	`string`	requerido si `region_id` está vacío.
`packages.*.destination_city`	`string`	requerido.
`packages.*.destination_address_line_1`	`string`	requerido.
`packages.*.destination_address_line_2`	`string`	opcional.
`packages.*.destination_postal_code`	`string`	opcional.
`packages.*.length`	`decimal`	opcional.
`packages.*.height`	`decimal`	opcional.
`packages.*.weight`	`decimal`	opcional.
`packages.*.description`	`string`	requerido.
`packages.*.units`	`string`	requerido.
`packages.*.type`	`string`	requerido . entre `parcel`, `box`
`packages.*.handling`	`string`	requerido . entre `normal`, `fragile`
`packages.*.special_instructions`	`string`	opcional.
`packages.*.latitude`	`decimal`	opcional.
`packages.*.longitude`	`decimal`	opcional.
`packages.*.value`	`decimal`	requerido.
`packages.*.amount_to_collect`	`decimal`	opcional. Por defecto, igual al `value` del paquete.
`packages.*.payment_collector`	`string`	opcional. entre `shaq`, `partner` (Este parámetro solo puede enviarse cuando ShaQ Express es el cobrador de pagos. Especifica quién es responsable de cobrar el pago al cliente por el paquete y está destinado a casos especiales donde el socio gestiona el cobro. Si no se proporciona, se utilizará la configuración predeterminada acordada de cobrador de pagos.)
`packages.*.items`	`array`	requerido.
`packages.*.region_id`	`integer`	requerido si `destination_region` está vacío.

Respuesta

200

{
  "message": "Shipment created successfully",
  "data": {
    "reference": "PAR-20260322053800"
  }
}

Obtener un Envío Específico

GET /shipments/{reference}

Obtener detalles de un envío

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Respuesta

200

{
  "message": "Request successful",
  "data": {
    "reference": "SAAM-20260322053800",
    "date": "2026-03-22 05:38",
    "packages": [
      {
        "partnerRef": "qwertyui1a1aaqweqqaqx",
        "trackingNumber": "C561819A",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceAddressLine1": "Accra spintex basket junction",
        "sourceAddressLine2": null,
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "units": 1,
        "type": "box",
        "handling": "normal",
        "specialInstructions": null,
        "status": "pending",
        "statusDescription": "Package is yet to be received by Partner",
        "latitude": null,
        "longitude": null,
        "value": "1468.00",
        "amountToCollect": "1468.00",
        "paymentCollector": "shaq",
        "date": "2026-03-22 05:38",
        "eta": "2026-04-20 - 2026-04-22",
        "trackingUrl": "https://dev.tracking-website.pages.dev/packages/C561819A",
        "items": [
          {
            "name": "14cm Alya Glass Cookie Holder - Transparent",
            "quantity": 4
          },
          {
            "name": "10.6 Color Splicing Cotton Rope Storage Basket Toys Clothes Sundries Storage Basket AB-026 - Beige Yellow+White",
            "quantity": 1
          },
          {
            "name": "6 Pieces Nossa 21cm Cake Plate Set",
            "quantity": 1
          }
        ]
      }
    ]
  }
}

Actualizar un Paquete

PATCH /packages/{partnerRef}

Actualizar un paquete específico

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Solicitud

Parámetro	Tipo	Descripción
`tracking_number`	`string`	opcional.
`customer_name`	`string`	opcional.
`customer_phone_1`	`string`	opcional.
`customer_phone_2`	`string`	opcional.
`source_country_iso2`	`string`	opcional.
`source_address_line_1`	`string`	opcional.
`source_address_line_2`	`string`	opcional.
`destination_region`	`string`	opcional.
`destination_city`	`string`	opcional.
`destination_address_line_1`	`string`	opcional.
`destination_address_line_2`	`string`	opcional.
`destination_postal_code`	`string`	opcional.
`length`	`decimal`	opcional.
`height`	`decimal`	opcional.
`weight`	`decimal`	opcional.
`description`	`string`	opcional.
`units`	`string`	opcional.
`type`	`string`	opcional . entre `parcel`, `box`
`handling`	`string`	opcional . entre `normal`, `fragile`
`special_instructions`	`string`	opcional.
`latitude`	`decimal`	opcional.
`longitude`	`decimal`	opcional.
`value`	`decimal`	opcional.
`amount_to_collect`	`decimal`	opcional.
`items`	`array`	opcional.

Respuesta

200

{
  "message": "Request successful",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "sourceCountry": "Ghana",
    "sourceAddressLine1": "Accra Spintex",
    "sourceAddressLine2": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "units": 1,
    "type": "box",
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "handling": "normal",
    "specialInstructions": null,
    "status": "not_delivered",
    "statusDescription": "Attempted delivery but couldn't complete it.",
    "latitude": null,
    "longitude": null,
    "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "dateCreated": "2025-04-10 11:15",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "trackingHistory": [
      {
        "name": "not_delivered",
        "description": "Attempted delivery but couldn't complete it.",
        "date": "2025-07-16 09:00",
        "comment": "Customer was unreachable upon arrival. Package rescheduled for 2nd delivery attempt."
      },
      {
        "name": "dispatched",
        "description": "Package is en-route to deliver.",
        "date": "2025-07-15 15:45",
        "comment": null
      }
    ]
  }
}

Rastrear Paquete

GET /tracking/{trackingNumber}

Obtener los estados de seguimiento de un paquete específico

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Respuesta

200

{
  "message": "Package tracking",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "description": "Kitchen cabinet",
    "status": "shipped",
    "statusDescription": "Package has been shipped by Partner.",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "tracking": [
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:17"
      },
      {
        "status": "pending",
        "description": "Package is yet to be shipped by Partner.",
        "date": "2025-04-10 15:16"
      },
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:15"
      },
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:15"
      },
      {
        "status": "pending",
        "description": "Package is yet to be shipped by Partner.",
        "date": "2025-04-10 15:14"
      }
    ]
  }
}

Obtener Regiones

GET /setup/regions

Obtener todas las regiones permitidas

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Respuesta

200

{
  "message": "Request successful",
  "data": [
    {
      "id": 16,
      "name": "Western North"
    },
    {
      "id": 15,
      "name": "Ashanti"
    }
  ]
}

Recibir Actualizaciones de Paquetes vía Webhook

POST /YOUR_WEBHOOK_URL

Realizaremos un POST a su URL webhook cada vez que ocurra un evento rastreado en un paquete.

Sobre

Cada payload de webhook comparte el mismo sobre de nivel superior:

Campo	Tipo	Descripción
`event`	`string`	El tipo de evento. Ver Eventos Webhook a continuación.
`event_id`	`string`	UUID único por entrega. Usar para idempotencia/deduplicación.
`api_version`	`string`	Versión del payload, ej. `v1`
`occurred_at`	`string`	Marca de tiempo UTC ISO 8601 de cuándo ocurrió el evento
`data`	`object`	Payload específico del evento. La forma varía según `event`.

Eventos Webhook

`package.status_updated`

Se dispara cada vez que cambia el estado de un paquete.

Campo	Tipo	Descripción
`tracking_number`	`string`	Número de seguimiento ShaQ Express
`partner_ref`	`string`	Su referencia para el paquete
`status`	`string`	El nuevo estado. Ver Estados de Paquetes para los valores
`description`	`string`	Descripción legible del estado
`comment`	`string`	Contexto o comentario adicional. Puede ser `null`
`meta`	`object`	Datos adicionales. Incluye `proof_url` cuando `status` es `delivered`

{
  "event": "package.status_updated",
  "event_id": "018e2b3c-7f4a-7c2d-9e1b-4a8f3d2c6b5a",
  "api_version": "v1",
  "occurred_at": "2025-05-29T10:30:00Z",
  "data": {
    "tracking_number": "20250410X51DIQ",
    "partner_ref": "FGVHKJ567",
    "status": "delivered",
    "description": "Package was successfully delivered to customer",
    "comment": null,
    "meta": {
      "proof_url": "https://example.com/proof.jpg"
    }
  }
}

`package.amount_to_collect_updated`

Se dispara cuando el monto a cobrar de un paquete es revisado, siempre solicitado y aprobado por el Cliente.

Campo	Tipo	Descripción
`tracking_number`	`string`	Número de seguimiento ShaQ Express
`partner_ref`	`string`	Su referencia para el paquete
`status`	`string`	Estado del paquete al momento de la revisión. Ver Estados de Paquetes para valores
`meta.old_amount_to_collect`	`number`	Monto anterior a cobrar
`meta.new_amount_to_collect`	`number`	Monto revisado a cobrar
`meta.currency`	`string`	Código de moneda, ej. `GHS`
`meta.reason`	`string`	Motivo de la revisión

{
  "event": "package.amount_to_collect_updated",
  "event_id": "039g4d5e-9h6c-9e4f-1g3d-6c0h5f4e8d7c",
  "api_version": "v1",
  "occurred_at": "2025-05-29T09:00:00Z",
  "data": {
    "tracking_number": "20250410X51DIQ",
    "partner_ref": "FGVHKJ567",
    "status": "received",
    "meta": {
      "old_amount_to_collect": 25.0,
      "new_amount_to_collect": 35.0,
      "currency": "GHS",
      "reason": "Items changed"
    }
  }
}

Respuesta Esperada

Su endpoint debe retornar una respuesta 2xx para confirmar la recepción del webhook. Cualquier respuesta no-2xx será reintentada hasta 3 veces.

{
  "message": "",
  "data": {
    "status": "OK"
  }
}

Requisitos del Webhook

Para garantizar una entrega confiable y evitar tiempos de espera del webhook, siga estas pautas:

*   **Tiempo de Respuesta:** Su servidor debe retornar un código de estado `2xx` dentro de los **10 segundos** de recibir el payload.
*   **Procesamiento Asíncrono:** Confirme la recepción del webhook inmediatamente y procese cualquier operación de base de datos, lógica de negocio o notificaciones externas de forma asíncrona (ej. usando una cola/worker en segundo plano).
*   **Deduplicación e Idempotencia:** Use el `event_id` proporcionado en el sobre del payload para garantizar la idempotencia. Mantenga un registro de los IDs de eventos procesados y omita el procesamiento si el ID ya fue visto.
*   **Espere Duplicados:** Su endpoint debe estar preparado para manejar entregas duplicadas de forma elegante en caso de reintentos de red o problemas de conexión transitorios.

Crear Reemplazo de Paquete

POST /packages/replacement

Descripción: Crear uno o dos paquetes para reemplazar un paquete existente. El campo rule determina cuántos paquetes se requieren y qué action debe realizar cada uno.

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Reglas

Regla	Paquetes Requeridos	Acciones Requeridas
`deliver`	1	`action = deliver`
`return`	1	`action = return`
`return_deliver`	2	Un `return`, un `deliver`

Solicitud

Parámetro	Tipo	Descripción
`rule`	`string`	Requerido. Uno de `deliver`, `return`, `return_deliver`
`packages`	`array`	Requerido. 1–2 objetos de paquete. Debe satisfacer las restricciones de la `rule`

Objeto Paquete

Cada elemento del array packages debe tener la siguiente estructura:

Parámetro	Tipo	Descripción
`action`	`string`	Requerido. Uno de `deliver`, `return`. Debe alinearse con la `rule`
`partner_ref`	`string`	Requerido. Debe ser único
`customer_name`	`string`	Requerido
`customer_phone_1`	`string`	Requerido. Número de móvil válido
`customer_phone_2`	`string`	Opcional
`source_country_iso2`	`string`	Requerido. Código de país ISO2 válido
`source_address_line_1`	`string`	Requerido
`source_address_line_2`	`string`	Opcional
`destination_country_iso2`	`string`	Requerido. Código de país ISO2 válido
`destination_region`	`string`	Requerido si `region_id` está ausente
`destination_city`	`string`	Requerido
`destination_address_line_1`	`string`	Requerido
`destination_address_line_2`	`string`	Opcional
`destination_postal_code`	`string`	Opcional
`landmark`	`string`	Opcional
`region_id`	`integer`	Requerido si `destination_region` está ausente
`length`	`decimal`	Opcional
`height`	`decimal`	Opcional
`weight`	`decimal`	Opcional
`description`	`string`	Requerido
`units`	`number`	Requerido
`type`	`string`	Requerido. Uno de `parcel`, `box`
`value`	`decimal`	Requerido. Mínimo `0`
`amount_to_collect`	`decimal`	Opcional. Mínimo `0`
`handling`	`string`	Requerido. Uno de `normal`, `fragile`
`payment_collector`	`string`	opcional. entre `shaq`, `partner` (Este parámetro solo puede enviarse cuando ShaQ Express es el cobrador de pagos. Especifica quién es responsable de cobrar el pago al cliente por el paquete y está destinado a casos especiales donde el socio gestiona el cobro. Si no se proporciona, se utilizará la configuración predeterminada acordada de cobrador de pagos.)
`items`	`array`	Requerido. Array de `{ name: string, quantity: number }`. Puede estar vacío
`special_instructions`	`string`	Opcional
`latitude`	`decimal`	Opcional
`longitude`	`decimal`	Opcional

Respuesta

200

{
  "message": "Package replacement created successfully",
  "data": [
    {
      "partnerRef": "GH945214",
      "trackingNumber": "9F0FD9D5",
      "customerName": "Derrick Nti",
      "customerPhone1": "+233549632604",
      "customerPhone2": null,
      "sourceCountry": "Ghana",
      "sourceAddressLine1": "21 Abiriw Street",
      "sourceAddressLine2": null,
      "destinationCountry": "Ghana",
      "destinationRegion": "Greater Accra",
      "destinationCity": "Kwashieman",
      "destinationAddressLine1": "23 Abiriw Street",
      "destinationAddressLine2": null,
      "destinationPostalCode": null,
      "length": 30,
      "height": 20,
      "weight": 5.5,
      "description": "Test package",
      "labelUrl": null,
      "units": 1,
      "type": "box",
      "value": 20,
      "amountToCollect": 20,
      "paymentStatus": "unpaid",
      "handling": "normal",
      "specialInstructions": null,
      "status": "pending",
      "statusDescription": "Package is yet to be received by Partner",
      "latitude": null,
      "longitude": null,
      "receivedAt": null,
      "isReplacement": true,
      "action": "deliver",
      "items": [
        {
          "name": "Bluetooth",
          "quantity": 3
        }
      ],
      "rescheduledDate": null,
      "deliveredAt": null,
      "eta": null,
      "maxEta": null,
      "pickedAt": null,
      "packedAt": null,
      "cancelledAt": null,
      "trackingHistory": [
        {
          "name": "pending",
          "description": "Package is yet to be received by Partner",
          "date": "2026-05-04 12:16",
          "comment": null
        }
      ]
    },
    {
      "partnerRef": "GH545728",
      "trackingNumber": "A797CA0A",
      "customerName": "Kwabena Azaglo",
      "customerPhone1": "+233549632604",
      "customerPhone2": null,
      "sourceCountry": "Ghana",
      "sourceAddressLine1": "21 Abiriw Street",
      "sourceAddressLine2": null,
      "destinationCountry": "Ghana",
      "destinationRegion": "Greater Accra",
      "destinationCity": "Kwashieman",
      "destinationAddressLine1": "23 Abiriw Street",
      "destinationAddressLine2": null,
      "destinationPostalCode": null,
      "length": 30,
      "height": 20,
      "weight": 5.5,
      "description": "Test package",
      "labelUrl": null,
      "units": 1,
      "type": "box",
      "value": 20,
      "amountToCollect": 20,
      "paymentStatus": "unpaid",
      "handling": "normal",
      "specialInstructions": null,
      "status": "pending",
      "statusDescription": "Package is yet to be received by Partner",
      "latitude": null,
      "longitude": null,
      "receivedAt": null,
      "isReplacement": true,
      "action": "return",
      "items": [
        {
          "name": "Bluetooth",
          "quantity": 3
        }
      ],
      "rescheduledDate": null,
      "deliveredAt": null,
      "eta": null,
      "maxEta": null,
      "pickedAt": null,
      "packedAt": null,
      "cancelledAt": null,
      "trackingHistory": [
        {
          "name": "pending",
          "description": "Package is yet to be received by Partner",
          "date": "2026-05-04 12:16",
          "comment": null
        }
      ]
    }
  ]
}

Obtener Etiqueta del Paquete

GET /packages/{partnerRef}/print-label

Obtener la etiqueta de un paquete específico

Cabeceras

Parámetro	Tipo	Descripción
`Authorization`	`bearer`	Requerido.

Respuesta

200

{
  "message": "Label ready",
  "data": {
    "url": "https://d167icvhk5jowg.cloudfront.net/labels/20250410X51DIQ.pdf"
  }
}

202

{
  "message": "Label generation started. Please retry shortly.",
  "data": null
}

404

{
  "message": "Package not found",
  "data": null
}