通过 
搜索
搜索octw / aramex
一个用于集成阿联酋快递API的库
1.2.1
2021-09-18 15:06 UTC
README
开源Laravel SDK，用于与阿联酋快递API集成。
安装
composer require octw/aramex
要发布包并创建配置文件 aramex.php，请运行此命令
php artisan vendor:publish --provider="Octw\Aramex\AramexServiceProvider"
注意，此包需要在您的服务器上启用
SOAP扩展。
请参考以下链接进行安装
php.net
digitalocean.com
配置
安装包后，您应该在项目中发布包，然后它会创建 config/aramex.php 文件。打开它并设置您的CientInfo并根据您的业务模式设置其他参数。
注意：仔细阅读配置文件中的注释
简要文档
首先，您应该阅读阿联酋快递的官方文档，了解其API的流程和参数，并决定使用阿联酋快递API的主要目的。
文档链接： https://www.aramex.com/docs/default-source/resourses/resourcesdata/shipping-services-api-manual.pdf
您可以通过以下方式使用阿联酋快递接口
use Octw\Aramex\Aramex;
或者将其添加到 config/app.php 文件的别名中
'Aramex' => Octw\Aramex\Aramex::class,
然后
use Aramex;
然而，该集成有7个主要功能
- 创建取件。
- 取消取件。
- 创建运输。
- 计算运费。
- 追踪运输。
- 获取国家。
- 获取城市。
- 验证地址。
创建取件方法
接受参数数组
"name" => 'John' // User’s Name, Sent By or in the case of the consignee, to the Attention of. "cell_phone" => '+123456789' // Phone Number "phone" => '+123456789' // Phone Number "email" => 'email@domain.com' "country_code" => 'US' // ISO 3166-1 Alpha-2 Code "city" => 'New York' // City Name "zip_code" => 10001 // Postal Code "line1" => 'Line 1 Details' "line2" => 'Line 2 Details' "line3" => 'Line 3 Details' "pickup_date" => time() // time parameter describe the date of the pickup "ready_time" => time() // time parameter describe the ready pickup date "last_pickup_time" => time() // time parameter "closing_time" => time() // time parameter "status" => 'Ready' // or Pending "pickup_location" => 'at company's reception' // location details "weight" => 12 // wieght of the pickup (in KG) "volume" => 80 // volume of the pickup (in CM^3)
返回stdClass
{
"error": 0,
"pickupGUID": "4e29b471-0ed8-4ba8-ac0e-fddedfb6beec",
"pickupID": "H310146"
}
in case of error
{
"error": 1,
"errors": [
// Aramex's response errors
]
}
示例代码
$data = Aramex::createPickup([ 'name' => 'MyName', 'cell_phone' => '+123123123', 'phone' => '+123123123', 'email' => 'myEmail@gmail.com', 'city' => 'New York', 'country_code' => 'US', 'zip_code'=> 10001, 'line1' => 'The line1 Details', 'line2' => 'The line2 Details', 'line3' => 'The line2 Details', 'pickup_date' => time() + 45000, 'ready_time' => time() + 43000, 'last_pickup_time' => time() + 45000, 'closing_time' => time() + 45000, 'status' => 'Ready', 'pickup_location' => 'some location', 'weight' => 123, 'volume' => 1 ]); // extracting GUID if (!$data->error) $guid = $data->pickupGUID;
创建运输方法
接受参数数组
'shipper' => [ 'name' => 'Steve', 'email' => 'email@users.companies', 'phone' => '+123456789982', 'cell_phone' => '+321654987789', 'country_code' => 'US', 'city' => 'New York', 'zip_code' => 10001, 'line1' => 'Line1 Details', 'line2' => 'Line2 Details', 'line3' => 'Line3 Details', ], 'consignee' => [ 'name' => 'Steve', 'email' => 'email@users.companies', 'phone' => '+123456789982', 'cell_phone' => '+321654987789', 'country_code' => 'US', 'city' => 'New York', 'zip_code' => 10001, 'line1' => 'Line1 Details', 'line2' => 'Line2 Details', 'line3' => 'Line3 Details', ], 'shipping_date_time' => time() + 50000, // shipping date 'due_date' => time() + 60000, // due date of the shipment 'comments' => 'No Comment', // ,comments 'pickup_location' => 'at reception', // location as pickup 'pickup_guid' => $guid, // GUID taken from createPickup method (optional) 'weight' => 1, // weight 'goods_country' => null, // optional 'number_of_pieces' => 1, // number of items 'description' => 'Goods Description, like Boxes of flowers', // description 'reference' => '01020102' // reference to print on shipment report (policy) 'shipper_reference' => '19191', // optional 'consignee_reference' => '010101', // optional 'services' => 'CODS,FIRST,FRDM, .. ' // ',' seperated string, refer to services in the official documentation 'cash_on_delivery_amount' => 10.32 // in case of CODS (in USD only "as they want") 'insurance_amount' => 0, // optional 'collect_amount' => 0, // optional 'customs_value_amount' => 0, //optional (required for express shipping) 'cash_additional_amount' => 0, // optional 'cash_additional_amount_description' => 'Something here', 'product_group' => 'DOM', // or EXP (defined in config file, if you dont pass it will take the config value) 'product_type' => 'PPX', // refer to the official documentation (defined in config file, if you dont pass it will take the config value) 'payment_type' => 'P', // P,C, 3 refer to the official documentation (defined in config file, if you dont pass it will take the config value) 'payment_option' => null, // refer to the official documentation (defined in config file, if you dont pass it will take the config value)
返回stdClass
{
"Transaction": {
"Reference1": "",
"Reference2": "",
"Reference3": "",
"Reference4": "",
"Reference5": null
},
"Notifications": {},
"HasErrors": false,
"Shipments": {
"ProcessedShipment": {
"ID": "0",
"Reference1": null,
"Reference2": null,
"Reference3": null,
"ForeignHAWB": null,
"HasErrors": false,
"Notifications": {},
"ShipmentLabel": null,
"ShipmentDetails": {
"Origin": "AMM",
"Destination": "AMM",
"ChargeableWeight": {
"Unit": "KG",
"Value": 1
},
"DescriptionOfGoods": "Hello World",
"GoodsOriginCountry": null,
"NumberOfPieces": 1,
"ProductGroup": "EXP",
"ProductType": "EPX",
"PaymentType": "P",
"PaymentOptions": null,
"CustomsValueAmount": {
"CurrencyCode": "USD",
"Value": 0
},
"CashOnDeliveryAmount": {
"CurrencyCode": "USD",
"Value": 0
},
"InsuranceAmount": {
"CurrencyCode": "USD",
"Value": 0
},
"CashAdditionalAmount": {
"CurrencyCode": "USD",
"Value": 0
},
"CollectAmount": {
"CurrencyCode": "USD",
"Value": 0
},
"Services": null
},
"ShipmentAttachments": {
"ProcessedShipmentAttachment": {
"Name": "CommercialInvoice_6048abe44a664c3cb7ce9f7d47879115.pdf",
"Type": "CommercialInvoice",
"Url": "http://www.dev.aramex.net/content/rpt_cache/CommercialInvoice_6048abe44a664c3cb7ce9f7d47879115.pdf"
}
},
"ShipmentThirdPartyProcessedObject": null
}
}
}
错误响应
{
"error": true,
"errors": [
{
"Code": "Aramex Error Code",
"Message": "Aramex Error Message"
},
{
"Code": "Aramex Error Code",
"Message": "Aramex Error Message"
}
]
}
示例代码
$callResponse = Aramex::createShipment([ 'shipper' => [ 'name' => 'Steve', 'email' => 'email@users.companies', 'phone' => '+123456789982', 'cell_phone' => '+321654987789', 'country_code' => 'US', 'city' => 'New York', 'zip_code' => 32160, 'line1' => 'Line1 Details', 'line2' => 'Line2 Details', 'line3' => 'Line3 Details', ], 'consignee' => [ 'name' => 'Steve', 'email' => 'email@users.companies', 'phone' => '+123456789982', 'cell_phone' => '+321654987789', 'country_code' => 'US', 'city' => 'New York', 'zip_code' => 32160, 'line1' => 'Line1 Details', 'line2' => 'Line2 Details', 'line3' => 'Line3 Details', ], 'shipping_date_time' => time() + 50000, 'due_date' => time() + 60000, 'comments' => 'No Comment', 'pickup_location' => 'at reception', // 'pickup_guid' => $guid, 'weight' => 1, 'number_of_pieces' => 1, 'description' => 'Goods Description, like Boxes of flowers', ]); if (!empty($callResponse->error)) { foreach ($callResponse->errors as $errorObject) { handleError($errorObject->Code, $errorObject->Message); } } else { // extract your data here, for example // $shipmentId = $response->Shipments->ProcessedShipment->ID; // $labelUrl = $response->Shipments->ProcessedShipment->ShipmentLabel->LabelURL; }
计算运费
计算运费API用于在运输之前获取运输定价和详细信息。
它接受4个参数
Aramex::calculateRate($originAddress, $destinationAddress, $shipementDetails, $currency)
$originAddress 和 $destinationAddress 都是数组，如下所示
[
'line1' => 'String|Required',
'line2' => 'String',
'line3' => 'String',
'city' => 'String|Required',
'state_code' => 'String',
'postal_code' => 'String',
'country_code' => 'String|max:2|min:2|Required',
'longitude' => 'Double',
'latitude' => 'Double',
'building_number' => 'String',
'building_name' => 'String',
]
$shipmentDetails 参数是一个数组，描述了运输的一些详细信息，如下所示
[
'payment_type' => '', // default value in config file
'product_group' => '', // default value in config file
'product_type' => '', // default value in config file
'weight' => 5.2, // IN KG (Kilograms)
'number_of_pieces' => 'Integer|Required',
'height' => 5, // Dimensions in CM (optional)
'width' => 3, // Dimensions in CM (optional)
'length' => 2 // Dimensions in CM (optional)
]
$currency 是一个字符串（3个字符），用于首选货币计算，如 USD、AED、EUR、KWD 等。
注意，如果您想传递尺寸，除非您传递所有 height、width、length 参数，否则它将不接收参数。
示例代码
$originAddress = [ 'line1' => 'Test string', 'city' => 'Amman', 'country_code' => 'JO' ]; $destinationAddress = [ 'line1' => 'Test String', 'city' => 'Dubai', 'country_code' => 'AE' ]; $shipmentDetails = [ 'weight' => 5, // KG 'number_of_pieces' => 2, 'payment_type' => 'P', // if u don't pass it, it will take the config default value 'product_group' => 'EXP', // if u don't pass it, it will take the config default value 'product_type' => 'PPX', // if u don't pass it, it will take the config default value 'height' => 5.5, // CM 'width' => 3, // CM 'length' => 2.3 // CM ]; $shipmentDetails = [ 'weight' => 5, // KG 'number_of_pieces' => 2, ]; $currency = 'USD'; $data = Aramex::calculateRate($originAddress, $destinationAddress , $shipmentDetails , 'USD'); if(!$data->error){ dd($data); } else{ // handle $data->errors }
响应对象示例
- 成功响应
{
"Transaction":{
"Reference1":"",
"Reference2":"",
"Reference3":"",
"Reference4":"",
"Reference5":null
},
"Notifications":{
},
"HasErrors":false,
"TotalAmount":{
"CurrencyCode":"USD",
"Value":1004.74
},
"RateDetails":{
"Amount":312.34,
"OtherAmount1":0,
"OtherAmount2":0,
"OtherAmount3":78.08,
"OtherAmount4":0,
"OtherAmount5":475.73,
"TotalAmountBeforeTax":866.15,
"TaxAmount":138.59
}
}
- 失败响应
{
"error": 1,
"errors": "Error strings one by one."
}
追踪运输
此服务显示了您创建的运输的详细更新。
Aramex::trackShipments($arrayOfShipmentIds);
基本地，获取已创建运输的ID（$createShipmentResults->Shipments->ProcessedShipment->ID），将这些ID堆叠在数组中，并将数组传递给该函数。
$shipments = [ $createShipmentResults->Shipments->ProcessedShipment->ID, $anotherCreateShipmentResults->Shipments->ProcessedShipment->ID, ]; $data = Aramex::trackShipments($shipments);
示例代码
$shipments = [ $createShipmentResults->Shipments->ProcessedShipment->ID, $anotherCreateShipmentResults->Shipments->ProcessedShipment->ID, ]; $data = Aramex::trackShipments($shipments); if (!$data->error){ // Code Here } else { // handle error }
响应示例
在这里，我应该提到，如果您传递错误的ID（不是运输ID），您将在 NonExistingWaybills 字段中看到您传递的字符串。
{
"Transaction": {
"Reference1": "",
"Reference2": "",
"Reference3": "",
"Reference4": "",
"Reference5": null
},
"Notifications": {},
"HasErrors": false,
"TrackingResults": {
"KeyValueOfstringArrayOfTrackingResultmFAkxlpY": {
"Key": "IdOfTheShipemnt",
"Value": {
"TrackingResult": [
{
"WaybillNumber": "41118182136",
"UpdateCode": "SH005",
"UpdateDescription": "Delivered",
"UpdateDateTime": "2015-07-13T13:08:00",
"UpdateLocation": "Al Muqabalain, Jordan",
"Comments": "AMJAD Delivered by (Ayman Abushhail)",
"ProblemCode": "",
"GrossWeight": "0.1",
"ChargeableWeight": "0.1",
"WeightUnit": "KG"
},
{
"WaybillNumber": "41118182136",
"UpdateCode": "SH003",
"UpdateDescription": "Out for Delivery",
"UpdateDateTime": "2015-07-13T08:46:00",
"UpdateLocation": "Al Muqabalain, Jordan",
"Comments": "",
"ProblemCode": "",
"GrossWeight": "0.1",
"ChargeableWeight": "0.1",
"WeightUnit": "KG"
},
{
"WaybillNumber": "41118182136",
"UpdateCode": "SH160",
"UpdateDescription": "Under processing at operations facility",
"UpdateDateTime": "2015-07-13T04:30:00",
"UpdateLocation": "Al Muqabalain, Jordan",
"Comments": "",
"ProblemCode": "V01",
"GrossWeight": "0.1",
"ChargeableWeight": "0.1",
"WeightUnit": "KG"
},
{
"WaybillNumber": "30994423681",
"UpdateCode": "SH014",
"UpdateDescription": "Record created.",
"UpdateDateTime": "2018-10-11T16:05:00",
"UpdateLocation": "Amman, Jordan",
"Comments": "0.5,0.5,KG ",
"ProblemCode": "",
"GrossWeight": "0.5",
"ChargeableWeight": "0.5"
}
]
}
}
},
"NonExistingWaybills":{
"string":[
"WrongIdIHavePassed",
"TestId"
]
}
}
获取国家
获取阿联酋快递支持并由其数据库存储的国家。
您可以获取所有国家或通过传递国家代码作为可选参数获取特定国家的信息。
请注意，我建议调用此方法并将所有响应插入到您的数据库中，这样您就可以从数据库中获取国家信息，并且这些信息是基于他们的国家，这样您就不必每次处理国家数据时都调用此API，从而节省时间和提高效率。
$data = Aramex::fetchCountries($countryCode); // Or $data = Aramex::fetchCountries();
响应示例
{
"Transaction":{
"Reference1":"",
"Reference2":"",
"Reference3":"",
"Reference4":"",
"Reference5":null
},
"Notifications":{
},
"HasErrors":false,
"Countries":{
"Country":[
{
"Code":"AD",
"Name":"Andorra",
"IsoCode":"AND",
"StateRequired":true,
"PostCodeRequired":false,
"PostCodeRegex":{
},
"InternationalCallingNumber":"376"
},
{
"Code":"AE",
"Name":"United Arab Emirates",
"IsoCode":"ARE",
"StateRequired":true,
"PostCodeRequired":false,
"PostCodeRegex":{
},
"InternationalCallingNumber":"971"
},
...
]
}
}
获取城市
通过国家代码获取Aramex的城市。
$data = Aramex::fetchCities('AE');
响应示例
{
"Transaction":{
"Reference1":"",
"Reference2":"",
"Reference3":"",
"Reference4":"",
"Reference5":null
},
"Notifications":{
},
"HasErrors":false,
"Cities":{
"string":[
"Abadilah",
"Abu Dhabi",
"Abu Hayl",
"Abu Shagara",
"Adhan",
"Ajman City",
"Akamiyah",
"Al Ain City",
"Al Ardiyah",
"Al Azrah",
"Al Dharbaniyah",
...
]
}
}
验证地址
为了验证地址并避免处理与Aramex末端不兼容的用户输入，您可以在创建取货或运输之前验证地址。
$data = Aramex::validateAddress([ 'line1':'Test', // optional (Passing it is recommended) 'line2':'Test', // optional 'line3':'Test', // optional 'country_code':'JO', 'postal_code':'', // optional 'city':'Amman', ]);
响应示例
{
"Transaction":{
"Reference1":"",
"Reference2":"",
"Reference3":"",
"Reference4":"",
"Reference5":null
},
"Notifications":{
},
"HasErrors":false,
"SuggestedAddresses":{
}
}
希望这能对您有所帮助，给我买杯咖啡吧 ;)
MIT许可证
版权所有 2019 Moustafa Allahham
任何人获得本软件及其相关文档（“软件”）的副本（以下简称“软件”），均被授予在此软件上无限制地处理的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许将软件提供给他人以执行上述行为，但须遵守以下条件：
上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。
本软件按“原样”提供，不提供任何形式的质量保证，无论是明示的还是隐含的，包括但不限于适销性、特定用途适用性和非侵权性保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论这些责任源于合同、侵权或其他原因，无论这些责任是否与软件有关或源于使用或以其他方式处理软件。