API Documentation

Welcome to the FC Express Logistics API. This set of endpoints allows you to programmatically manage the entire logistics lifecycle—from authenticating users and creating shipments to tracking real-time status updates and handling cancellations.

Environment Configuration

Base URL: https://test.fcexpressgh.com

Authentication

Security is handled via JSON Web Tokens (JWT). Aside from the initial Login request, every API call must include a valid token in the HTTP headers.

                            HTTP Header
                            Required
                        
                            Authorization: Bearer <your_jwt_token>

Endpoint Reference

POST /api/collections/clients/auth-with-password

Client Login

Authenticate a user to receive an access token.

Critical Integration Step

The response contains a record object. You must extract the id from this object and use it as the client_id in the body of all shipment creation requests.

Request Body

{
  "identity": "client@example.com",
  "password": "super_secure_password"
}

Success Response (200 OK)

{
  "token": "eyJhbGciOiJIUzI1Ni...",
  "record": {
    "id": "6nsy5tql8ckjoe2", // Save this as client_id
    "email": "client@example.com",
    "name": "John Doe"
  }
}

POST /api/external/create-shipment

Create Shipment

Request Payload

{
  "client_id": "6nsy5tql8ckjoe2", // From login response
  "sender_name": "John Doe",
  "sender_phone_number": "+233123456789",
  "pickup_address": "123 Main St",
  "pickup_city": "Accra",
  "pickup_region": "Greater Accra",
  "receiver_name": "Jane Smith",
  "receiver_phone_number": "+233987654321",
  "delivery_address": "456 Oak Ave",
  "delivery_city": "Kumasi",
  "courier_type": "bike", // Options: bike, van, truck
  "packages": [
    {
      "description": "Electronics",
      "quantity": 1,
      "weight": 2.5
    }
  ]
}

Success Response (200 OK)

{
  "message": "Shipment created successfully",
  "shipment_id": "6ev9jntzpmca9we",
  "tracking_number": "FCX1327396762",
  "price": "864",
  "status": "pending_pickup"
}

GET /api/collections/shipments/records

Get All Client Shipments

Retrieve a paginated history of your shipments.

Query Param	Type	Description
page	int	Page number (default: 1)
perPage	int	Items per page (default: 30)
sort	string	Sort field (e.g., '-created')

Response Format

{
  "page": 1,
  "perPage": 30,
  "totalItems": 15,
  "items": [
    {
      "id": "d6pg4tjmpq8il22",
      "track_code": "FCX1094074222",
      "status": "cancelled",
      "delivery_city": "Accra",
      "price": 29.96
    }
  ]
}

GET /api/collections/shipments/records/:id

Get Single Shipment Details

Fetch comprehensive details for a specific shipment ID.

Example Response

{
  "id": "6ev9jntzpmca9we",
  "track_code": "FCX1327396762",
  "status": "cancelled",
  "pickup_address": "123 Main St",
  "delivery_address": "456 Oak Ave",
  "price": 864,
  "courier_type": "bike"
}

POST /api/external/shipments/cancel/:shipment_id

Cancel Shipment

Cancel an active shipment. Cannot cancel delivered items.

No Body Required - Pass the ID in the URL path.

Response

{
  "message": "shipment cancelled successfully"
}

GET /api/external/shipments/shipment-status-list/:shipment_id

Get Shipment Status Timeline

Retrieve the full audit trail and status history of a shipment.

Response Object

{
  "data": [
    {
      "status": "at_facility",
      "reason": "Shipment dropped of at Dansoman",
      "created": "2024-11-12 08:43:22.944Z",
      "geo_coordinates": "5.617,-0.176"
    },
    {
      "status": "in_transit",
      "reason": "Picked up by courier",
      "created": "2024-11-11 15:23:32.246Z"
    }
  ],
  "message": "shipment status list fetched successfully"
}

Implementation Guide

Copy-paste ready code for your application.

Select Endpoint

1. Login

2. Create

3. List All

4. Details

5. Cancel

6. Status List

// Select an operation to see the code

// Select an operation to see the code

# Select an operation to see the code