Get Started

Welcome to the Ainsoft Delivery API documentation. This guide will help you integrate our delivery services into your application.

Overview

The Ainsoft Delivery API provides programmatic access to send orders, receive order status, manage address lists, and track deliveries. Our RESTful API is designed to be simple, secure, and reliable.

API Key Required: To use this API, you need an API key (Client No). Contact us at info@ainsoftsolutions.com to get your API key.

Base URL

GET https://api.ainsoftdelivery.com/

Test Credentials

TEST Client No: CL21

Get Status List

Retrieve the list of available delivery statuses for tracking orders.

GET /GetIntegrationStatus

Returns a list of all available delivery statuses with their IDs and keywords.

Request

Headers 
{
"Accept": "application/json",
"Content-Type": "application/json"
}

Response

Example Response 
{
  "result": [
    {
      "Id": 1,
      "Keyword": "DLV",
      "Name": "Delivered"
    },
    {
      "Id": 2,
      "Keyword": "RTN",
      "Name": "Return"
    },
    {
      "Id": 3,
      "Keyword": "CNL",
      "Name": "Cancelled"
    }
  ]
}

Get Emirates List

Retrieve the list of available emirates for delivery locations.

GET /GetEmirates

Returns a list of all available emirates with their IDs and names.

Request

Headers 
{
"Accept": "application/json",
"Content-Type": "application/json"
}

Response

Example Response 
{
  "result": [
    {
      "Id": 1,
      "Name": "Dubai"
    },
    {
      "Id": 2,
      "Name": "Sharjah"
    },
    {
      "Id": 3,
      "Name": "Ajman"
    }
  ]
}

Get Locations by Emirate

Retrieve locations within a specific emirate for precise delivery addressing.

GET /GetLocationsByEid/{EmirateId}

Returns a list of locations within the specified emirate.

Path Parameters

Parameter Type Required Description
EmirateId number Yes Emirate ID from the emirates list API

Request

Headers 
{
"Accept": "application/json",
"Content-Type": "application/json"
}

Response

Example Response 
{
  "result": [
    {
      "Id": 1,
      "Name": "Deira"
    },
    {
      "Id": 2,
      "Name": "International City"
    },
    {
      "Id": 3,
      "Name": "Al Quoz"
    }
  ]
}

Save Address

Create and send a new client / store address to the delivery company.

POST /RegisterClientAddress

Sends a new address with customer details and address information.

Request Body Parameters

Parameter Type Required Description
ClientNo string Yes Client number/API key
EmirateId number Yes Emirate ID from emirate list
LocationId string Yes Location Id from location list
POBOX string Yes Po box number
StoreNo string Yes Unique store identifier number from client
Address string Yes Complete address description
LocationUrl string No Google map location url
ContactNo string Yes Particular store contact number

Request

Headers 
{
"Accept": "application/json",
"Content-Type": "application/json"
}
Request Body 
{
  "ClientNo": "CL21",
  "EmirateId": "1",
  "LocationId": 1,
  "POBOX": "12345",
  "StoreNo": "12345",
  "Address": "123 Main Street, Building A",
  "LocationUrl": "https://www.google.com/maps/place/123+Main+Street,+Building+A",
  "ContactNo": "0501234567"
}

Response

Success Response 
{
  "Success": "Address saved successfully",
  "Error": "Client information not found. Please check ClientNo."
}
Error Response 
{
  "Error": "Network Failed, Please Try Again"
}

Update Address

Update existing client / store address to the delivery company.

POST /updateClientAddress

update existing address with customer details and address information.

Request Body Parameters

Parameter Type Required Description
ClientNo string Yes Client number/API key
Id number Yes Existing Address Id
EmirateId number Yes Emirate ID from emirate list
LocationId string Yes Location Id from location list
POBOX string Yes Po box number
StoreNo string Yes Unique store identifier number from client
Address string Yes Complete address description
LocationUrl string No Google map location url
ContactNo string Yes Particular store contact number

Request

Headers 
{
"Accept": "application/json",
"Content-Type": "application/json"
}
Request Body 
{
  "ClientNo": "CL21",
  "Id": 1,
  "EmirateId": "1",
  "LocationId": 1,
  "POBOX": "12345",
  "StoreNo": "12345",
  "Address": "123 Main Street, Building A",
  "LocationUrl": "https://www.google.com/maps/place/123+Main+Street,+Building+A",
  "ContactNo": "0501234567"
}

Response

Success Response 
{
  "Success": "Address updated successfully",
  "Error": "Client information not found. Please check ClientNo.",
  "Error": "Address not found"
}
Error Response 
{
  "Error": "Network Failed, Please Try Again"
}

Get Address List

Retrieve the list of saved addresses for a specific client.

GET /GetMyAddressList/{ClientNo}

Returns a list of all saved addresses for the specified client.

Path Parameters

Parameter Type Required Description
ClientNo string Yes Client number/API key from the delivery company

Request

Headers 
{
  "Accept": "application/json",
  "Content-Type": "application/json"
}

Response

Example Response 
{
  "result": [
    {
      "Id": 1,
      "Address": "Office 123, Test Address",
      "Emirate": {
        "Id": 1,
        "Name": "Dubai"
      },
      "Location": {
        "Id": 1,
        "Name": "Deira"
      },
      "POBOX": "1B22",
      "StoreNo": "12345",
      "IsDefault": true
    }
  ]
}

Send Order

Create and send a new delivery order to the delivery company.

POST /SendOrder

Sends a new delivery order with customer details and delivery information.

Request Body Parameters

Parameter Type Required Description
ClientNo string Yes Client number/API key
ClientAddressId number Yes Address ID from address list
PayType string Yes CAD or COD payment type
IsFragile boolean Yes Whether items are fragile
Quantity number Yes Total items in parcel
ClientBillNo string Yes Order invoice number
Remarks string No Order instructions and notes
PickupDate string Yes Order pickup date (DD/MM/YYYY)
DeliveryDate string Yes Order delivery date (DD/MM/YYYY)
ProductPrice number Yes Collection amount from receiver
Customer.Name string Yes Receiver name
Customer.MobileNo1 string Yes Primary mobile number
CustomerAddress.EmirateId number Yes Receiver emirate ID
CustomerAddress.LocationId number Yes Receiver location ID
CustomerAddress.Address string Yes Complete delivery address

Request

Headers 
{
"Accept": "application/json",
"Content-Type": "application/json"
}
Request Body 
{
  "ClientNo": "CL21",
  "ClientAddressId": 1,
  "PayType": "COD",
  "IsFragile": false,
  "Quantity": 1,
  "ClientBillNo": "INV-001",
  "Remarks": "Handle with care",
  "PickupDate": "25/02/2024",
  "DeliveryDate": "26/02/2024",
  "ProductPrice": 100.00,
  "Customer": {
    "Name": "John Doe",
    "MobileNo1": "0501234567",
    "EmailId": "john@example.com"
  },
  "CustomerAddress": {
    "EmirateId": 1,
    "LocationId": 1,
    "Address": "123 Main Street, Building A",
    "POBOX": "12345"
  }
}

Response

Success Response 
{
  "result": {
    "Status": "Success",
    "VoucherNo": "OD345",
    "Message": "Order created successfully"
  }
}
Error Response 
{
  "result": {
    "Status": "Error",
    "VoucherNo": "",
    "Message": "Invalid client number"
  }
}

Track Order

Track the status and progress of a specific delivery order.

GET /TrackClientVoucher/{VoucherNo}/{ClientNo}

Returns the current status and tracking information for a specific order.

Path Parameters

Parameter Type Required Description
VoucherNo string Yes Voucher number from order creation
ClientNo string Yes Client number/API key

Request

Headers 
{
"Accept": "application/json",
"Content-Type": "application/json"
}

Response

Example Response 
{
  "result": {
    "Date": "25/02/2024",
    "DeliveryDate": "26/02/2024",
    "PickupDate": "25/02/2024",
    "Quantity": 1,
    "DeliveryStatus": "In Transit",
    "VoucherNo": "OD4433",
    "StatusList": [
      {
        "StatusName": "In Transit",
        "Keyword": "INS"
      },
      {
        "StatusName": "Delivered",
        "Keyword": "DLV"
      }
    ]
  }
}

Update Order Status

Response back API to send order status updates to the ecommerce website. Client needs to create an endpoint with the exact structure specified.

POST https://{yourdomain}/UpdateOrderStatus/{voucher_no}/{status_name}/{status_key}

This endpoint allows the delivery company to send order status updates back to the ecommerce website. The client must implement this endpoint on their server to receive status updates.

Path Parameters

Parameter Type Required Description
voucher_no string Yes Order voucher number from the original order
status_name string Yes Human-readable status name (e.g., "Delivered", "In Transit")
status_key string Yes Status keyword identifier (e.g., "DLV", "INS")
Implementation Required: The client must create this endpoint on their server to receive status updates from the delivery company. The endpoint should handle the POST request and update the order status in their system.

Example Request

POST Request 
POST https://yourdomain.com/UpdateOrderStatus/OD345/Delivered/DLV

Expected Response

Success Response 

 true

Cancel Order

Cancel a delivery order that is currently in the system.

GET /CancelPortalOrder/{VoucherNo}/{ClientNo}

Cancels a delivery order if it's not already in process. Returns success message or specific error details.

Path Parameters

Parameter Type Required Description
VoucherNo string Yes Order voucher number to cancel
ClientNo string Yes Client number/API key

Request

Headers 
{
"Accept": "application/json",
"Content-Type": "application/json"
 }

Response

Success Response 
"Success"
Error Responses 
// Possible error responses:
"Account Not Found"
"Account Not Authorised"
"Order Not Found"
"Order In Process"
"Network Error"
Note: Orders can only be cancelled if they are not already in process. Once an order is picked up or in transit, it cannot be cancelled.