API Documentation

Introduction

Welcome to the API documentation. This document outlines the key features and usage guidelines for integrating with our API.

Base URL

https://swiftpikup.com/api/v1/vendor

Error Codes

400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
500 - System Error

Login API

Request Parameters

Element	Format	Comments	Mandatory/ Optional
email	String	User's email address	Mandatory
password	String	App password. you can genreate from you panel	Mandatory

Request Example

POST /login
Content-Type: application/json
Body: {
    "email": "user@example.com",
    "password": "apppassword"
}

Response Example

Status: 200 OK
{
    "success": true,
    "message": "Login successful",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Country API

Request Parameters

GET /country-list

Response Example

Status: 200 OK
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Nigeria",
            "code": "NG",
            "distance_type": "km",
            "weight_type": "kg",
            "status": 1,
            "links": null,
            "created_at": "2024-12-21T01:06:19.000000Z",
            "updated_at": "2024-12-21T01:06:19.000000Z",
            "deleted_at": null
        }
    ]
}

City API

Request Parameters

Element	Format	Comments	Mandatory/ Optional
country_id	Integer	Country ID referred from country api	Mandatory

GET /city-list

Response Example

Status: 200 OK
{
    "success": true,
    "data": [
        {
            "id": 5,
            "name": "Abuja",
            "country_id": 1
        },
        {
            "id": 4,
            "name": "Enugu",
            "country_id": 1
        },
        {
            "id": 1,
            "name": "Lagos",
            "country_id": 1
        }
    ]
}

Vehicle API

Request Parameters

GET /vehicles

Response Example

Status: 200 OK
{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "BIKE",
            "type": "all",
            "capacity": "50",
            "description": "Motorcycle",
            "min_km": 1,
            "size": "Bike",
            "price": 1900,
            "per_km_charge": 100
        },
        {
            "id": 2,
            "name": "TRUCK",
            "type": "all",
            "capacity": "2000kg",
            "description": "Delivery Truck For Heavy loads",
            "min_km": 1,
            "size": "500 inches",
            "price": 5000,
            "per_km_charge": 450
        }
    ]
}

Parcel Type API

Request Parameters

GET /parcel-list

Response Example

Status: 200 OK
{
    "success": true,
    "data": [
        {
            "label": "Drinks"
        },
        {
            "label": "Food"
        },
        {
            "label": "Electronics"
        },
        {
            "label": "Shoes and bags"
        },
        {
            "label": "Medications"
        },
        {
            "label": "Package"
        }
    ]
}

Get Quote API

Request Parameters

Element	Format	Comments	Mandatory/ Optional
city	Integer	City Id referred from city api	Mandatory
vehicle_id	Integer	Vehicle Id referred from vehicle api	Mandatory
total_weight	double	Total Weight of parcel	Mandatory
total_distance	double		Mandatory
is_insurance	Integer	0/1	Mandatory

Request Example

                POST /calculatetotal-get
Content-Type: application/json
Body: {
    {
        "city_id": 3,
        "vehicle_id": 1,
        "total_weight":1.0,
        "total_distance":"22",
        "is_insurance":false,
        "insurance_amount":0
    }
}

Response Example

Status: 200 OK
{
    {
        "fixed_amount": 10,
        "weight_amount": 0,
        "distance_amount": 0,
        "extra_charges": [
            {
                "key": "gst",
                "value": 5,
                "value_type": "percentage"
            },
            {
                "key": "sgst",
                "value": 7,
                "value_type": "percentage"
            }
        ],
        "vehicle_amount": 4000,
        "insurance_amount": 0,
        "diff_weight": 0,
        "diff_distance": 21,
        "total_amount": 4010,
        "base_total": 4010
    }
}

Create Order API

Request Parameters

Element	Format	Comments	Mandatory/ Optional
date	datetime	Y-m-d H:i:s	Mandatory
customer	Object (JSON)	Contains customer information such as name, mobile number, and email ID. \|\| Required Details: email_id
country_id	Integer	Country Id referred from country api	Mandatory
city_id	Integer	City Id referred from city api	Mandatory
vehicle_id	Integer	Vehicle Id referred from vehicle api	Mandatory
extra_charges	Array (JSON)	Extra charges for the order, e.g., GST.	Optional
pickup_point	Object (JSON)
start_time	datetime	From Date
end_time	datetime	To Date
address	String	Pickup Address	Mandatory
latitude	String	Pickup location latitude	Mandatory
longitude	String	Pickup location longitude	Mandatory
name	String	Name	Mandatory
description	String		Optional
instruction	String		Optional
contact_number	String	Contact No. of pickup point	Optional
End of Pickup point
delivery_point	Object (JSON)
start_time	datetime	From Date
end_time	datetime	To Date
address	String	Delivery Address	Mandatory
latitude	String	Delivery location latitude	Mandatory
longitude	String	Delivery location longitude	Mandatory
name	String	Name	Mandatory
description	String		Optional
instruction	String		Optional
contact_number	String	Contact No. of delivery point	Optional
End of Delivery point
parcel_type	String	Type of parcel being shipped, e.g., documents, electronics.	Mandatory
total_weight	double	Total weight of the parcel in kilograms.	Mandatory
total_distance	double		Mandatory
payment_collect_from	String	valid details: on_pickup,on_delivery.	Mandatory
payment_type	String	Method of payment, either online or cash on delivery. \|\| valid details: cash,online.	Mandatory
total_parcel	Integer	Total Number of Parcel
is_insurance	Integer	0/1	Mandatory
packaging_symbols	Array (JSON)	A list of packaging symbols for the parcel, each containing a title and key. \|\| valid details: this_way_up,do_not_stack,temperature_sensitive,do_not_use_hooks,explosive_material,hazardous_material,bike_delivery,keep_dry,perishable,recycle,do_not_open_with_sharp_objects,fragile	Optional

Request Example

POST /orders
Content-Type: application/json
Body: {
  "date": "2025-02-19 15:10:35",
  "customer":{
        "name":"",
        "mobile_number":"",
        "email_id":""
    },
  "country_id": "3",
  "city_id": "3",
  "vehicle_id": "1",
  "pickup_point": {
    "start_time": "2025-04-15 12:56:05.498639",
    "end_time": null,
    "address": "address",
    "latitude": "XX.XXXXXX",
    "longitude": "XX.XXXXX",
    "name": "name",
    "description": null,
    "instruction": null,
    "contact_number": "XXXXXXXX"
  },
  "delivery_point": {
    "start_time": null,
    "end_time": null,
    "address": "address",
    "latitude": "XX.XXXXXX",
    "longitude": "XX.XXXXX",
    "description": null,
    "name": "name",
    "instruction": null,
    "contact_number": "XXXXXXXX"
  },
  "extra_charges" :[
        {
            "key": "gst",
            "value": 10,
            "value_type": "fixed"
        },
        {
            "key": "sgst",
            "value": 2,
            "value_type": "percentage"
        }
    ],
  "packaging_symbols": [
        {"title": "Do Not Use Hooks", "key": "do_not_use_hooks"},
        {"title": "Bike Delivery", "key": "bike_delivery"},
        {"title": "Hazardous Material", "key": "hazardous_material"}
    ]
  
  "parcel_type": "Medications",
  "total_weight": 1.0,
  "total_distance": "22.90",
  "payment_collect_from": "on_pickup",
  "payment_type": null,
  "total_parcel": 1,
  "is_insurance": false
}

Response Example

Status: 200 OK
 {
    "success": true,
    "order_id": 513,
    "message": "Order has been saved successfully"
}

Error Response Example

When a customer's email is null, the API will return a response with an appropriate status and message.

{
    "message": "Email Required",
    "success": false
}

When a customer's Details is null, the API will return a response with an appropriate status and message.

{
    "message": "Please Fill Customer Details Is Valid",
    "success": false
}

When a Pickup Delivery Details is null, the API will return a response with an appropriate status and message.

{
    "message": "Please Fill Valid Delivery Point",
    "success": false
}

When a Enter Minus Value, the API will return a response with an appropriate status and message.

{
    "message": "Invalid Value Minus",
    "success": false
}

When a Enter Packaging Symbols Invalid, the API will return a response with an appropriate status and message.

{
    "message": "Packaging_Symbols_Invalid",
    "success": false,
    "invalid_keys": [
        "recycleppppppppp"
    ]
}

Pay Order API

Request Parameters

Element	Format	Comments	Mandatory/ Optional
order_id	integer		Mandatory
payment_method	string	flutterwave	Mandatory

Note: Set callback url for pay order while generating Api key

Request Example

POST /pay-order
Content-Type: application/json
Body: {
    "order_id": "xxx",
    "payment_method": "flutterwave",   
}

Response Example

Status: 200 OK
 {
    "success": true,
    "message": "Order payment created",
    "payment_link": "",
    "order_id": xxx
}

Payment Callback API

Request Parameters

Element	Format	Mandatory/ Optional
status	string	Mandatory
tx_ref	string	Mandatory
transaction_id	string	Mandatory

Request Example

POST /pay/callback
Content-Type: application/json
Body: {
    "status": "successful",
    "tx_ref": "SWP-406",
    "transaction_id": "9272254"
}

Response Example

Status: 200 OK
 {
    "success": true,
    "order_id": 406,
    "payment_detail": {
        "tx_id": 9272254,
        "tx_ref": "SWP-406",
        "amount": 20,
        "currency": "NGN",
        "payment_type": "card",
        "created_at": "2025-05-14T07:21:03.000Z",
        "processor_response": "Approved. Successful"
    },
    "message": "Payment created successfully"
}