Skip to main content

Intro to APIs for Logistics Agents

As a logistics agent working with Xpress Global Systems (XGS), you play a critical role in managing and handling shipments on our behalf. Efficiently tracking shipments, updating statuses, handling proof of delivery documentation(POD), schduling appointments and managing exceptions are essential responsibilities to ensure smooth operations and maintain effective communication with XGS and its customers.

In this guide, we’ll walk through a series of API endpoints designed to help logistics agents manage every stage of a shipment’s lifecycle. From dispatch to proof of delivery, these APIs provide the tools needed to keep operations between XGS and its partners transparent and up-to-date.

Understanding the Shipment Lifecycle for Agents​

As an XGS logistics agent, your primary responsibilities in the shipment lifecycle include:

  1. Retrieving Dispatches: Accessing the list of dispatched shipments assigned to you by XGS.
  2. Tracking and Status Updates: Keeping XGS and its customers informed with timely status updates.
  3. Proof of Delivery (POD): Providing delivery confirmation when shipments reach their final destinations.
  4. Exception Management: Reporting and handling any issues that arise during transport.
  5. Appointment Scheduling: Scheduling delivery appointments when required by XGS.

Let’s explore how each API endpoint can support you in managing these tasks efficiently.

1. Accessing Dispatched Shipments​

To begin, you'll want to retrieve a list of shipments (probills) dispatched to you by XGS. The GET /agent/probill/live/list endpoint provides a real-time list of these active shipments, helping you stay organized and prepared.

Example Usage:

GET /agent/probill/live/list

By using this endpoint, you’ll get an up-to-date list of all probills assigned to you. This is particularly useful for your dispatch dashboard, allowing you to see shipments that need to be managed.

2. Retrieving Shipment Details​

Once you have the list of dispatched shipments, you may need to access specific details for each probill. The GET /agent/probill endpoint allows you to fetch detailed information about a specific shipment, including pickup and delivery locations, estimated delivery time, and other shipment-related information.

Example Usage:

GET /agent/probill?probillNumber=12345678

This endpoint ensures you have all necessary details at your fingertips, enabling you to keep XGS informed and providing any required data for further processing.

3. Updating Shipment Status​

As you manage shipments, it’s important to provide real-time status updates to XGS. The POST /agent/probill/status endpoint lets you update the status of a probill, marking important milestones like "Picked Up" or "Out for Delivery".

Example Usage:

POST /agent/probill/status
Content-Type: application/json

{
    "probillNumber": "12345678",
    "status": "In Transit"
}

By using this endpoint, you can ensure that XGS is aware of the current status of each shipment you’re handling, maintaining transparency and keeping operations on track.

4. Arriving a Manifest​

When a shipment or group of shipments arrives at the agent terminal, the POST /agent/manifest/arrive endpoint allows you to mark the manifest as "Arrived." This signals to XGS that the shipments on the manifest has reached an agent terminal, triggering subsequent workflows with XGS systems.

Example Usage:

POST /agent/manifest/arrive
Content-Type: application/json

{
    "manifestNumber": "67890"
}

This endpoint helps XGS stay informed about the movement of shipments through key transit points, helping streamline operations and communication.

5. Submitting Proof of Delivery (POD)​

When you complete a delivery, confirming it with a proof of delivery (POD) is essential. The POST /agent/probill/pod endpoint allows you to submit a POD image and mark the probill status as "Delivered." This update ensures that XGS has a record of delivery, complete with a POD signature for verification purposes.

Example Usage:

POST /agent/probill/pod
Content-Type: application/json

{
    "probillNumber": "12345678",
    "podImage": "base64_encoded_image_data"
}

This endpoint is crucial for documenting successful deliveries and providing accountability in case of any future queries or disputes.

6. Scheduling Delivery Appointments​

In cases where an appointment is needed for delivery, the agent is expected to schedule the appointment by contacting the consignee and share the agredd upon delivery date-time and other infomation with XGS. Tthe POST /agent/probill/appointment endpoint allows you to share the appointment information with XGS.

Example Usage:

POST /agent/probill/appointment
Content-Type: application/json

{
    "probillNumber": "12345678",
    "appointmentTime": "2024-11-10T10:00:00Z"
}

This endpoint helps you keeps XGS infromed about the delivery appointment so that XGS can update the ETA with the new delivery date.

7. Reporting Exceptions​

Issues like damaged items can occur unexpectedly. The POST /agent/probill/exception endpoint allows you to report these exceptions, documenting any problems that arise during shipment handling.

Example Usage:

POST /agent/probill/exception
Content-Type: application/json

{
    "probillNumber": "12345",
    "exceptionReason": "Damaged goods",
    "notes": "Box damaged upon arrival"
}

This endpoint ensures XGS is notified of any issues, enabling them to take corrective actions or provide additional support as needed.