Introduction

Welcome to the Proof Of Delivery API! You can use our API to access our API endpoints, which can get information on various invoice records, profiles of driver in our database.

To gain access to the APIs buy the KPOD service from the azure marketplace.

BASE URL: https://kpodportal.kaispe.com/api/v1/:companyName

Here, companyName is the sub url which is assigned to the buyer.

Authentication

Get Access Token

curl --location -g --request POST '{{BASE_URL}}/Auth/createOAuthToken' \
--header 'clientid: client-id' \
--header 'clientsecret: client-secret'

The above command returns JSON structured like this:

{
    "token_type": "Bearer",
    "expires_in": "4 hours",
    "accessToken": "accessToken"
}

This endpoint is used to get the JWT access token.

HTTP Request

POST {{BASE_URL}}/Auth/createOAuthToken

Header Parameters

Parameter	Description
clientid	The client id of the admin
clientsecret	The client secret of the admin

Authorization

To authorize, use this code:

curl "api_endpoint_here"
  -H "Authorization: accessToken"

Make sure to replace accessToken with the token you get by calling the Get Access Token API.

KPOD API uses a JWT token to allow access to the API which is retrieved by the Get Access Token API.

KPOD API expects for the token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer accessToken

You must replace accessToken with the token received from the Get Access Token API.

Invoice Records

Get All Invoices

curl --location -g '{{BASE_URL}}/Auth' \
--header 'Authorization: Bearer accessToken'

The above command returns JSON structured like this:

{
    "context": "",
    "value": [
        {
            "packageImages": [],
            "_id": "63c7ffe6a3341b00117d2cd8",
            "invoice": "AR028288_SO-Inv",
            "truckId": "TR",
            "deliveryDate": "2022-01-26T12:00:00.000Z",
            "dataAreaId": "bsi",
            "company": "BSI Steel (PTY) LTD",
            "salesUnit": "KG",
            "invoiceDate": "2022-01-19T12:00:00.000Z",
            "invoiceAmount": "0",
            "invoiceAmountMST": "0",
            "address": "73 Sardine Road\nGermiston\n1422",
            "grossWeight": "2300",
            "currencyCode": "",
            "customerName": "",
            "signatureImageUrl": "",
            "nameOfReceiver": "",
            "commentByReciver": "",
            "actualDateOfDelivery": "",
            "deliveryStatus": "notDelivered",
            "latitude": "24.922901096541818",
            "longitude": "67.10812835212685",
            "invoiceDetails": [
                {
                    "_id": "63c7ffe6a3341b00117d2cd9",
                    "invoice": "AR028288_SO-Inv",
                    "truckId": "TR",
                    "deliveryDate": "2022-01-26T12:00:00.000Z",
                    "dataAreaId": "bsi",
                    "companyName": "BSI Steel (PTY) LTD",
                    "invoiceAmountMST": "0",
                    "salesUnit": "KG",
                    "invoiceDate": "2022-01-19T12:00:00.000Z",
                    "invoiceAmount": "0",
                    "address": "73 Sardine Road\nGermiston\n1422",
                    "odataetag": "",
                    "name": "Slit Galvanised ISQ 230 Prime Z275  132.0x0.96",
                    "grossWeight": "2300",
                    "currencyCode": "ZAR",
                    "customerName": "Teichmann Steel (Pty) Ltd",
                    "itemId": "0012580",
                    "qty": "6786"
                }
            ]
        }
    ]
}

This endpoint retrieves all invoices.

HTTP Request

GET {{BASE_URL}}/Auth

Query Parameters

Parameter	Default	Required	Description
truckId		True	If value is given, the result will only consists of the invoices of the this specific truck id .

View all delivered invoices

curl --location -g '{{BASE_URL}}/Auth/history' \
--header 'Authorization: Bearer accessToken'

The above command returns JSON structured like this:

{
    "context": "",
    "value": [
        {
            "packageImages": [
                "[{filename: 3994222711306379-wallpaperflare.com_wallpaper.jpg, url: https://kspnmpod.blob.core.windows.net/profile/3994222711306379-wallpaperflare.com_wallpaper.jpg},{filename: 6915330357416125-wp6422756-4k-iphone-7-wallpapers.jpg,url: https://kspnmpod.blob.core.windows.net/profile/6915330357416125-wp6422756-4k-iphone-7-wallpapers.jpg}]"
            ],
            "_id": "639b236454dee229d84d3033",
            "invoice": "AR028289_SO-Inv",
            "truckId": "TR",
            "deliveryDate": "2022-01-26T12:00:00.000Z",
            "dataAreaId": "bsi",
            "company": "BSI Steel (PTY) LTD",
            "salesUnit": "EA",
            "invoiceDate": "2022-01-19T12:00:00.000Z",
            "invoiceAmount": "128528.37",
            "invoiceAmountMST": "128528.37",
            "address": "24 Harry Street \nRobertsham\nJohannesburg\n2130",
            "grossWeight": "2400",
            "currencyCode": "",
            "customerName": "",
            "signatureImageUrl": "",
            "nameOfReceiver": "receiver name",
            "commentByReciver": "Hello",
            "actualDateOfDelivery": "2022-01-19T12:00:00Z",
            "deliveryStatus": "delivered",
            "latitude": "24.922901096541818",
            "longitude": "67.10812835212685",
            "invoiceDetails": [
                {
                    "_id": "639b236454dee229d84d3034",
                    "invoice": "AR028289_SO-Inv",
                    "truckId": "TR",
                    "deliveryDate": "2022-01-26T12:00:00.000Z",
                    "dataAreaId": "bsi",
                    "companyName": "BSI Steel (PTY) LTD",
                    "invoiceAmountMST": "128528.37",
                    "salesUnit": "EA",
                    "invoiceDate": "2022-01-19T12:00:00.000Z",
                    "invoiceAmount": "128528.37",
                    "address": "24 Harry Street \nRobertsham\nJohannesburg\n2130",
                    "odataetag": "",
                    "name": "Sheet CR CQ Prime Dry  2450x1225x0.80",
                    "grossWeight": "2400",
                    "currencyCode": "ZAR",
                    "customerName": "Strut Africa (Pty) LTD",
                    "itemId": "0010870",
                    "qty": "270"
                }
            ],
            "imageRef": "6409d5c94285fc31184f0899"
        }
    ]
}

This endpoint retrieves all invoices.

HTTP Request

GET {{BASE_URL}}/Auth/history

Query Parameters

Parameter	Default	Required	Description
truckId		True	If value is given, the result will only consists of the invoices of the this specific truck id .

Post invoice data in bulk

curl --location -g '{{BASE_URL}}/Auth/new' \
--header 'Authorization: Bearer accessToken' \
--header 'Content-Type: application/json' \
--data '[
    {
        "invoice": "AR028288_SO-Inv",
        "truckId": "TR",
        "deliveryDate": "2022-01-26T12:00:00.000Z",
        "dataAreaId": "bsi",
        "company": "BSI Steel (PTY) LTD",
        "salesUnit": "KG",
        "invoiceDate": "2022-01-19T12:00:00.000Z",
        "invoiceAmount": "0",
        "invoiceAmountMST": "0",
        "address": "73 Sardine Road\nGermiston\n1422",
        "grossWeight": "2300",
        "currencyCode": "",
        "customerName": "",
        "signatureImageUrl": "",
        "nameOfReceiver": "",
        "commentByReciver": "",
        "actualDateOfDelivery": "",
        "deliveryStatus": "notDelivered",
        "latitude": "24.922901096541818",
        "longitude": "67.10812835212685",
        "invoiceDetails": [
            {
                "invoice": "AR028288_SO-Inv",
                "truckId": "TR",
                "deliveryDate": "2022-01-26T12:00:00.000Z",
                "dataAreaId": "bsi",
                "companyName": "BSI Steel (PTY) LTD",
                "invoiceAmountMST": "0",
                "salesUnit": "KG",
                "invoiceDate": "2022-01-19T12:00:00.000Z",
                "invoiceAmount": "0",
                "address": "73 Sardine Road\nGermiston\n1422",
                "odataetag": "",
                "name": "Slit Galvanised ISQ 230 Prime Z275  132.0x0.96",
                "grossWeight": "2300",
                "currencyCode": "ZAR",
                "customerName": "Teichmann Steel (Pty) Ltd",
                "itemId": "0012580",
                "qty": "6786"
            }
        ]
    }
]'

The above command returns status code message like this:

Created

This endpoint is used to insert invoices in bulk quantity.

HTTP Request

POST {{BASE_URL}}/Auth/new

Body Parameters

Parameter	Data Type	Required	Restrictions	Description
invoice	String	Yes	N/A	Invoice number
truckId	String	Yes	N/A	Unique identifier for the truck transporting the package
deliveryDate	Date	Yes	N/A	Date on which package was delivered
dataAreaId	String	Yes	N/A	Identifier for the geographical region
company	String	Yes	N/A	Company name
salesUnit	String	Yes	N/A	Unit responsible for sales
invoiceDate	Date	Yes	N/A	Date on which the invoice was generated
invoiceAmount	String	Yes	N/A	Amount charged in the invoice currency
invoiceAmountMST	String	Yes	N/A	Amount charged in the invoice currency after adjusting for taxes
address	String	Yes	N/A	Delivery address
grossWeight	String	Yes	N/A	Total weight of the package in kilograms
currencyCode	String	Yes	N/A	Currency code of the invoice amount
customerName	String	Yes	N/A	Name of the customer who placed the order
signatureImageUrl	String	No	N/A	URL of the signature image captured at the time of delivery
nameOfReceiver	String	No	N/A	Name of the person who received the package
commentByReciver	String	No	N/A	Any comments made by the receiver
actualDateOfDelivery	String	No	N/A	Actual date on which the package was delivered
deliveryStatus	Enum: ['delivered', 'notDelivered']	Yes	N/A	Status of the package delivery
latitude	String	No	N/A	Latitude coordinate of the delivery location
longitude	String	No	N/A	Longitude coordinate of the delivery location
imageRef	ObjectId	No	N/A	Reference to the signature image in the database
packageImages	Array	No	N/A	Array of URLs of images of the package
invoiceDetails	Array of Objects	Yes	N/A	Array of objects containing details of the invoice
- invoice	String	Yes	N/A	Invoice number
- truckId	String	Yes	N/A	Unique identifier for the truck transporting the package
- deliveryDate	Date	Yes	N/A	Date on which package was delivered
- dataAreaId	String	Yes	N/A	Identifier for the geographical region
- companyName	String	Yes	N/A	Company name
- invoiceAmountMST	String	Yes	N/A	Amount charged in the invoice currency after adjusting for taxes
- salesUnit	String	Yes	N/A	Unit responsible for sales
- invoiceDate	Date	Yes	N/A	Date of the invoice
- invoiceAmount	String	Yes	N/A	Total amount of order
- address	String	Yes	N/A	Delivery address
- odataetag	String	Yes	N/A	The tag of odataetag
- name	String	No	N/A	Name of the person who received the package
- grossWeight	String	Yes	N/A	Total weight of the package in kilograms
- currencyCode	String	Yes	N/A	Currency code of the invoice amount
- customerName	String	Yes	N/A	Unit responsible for sales
- invoiceDate	String	Yes	N/A	Name of the customer
- itemId	String	Yes	N/A	The id of the item
- qty	String	Yes	N/A	The quantity of the item

Uploading package images

curl --location -g '{{BASE_URL}}/Auth/uploadPackageImages' \
--header 'Authorization: Bearer accessToken' \
--form 'packageImages=@"/image.jpg"'

The above command returns status code message like this:

[
    {
        "filename": "image.jpg",
        "url": "https://kspnmpod.blob.core.windows.net/packageimages/image.jpg"
    }
]

This endpoint is used to upload the package images to upload to cloud

HTTP Request

POST {{BASE_URL}}/Auth/uploadPackageImages

Body Parameters

Parameter	Data Type	Required	Restrictions	Description
packageImages	Media	Yes	Supported extension: png, jpg, jpeg and max 5 files allowed	The images of the package.

Changing invoice staus to delivered

curl --location -g '{{BASE_URL}}/Auth/upload' \
--header 'Authorization: Bearer accessToken' \
--form 'Name="Receiver"' \
--form 'Comments="Order was good"' \
--form 'DataAreaId="D1"' \
--form 'TruckId="TR"' \
--form 'FileName="file1"' \
--form 'FileData="filed1"' \
--form 'InvoiceNo="AR028288_SO-Inv"' \
--form 'actualDateOfDelivery="2022-01-19T12:00:00Z"' \
--form 'packageImages="[{\"filename\": \"image.jpg\", \"url\": \"https://kspnmpod.blob.core.windows.net/packageimages/image.jpg\"}]"'

The above command returns status code message like this:

{
    "successfull": true
}

This endpoint is used to upload the package, signature image url and change invoice delivery status

HTTP Request

POST {{BASE_URL}}/Auth/upload

Body Parameters

Parameter	Data Type	Required	Restrictions	Description
name	String	Yes	N/A	The name of the receiver with the package or delivery.
comments	String	No	N/A	Comments given by receiver.
dataAreaId	String	Yes	N/A	The
truckId	String	Yes	N/A	The identifier for the truck or vehicle associated with the package or delivery.
fileName	String	No	N/A	The name of the signed image associated with the package or delivery.
fileData	String	No	N/A	The data of the signed image decoded associated with the package or delivery.
invoiceNo	String	No	N/A	The invoice number associated with the package or delivery.
actualDateOfDelivery	String	No	N/A	The actual date of delivery for the package.
packageImages	Array	No	N/A	An array of package images associated with the package or delivery.

Driver Profile

Create profile

curl --location -g '{{BASE_URL}}/profile/create' \
--header 'Authorization: Bearer accessToken' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Truck Driver",
    "password": "pass123",
    "truckId": "TR",
    "profile_image": "http://url.com",
    "phoneNumber": "123456",
    "address": "this one"
}'

The above command returns status code message like this:

{ "message": "Profile image updated successfully" }

This endpoint is used to create a driver profile

HTTP Request

POST {{BASE_URL}}/profile/create

Body Parameters

Parameter	Data Type	Required	Restrictions	Description
name	String	Yes		The name of the user
password	String	Yes		The password of the user
truckId	String	Yes	Unique	The unique id of the user
phoneNumber	String			The contact number of the user
address	String	Yes		The address of the user
profile_image	String	Yes		The profile image of the user

Get all driver profiles

curl --location -g '{{BASE_URL}}/profile/viewAll/profiles' \
--header 'Authorization: Bearer accessToken'

This endpoint is used to get the specific driver profile

[{
    "_id": "63f31e65b2bad7276c3716d1",
    "name": "truck rider",
    "password": "$2b$10$NMsbQcx6P3Wy4nYpClYidePZlCsuE4n7hMvG6Y/SsZCqlHuo.rXRe",
    "truckId": "TR",
    "phoneNumber": "123456",
    "address": "this one",
    "licenseNo": "233-SD",
    "profile_image": "https://kspnmpod.blob.core.windows.net/profile/6239398899617339-casey-horner-JNHrBVfdT_A-unsplash.jpg"
}]

HTTP Request

GET {{BASE_URL}}/profile/viewAll/profiles

Get the driver profile

curl --location -g '{{BASE_URL}}/profile/:truckId' \
--header 'Authorization: Bearer accessToken'

This endpoint is used to get the specific driver profile

{
    "_id": "63f31e65b2bad7276c3716d1",
    "name": "truck rider",
    "password": "$2b$10$NMsbQcx6P3Wy4nYpClYidePZlCsuE4n7hMvG6Y/SsZCqlHuo.rXRe",
    "truckId": "TR",
    "phoneNumber": "123456",
    "address": "this one",
    "licenseNo": "233-SD",
    "profile_image": "https://kspnmpod.blob.core.windows.net/profile/6239398899617339-casey-horner-JNHrBVfdT_A-unsplash.jpg"
}

HTTP Request

GET {{BASE_URL}}/profile/:truckId

URL Parameters

Parameter	Description
truckId	The truck id of the driver given

Update the driver profile

curl --location -g --request PATCH '{{BASE_URL}}/profile/:truckId' \
--header 'Authorization: Bearer accessToken' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Truck Driver",
    "email": "tr@email.com",
    "password": "pass123",
    "phoneNumber": "123456",
    "address": "this one",
    "truckId": "TR",
    "licenseNo": "TRL",
    "profile_image": "http://url.com"
}'

The above command returns JSON structured like this:

{ 
  "message": "User updated successfully"
}

This endpoint is used to update the specific driver profile

HTTP Request

PATCH {{BASE_URL}}/profile/:truckId

URL Parameters

Parameter	Description
truckId	The truck id of the driver should be given

Body Parameters

Parameter	Data Type	Required	Restrictions	Description
name	String	Yes		The name of the user
password	String	Yes		The password of the user
truckId	String	Yes	Unique	The unique id of the user
phoneNumber	String			The contact number of the user
address	String	Yes		The address of the user
profile_image	String	Yes		The profile image of the user

Delete the driver profile

curl --location -g --request DELETE '{{BASE_URL}}/profile/:truckId' \
--header 'Authorization: Bearer accessToken'

The above command returns JSON structured like this:

{ 
  "message": "User deleted successfully"
}

This endpoint is used to delete the specific driver profile

HTTP Request

DELETE {{BASE_URL}}/profile/:truckId

URL Parameters

Parameter	Description
truckId	The truck id of the driver should be given

Upload profile image

curl --location -g '{{BASE_URL}}/profile/image/:truckId' \
--header 'Authorization: Bearer accessToken' \
--form 'profileImage=@"/image.jpg"'

The above command returns status code message like this:

{ "message": "Profile image updated successfully" }

This endpoint is used to upload driver profile image

HTTP Request

POST {{BASE_URL}}/profile/image/:truckId

URL Parameters

Parameter	Description
truckId	The truck id of the driver profile

Body Parameters

Parameter	Data Type	Required	Restrictions	Description
profileImage	Media type	Yes	Extension supported: jpg, jpeg, png	The image of the user