This method authenticates a user with a username and password and generates an access token.

The "Get Locations" method retrieves locations from the system and supports pagination using offset or limit parameters.

This API facilitates the creation of an order with alfred24 by generating a unique tracking number and providing a corresponding waybill label. These elements serve the purpose of facilitating the shipment process and serve as reference information for tracking and logistics management.

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.

List of shipment statuses

The statuses returned are as follows:

Pickup point delivery service (serviceKey:"SELFPICKUP")

Status Code	Status value	Status Description	Remarks
Normal statuses
1001	CREATED	Created	The shipment record has been created in the system and is ready for further processing.
2001	PICKUP_REQUESTED	Pickup requested	The order has been scheduled for a courier pickup from the sender's or merchant's address.
2002	DROP_OFF_REQUESTED	Delivery Requested	The order has been successfully notified for drop-off to the warehouse.
3002	ARRIVED_AT_WAREHOUSE	Inbound	The shipment has been successfully checked into the warehouse.
3012	ARRIVED_AT_PARTNER_WAREHOUSE	Arrived at partner warehouse	The shipment has been successfully checked into the partner's warehouse.
3003	READY_FOR_DISPATCH	Ready for dispatch	The shipment is prepared for dispatch.
3004	OUT_FOR_DELIVERY	Out for delivery	The shipment is currently in transit for delivery.
4001	COURIER_STORED	Courier stored	The shipment has successfully reached the designated pickup location.
5001	CUSTOMER_COLLECTED	Delivered	The recipient has successfully collected the shipment at the pickup location.
5002	COMPLETED	Completed	The shipment has been successfully confirmed as delivered and received by the recipient.
0001	CANCELLED	Cancelled	The order has been cancelled
Abnormal statuses
5011	RECREATED	Recreated	A new tracking number has already been obtained for the shipment, it will be used for the subsequent delivery attempt.
E2001	PICKUP_FAILURE	Pickup failure	Failed to pick up from sender
E4001	STORE_FAILURE	Store failure	Failed to store at the pickup location
7001	RETURNED_TO_COURIER	Returned to courier	The expired shipment has been collected by the courier.
7002	RETURNED_TO_WAREHOUSE	Returned to warehouse	The shipment has been returned to the warehouse.
5021	SCHEDULED_FOR_DELIVERY	Change to delivery	The shipment has been rescheduled for delivery to a new address.
5031	RETURNED_TO_MERCHANT	Returned to merchant	The shipment has been returned to the sender.
6002	OPERATOR_COLLECTED	Operator collected	The operator has collected the shipment from the pickup location.
E3004	DELIVERY_FAILURE	Delivery failure	The shipment failed to be delivered to the pickup location or the recipient address.

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

Status Code	Status value	Status Description	Remarks
Normal statuses
1001	CREATED	Created	The shipment record has been created in the system and is ready for further processing.
4002	CUSTOMER_STORED	Customer stored	The shipment has been stored at the drop-off location.
6001	COURIER_COLLECTED	Courier collected	The courier has collected the shipment from the drop-off location.
7002	RETURNED_TO_WAREHOUSE	Returned to warehouse	The shipment has been returned to the warehouse.
5031	RETURNED_TO_MERCHANT	Returned to merchant	The shipment has been returned to merchant.

Send from address service (serviceKey:"D2DSEND")

Status Code	Status value	Status Description	Remarks
Normal statuses
1001	CREATED	Created	The shipment record has been created in the system and is ready for further processing.
2003	PICKUP_ARRANGED	Pickup arranged	The courier scheduled for pickup at sender's address.
2004	OUT_FOR_PICKUP	Out for pickup	The courier en route for pickup at sender's address.
2005	PICKED_UP_FROM_SENDER	Picked up from sender	The courier has already collected the shipment from the sender's address.
3012	ARRIVED_AT_PARTNER_WAREHOUSE	Arrived at partner warehouse	The shipment has been successfully checked into the partner's warehouse.
5031	RETURNED_TO_MERCHANT	Returned to merchant	The shipment has been sent back to the original sender or merchant.
0001	CANCELLED	Cancelled	The order has been cancelled
Abnormal statuses
E2001	PICKUP_FAILURE	Pickup failure	Failed to pick up from sender

List of Delivery / Pickup failure reasons

Failure reason code ("orderFlagCode")	Remarks
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

This method allows you to cancel a shipment. When using the cancel order API call, please exercise caution as the cancellation is irreversible. Once the shipment is canceled, it cannot be undone, and all associated shipment information will be permanently inaccessible. To ensure accuracy, carefully review the order details before initiating the cancellation.

This method provides the capability to retrieve the available time slots for courier pickups or warehouse drop-offs. By making use of this API, you can access a comprehensive list of time slots specifically designated for scheduling courier pickups or arranging warehouse drop-offs.

This method enables you to request a courier to pick up the shipment from your specified address. It requires the use of the appropriate time slot, which can be obtained by invoking the Get Available Time Slots of Courier Pickup method. API calls made with the same time slot and pickup information will be considered as a single pickup request, and the handoverId (the ID of the pickup request) will be returned.

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.

This API allows you to cancel a previously requested courier pickup or warehouse drop-off notice. By providing the order tracking number, you can initiate the cancellation process. It's important to note that once the cancellation is confirmed, it cannot be undone. Please ensure that you have the correct information and intent before proceeding with the cancellation.

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

The webhook module facilitates the transmission of callback information from alfred24 to partners, triggered by specific events. To enable this functionality, partners are required to furnish alfred24 with a secure webhook notification URL.

Responses to Webhook

Partners will need to configure their servers to accept webhook information when the events are triggered. Acknowledgement of successful receipt of the webhook should be included in the payload. Repeated attempts to send the webhook information will be made every 30 mintues for 10 times until a 2xx status is received.

Below is a sample webhook response that alfred24 will send on event trigger.

Webhook Events

The following events trigger a webhook update:

Event list of Delivery pickup points (serviceKey:"SELFPICKUP") and Door-to-door delivery (serviceKey:"HOMEDELIVERY")

Event	Status	Remarks
Normal events:
ARRIVED_AT_WAREHOUSE	Arrived at warehosue	This event is triggered when a shipment is scanned into an affiliated warehouse.
COURIER_STORED	Courier stored	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	Delivered	This event is triggered when a customer has collected their shipment.
Abnormal events:
COURIER_COLLECTED	Courier collected	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	Operator collectecd	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	Delivery failure	The shipment has some issue on the delivery, and will be returning back to the warehouse.
RECREATED	Recreated	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	Returned to warehouse	The shipment has returned to warehouse.
RETURNED_TO_MERCHANT	Returned to merchant	The shipment has been returned back to merchant.
DISPOSED	Disposed	The shipment has been disposed.
LOST	Lost	The shipment is lost.

Event list of Pickup point drop-off service (serviceKey:"RETURN"/"MRETURN")

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

Event list of Send from address service (serviceKey:"D2DSEND") and failure reasons

Event	Status	Remarks
Normal events
PICKUP_ARRANGED	Pickup arranged	The courier scheduled for pickup at sender's address.
OUT_FOR_PICKUP	Out for pickup	The courier en route for pickup at sender's address.
PICKED_UP_FROM_SENDER	Picked up from sender	The courier has already collected the shipment from the sender's address.
ARRIVED_AT_PARTNER_WAREHOUSE	Arrived at partner warehouse	The shipment has been successfully checked into the partner's warehouse.
RETURNED_TO_MERCHANT	Returned to merchant	The shipment has been sent back to the original sender or merchant.
CANCELLED	Cancelled	The order has been cancelled
Abnormal event
PICKUP_FAILURE	Pickup failure	Failed to pick up from sender

Failure reason code ("orderFlagCode")	Remarks for Send from address service
FR001	No one responded
FR002	Customer requested a change of pickup time
FR003	Customer claimed there was nothing to pick up
FR005	Incorrect pickup address
FR007	Restricted zone

GEOv1 (also known as alfred24 Geowidget v1) is a JavaScript widget that displays a comprehensive list of locations where alfred24 services are available. It offers the convenience of filtering the location list based on location type, region, district, and area, allowing users to view only the relevant listings. As a widget-based solution, the entire code and processing are hosted on alfred24 servers, requiring external clients to simply link to the code and configure it according to their system requirements. To begin integrating GEOv1, please reach out to alfred24 at sales-hk@alfred24.com to obtain a Geowidget account.

Responsive web design (RWD)

Integration

Geowidget v1 can be easily integrated into any system or web page.

Add <script> in header tag. Change source path to the link below:

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

Add div with id mapBox and class mapBox in the body:

(Note: The following initialization pertains to all types of usage except for Modal , which is explained in point 5 below)

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

Parameters

Parameter name	Description	Defaults
mapBoxClassName	The class name given to the mapBox div. This is where the Geowidget will render	mapBox
defaultLocation	Which location to use for the Geowidget	HK
mapType	Whether to render Google Maps (use gmap) or Openstreet Map (use osm) Available: gmap, osm For Google Maps option apiKey is required.	osm
locale	Select which language to init Geowidget with. Available: en, zh	en
mode	Select which mode to open the Geowidget in. Available: basic, modal, dropdown	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	false
apiKey	The Google Maps API key
onSelect	The call back that returns the selected location	onSelect
userAuthObject	A javascript object with username and password that connets to the alfred24 API: e.g. userAuthObject: { username: "your username", password: "your password", },

Examples

1. Basic integration

<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>

Map type options are 1) “osm” for openstreet map and 2) “gmap” for Google Maps.

Add api key, username and password as above.

The selected location data can be retrieved from the getData method.

Click here to see example 1: Basic Integration (https://geowidget.alfred.delivery/basic.html)

2. With initial filtering

We can also filter out initial values from the Api based on search filters; E.g. in this case we only show results from alfred24 locker. If we want to filter services / operating time etc; it can be done passing the parameters as an object.

<script>
      geoWidget.init({
        mapType: "osm",
        defaultLocation: "HK",
        userAuthObject: {
          username: "username",
          password: "password",
        },
        filter: {
          locationType: ["ALFRED_LOCKER"],
        },
        onSelect: getData,
      });
</script>

Click here to see example 2: With Initial Value filtering (shows alfred24 Lockers with service: Returns) (https://geowidget.alfred.delivery/withfilter.html)

3. With dropdown filtering

<script>
      geoWidget.init({
        mapType: "osm",
        defaultLocation: "HK",
        mode: "dropdown",
        userAuthObject: {
          username: "username",
          password: "password",
        },
        onSelect: getData,
      });
</script>

By adding a mode object; and setting mode to “dropdown” we can initialize the geo widget to display in dropdown mode.

Click here to see example 3: With Dropdown filtering (https://geowidget.alfred.delivery/dropdown.html)

4. Google Maps

By switching map mode to “gmap” we can display Google Maps instead of Open Street Maps:

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

Click here to see example 4: Enable Google Maps (https://geowidget.alfred.delivery/googlemaps.html)

5. Open map as modal

To open the map as modal we need to do 2 things;

a. Change mode to modal as below:

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

b. Wrap the map box div inside a modal parent div and provide a button to open the modal like below:

<button id="modalOpenBtn">Open Modal</button>
    <div id="modal" class="modal">
      <div id="mapWrapper" class="mapWrapper">
        <div class="loader" id="loader"></div>
        <div id="mapBox" class="mapBox"></div>
      </div>
</div>

Click here to see example 5: Modal without filtering (https://geowidget.alfred.delivery/modal.html)

6. With search bar

To use Geowidget as a search bar, we provide a searchBar object and set it to true as below:

<script>
      geoWidget.init({
        mapType:"osm",
        defaultLocation: "HK",
        locale: "en",
        onSelect: getData,
        userAuthObject:{
          username: "username",
          password: "password"
        },
        searchBar: true
      });
</script>

Click here to see example 6: With Search bar (https://geowidget.alfred.delivery/withSearchBar.html)

Demo: Live Links

Example 1: Basic Integration (https://geowidget.alfred.delivery/basic.html)

Example 2: With initial value filtering (shows alfred24 lockers with service: Returns) (https://geowidget.alfred.delivery/withfilter.html)

Example 3: With dropdown filtering (https://geowidget.alfred.delivery/dropdown.html)

Example 4: Enable Google Maps (https://geowidget.alfred.delivery/googlemaps.html)

Example 5: Modal without filtering (https://geowidget.alfred.delivery/modal.html)

Example 6: With search bar (https://geowidget.alfred.delivery/withSearchBar.html)