alfred24 API

https://web.alfred24.com.hk/api-docs
Admin
The alfred24 API provides logistics and e-commerce partners access to the alfred24 network, enabling...
Tokens:12,160
Snippets:46
Trust Score:7.2
Update:1 year ago
Show doc for...
Tokens:
Raw
### Example JSON Request Payload for Company User Account Creation

Source: https://web.alfred24.com.hk/api-docs/index

An example JSON object demonstrating a valid request payload for creating a new company user account, adhering to the defined schema for the 'post/v1/account/user/company' endpoint.

```JSON
{
  "merchantName": "My company",
  "accountType": "BUSINESS",
  "serviceType": "PICKUP",
  "firstName": "John",
  "lastName": "Lee",
  "initialUserEmail": "test@test.com",
  "webPassword": "Ab1234567890",
  "initialUserMobile": "87654321",
  "streetAddress": "111 Parliament Road, City",
  "website": "string",
  "monthlyVolume": 1000,
  "companyName": "Company BR name",
  "businessRegistration": "12345678",
  "collectionAreaType": "COMMERCIAL",
  "level3AriaId": "灣仔",
  "warehouseAddress": [
    "The parcel pickup address"
  ],
  "promoCode": "string"
}
```

--------------------------------

### Example JSON Response Payload for Successful Account Creation

Source: https://web.alfred24.com.hk/api-docs/index

An example JSON object representing a successful 200 OK response after a company user account has been created, including a token, company name, company ID, and parent company details.

```JSON
{
  "code": 0,
  "message": "string",
  "data": {
    "token": "string",
    "companyName": "string",
    "companyID": "string",
    "parentCompany": "string"
  }
}
```

--------------------------------

### Example: User Authorization Request JSON Payload

Source: https://web.alfred24.com.hk/api-docs/index

This JSON snippet provides an example of the request body required for the user authorization endpoint, demonstrating the structure for submitting username and password.

```JSON
{
  "username": "Partner",
  "password": "888888"
}
```

--------------------------------

### Example Request Payload for Alfred24 API

Source: https://web.alfred24.com.hk/api-docs/index

A sample JSON payload demonstrating the structure and typical values for a request to the Alfred24 API, including various service and recipient details. This example illustrates a comprehensive set of parameters for creating or updating a shipment.

```json
{
  "serviceType": "DELIVERY",
  "serviceKey": "SELFPICKUP",
  "trackingNumber": "CLP0007770000",
  "additionalTrackingNumber": "CLP0007770000",
  "referenceNumber": "YOUR_ORDER_REFERENCE",
  "locationId": "ALF001",
  "locationName": "alfred24 locker 1",
  "locationType": "alfred24 Locker",
  "accessCode": "77788899",
  "recipientPhone": "87654321",
  "recipientEmail": "recipient@email.com",
  "recipientAddress": "11 Recipient Street, City, Province",
  "recipientName": "Recipient Name",
  "note": "Delivery with care",
  "pickupNotes": "Please come pickup by 4pm",
  "charge": 0,
  "numberOfParcels": 1,
  "length": 10,
  "width": 10,
  "height": 10,
  "status": "Delivered",
  "statusTime": "2019-08-01T10:00:00Z",
  "statusTimestamp": "1573648442070",
  "overdueTimestamp": "1574648442070",
  "senderPhone": "536908507",
  "senderEmail": "sender@email.com",
  "senderAddress": "10 Sender Street, City, Province",
  "compartmentNumber": "E11",
  "event": "FOR_MERCHANT_STORE_CUSTOMER_TAKEN",
  "orderFlag": [
    {
      "orderFlagName": "Recipient not available",
      "orderFlagCode": "FR001"
    }
  ],
  "operator": "alfred24 HK",
  "newTrackingNumber": "M123456789",
  "oldTrackingNumber": "L123456789"
}
```

--------------------------------

### Example Success Response for Alfred24 API

Source: https://web.alfred24.com.hk/api-docs/index

A sample JSON response indicating a successful operation from the Alfred24 API. This simple structure confirms the successful processing of the request.

```json
{
  "status": "success"
}
```

--------------------------------

### Example: User Authorization Success JSON Response (200)

Source: https://web.alfred24.com.hk/api-docs/index

This JSON snippet illustrates a successful response from the user authorization endpoint, including the generated bearer token, user roles, and company details.

```JSON
{
  "username": "Partner",
  "token": "FeimhHNjeqDoS0KBUze8VSraUgTlp1jwHDPwb7jrdOk279AlqwmaMEvf3NLvRIOD",
  "role": [
    {
      "roleName": "alfred24 user",
      "roleId": "23634280-8c19-49c2-b0ec-785a5e0ac994"
    }
  ],
  "company": [
    {
      "companyName": "Sample Company",
      "companyId": "f8907275-0763-47d4-92ec-1b5fe925fda3"
    }
  ]
}
```

--------------------------------

### Example 200 OK Response for Shipment Creation

Source: https://web.alfred24.com.hk/api-docs/index

A sample JSON object representing a successful response (HTTP 200 OK) from the shipment creation API. It provides details such as `shipmentId`, `orderId`, `trackingNumber`, and a link to the generated waybill.

```JSON
{
  "NOT_PERMISSION": [],
  "SUCCEED": [
    {
      "shipmentId": "8a876ae8-658d-4ab5-bb31-d88e767a394e",
      "orderId": "ORDERNUMBER04",
      "trackingNumber": "M002799893",
      "additionalTrackingNumber": null,
      "errorMessage": null,
      "waybillLink": "https://{{URL}}/platform/label/exportPdf?trackNumberList=M002799893&userToken=aabbcc",
      "qrCodeLink": null
    }
  ],
  "BAD_PARAMETER": [],
  "ALREADY_EXIST": []
}
```

--------------------------------

### Example JSON Payload for Shipment Creation (Pickup Service)

Source: https://web.alfred24.com.hk/api-docs/index

A sample JSON array illustrating the structure of a request body for creating a shipment, specifically for a pickup point service. It includes typical values for all relevant fields, demonstrating how to format the data for the API.

```JSON
[
  {
    "serviceKey": "SELFPICKUP",
    "trackingNumber": "YOUR_ORDER_REFERENCE",
    "locationId": "TEST001",
    "senderName": "Sender Name",
    "senderPhone": "87654321",
    "senderEmail": "sender@email.com",
    "senderAddress": "10 Sender Road, City, Province",
    "recipientName": "Recipient Name",
    "recipientPhone": "87654321",
    "recipientEmail": "recipient@email.com",
    "recipientAddress": "11 Recipient Road, City, Province",
    "note": "Delivery with care",
    "weight": 2.25,
    "length": 10,
    "width": 20,
    "height": 30
  }
]
```

--------------------------------

### API Endpoint: Get Shipment Details

Source: https://web.alfred24.com.hk/api-docs/index

Documents the `GET /v1/order/shipment` API endpoint, including query parameters, response codes, and a sample successful response body for retrieving shipment information.

```APIDOC
API Endpoint: GET /v1/order/shipment

Query Parameters:
- limit (integer <int32>): Return limit count in rows. Example: limit=10
- offset (integer): Skip offset count of rows before return. Example: offset=10
- status (string): Status of the Shipment at the given time. Example: status=COURIER_STORED
- from (string): From the time created. Format is YYYY-MM-DDThh-mm-ss.000. Example: from=2019-07-01T09:00:00.000
- to (string): Before the time created. Format is YYYY-MM-DDThh-mm-ss.000. Example: to=2019-07-02T13:00:00.000
- trackingNumber (string): The tracking number provided by alfred24. Example: trackingNumber=ALFREDPP201907161042TEST
- locationId (string): Unique identifier of alfred24 location. Example: locationId=TEST001
- overdueFlag (boolean): Returns results which have "Expired" status. Valid inputs are true = expired, false = non-expired. Example: overdueFlag=false

Responses:
- 200: Success
- 401: Unauthorized

Sample 200 OK Response Body (application/json):
[
  {
    "limit": "1",
    "offset": "1",
    "currentPage": "1",
    "pageCount": "10",
    "totalCount": "10",
    "content": [
      {
        "trackingNumber": "ALFREDPP201907161042TEST",
        "referenceNumber": "ecommerce_reference_number",
        "additionalTrackingNumber": "PP201907161042",
        "waybillLink": "https://waybilllinksample.alfred24.com.hk",
        "status": "COURIER_STORED",
        "statusDescription": "Courier stored",
        "statusTime": "2019-06-01T12:30:00.000Z",
        "statusTimeStamp": "1571986363517",
        "weight": "2.25",
        "length": 10,
        "width": 20,
        "height": 30,
        "accessCode": "123456",
        "createTime": "2023-05-09T21:18:01+08:00",
        "overDueFlag": "true",
        "serviceType": "DELIVERY",
        "service": "Pickup service 自提點派送",
        "compartment": "A30",
        "timeStored": "2023-05-11T13:07:04+08:00",
        "timeCollected": "null,",
        "timeOverdue": "2023-05-15T13:07:04+08:00",
        "newTrackingNumber": "NEW_ATTEMPT_TRAKCING_NUMBER",
        "oldTrackingNumber": "ORIGINAL_ATTEMPT_TRACKING_NUMBER",
        "company": {
          "companyId": "f8907275076347d492ec1bfe25fda3",
          "companyName": "Your company name"
        },
        "creator": {
          "createdBy": "CREATOR_NAME",
          "createdUserId": "64123123237126b8bf",
          "createdUserLoginName": "name@domain.com"
        },
        "location": {
          "locationName": "BaoanTestLocker",
          "locationId": "TEST001",
          "boxTypeName": null,
          "boxName": null
        },
        "recipient": {
          "recipientPhone": "536908434",
          "recipientMail": "recipient@domain.com",
          "recipientName": "Joey"
        },
        "courier": {
          "companyId": "61e9756c0431220736f52ad",
          "companyName": "alfred24 Delivery"
        },
        "storeUser": {
          "storeBy": "STORE_NAME",
          "storeUserId": "112123111246b8bf",
          "storeUserPhone": "81731672"
        },
        "orderFlag": [
          "Test order",
          "overweight"
        ],
        "events": [
          {
            "status": "CREATED",
            "statusCode": "1001",
            "statusDescription": "Created",
            "statusDescriptionCn": "已創建",
            "timestamp": 1683638281171,
            "time": "2022-11-08T11:01:40+08:00",
            "timezone": "Asia/Hong_Kong"
          },
          {
            "status": "ARRIVED_AT_WAREHOUSE",
            "statusCode": "3002",
            "statusDescription": "Arrived at warehouse",
            "statusDescriptionCn": "倉庫簽入",
            "timestamp": 1683638281172,
            "time": "2022-11-10T19:01:34+08:00",
            "timezone": "Asia/Hong_Kong"
          },
          {
            "status": "READY_FOR_DISPATCH",
            "statusCode": "3003",
            "statusDescription": "Ready for dispatch",
            "statusDescriptionCn": "準備出倉",
            "timestamp": 1683638281173,
            "time": "2022-11-10T21:42:10+08:00",
            "timezone": "Asia/Hong_Kong"
          },
          {
            "status": "COURIER_STORED",
            "statusCode": "4001",
            "statusDescription": "Courier stored",
            "statusDescriptionCn": "已存",
            "timestamp": 1683638281174,
            "time": "2022-11-11T14:41:57+08:00",
            "timezone": "Asia/Hong_Kong"
          },
          {
            "status": "CUSTOMER_COLLECTED",
            "statusCode": "5001",
            "statusDescription": "Delivered",
            "statusDescriptionCn": "已簽收",
            "timestamp": 1683638281175,
            "time": "2022-11-14T19:35:51+08:00",
            "timezone": "Asia/Hong_Kong"
          }
        ]
      }
    ]
  }
]
```

--------------------------------

### Location API Successful Response (200 OK) Sample

Source: https://web.alfred24.com.hk/api-docs/index

An example JSON structure returned upon a successful (HTTP 200) request to the location API, detailing pagination information and a comprehensive sample location object with various attributes including services, coordinates, addresses, and operating hours.

```APIDOC
[
  {
    "limit": 10,
    "offset": 0,
    "currentPage": 1,
    "pageCount": 1,
    "totalCount": 20,
    "pagination": [
      {
        "locationId": "P2034871334",
        "locationName": "測試櫃",
        "locationEn": "test locker",
        "locationTypeCn": "alfred24智能櫃",
        "locationType": "ALFRED_LOCKER",
        "services": [
          {
            "name": "Pickup service 自提點派送",
            "serviceKey": "SELFPICKUP"
          }
        ],
        "longitude": 114.6295727,
        "latitude": 22.0788713,
        "country": "Hong Kong SAR",
        "countryCn": "香港",
        "province": "Hong Kong Island",
        "provinceCn": "港島",
        "city": "Southern",
        "cityCn": "南區",
        "district": "Aberdeen",
        "districtCn": "香港仔",
        "postalCode": "",
        "address1": "香港仔南寧街9號香港仔中心商場二期2樓10A號舖",
        "address1En": "Shop 10A, 2/F ,Aberdeen Centre Phase 2 ,9 Nam Ning St, Aberdeen, HK",
        "address2": "",
        "address2En": "",
        "availableCompartments": 46,
        "operatingTime": "星期一 - 星期日: 10:00 - 22:00",
        "location_picture": "https://domain.com/link/9bb9de818",
        "displayHours": "Mon - Sun: 10:00 - 22:00",
        "displayHoursCn": "星期一 - 星期日: 10:00 - 22:00",
        "displayHoursSimplifiedCn": "星期一至日10:00-22:00",
        "specialHolidays": "",
        "specialHolidaysCn": "",
        "unformattedHours": "Mon - Sun: 10:00 - 22:00",
        "unformattedHoursCn": "星期一 - 星期日: 10:00 - 22:00",
        "detailHours": [
          {
            "closing1": "2200",
            "opening1": "1000",
            "weekday": "Mon"
          },
          {
            "closing1": "2200",
            "opening1": "1000",
            "weekday": "Tue"
          },
          {
            "closing1": "2200",
            "opening1": "1000",
            "weekday": "Wed"
          },
          {
            "closing1": "2200",
            "opening1": "1000",
            "weekday": "Thu"
          },
          {
            "closing1": "2200",
            "opening1": "1000",
            "weekday": "Fri"
          },
          {
            "closing1": "2200",
            "opening1": "1000",
            "weekday": "Sat"
          },
          {
            "closing1": "2200",
            "opening1": "1000",
            "weekday": "Sun"
          }
        ]
      }
    ]
  }
]
```

--------------------------------

### API: Get Locations Endpoint Specification

Source: https://web.alfred24.com.hk/api-docs/index

This API method retrieves location data from the system. It supports pagination using offset or limit parameters and requires bearer token authentication for access.

```APIDOC
Method: GET
Description: Retrieves locations from the system and supports pagination using offset or limit parameters.
Security: bearerAuth
```

--------------------------------

### Overview of Get Shipments Information API

Source: https://web.alfred24.com.hk/api-docs/index

Describes the purpose and functionality of the API method used to retrieve the latest shipment information. It highlights the ability to search by order or tracking number and apply filters based on specific status or timeframes for up-to-date details.

```APIDOC
## Get Shipments Information
This API method allows you to retrieve the latest shipment information. You can search by order number or tracking number, and apply filters based on specific status or timeframes. Use this method to fetch the most up-to-date details about shipments according to your search criteria.
```

--------------------------------

### Get Available Time Slots for Courier Pickup or Warehouse Drop-off API

Source: https://web.alfred24.com.hk/api-docs/index

This method retrieves available time slots for courier pickups or warehouse drop-offs. It provides a comprehensive list of designated time slots for scheduling these services.

```APIDOC
GET /v1/order/shipment/timeslot
Security: bearerAuth

Request:
  Header Parameters:
    requestType: string (required) - Enum: "DELIVERY", "PICKUP"

Responses:
  200: OK

Response Example (Status 200):
[
  {
    "title": "Apr 14 AM (10:00 - 13:00)",
    "requestStartTime": 1649901600000,
    "requestEndTime": 1649912400000
  },
  {
    "title": "Apr 14 PM (14:00 - 18:00)",
    "requestStartTime": 1649916000000,
    "requestEndTime": 1649930400000
  },
  {
    "title": "Apr 19 AM (10:00 - 13:00)",
    "requestStartTime": 1650333600000,
    "requestEndTime": 1650344400000
  },
  {
    "title": "Apr 19 PM (14:00 - 18:00)",
    "requestStartTime": 1650348000000,
    "requestEndTime": 1650362400000
  },
  {
    "title": "Apr 20 AM (10:00 - 13:00)",
    "requestStartTime": 1650420000000,
    "requestEndTime": 1650430800000
  },
  {
    "title": "Apr 20 PM (14:00 - 18:00)",
    "requestStartTime": 1650434400000,
    "requestEndTime": 1650448800000
  },
  {
    "title": "Apr 21 AM (10:00 - 13:00)",
    "requestStartTime": 1650506400000,
    "requestEndTime": 1650517200000
  }
]
```

--------------------------------

### Request Courier Pickup API

Source: https://web.alfred24.com.hk/api-docs/index

This method allows you to request a courier to pick up a shipment from a specified address. It requires a valid time slot, obtainable via the 'Get Available Time Slots' method. Multiple calls with the same time slot and pickup information are treated as a single request, returning a handoverId.

```APIDOC
POST /v1/order/shipment/newHandover/pickup
Security: bearerAuth

Request:
  Content-Type: application/json
  Body Schema:
    requestStartTime: number (required)
    requestEndTime: number (required)
    trackingNumbers: Array of strings (required)
    pickupInfo: object
      address: string
      contactPhone: string
      contactName: string
      buildingType: string
      note: string

Request Example:
{
  "requestStartTime": 1629180000000,
  "requestEndTime": 1629194400000,
  "trackingNumbers": [
    "A123456",
    "B123456"
  ],
  "pickupInfo": {
    "address": "My warehouse address",
    "contactPhone": "87654321",
    "contactName": "John",
    "buildingType": "RESIDENTIAL",
    "note": "Please pickup with pallet"
  }
}

Responses:
  200: OK
  400: Bad Request

Response Example (Status 200):
{
  "NOT_PERMISSION": [],
  "SUCCEED": [
    {
      "trackingNumber": "A123456",
      "handoverId": "PU000001"
    },
    {
      "trackingNumber": "B123456",
      "handoverId": "PU000001"
    }
  ],
  "BAD_PARAMETER": [],
  "ALREADY_EXIST": []
}
```

--------------------------------

### Notify Warehouse Drop-off API

Source: https://web.alfred24.com.hk/api-docs/index

This method enables you to submit notifications for the drop-off of your shipments to alfred24 warehouses. It requires the use of the appropriate time slot, which can be obtained by invoking the Get Available Time Slots of Warehouse Drop-off method to create a drop-off notice. API calls made with the same time slot will be considered as a single drop-off notification, and the handoverId (the ID of the drop-off notification) will be returned.

```APIDOC
Endpoint: POST /v1/order/shipment/newHandover/dropoff
Security: bearerAuth

Request Body (application/json):
- requestStartTime: number
- requestEndTime: number
- trackingNumbers: Array of strings
- note: string (<= 255 characters)
```

```APIDOC
{
  "requestStartTime": 1629180000000,
  "requestEndTime": 1629194400000,
  "trackingNumbers": [
    "A123456",
    "B123456"
  ],
  "note": "Total 103 pcs. Please come pick up with pallet."
}
```

```APIDOC
{
  "NOT_PERMISSION": [],
  "SUCCEED": [
    {
      "trackingNubmer": "A123456",
      "handoverId": "DF000001"
    },
    {
      "trackingNubmer": "B123456",
      "handoverId": "DF000001"
    }
  ],
  "BAD_PARAMETER": [],
  "ALREADY_EXIST": []
}
```

--------------------------------

### Geowidget Initialization Parameters Reference

Source: https://web.alfred24.com.hk/api-docs/index

Details the configuration parameters available for the geoWidget.init() method, including their purpose, default values, and accepted options for customizing the Geowidget's behavior and appearance.

```APIDOC
Parameters for geoWidget.init():
- mapBoxClassName: The class name given to the mapBox div. This is where the Geowidget will render. Defaults: `mapBox`
- defaultLocation: Which location to use for the Geowidget. Defaults: `HK`
- mapType: Whether to render Google Maps (`gmap`) or Openstreet Map (`osm`). Available: `gmap`, `osm`. Defaults: `osm`. (apiKey required for `gmap`)
- locale: Select which language to init Geowidget with. Available: `en`, `zh`. Defaults: `en`
- mode: Select which mode to open the Geowidget in. Available: `basic`, `modal`, `dropdown`. Defaults: `basic`
- filter: A javascript object that will filter out all non-matching items from the API call. E.g. `filter: { locationType: ["ALFRED_LOCKER"] }`. This will only display locker with location type ALFRED_LOCKER.
- searchBar: Whether the widget should be intialised with a searchbar displaying. Available: `true`, `false`. Defaults: `false`
- apiKey: The Google Maps API key.
- onSelect: The call back that returns the selected location. Defaults: `onSelect`
- userAuthObject: A javascript object with username and password that connects to the alfred24 API: e.g. `userAuthObject: { username: "your username", password: "your password", }`
```

--------------------------------

### alfred24 API Reference Overview and Navigation

Source: https://web.alfred24.com.hk/api-docs/index

This section provides an overview of the alfred24 API, including its purpose, how to access it, and a navigation structure for different API categories like Authorization, Locations, and Shipments. It also lists the available environments and standard HTTP status codes.

```APIDOC
API Categories:
- Authorization
- Locations
- Shipments
- Accounts
- Webhook
- Geowidget

Environments:
| Environment | URL |
| --- | --- |
| Staging | https://api-staging.alfred24.com.hk |
| Production | https://api.alfred24.com.hk |

HTTP Status Codes:
| HTTP Status Code | Description |
| --- | --- |
| 2xx Success | The request was successfully received and proccessed by alfred24 |
| 4xx Client Error | This indicates there is an error in the payload |
| 5xx Server Error | This error occurs when alfred24 is unable to carry out an action |
```

--------------------------------

### Initialize Geowidget in Basic Mode

Source: https://web.alfred24.com.hk/api-docs/index

Demonstrates the basic initialization of the Geowidget using OpenStreetMap, a default location, and a callback function to retrieve selected location data. Requires user authentication credentials.

```JavaScript
<script>
const getData = (arg) => {//get selected location data
  console.log(arg)
};
geoWidget.init({
  mapType: "osm",
  defaultLocation: "HK",
  onSelect: getData,
  userAuthObject: {
    username: "username",
    password: "password",
  },
});
</script>
```

--------------------------------

### Introduction to Shipment Statuses List

Source: https://web.alfred24.com.hk/api-docs/index

Introduces the section that will enumerate and describe the various shipment statuses returned by the alfred24 API, providing context for understanding shipment lifecycle.

```APIDOC
## List of shipment statuses
The statuses returned are as follows:
```

--------------------------------

### Geowidget API Endpoint and Security Documentation

Source: https://web.alfred24.com.hk/api-docs/index

API documentation for the Geowidget service, detailing the `post/Geowidget` endpoint and the `bearerAuth` security scheme. It also lists the various programming languages for which request samples are available.

```APIDOC
Security:
  bearerAuth

Endpoint:
  post /Geowidget

Request Sample Languages:
  - curl
  - Node.js
  - JavaScript
  - Python
  - C#
  - Java
  - Java 8 with Apache
  - Go
  - PHP
  - Ruby
```

--------------------------------

### Geowidget JavaScript Initialization Snippet

Source: https://web.alfred24.com.hk/api-docs/index

A partial JavaScript code snippet demonstrating configuration parameters for the Geowidget, specifically setting a password and enabling a search bar. This likely forms part of a larger initialization object or function call.

```JavaScript
password: "password" }, searchBar: true });
```

--------------------------------

### Pickup Point Drop-off Service Status Codes (serviceKey: "RETURN"/"MRETURN")

Source: https://web.alfred24.com.hk/api-docs/index

Defines status codes for the 'RETURN' and 'MRETURN' services, detailing the process from creation to return to merchant. These codes track the status of items being dropped off at a designated location.

```APIDOC
Pickup point drop-off service (serviceKey:"RETURN"/"MRETURN")

Normal statuses:
  1001: CREATED - The shipment record has been created in the system and is ready for further processing.
  4002: CUSTOMER_STORED - The shipment has been stored at the drop-off location.
  6001: COURIER_COLLECTED - The courier has collected the shipment from the drop-off location.
  7002: RETURNED_TO_WAREHOUSE - The shipment has been returned to the warehouse.
  5031: RETURNED_TO_MERCHANT - The shipment has been returned to merchant.
```

--------------------------------

### Create Sub-Accounts API

Source: https://web.alfred24.com.hk/api-docs/index

This method allows for the creation of sub-accounts under your primary account.

```APIDOC
Security: bearerAuth
```

--------------------------------

### API Request Body Schema for Company User Account Creation

Source: https://web.alfred24.com.hk/api-docs/index

Defines the structure and validation rules for the JSON request body used to create a new company user account. It specifies required fields, data types, and constraints for various parameters like merchant details, contact information, and address.

```APIDOC
Request Body schema: application/json
  merchantName: string (required) - Merchant name of the sub-account. This merchant name need to be unique.
  accountType: any (Enum: "BUSINESS", "INDIVIDUAL") - The merchant is a business type or a individual type. Different type of certificate file may needed.
  serviceType: any (required, Enum: "PICKUP", "DELIVERY") - The parcel handover method of this merchant. "PICKUP": Set merchant is going to use courier pick up from the warehouse address. "DELVIERY": Set merchant is going to use drop-off to our warehouse.
  firstName: string (required if "serviceType" is "PICKUP") - Contact person first name. This field is required if "serviceType" is "PICKUP" in order to identify which person to be contacted with while the courier picking up the parcels.
  lastName: string - Contact person last name
  initialUserEmail: string <email> (required) - Contact person email. A valid email format is required.
  webPassword: string (required, [ 8 .. 20 ] characters) - Password for web portal login. Must be 8-20 characters, at least one uppercase, one lowercase and one number.
  initialUserMobile: string (required if "serviceType" is "PICKUP") - Contact person phone number. This field is required if "serviceType" is "PICKUP" in order to identify which phone number to be contacted with while the courier picking up the parcels.
  streetAddress: string - Company address
  website: string (<= 255 characters) - Company website
  monthlyVolume: number - Estimated monthly volume of shipment
  companyName: string - Company name on Business registration certificate
  businessRegistration: string (<= 8 characters) - BR number on Business registration certificate.
  collectionAreaType: any (required if "serviceType" is "PICKUP", Enum: "COMMERCIAL", "RESIDENTIAL") - Pickup address building type. This field is required if "serviceType" is "PICKUP"
  level3AriaId: string - Pickup address district ID
  warehouseAddress: Array of strings (required if "serviceType" is "PICKUP") - The address that we pickup from you. This field is required if "serviceType" is "PICKUP"
  promoCode: string - Promo code
```

--------------------------------

### Shipment Events for Pickup Point Drop-off Services

Source: https://web.alfred24.com.hk/api-docs/index

This section details the normal events specific to shipments using the 'RETURN' and 'MRETURN' pickup point drop-off services, including customer storage and courier collection.

```APIDOC
Service Keys: RETURN, MRETURN

Normal events:
  CUSTOMER_STORED:
    Status: Customer stored
    Remarks: For "RETURN"/"MRETURN" orders only. This event is triggered when a shipment has been deposited by a customer.
  COURIER_COLLECTED:
    Status: Courier collected
    Remarks: For "RETURN"/"MRETURN" orders only. This event is triggered when a shipment has been collected by a courier.
  RETURNED_TO_WAREHOUSE:
    Status: Returned to warehouse
    Remarks: The shipment has returned to warehouse.
  RETURNED_TO_MERCHANT:
    Status: Returned to merchant
    Remarks: The shipment has been returned back to merchant.
```

--------------------------------

### Initialize Geowidget with Search Bar

Source: https://web.alfred24.com.hk/api-docs/index

Configures the Geowidget to display an integrated search bar, allowing users to search for locations directly within the widget. This is enabled by setting the `searchBar` parameter to `true`.

```JavaScript
<script>
geowidget.init({
  mapType:"osm",
  defaultLocation: "HK",
  locale: "en",
  onSelect: getData,
  userAuthObject:{
    username: "username",
```

--------------------------------

### API: User Authorization Endpoint Specification

Source: https://web.alfred24.com.hk/api-docs/index

This API endpoint authenticates a user with a username and password to generate an access token. It specifies the request method, path, required request body schema, and possible HTTP responses.

```APIDOC
Method: POST
Path: /v1/account/user/auth

Request Body Schema (application/json):
  username: string (required)
  password: string (required)

Responses:
  200 Success
  401 Unauthorized
  415 Unsupported Media Type
```

--------------------------------

### Shipment Creation API Endpoint and Response Codes

Source: https://web.alfred24.com.hk/api-docs/index

Outlines the HTTP endpoint for creating shipments and lists the standard HTTP response codes that can be expected, indicating success or various error conditions.

```APIDOC
post/v1/order/shipment

Responses

200

OK

400

Bad Request

401

Unauthorized

404

Not Found
```

--------------------------------

### Include Geowidget JavaScript Library

Source: https://web.alfred24.com.hk/api-docs/index

Adds the Geowidget library to the HTML document by referencing its CDN path in a <script> tag, typically placed within the header section.

```HTML
<script src="https://alfred-geowidget.s3-ap-southeast-1.amazonaws.com/cdn-scripts/geoWidget.js"></script>
```

--------------------------------

### API Security Authentication Method

Source: https://web.alfred24.com.hk/api-docs/index

Describes the authentication method required for API requests. This section specifies how clients should authenticate when interacting with the API.

```APIDOC
Security:
  bearerAuth: Bearer Token Authentication
Request:
```

--------------------------------

### Define Geowidget Map Container HTML

Source: https://web.alfred24.com.hk/api-docs/index

Sets up the necessary HTML structure for the Geowidget to render, including a loader and the main map box div. This structure is used for all Geowidget modes except for the 'modal' mode.

```HTML
<div id="mapsPlaceHolder">
  <div class="loader" id="loader">
  </div>
  <div id="mapBox" class="mapBox">
  </div>
</div>
```

--------------------------------

### Initialize Geowidget with Google Maps

Source: https://web.alfred24.com.hk/api-docs/index

Configures the Geowidget to use Google Maps instead of OpenStreetMap by setting `mapType` to 'gmap'. This requires providing a valid Google Maps API key.

```JavaScript
<script>
geowidget.init({
  mapType: "gmap",
  defaultLocation: "HK",
  apiKey: "Your Google Maps Apikey",
  locale: "en",
  onSelect: getData,
  userAuthObject: {
    username: "username",
    password: "password",
  },
});
</script>
```

--------------------------------

### Delivery / Pickup Failure Reason Codes

Source: https://web.alfred24.com.hk/api-docs/index

Provides a list of codes and descriptions for common delivery and pickup failures, identified by 'orderFlagCode'. These codes help in understanding why a delivery or pickup attempt was unsuccessful.

```APIDOC
List of Delivery / Pickup failure reasons:
  FR001: Recipient not available / No one responded
  FR002: Customer requested a change of delivery/pick up time
  FR003: Customer refused / claimed there was nothing to pick up
  FR005: Incorrect address
  FR007: Restricted zone
```

--------------------------------

### Shipment Events for Delivery Pickup and Door-to-Door Services

Source: https://web.alfred24.com.hk/api-docs/index

This section outlines the normal and abnormal events that can occur for shipments handled by 'SELFPICKUP' (delivery pickup points) and 'HOMEDELIVERY' (door-to-door delivery) services, along with their corresponding statuses and remarks.

```APIDOC
Service Keys: SELFPICKUP, HOMEDELIVERY

Normal events:
  ARRIVED_AT_WAREHOUSE:
    Status: Arrived at warehouse
    Remarks: This event is triggered when a shipment is scanned into an affiliated warehouse.
  COURIER_STORED:
    Status: Courier stored
    Remarks: This event is triggered when a shipment has been stored at an alfred24 location by an operator or courier. This event will trigger a notification to a customer if it is enabled.
  DELIVERED:
    Status: Delivered
    Remarks: This event is triggered when a customer has collected their shipment.

Abnormal events:
  COURIER_COLLECTED:
    Status: Courier collected
    Remarks: This event is triggered when a shipment has been removed from an alfred24 location and to be returned to the logistics service provider. This event will trigger a notification to the customer if it is enabled.
  OPERATOR_COLLECTED:
    Status: Operator collectecd
    Remarks: This event is triggered when a shipment has been removed from an alfred24 location and to be returned to the locker operator. This event will trigger a notification to the customer if it is enabled.
  DELIVERY_FAILURE:
    Status: Delivery failure
    Remarks: The shipment has some issue on the delivery, and will be returning back to the warehouse.
  RECREATED:
    Status: Recreated
    Remarks: This event is triggered when the shipment is going to apply for a new tracking number and make another attempt for the delivery.
  RETURNED_TO_WAREHOUSE:
    Status: Returned to warehouse
    Remarks: The shipment has returned to warehouse.
  RETURNED_TO_MERCHANT:
    Status: Returned to merchant
    Remarks: The shipment has been returned back to merchant.
  DISPOSED:
    Status: Disposed
    Remarks: The shipment has been disposed.
  LOST:
    Status: Lost
    Remarks: The shipment is lost.
```

--------------------------------

### Initialize Geowidget in Modal Mode

Source: https://web.alfred24.com.hk/api-docs/index

Sets the Geowidget to operate in 'modal' mode, which requires additional HTML structure for the modal container. This is configured by setting the `mode` parameter to 'modal'.

```JavaScript
<script>
geowidget.init({
  mapType: "osm",
  defaultLocation: "HK",
  mode: "modal",
  locale: "en",
  userAuthObject: {
    username: "username",
    password: "password",
  },
  onSelect: getData,
});
</script>
```

--------------------------------

### Request Body Schema for Alfred24 API

Source: https://web.alfred24.com.hk/api-docs/index

Defines the structure and types of fields required in the request body for Alfred24 API calls, specifically for `application/json` content type. This schema outlines all possible parameters for order and shipment details.

```APIDOC
Request Body Schema: application/json
  serviceType: string - Service type of the order.
  serviceKey: string - The service identifier specifies the type of service requested.
  trackingNumber: string - Unique identifer.
  additionalTrackingNumber: string
  referenceNumber: string
  locationId: string - Unique identifier of alfred24 location.
  locationType: string
  accessCode: string - PIN code for customer to access locker.
  locationName: string - Name of alfred24 location
  recipientPhone: string - Recipient phone number
  recipientEmail: string - Recipient email address
  recipientAddress: string - Recipient mailing address
  recipientName: string - Recipient name
  note: string - Any miscellaneous remarks
  pickupNotes: string - Optional notes for shipment pickup.
  status: string - Status as it appears to the customer
  statusTime: string - Time at which the status was last updated
  statusTimestamp: string - Time at which the status was last updated in timestamp format
  overdueTimestamp: string - Time at which the shipment will be deemed overdue in timestamp format
  numberOfParcels: integer - Count of shipment parcels.
  weight: number - Weight of shipment
  length: number - Length of shipment
  width: number - Width of shipment
  height: number - Height of shipment
  senderPhone: string - Sender phone number
  senderEmail: string - Sender email address
  senderAddress: string - Sender mailing address
  compartmentNumber: string - The compartment number as shown to the customer
  event: string - The event which has triggered the webhook update
  operator: string - The company to which this shipment is operated by
  orderFlag: object
  newTrackingNumber: string - Tracking number assigned to a new delivery attempt of a shipment that was either rescheduled for delivery or recreated from another shipment.
  oldTrackingNumber: string - Tracking number of the previous shipment that is being attempted for delivery again.
```

--------------------------------

### Pickup Point Delivery Service Status Codes (serviceKey: "SELFPICKUP")

Source: https://web.alfred24.com.hk/api-docs/index

Defines status codes for the 'SELFPICKUP' service, covering the lifecycle from creation to delivery or cancellation, including normal and abnormal states. These codes indicate the current state of a shipment within the system.

```APIDOC
Pickup point delivery service (serviceKey:"SELFPICKUP")

Normal statuses:
  1001: CREATED - The shipment record has been created in the system and is ready for further processing.
  2001: PICKUP_REQUESTED - The order has been scheduled for a courier pickup from the sender's or merchant's address.
  2002: DROP_OFF_REQUESTED - The order has been successfully notified for drop-off to the warehouse.
  3002: ARRIVED_AT_WAREHOUSE - The shipment has been successfully checked into the warehouse.
  3012: ARRIVED_AT_PARTNER_WAREHOUSE - The shipment has been successfully checked into the partner's warehouse.
  3003: READY_FOR_DISPATCH - The shipment is prepared for dispatch.
  3004: OUT_FOR_DELIVERY - The shipment is currently in transit for delivery.
  4001: COURIER_STORED - The shipment has successfully reached the designated pickup location.
  5001: CUSTOMER_COLLECTED - The recipient has successfully collected the shipment at the pickup location.
  5002: COMPLETED - The shipment has been successfully confirmed as delivered and received by the recipient.
  0001: CANCELLED - The order has been cancelled

Abnormal statuses:
  5011: RECREATED - A new tracking number has already been obtained for the shipment, it will be used for the subsequent delivery attempt.
  E2001: PICKUP_FAILURE - Failed to pick up from sender
  E4001: STORE_FAILURE - Failed to store at the pickup location
  7001: RETURNED_TO_COURIER - The expired shipment has been collected by the courier.
  7002: RETURNED_TO_WAREHOUSE - The shipment has been returned to the warehouse.
  5021: SCHEDULED_FOR_DELIVERY - The shipment has been rescheduled for delivery to a new address.
  5031: RETURNED_TO_MERCHANT - The shipment has been returned to the sender.
  6002: OPERATOR_COLLECTED - The operator has collected the shipment from the pickup location.
  E3004: DELIVERY_FAILURE - The shipment failed to be delivered to the pickup location or the recipient address.
```
Tokens:
Raw