Introduction

Welcome to the Link Express API! You can use our API to access Link Express API endpoints.

Authentication

# With shell, you can just pass the correct header with each request
curl "https://apigw.mylinkexpress.com/api" \
  -H "X-API-KEY: API_KEY"

Link Express uses API keys to allow access to the API. You can register a new user for a key.

Link Express expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-API-KEY: API_KEY

You must replace API_KEY with your personal API key.

Senders

Get All Senders

curl "https://apigw.mylinkexpress.com/api/senders" \
  -H "X-API-KEY: API_KEY"

[
    {
        "id": "15414b28-ccb3-4a48-9fd8-08dcdd2ac83f",
        "senderAddress": {
            "id": "8c3f5cf9-1ac7-41f8-31ab-08dcdd2ac83f",
            "city": {
                "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90",
                "name": "تهران"
            },
            "streetAddress": "میدان هروی خ وفامنش",
            "postalCode": "1911611421",
            "unit": "3",
            "plaqueNo": "20",
            "latitude": 35.7715011,
            "longitude": 51.4834774,
            "description": "دفتر مرکزی"
        },
        "firstName": "علی",
        "lastName": "جسینی",
        "companyName": "لینک اکسپرس",
        "active": true
    },
    {
        "id": "7b2ffd0e-60aa-4739-3985-08dcdbafe7b7",
        "senderAddress": {
            "id": "648c07c5-4978-481d-2d38-08dcdbafe7ae",
            "city": {
                "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90",
                "name": "تهران"
            },
            "streetAddress": "میدان هروی خ وفامنش کوچه مومنی",
            "postalCode": "1911611421",
            "unit": "3",
            "plaqueNo": "20",
            "latitude": 35.7715011,
            "longitude": 51.4834774,
            "description": "دفتر مرکزی"
        },
        "firstName": "مهران",
        "lastName": "زند",
        "companyName": "لینک اکسپرس",
        "active": true
    }
]

This endpoint retrieves all senders.

HTTP Request

GET https://apigw.mylinkexpress.com/api/senders

Query Parameters

Parameter	Default	Description
active	optional	If set to true or false the result will filter by active otherwise include all records.

Store a Sender

curl --url https://apigw.mylinkexpress.com/api/senders \
     -X POST \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H "X-API-KEY: API_KEY" \
     --data '
    {
      "firstName": "مهران",
      "lastName": "زند",
      "companyName": "لینک اکسپرس",
      "active": true,
      "address": {
        "city": {
          "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90"
        },
        "streetAddress": "عباس آباد",
        "postalCode": "1911618117",
        "unit": "2",
        "plaqueNo": "2",
        "latitude": 0,
        "longitude": 0,
        "description": ""
      }
    }
'

{
    "success": "success",
    "code": 201,
    "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90"
}

This endpoint store a specific sender.

HTTP Request

POST https://apigw.mylinkexpress.com/api/senders

Sender Parameters

Parameter	Type	Description
firstName	string	firstname
lastName	string	lastName
companyName	string	companyName
active	bool	active
address	object	address object

Address Parameters

Parameter	Type	Description
city	object	city object
streetAddress	string	streetAddress
postalCode	string	postalCode
unit	int	unit
plaqueNo	int	plaqueNo
latitude	float	latitude
longitude	float	longitude
description	string	description

City Parameters

Parameter	Type	Description
id	string	id
name	string	name

Update a Sender

curl --url https://apigw.mylinkexpress.com/api/senders \
     -X PUT \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H "X-API-KEY: API_KEY" \
     --data '
    {
      "id": "cdcebad6-cb73-45a3-ace4-eb570718cd70",
      "firstName": "مهران",
      "lastName": "زند",
      "companyName": "لینک اکسپرس",
      "active": true,
      "address": {
        "city": {
          "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90"
        },
        "streetAddress": "عباس آباد",
        "postalCode": "1911618117",
        "unit": "2",
        "plaqueNo": "2",
        "latitude": 0,
        "longitude": 0,
        "description": ""
      }
    }
'

{
    "success": "success",
    "code": 200
}

This endpoint update a specific sender.

HTTP Request

PUT https://apigw.mylinkexpress.com/api/senders

Sender Parameters

Parameter	Type	Description
id	string	id
firstName	string	firstname
lastName	string	lastName
companyName	string	companyName
active	bool	active
address	object	address object

Address Parameters

Parameter	Type	Description
city	object	city object
streetAddress	string	streetAddress
postalCode	string	postalCode
unit	int	unit
plaqueNo	int	plaqueNo
latitude	float	latitude
longitude	float	longitude
description	string	description

City Parameters

Parameter	Type	Description
id	string	id
name	string	name

Delete a Sender

curl "https://apigw.mylinkexpress.com/api/senders/<ID>" \
  -X "DELETE" \
  -H "X-API-KEY: API_KEY"

{
  "success" : "success",
  "code" : 200
}

This endpoint delete a specific sender.

HTTP Request

DELETE https://apigw.mylinkexpress.com/api/senders/<ID>

URL Parameters

Parameter	Description
ID	The ID of the sender to delete

Parcels

Get a Parcel

curl "https://apigw.mylinkexpress.com/api/parcels/<ID>" \
  -H "X-API-KEY: API_KEY"

{
    "success": "success",
    "code": 200,
    "data": {
        "id": "5a8346ef-c7e7-4101-7395-08dce2d3bc1f",
        "customerId": "0cdeeda2-39dd-4b30-9786-f3efc829d7b8",
        "recipient": {
            "id": "4bf2f758-fb9b-4c71-bfbc-4b8786c408dd",
            "address": {
                "id": "1f0d36a0-ed07-4c9e-15ac-08dce2d3bc17",
                "city": {
                    "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90",
                    "name": "تهران"
                },
                "streetAddress": "میدان ونک خ ملاصدرا",
                "postalCode": "1234567890",
                "unit": "1",
                "plaqueNo": "12",
                "description": "توضیحات"
            },
            "nationalId": "0921222123",
            "firstName": "علی",
            "lastName": "حسینی",
            "companyName": "لینک اکسپرس",
            "cellPhone": "09121572357",
            "phone": "02122568907",
            "email": "mem@me.com"
        },
        "sender": {
            "id": "de1ae3a8-2d1f-4393-9049-08dcdd4458b0",
            "firstName": "مهران",
            "lastName": "زند",
            "companyName": "لینک اکسپرس"
        },
        "value": 1200.00,
        "weight": 12.00,
        "height": 100.00,
        "length": 100.00,
        "width": 100.00
    }
}

This endpoint retrieve a parcel.

HTTP Request

GET https://apigw.mylinkexpress.com/api/parcels/<ID>

Query Parameters

Parameter	Description
ID	The ID of the parcel to get

Store a Parcel

curl --url https://apigw.mylinkexpress.com/api/parcels \
     -X POST \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H "X-API-KEY: API_KEY" \
     --data '
     {
      "width": "100",
      "length": "100",
      "height": "100",
      "weight": "12",
      "value": "1200",
      "recipient": {
        "address": {
          "city": {
            "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90"
          },
          "streetAddress": "میدان هروی",
          "postalCode": "1234567890",
          "unit": "1",
          "plaqueNo": "12",
          "latitude": 37.141556,
          "longitude": 52.345466,
          "description": "توضیحات ندارد"
        },
        "nationalId": "006333459",
        "firstName": "mehran",
        "lastName": "zand",
        "companyName": "my companyName",
        "cellPhone": "09121002001",
        "phone": "02122568907",
        "email": "me@example.com"
      },
      "sender": {
        "id": "de1ae3a8-2d1f-4393-9049-08dcdd4458b0"
      }
    }
'

{
    "success": "success",
    "code": 201,
    "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90"
}

This endpoint store a specific parcel.

HTTP Request

POST https://apigw.mylinkexpress.com/api/parcels

Parcel Parameters

Parameter	Type	Description
width	decimal	width
length	decimal	length
height	decimal	height
weight	decimal	weight
value	decimal	value
Recipient	object	recipient object
Sender	object	sender object

Recipient Parameters

Parameter	Type	Description
firstName	string	firstname
lastName	string	lastName
companyName	string	companyName
nationalId	string	nationalId
cellPhone	string	cellPhone
phone	string	phone
email	string	email
address	object	address object

Address Parameters

Parameter	Type	Description
city	object	city object
streetAddress	string	streetAddress
postalCode	string	postalCode
unit	int	unit
plaqueNo	int	plaqueNo
latitude	float	latitude
longitude	float	longitude
description	string	description

Sender Parameters

Parameter	Type	Description
id	string	id

City Parameters

Parameter	Type	Description
id	string	id

Update a Parcel

curl --url https://apigw.mylinkexpress.com/api/parcels \
     -X PUT \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H "X-API-KEY: API_KEY" \
     --data '
  {
    "id":"5a8346ef-c7e7-4101-7395-08dce2d3bc1f",
    "width": "100",
    "length": "100",
    "height": "100",
    "weight": "12",
    "value": "1200",
    "recipient": {
      "address": {
        "city": {
          "id": "bfcebad6-cb73-45a3-ace4-eb570718cd9"
        },
        "streetAddress": "میدان هروی",
        "postalCode": "1234567890",
        "unit": "1",
        "plaqueNo": "12",
        "latitude": 37.141556,
        "longitude": 52.345466,
        "description": "توضیحات ندارد"
      },
      "nationalId": "006333459",
      "firstName": "mehran",
      "lastName": "zand",
      "companyName": "my companyName",
      "cellPhone": "09121002001",
      "phone": "02122568907",
      "email": "me@example.com"
    },
    "sender": {
      "id": "de1ae3a8-2d1f-4393-9049-08dcdd4458b0"
    }
  }
'

{
    "success": "success",
    "code": 200
}

This endpoint update a specific parcel.

HTTP Request

PUT https://apigw.mylinkexpress.com/api/parcels

Parcel Parameters

Parameter	Type	Description
id	string	id of parcel
width	decimal	width
length	decimal	length
height	decimal	height
weight	decimal	weight
value	decimal	value
Recipient	object	recipient object
Sender	object	sender object

Recipient Parameters

Parameter	Type	Description
firstName	string	firstname
lastName	string	lastName
companyName	string	companyName
nationalId	string	nationalId
cellPhone	string	cellPhone
phone	string	phone
email	string	email
address	object	address object

Address Parameters

Parameter	Type	Description
city	object	city object
streetAddress	string	streetAddress
postalCode	string	postalCode
unit	int	unit
plaqueNo	int	plaqueNo
latitude	float	latitude
longitude	float	longitude
description	string	description

Sender Parameters

Parameter	Type	Description
id	string	id

City Parameters

Parameter	Type	Description
id	string	id

Delete a Parcel

curl "https://apigw.mylinkexpress.com/api/parcels/<ID>" \
  -X "DELETE" \
  -H "X-API-KEY: API_KEY"

{
  "success" : "success",
  "code" : 200
}

This endpoint delete a specific parcel.

HTTP Request

DELETE https://apigw.mylinkexpress.com/api/parcels/<ID>

URL Parameters

Parameter	Description
ID	The ID of the parcel to delete

Orders

Store order async

curl --url https://apigw.mylinkexpress.com/api/parcels \
     -X POST \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H "X-API-KEY: API_KEY" \
     --data '
     {
      "width": "100",
      "length": "100",
      "height": "100",
      "weight": "12",
      "value": "1200",
      "recipient": {
        "address": {
          "city": {
            "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90"
          },
          "streetAddress": "میدان هروی",
          "postalCode": "1234567890",
          "unit": "1",
          "plaqueNo": "12",
          "latitude": 37.141556,
          "longitude": 52.345466,
          "description": "توضیحات ندارد"
        },
        "nationalId": "006333459",
        "firstName": "mehran",
        "lastName": "zand",
        "companyName": "my companyName",
        "cellPhone": "09121002001",
        "phone": "02122568907",
        "email": "me@example.com"
      },
      "sender": {
        "id": "de1ae3a8-2d1f-4393-9049-08dcdd4458b0"
      }
    }
'

{
    "success": "success",
    "code": 201,
    "id": "bfcebad6-cb73-45a3-ace4-eb570718cd90"
}

This endpoint store a specific parcel.

HTTP Request

POST https://apigw.mylinkexpress.com/api/parcels

Parcel Parameters

Parameter	Type	Description
width	decimal	width
length	decimal	length
height	decimal	height
weight	decimal	weight
value	decimal	value
Recipient	object	recipient object
Sender	object	sender object

Recipient Parameters

Parameter	Type	Description
firstName	string	firstname
lastName	string	lastName
companyName	string	companyName
nationalId	string	nationalId
cellPhone	string	cellPhone
phone	string	phone
email	string	email
address	object	address object

Address Parameters

Parameter	Type	Description
city	object	city object
streetAddress	string	streetAddress
postalCode	string	postalCode
unit	int	unit
plaqueNo	int	plaqueNo
latitude	float	latitude
longitude	float	longitude
description	string	description

Sender Parameters

Parameter	Type	Description
id	string	id

City Parameters

Parameter	Type	Description
id	string	id

Webhooks

Get All Events

curl "https://apigw.mylinkexpress.com/api/webhooks/events" \
  -H "X-API-KEY: API_KEY"

{
    "success": "success",
    "code": 200,
    "data": [
        {
            "id": "8aaeb0ad-a864-44e3-8c20-edb1c5fd66ac",
            "type": "slot.reserved",
            "description": "parcel slot reservation status"
        }
    ]
}

This endpoint retrieves all available events.

HTTP Request

GET https://apigw.mylinkexpress.com/api/webhooks/events

Get All Webhooks

curl "https://apigw.mylinkexpress.com/api/webhooks" \
  -H "X-API-KEY: API_KEY"

{
    "success": "success",
    "code": 200,
    "data": [
        {
            "id": "05e6c3bf-4ad5-432b-f4ad-08dce20c0b11",
            "event": {
                "id": "8aaeb0ad-a864-44e3-8c20-edb1c5fd66ac",
                "type": "slot.reserved",
                "description": "parcel slot reservation status"
            },
            "url": "https://webhook.site/d3ccd7d4-a152-4405-a1a9-4cc2b1c5a997",
            "secret": "S8S2TtdH8EyYB0Ndb2kde4HbbJWLj2SlRz5YSNC3zbw=",
            "created": "2024-10-01T14:57:33.2907511",
            "active": true
        }
    ]
}

This endpoint retrieves all webhooks.

HTTP Request

GET https://apigw.mylinkexpress.com/api/webhooks

Store a Webhook

curl --url https://apigw.mylinkexpress.com/api/webhooks \
     -X POST \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H "X-API-KEY: API_KEY" \
     --data '
      {
          "active" : true,
          "url" : "https://webhook.site/d3ccd7d4-a152-4405-a1a9-4cc2b1c5a997",
          "eventId": "8aaeb0ad-a864-44e3-8c20-edb1c5fd66ac",
          "usehmac": true
      }
'

{
    "success": "success",
    "code": 201,
    "data": {
        "id": "148c9955-f48b-475c-f4ae-08dce20c0b11",
        "customerId": "6dbfb446-4a48-4f4c-9ac7-20b2249bcc51",
        "event": {
            "id": "8aaeb0ad-a864-44e3-8c20-edb1c5fd66ac",
            "type": "slot.reserved",
            "description": "parcel slot reservation status",
            "active": true
        },
        "url": "https://webhook.site/d3ccd7d4-a152-4405-a1a9-4cc2b1c5a997",
        "secret": "dOdyi7h04mgIyY0LXrJrrAgFlWa6LztccT8oQ6kjZfk=",
        "created": "2024-10-02T09:27:24.0771494+03:30",
        "active": true
    }
}

This endpoint store a specific webhook for an event.

HTTP Request

POST https://apigw.mylinkexpress.com/api/webhooks

Webhook Parameters

Parameter	Type	Description
eventId	string	eventId that retrieves from event list
usehmac	bool	It generates a secret key using HMAC (Hash-based Message Authentication Code) to ensure secure message authentication and data integrity
url	string	callback url
active	bool	active

Update a Webhook

curl --url https://apigw.mylinkexpress.com/api/webhooks \
     -X PUT \
     -H 'accept: application/json' \
     -H 'content-type: application/json' \
     -H "X-API-KEY: API_KEY" \
     --data '
    {
        "active" : false,
        "url" : "https://webhook.site/d3ccd7d4-a152-4405-a1a9-4cc2b1c5a997",
        "id": "d4643273-c18c-4e5d-5409-08dcdfaa9a05"
    }
'

{
    "success": "success",
    "code": 200
}

This endpoint update a specific webhook.

HTTP Request

PUT https://apigw.mylinkexpress.com/api/webhooks

Parameters

Parameter	Type	Description
id	string	webhook id
url	string	callback url
active	bool	active

Delete a Webhook

curl "https://apigw.mylinkexpress.com/api/webhooks/<ID>" \
  -X "DELETE" \
  -H "X-API-KEY: API_KEY"

{
  "success" : "success",
  "code" : 200
}

This endpoint delete a specific webhook.

HTTP Request

DELETE https://apigw.mylinkexpress.com/api/webhooks/<ID>

URL Parameters

Parameter	Description
ID	The ID of the webhook to delete

Errors

Error codes and their meaning

Error Code	Meaning
400	Bad Request – Your request is invalid.
401	Unauthorized – Your API key is invalid.
403	Forbidden – You do not enough permissions to perform this action.
404	Not Found – The specified resource could not be found.
405	Method Not Allowed – You tried to access an API endpoint with an invalid REST method.
406	Not Acceptable – You requested a format that isn’t JSON.
410	Gone – The requested resource has been removed from our servers.
429	Too Many Requests – You’re requesting too many resources.
500	Internal Server Error – We had a problem with our server. Try again later.
502	Bad Gateway – The server cant handle your request for the moment. Try again later.
503	Service Unavailable – We’re temporarily offline for maintenance. Please try again later.