通过以下方式搜索 
shipper / aramex
一个用于集成Aramex API的库
v1.2
2024-06-07 21:27 UTC
This package is auto-updated.
Last update: 2024-09-07 22:06:33 UTC
README
开源的Laravel SDK，用于集成Aramex API。
安装
composer require shipper/aramex
要发布包并创建配置文件 aramex.php，请运行以下命令
php artisan vendor:publish --provider="Shipper\Aramex\AramexServiceProvider"
注意，此包需要在您的服务器上安装
SOAP扩展。
有关安装的更多信息，请参阅以下链接
> php.net
> digitalocean.com
配置
安装包后，您应在项目中发布包，然后它将创建 config/aramex.php 文件。打开它并设置您的ClientInfo以及根据您的业务模式设置其他参数。
注意：仔细阅读配置文件中的注释
简短文档
首先，您应该阅读Aramex的官方文档，了解其API的流程和参数，并决定使用Aramex API的主要目的。
文档链接：https://www.aramex.com/docs/default-source/resourses/resourcesdata/shipping-services-api-manual.pdf
您可以通过以下方式使用Aramex接口
use Shipper\Aramex\Aramex;
或将它添加到config/app.php文件中的别名
'Aramex' => Shipper\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"]
}
}
获取国家
获取Aramex支持的Aramex国家及其存储在其数据库中的信息。
您可以通过传递国家代码作为可选参数来获取所有国家或获取特定国家的信息。
请注意，我建议调用此方法并将所有响应插入到您的数据库中，这样您可以从数据库中获取国家，它基于他们的国家，这样您就不会浪费时间并使其在每次需要处理国家数据时都变得低效，通过调用此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
在此特此授予任何人，免费获得本软件及其相关文档副本（“软件”），在不进行限制的情况下处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本，并允许向提供软件的个人进行此类操作，但受以下条件约束：
上述版权声明和本许可声明应包含在软件的所有副本或主要部分中。
本软件按“原样”提供，不提供任何形式的保证，明示或暗示，包括但不限于适销性、特定用途的适用性和非侵权性。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任承担责任，无论该责任是因合同、侵权或其他原因引起的，也不论该责任是否与软件或软件的使用或其他方式相关。