### Install Aramex Package

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/INDEX.md

Install the Aramex SDK package using Composer.

```bash
composer require octw/aramex
```

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

### Install Aramex Service Provider

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/service-provider.md

Run these commands to install the package and update composer autoloading. Cache configuration if needed.

```bash
composer install
composer dump-autoload
php artisan config:cache
```

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

### initializePickupCancelation

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a pickup cancellation request by setting the pickup GUID and cancellation comments.

```APIDOC
## initializePickupCancelation

### Description
Prepares a pickup cancellation request.

### Method
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **guid** (string) - Required - UUID of pickup to cancel
- **comment** (string) - Required - Cancellation reason

### Side Effects
Sets `$this->param['PickupGUID']` and `$this->param['Comments']`.
```

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

### PHP Aramex SDK Integration Test Example

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/INDEX.md

This example demonstrates how to set up an integration test for the Aramex SDK using Orchestra Testbench. It includes the necessary service provider registration and a basic test case for creating a pickup, asserting that an error attribute is present in the result.

```php
use Orchestra\Testbench\TestCase;
use Octw\Aramex\Aramex;

class AramexIntegrationTest extends TestCase
{
    protected function getPackageProviders($app)
    {
        return ['Octw\Aramex\AramexServiceProvider'];
    }

    public function testCreatePickup()
    {
        try {
            $result = Aramex::createPickup([...]);
            $this->assertObjectHasAttribute('error', $result);
        } catch (Exception $e) {
            $this->fail('Unexpected exception: ' . $e->getMessage());
        }
    }
}
```

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

### Initialize Pickup Cancellation Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a pickup cancellation request. Sets the pickup GUID and cancellation comments.

```php
public function initializePickupCancelation(string $guid, string $comment): void
```

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

### Initialize Fetch Cities Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a request to fetch city data for a given country. Can filter cities by a starting letter sequence.

```php
public function initializeFetchCities(string $code, ?string $nameStartWith = null): void
```

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

### Create Shipment

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/aramex-class.md

This example demonstrates how to create a shipment using the Aramex SDK. It includes detailed shipper and consignee information, shipping details, and error handling.

```APIDOC
## createShipment

This method creates a new shipment with Aramex.

### Request Example
```php
$shipmentData = Aramex::createShipment([
    'shipper' => [
        'name' => 'Steve Company',
        'email' => 'steve@company.com',
        'phone' => '+123456789',
        'cell_phone' => '+987654321',
        'country_code' => 'US',
        'city' => 'New York',
        'zip_code' => '10001',
        'line1' => '123 Main St',
        'line2' => 'Floor 5',
        'line3' => 'Building A'
    ],
    'consignee' => [
        'name' => 'Jane Recipient',
        'email' => 'jane@recipient.com',
        'phone' => '+111111111',
        'cell_phone' => '+987654321',
        'country_code' => 'AE',
        'city' => 'Dubai',
        'zip_code' => '00000',
        'line1' => '456 Sheikh Zayed Rd',
        'line2' => 'Downtown',
        'line3' => 'Zone A'
    ],
    'shipping_date_time' => time() + 86400,
    'due_date' => time() + 172800,
    'comments' => 'Fragile items',
    'pickup_location' => 'Main warehouse',
    'weight' => 5,
    'number_of_pieces' => 2,
    'description' => 'Electronic equipment',
    'reference' => 'ORD-2024-001',
    'cash_on_delivery_amount' => 100
]);

if (empty($shipmentData->error)) {
    $shipmentId = $shipmentData->Shipments->ProcessedShipment->ID;
    $labelUrl = $shipmentData->Shipments->ProcessedShipment->ShipmentLabel->LabelURL;
} else {
    foreach ($shipmentData->errors as $error) {
        echo $error->Code . ': ' . $error->Message;
    }
}
```
```

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

### initializeFetchCities

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a cities fetch request, filtering by country code and an optional starting string for city names.

```APIDOC
## initializeFetchCities

### Description
Prepares a cities fetch request, filtering by country code and an optional starting string for city names.

### Method
```php
public function initializeFetchCities(string $code, ?string $nameStartWith = null): void
```

### Parameters
#### Path Parameters
- **code** (string) - Required - ISO 2-letter country code
#### Query Parameters
- **nameStartWith** (string) - Optional - Filter cities by starting letters

### Side Effects
Sets `$this->param['CountryCode']` and `$this->param['NameStartsWith']`.
```

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

### Example Pickup Status Validation Error Response

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/errors.md

Shows an example of an error response when the 'status' field for pickup details is invalid. It indicates that the status must be one of the allowed values, 'Pending' or 'Ready'.

```json
{
    "status": ["The status must be one of the following types: Pending, Ready."]
}
```

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

### Environment Variables for Aramex SDK

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/configuration.md

Example .env file content for configuring the Aramex SDK. Includes settings for both test and live environments, as well as general shipment parameters.

```dotenv
ARAMEX_ENV=TEST
ARAMEX_TEST_ACCOUNT=20016
ARAMEX_TEST_USERNAME=testingapi@aramex.com
ARAMEX_TEST_PASSWORD=R123456789$
ARAMEX_TEST_PIN=331421
ARAMEX_TEST_ENTITY=AMM
ARAMEX_TEST_COUNTRY=JO

ARAMEX_LIVE_ACCOUNT=
ARAMEX_LIVE_USERNAME=
ARAMEX_LIVE_PASSWORD=
ARAMEX_LIVE_PIN=
ARAMEX_LIVE_ENTITY=
ARAMEX_LIVE_COUNTRY=

COMPANY_NAME=My Company
ARAMEX_PRODUCT_GROUP=EXP
ARAMEX_PRODUCT_TYPE=PPX
ARAMEX_PAYMENT_TYPE=P
ARAMEX_CURRENCY=USD
ARAMEX_REPORT_ID=9201
ARAMEX_REPORT_TYPE=URL
```

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

### Fetch Cities by Country

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/INDEX.md

Use the `fetchCities` method to get a list of cities for a given country code. You can optionally filter by a starting name.

```php
Aramex::fetchCities(string $code, ?string $nameStartWith)
```

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

### Fetch Cities Starting with a Specific String with Aramex SDK

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/aramex-class.md

Retrieves a list of cities for a specified country that start with a given string. This is useful for implementing type-ahead city search functionality.

```php
// With filter
$dubaiCities = Aramex::fetchCities('AE', 'Du');
```

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

### Example .env File for Aramex Credentials

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/configuration.md

Define your Aramex API credentials in the .env file for secure and easy management. These values are used by the SDK when configured with environment variables.

```dotenv
ARAMEX_ACCOUNT_NUMBER=your_account_number
ARAMEX_USERNAME=your_username
ARAMEX_PASSWORD=your_password
ARAMEX_PIN=your_pin
ARAMEX_ENTITY=AMM
ARAMEX_COUNTRY=JO
ARAMEX_VERSION=v1
```

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

### Pickup Response Object (Success)

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/types.md

Returned by Aramex::createPickup() on success. Contains error status, pickup GUID, and pickup ID.

```php
stdClass {
    ->error: 0 (integer),
    ->pickupGUID: 'string' (UUID format),
    ->pickupID: 'string' (numeric ID)
}
```

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

### Calculate Rate API Success Response Sample

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/README.md

Example of a successful response from the Calculate Rate API, showing transaction details, notifications, and total calculated amount with currency.

```json
      {
         "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
         }
      }
```

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

### Get Configured SOAP Client for Aramex Services

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/helpers.md

Use this factory method to obtain a pre-configured SoapClient instance for various Aramex services like shipping, tracking, rate, or location. The WSDL file used depends on the configured environment (TEST or LIVE). For PHP versions below 8.0, XML entity loading is disabled.

```php
use Octw\Aramex\Helpers\AramexHelper;

// Get SOAP client for shipping operations
$shippingClient = AramexHelper::getSoapClient(AramexHelper::SHIPPING);

// Use for SOAP calls
$response = $shippingClient->CreatePickup($params);

// Get tracking client
$trackingClient = AramexHelper::getSoapClient(AramexHelper::TRACKING);
$trackingResponse = $trackingClient->TrackShipments($params);
```

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

### Aramex LIVE Client Credentials (Environment Variables)

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/configuration.md

Recommended practice for configuring live credentials using environment variables for enhanced security. Load values from your .env file.

```php
'LIVE' => [
    'AccountNumber' => env('ARAMEX_ACCOUNT_NUMBER'),
    'UserName' => env('ARAMEX_USERNAME'),
    'Password' => env('ARAMEX_PASSWORD'),
    'AccountPin' => env('ARAMEX_PIN'),
    'AccountEntity' => env('ARAMEX_ENTITY'),
    'AccountCountryCode' => env('ARAMEX_COUNTRY'),
    'Version' => env('ARAMEX_VERSION', 'v1')
]
```

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

### Deferred Provider Implementation

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/service-provider.md

Shows the necessary properties and methods to implement a deferred service provider pattern. This defers the loading of the provider until it's actually needed, potentially improving performance.

```php
protected $defer = true;

public function provides()
{
    return ['Octw\Aramex\Aramex'];
}
```

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

### initializeCalculateRate

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a rate calculation request with origin, destination, shipment details, and currency code.

```APIDOC
## initializeCalculateRate

### Description
Prepares a rate calculation request.

### Method
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **originAddress** (stdClass) - Required - Origin address object
- **destinationAddress** (stdClass) - Required - Destination address object
- **shipmentDetails** (stdClass) - Required - Shipment specifications
- **currencyCode** (string) - Required - 3-letter currency code

### Side Effects
Sets `$this->param['OriginAddress']`, `$this->param['DestinationAddress']`, `$this->param['ShipmentDetails']`, and `$this->param['PreferredCurrencyCode']`.
```

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

### Cancel Pickup

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/INDEX.md

Use the `cancelPickup` method to cancel an existing pickup using its GUID and a comment.

```php
Aramex::cancelPickup(string $guid, string $comment)
```

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

### fetchCities

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/aramex-class.md

Fetches a list of cities supported by Aramex for a given country. It can also filter cities by a starting string.

```APIDOC
## fetchCities

### Description
Fetches a list of cities supported by Aramex for a given country. It can also filter cities by a starting string.

### Method
```php
public static function fetchCities(string $countryCode, ?string $nameStartWith = null): stdClass
```

### Parameters
#### Path Parameters
- **countryCode** (string) - Required - ISO 2-letter country code.
- **nameStartWith** (string) - Optional - Filter cities starting with this string.

### Return Value
Returns `stdClass` object.

**On Success:**
```json
{
  "Transaction": { ... },
  "HasErrors": false,
  "Cities": {
    "string": [
      "Abu Dhabi",
      "Ajman",
      "Dubai",
      "Fujairah",
      ...
    ]
  }
}
```

**On Error:**
```json
{
  "error": 1,
  "errors": [array of error objects]
}
```

### Example
```php
$cities = Aramex::fetchCities('AE');

if (!$cities->error) {
    foreach ($cities->Cities->string as $city) {
        echo $city . '\n';
    }
}

// With filter
$dubaiCities = Aramex::fetchCities('AE', 'Du');
```
```

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

### Create Pickup with Aramex SDK

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/README.md

Use the `createPickup` method to schedule a pickup with Aramex. Pass an array of parameters detailing the pickup location, contact information, and package details. The response indicates success or failure with relevant details.

```php
$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;
```

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

### initializeShipmentTracking

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a shipment tracking request by providing an array of shipment IDs.

```APIDOC
## initializeShipmentTracking

### Description
Prepares a shipment tracking request.

### Method
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **shipmentIds** (array) - Required - Array of shipment ID strings

### Side Effects
Sets `$this->param['Shipments']` to the provided array of shipment IDs.
```

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

### initializePickup

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a pickup request structure with location details and shipment specifications. This method modifies the internal pickup parameter ready for SOAP transmission.

```APIDOC
## initializePickup

### Description
Prepares a pickup request structure with location details and shipment specifications.

### Method
```php
public function initializePickup(
    stdClass $pickupDetails,
    stdClass $pickupAddress
): void
```

### Parameters
#### Path Parameters
- **$pickupDetails** (stdClass) - Required - Pickup specification object
- **$pickupAddress** (stdClass) - Required - Pickup location/contact object

### Object Structures
#### $pickupDetails object
- **Reference1** (string) - Required - Example: "PU001"
- **PickupLocation** (string) - Required - Example: "Reception area"
- **Status** (string) - Required - Example: "Ready" or "Pending"
- **PickupDate** (timestamp) - Required - Example: 1609459200
- **ReadyTime** (timestamp) - Required - Example: 1609456000
- **LastPickupTime** (timestamp) - Required - Example: 1609462800
- **ClosingTime** (timestamp) - Required - Example: 1609466400
- **ProductGroup** (string) - Required - Example: "EXP" or "DOM"
- **Payment** (string) - Required - Example: "P"
- **ProductType** (string) - Required - Example: "PPX"
- **Weight** (numeric) - Required - Example: 10
- **Volume** (numeric) - Required - Example: 500

#### $pickupAddress object
- **PersonName** (string) - Required - Example: "Manager"
- **PhoneNumber1** (string) - Required - Example: "+1234567890"
- **CellPhone** (string) - Required - Example: "+0987654321"
- **EmailAddress** (string) - Required - Example: "pickup@example.com"
- **Line1** (string) - Required - Example: "456 Business Ave"
- **Line2** (string) - Optional - Example: "Floor 5"
- **Line3** (string) - Optional - Example: "Building B"
- **CountryCode** (string) - Required - Example: "US"
- **City** (string) - Required - Example: "Chicago"
- **ZipCode** (string) - Required - Example: "60601"

### Side Effects
Modifies `$this->param['Pickup']` with a complete pickup structure ready for SOAP transmission.
```

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

### Cancel Aramex Pickup Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/aramex-class.md

Use this method to cancel an existing Aramex pickup request. You need the pickup GUID and a reason for cancellation.

```php
public static function cancelPickup(string $pickupGuid, string $comment): stdClass
```

```php
$response = Aramex::cancelPickup('4e29b471-0ed8-4ba8-ac0e-fddedfb6beec', 'Cancelled per customer request');

if (!isset($response->error) || !$response->error) {
    echo 'Pickup cancelled successfully';
}
```

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

### Calculate Rate API Fail Response Sample

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/README.md

Example of a failed response from the Calculate Rate API, indicating an error and providing error messages.

```json
    {
      "error": 1,
      "errors": "Error strings one by one."
    }
```

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

### Core Class Constructor

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Initializes the Core instance with client credentials from Laravel's configuration. The constructor automatically sets up the parameter array with ClientInfo and Transaction structures, loads configuration, and populates ClientInfo with account details.

```php
public function __construct()
```

```php
use Octw\Aramex\Core;

$core = new Core();
// Constructor automatically loads config and initializes params
```

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

### Full Configuration with Environment Variables

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/configuration.md

Defines the complete configuration array for the Aramex SDK, utilizing environment variables for sensitive data and settings. Supports both TEST and LIVE environments.

```php
<?php

return [
    'ENV' => env('ARAMEX_ENV', 'TEST'),

    'TEST' => [
        'AccountNumber' => env('ARAMEX_TEST_ACCOUNT'),
        'UserName' => env('ARAMEX_TEST_USERNAME'),
        'Password' => env('ARAMEX_TEST_PASSWORD'),
        'AccountPin' => env('ARAMEX_TEST_PIN'),
        'AccountEntity' => env('ARAMEX_TEST_ENTITY', 'AMM'),
        'AccountCountryCode' => env('ARAMEX_TEST_COUNTRY', 'JO'),
        'Version' => 'v1'
    ],

    'LIVE' => [
        'AccountNumber' => env('ARAMEX_LIVE_ACCOUNT'),
        'UserName' => env('ARAMEX_LIVE_USERNAME'),
        'Password' => env('ARAMEX_LIVE_PASSWORD'),
        'AccountPin' => env('ARAMEX_LIVE_PIN'),
        'AccountEntity' => env('ARAMEX_LIVE_ENTITY'),
        'AccountCountryCode' => env('ARAMEX_LIVE_COUNTRY'),
        'Version' => 'v1'
    ],

    'CompanyName' => env('COMPANY_NAME', 'My Company'),

    'ProductGroup' => env('ARAMEX_PRODUCT_GROUP', 'EXP'),
    'ProductType' => env('ARAMEX_PRODUCT_TYPE', 'PPX'),
    'Payment' => env('ARAMEX_PAYMENT_TYPE', 'P'),
    'PaymentOptions' => env('ARAMEX_PAYMENT_OPTIONS'),
    'Services' => env('ARAMEX_SERVICES'),
    'CurrencyCode' => env('ARAMEX_CURRENCY', 'USD'),

    'LabelInfo' => [
        'ReportID' => (int) env('ARAMEX_REPORT_ID', 9201),
        'ReportType' => env('ARAMEX_REPORT_TYPE', 'URL'),
    ]
];
```

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

### Get SOAP Parameters

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Retrieve the complete parameters array formatted for SOAP transmission after initializing shipment details. This array is then passed to the SOAP API.

```php
public function getParam(): array
```

```php
$core = new Core();
$core->initializeShipment($shipper, $consignee, $details);
$soapParams = $core->getParam();
// $soapParams is passed to SOAP API
```

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

### Create Pickup Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/INDEX.md

Use the `createPickup` method to create a pickup request with the specified parameters.

```php
Aramex::createPickup(array $params)
```

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

### Initialize Shipment Tracking Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a shipment tracking request. Sets the array of shipment IDs to track.

```php
public function initializeShipmentTracking(array $shipmentIds): void
```

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

### Loading Aramex Configuration

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/service-provider.md

Demonstrates how to access various Aramex SDK configuration values using Laravel's `config()` helper. Ensure the configuration file is published and updated with your credentials.

```php
config('aramex.ENV')                    // Environment (TEST or LIVE)
config("aramex." . config('aramex.ENV'))  // Credentials for current environment
config('aramex.CompanyName')            // Company name
config('aramex.ProductGroup')           // Default product group
config('aramex.LabelInfo')              // Label configuration
```

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

### Aramex LIVE Client Credentials (Direct)

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/configuration.md

Configure the live (production) credentials for the Aramex API. Ensure these are kept secure and are not committed to version control.

```php
'LIVE' => [
    'AccountNumber' => '',
    'UserName' => '',
    'Password' => '',
    'AccountPin' => '',
    'AccountEntity' => '',
    'AccountCountryCode' => '',
    'Version' => ''
]
```

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

### Calculate Rate

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/README.md

The Calculate Rate API is used to get shipment pricing and details before you ship it. It takes origin address, destination address, shipment details, and currency as parameters.

```APIDOC
## Calculate Rate

### Description
Calculate Rate API is used to get shipment pricing and details before you ship it.

### Method
`Aramex::calculateRate($originAddress, $destinationAddress, $shipementDetails, $currency)`

### Parameters
#### Origin Address (`$originAddress`)
An array with the following structure:
- **line1** (String|Required) - The first line of the address.
- **line2** (String) - The second line of the address.
- **line3** (String) - The third line of the address.
- **city** (String|Required) - The city of the address.
- **state_code** (String) - The state code.
- **postal_code** (String) - The postal code.
- **country_code** (String|max:2|min:2|Required) - The two-character country code.
- **longitude** (Double) - The longitude coordinate.
- **latitude** (Double) - The latitude coordinate.
- **building_number** (String) - The building number.
- **building_name** (String) - The building name.

#### Destination Address (`$destinationAddress`)
An array with the same structure as `$originAddress`.

#### Shipment Details (`$shipmentDetails`)
An array describing shipment details:
- **payment_type** (String) - The payment type (defaults to config value).
- **product_group** (String) - The product group (defaults to config value).
- **product_type** (String) - The product type (defaults to config value).
- **weight** (Double|Required) - The weight of the shipment in KG.
- **number_of_pieces** (Integer|Required) - The number of pieces in the shipment.
- **height** (Double) - The height of the shipment in CM (optional, requires width and length).
- **width** (Double) - The width of the shipment in CM (optional, requires height and length).
- **length** (Double) - The length of the shipment in CM (optional, requires height and width).

#### Currency (`$currency`)
A string representing the preferred currency (e.g., 'USD', 'AED', 'EUR', 'KWD').

### Request Example
```php
$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
];

$currency = 'USD';
$data = Aramex::calculateRate($originAddress, $destinationAddress , $shipmentDetails , $currency);

if(!isset($data->error) || !$data->error){
  // Process successful response
  print_r($data);
}
else{
  // handle $data->errors
  echo $data->errors;
}
```

### Response
#### Success Response
- **Transaction** (Object) - Transaction details.
- **Notifications** (Object) - Notification details.
- **HasErrors** (Boolean) - Indicates if there were errors.
- **TotalAmount** (Object) - Contains `CurrencyCode` and `Value`.
- **RateDetails** (Object) - Contains detailed rate information like `Amount`, `TaxAmount`, etc.

#### Success Response Example
```json
{
   "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
   }
}
```

#### Fail Response
- **error** (Integer) - Indicates an error occurred (typically 1).
- **errors** (String) - A string containing error messages.

#### Fail Response Example
```json
{
  "error": 1,
  "errors": "Error strings one by one."
}
```
```

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

### Unit Testing with Aramex Service Provider

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/service-provider.md

Set up unit tests using Orchestra Testbench, registering the Aramex service provider and aliases for testing.

```php
use Orchestra\Testbench\TestCase;

class AramexTest extends TestCase
{
    protected function getPackageProviders($app)
    {
        return ['Octw\Aramex\AramexServiceProvider'];
    }

    protected function getPackageAliases($app)
    {
        return [
            'Aramex' => 'Octw\Aramex\Aramex',
        ];
    }

    public function testPickupCreation()
    {
        // Provider is loaded
        $result = Aramex::createPickup([...]);
    }
}
```

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

### Fetch All or Specific Countries with Aramex SDK

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/README.md

Use this snippet to fetch country data from Aramex. You can retrieve all supported countries by calling the function without parameters, or get details for a specific country by passing its code.

```php
$data = Aramex::fetchCountries($countryCode);
        // Or 
        $data = Aramex::fetchCountries();
```

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

### Initialize Fetch Countries Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a request to fetch country data. Optionally filters by a specific country code.

```php
public function initializeFetchCountries(?string $code = null): void
```

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

### Example Validation Error Response Structure

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/errors.md

Illustrates the expected JSON format for validation errors, where keys represent fields and values are arrays of error messages for that field. This structure is common across various validation sources.

```json
{
    "field_name": [
        "Validation rule 1 message",
        "Validation rule 2 message"
    ]
}
```

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

### Example Address Validation Error Response

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/errors.md

Demonstrates a typical error response for address validation failures, highlighting specific fields like 'name' and 'phone' with their respective validation rule violations. This response is generated when address objects do not meet the required criteria.

```json
{
    "name": ["The name must be at least 3 characters."],
    "phone": ["The phone must be at least 8 characters."]
}
```

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

### Initialize Pickup Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a pickup request structure with location details and shipment specifications. Modifies the internal pickup parameter for SOAP transmission.

```php
public function initializePickup(
    stdClass $pickupDetails,
    stdClass $pickupAddress
): void
```

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

### Calculate Aramex Shipping Rate

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/aramex-class.md

Use this function to get shipping rates before creating a shipment. It requires origin, destination, and shipment details, along with the desired currency. The return value includes total amount and rate details on success, or error information on failure.

```php
$originAddress = [
    'line1' => 'Business Plaza',
    'city' => 'Amman',
    'country_code' => 'JO'
];

$destinationAddress = [
    'line1' => 'Trade Center',
    'city' => 'Dubai',
    'country_code' => 'AE'
];

$shipmentDetails = [
    'weight' => 5.5,
    'number_of_pieces' => 2,
    'length' => 20,
    'width' => 15,
    'height' => 10
];

$rateData = Aramex::calculateRate(
    $originAddress,
    $destinationAddress,
    $shipmentDetails,
    'USD'
);

if (!$rateData->error) {
    echo 'Total: ' . $rateData->TotalAmount->Value . ' ' . $rateData->TotalAmount->CurrencyCode;
    echo 'Tax: ' . $rateData->RateDetails->TaxAmount;
}
```

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

### Create a Shipment

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/INDEX.md

This code demonstrates how to create a new shipment. It requires detailed information for both the shipper and the consignee, along with shipment specifics.

```php
$shipment = Aramex::createShipment([
    'shipper' => [
        'name' => 'Shipper Name',
        'email' => 'shipper@company.com',
        'phone' => '+1234567890',
        'cell_phone' => '+0987654321',
        'country_code' => 'US',
        'city' => 'New York',
        'zip_code' => '10001',
        'line1' => '123 Main St',
        'line2' => 'Floor 5'
    ],
    'consignee' => [
        'name' => 'Recipient Name',
        'email' => 'recipient@example.com',
        'phone' => '+971234567890',
        'cell_phone' => '+971987654321',
        'country_code' => 'AE',
        'city' => 'Dubai',
        'zip_code' => '00000',
        'line1' => '456 Sheikh Zayed Rd',
        'line2' => 'Downtown'
    ],
    'shipping_date_time' => time() + 86400,
    'due_date' => time() + 172800,
    'pickup_location' => 'Warehouse',
    'weight' => 10,
    'description' => 'Electronics shipment',
    'reference' => 'ORD-2024-001'
]);

if (empty($shipment->error)) {
    $shipmentId = $shipment->Shipments->ProcessedShipment->ID;
    echo "Shipment created: $shipmentId";
}
```

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

### Initialize Rate Calculation Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a rate calculation request. Sets origin and destination addresses, shipment details, and currency code.

```php
public function initializeCalculateRate(
    stdClass $originAddress,
    stdClass $destinationAddress,
    stdClass $shipmentDetails,
    string $currencyCode
): void
```

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

### Publish Aramex Configuration File

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/service-provider.md

Publishes the package's configuration file to the application's config directory. This is part of the boot method, executed after all service providers are registered.

```php
$this->publishes([
    __DIR__ . '/config/main.php' => config_path('aramex.php'),
]);
```

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

### Create a Pickup

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/INDEX.md

Use this snippet to create a new pickup request with Aramex. Ensure all required address and timing details are provided.

```php
use Octw\Aramex\Aramex;

$pickup = Aramex::createPickup([
    'name' => 'John Smith',
    'email' => 'john@example.com',
    'phone' => '+1234567890',
    'cell_phone' => '+0987654321',
    'country_code' => 'US',
    'city' => 'New York',
    'zip_code' => '10001',
    'line1' => '123 Main Street',
    'line2' => 'Suite 100',
    'pickup_date' => time() + 86400,
    'ready_time' => time() + 82800,
    'last_pickup_time' => time() + 90000,
    'closing_time' => time() + 93600,
    'status' => 'Ready',
    'pickup_location' => 'Warehouse A',
    'weight' => 25,
    'volume' => 1000
]);

if (!$pickup->error) {
    echo "Pickup created: " . $pickup->pickupID;
} else {
    foreach ($pickup->errors as $error) {
        echo $error->Code . ": " . $error->Message;
    }
}
```

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

### Initialize Address Validation Request

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a request to validate an address. Requires a structured address object.

```php
public function initializeValidateAddress(stdClass $address): void
```

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

### initializeFetchCountries

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a country fetch request. Optionally filters by a specific country code.

```APIDOC
## initializeFetchCountries

### Description
Prepares a country fetch request. Optionally filters by a specific country code.

### Method
```php
public function initializeFetchCountries(?string $code = null): void
```

### Parameters
#### Query Parameters
- **code** (string) - Optional - ISO 2-letter country code (optional)

### Side Effects
If `$code` is provided, sets `$this->param['Code']`. If null, only the ClientInfo is set.
```

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

### Import Aramex Facade

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/README.md

Import the Aramex facade into your PHP files to easily access its methods. Alternatively, you can add it to the 'aliases' array in config/app.php.

```php
use Octw\Aramex\Aramex;
```

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

### Cache Configuration

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/configuration.md

After publishing or modifying the configuration, cache it for production environments to improve performance. This command optimizes the loading of configuration files.

```bash
php artisan config:cache
```

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

### Publish Aramex Configuration

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/service-provider.md

Use this command to publish the Aramex configuration file to your application's config directory. This allows you to customize Aramex credentials.

```bash
php artisan vendor:publish --provider="Octw\Aramex\AramexServiceProvider"
```

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

### initializeShipment

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/core-class.md

Prepares a shipment request structure with shipper, consignee, and shipment details. This method populates the internal shipment structure ready for API transmission.

```APIDOC
## initializeShipment

### Description
Prepares a shipment request structure with shipper, consignee, and shipment details.

### Method Signature
`public function initializeShipment(stdClass $shipper, stdClass $consignee, stdClass $details): void`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### `$shipper` (stdClass) - Required
- **PersonName** (string) - Shipper's full name.
- **PhoneNumber1** (string) - Shipper's primary phone number.
- **CellPhone** (string) - Shipper's mobile phone number.
- **EmailAddress** (string) - Shipper's email address.
- **Line1** (string) - Shipper's primary address line.
- **Line2** (string) - Shipper's secondary address line (optional).
- **Line3** (string) - Shipper's tertiary address line (optional).
- **City** (string) - Shipper's city.
- **ZipCode** (string) - Shipper's postal code.
- **CountryCode** (string) - Shipper's country code (e.g., "US").

##### `$consignee` (stdClass) - Required
- **PersonName** (string) - Consignee's full name.
- **PhoneNumber1** (string) - Consignee's primary phone number.
- **CellPhone** (string) - Consignee's mobile phone number.
- **EmailAddress** (string) - Consignee's email address.
- **Line1** (string) - Consignee's primary address line.
- **Line2** (string) - Consignee's secondary address line (optional).
- **Line3** (string) - Consignee's tertiary address line (optional).
- **City** (string) - Consignee's city.
- **ZipCode** (string) - Consignee's postal code.
- **CountryCode** (string) - Consignee's country code (e.g., "US").

##### `$details` (stdClass) - Required
- **ShippingDateTime** (timestamp) - The desired shipping date and time.
- **DueDate** (timestamp) - The expected delivery date and time.
- **Comments** (string) - Any special comments for the shipment.
- **PickupLocation** (string) - The location for pickup.
- **PickupGUID** (string or null) - Unique identifier for the pickup location.
- **ActualWeight** (numeric) - The actual weight of the shipment.
- **NumberOfPieces** (numeric) - The number of pieces in the shipment.
- **GoodsOriginCountry** (string or null) - The country of origin for the goods.
- **ProductGroup** (string) - The product group (e.g., "EXP" for Express, "DOM" for Domestic).
- **ProductType** (string) - The specific product type (e.g., "PPX").
- **PaymentType** (string) - The payment type (e.g., "P" for Prepaid).
- **PaymentOptions** (string or null) - Additional payment options.
- **DescriptionOfGoods** (string) - A description of the goods being shipped.
- **Services** (string or null) - Additional services required (e.g., "CODS,FIRST").
- **Reference1** (string) - A reference number.
- **ShipperReference** (string) - Shipper's reference number.
- **ConsgineeReference** (string) - Consignee's reference number.
- **CollectAmount** (numeric) - Amount to be collected upon delivery (if applicable).
- **CashOnDeliveryAmount** (numeric) - The cash on delivery amount.
- **InsuranceAmount** (numeric) - The insured value of the shipment.
- **CashAdditionalAmount** (numeric) - Additional cash amount.
- **CashAdditionalAmountDescription** (string) - Description for the additional cash amount.
- **CustomsValueAmount** (numeric) - The declared customs value.
- **CurrencyCode** (string) - The currency code (e.g., "USD").

### Response
This method does not return a value directly. It modifies the internal state of the object.

### Side Effects
Modifies `$this->param['Shipments']` with a complete shipment structure ready for SOAP transmission.
```

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

### Register Custom Service Provider in app.php

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/service-provider.md

Register the custom service provider in your application's config/app.php file. Ensure the original provider is removed and the custom one is added.

```php
'providers' => [
    // Remove original
    // Octw\Aramex\AramexServiceProvider::class,
    
    // Add custom
    App\Providers\CustomAramexServiceProvider::class,
],
```

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

### Access Configuration via Facade

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/configuration.md

Retrieve specific configuration values, such as the ReportID for label information, using the Illuminate Support Facades Config class.

```php
use Illuminate\Support\Facades\Config;

$reportId = Config::get('aramex.LabelInfo.ReportID');
```

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

### createPickup

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/api-reference/aramex-class.md

Creates a new pickup request with Aramex. It requires an array of details including contact information, address, shipment specifics, and timing.

```APIDOC
## createPickup

### Description
Creates a new pickup request with Aramex.

### Method
`static public function createPickup(array $param = []): stdClass`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### $param (array) - Required
Pickup details array containing address and shipment information.

###### Array Parameters (for $param)
- **name** (string) - Required - Contact person's name (min 3 chars)
- **cell_phone** (string) - Required - Mobile phone number (min 8 chars)
- **phone** (string) - Required - Land phone number (min 8 chars)
- **email** (string) - Required - Email address (min 3 chars)
- **city** (string) - Required - City name (min 3 chars)
- **country_code** (string) - Required - ISO 2-letter country code (min 2 chars)
- **line1** (string) - Required - Address line 1 (min 5 chars)
- **line2** (string) - Required - Address line 2 (min 5 chars)
- **line3** (string) - Optional - Address line 3
- **zip_code** (string) - Optional - Postal code
- **pickup_date** (timestamp) - Required - Pickup date as Unix timestamp
- **ready_time** (timestamp) - Required - Time when pickup is ready (Unix timestamp)
- **last_pickup_time** (timestamp) - Required - Last allowed pickup time (Unix timestamp)
- **closing_time** (timestamp) - Required - Location closing time (Unix timestamp)
- **status** (string) - Required - Either 'Pending' or 'Ready'
- **pickup_location** (string) - Required - Description of pickup location
- **weight** (numeric) - Required - Weight in kilograms (KG)
- **volume** (numeric) - Required - Volume in cubic centimeters (CM³)
- **product_group** (string) - Optional - 'EXP' (Express) or 'DOM' (Domestic). Default from config
- **product_type** (string) - Optional - Product type code. Default from config
- **payment** (string) - Optional - Payment method code. Default from config
- **reference1** (string) - Optional - Reference identifier (defaults to current timestamp)
- **reference2** (string) - Optional - Additional reference
- **reference3** (string) - Optional - Additional reference

### Request Example
```php
use Octw\Aramex\Aramex;

$pickupData = Aramex::createPickup([
    'name' => 'John Smith',
    'cell_phone' => '+1234567890',
    'phone' => '+1234567890',
    'email' => 'john@example.com',
    'city' => 'New York',
    'country_code' => 'US',
    'zip_code' => '10001',
    'line1' => '123 Main Street',
    'line2' => 'Suite 100',
    'line3' => 'Building A',
    'pickup_date' => time() + 86400,
    'ready_time' => time() + 82800,
    'last_pickup_time' => time() + 90000,
    'closing_time' => time() + 93600,
    'status' => 'Ready',
    'pickup_location' => 'At reception desk',
    'weight' => 15,
    'volume' => 500
]);

if (!$pickupData->error) {
    echo $pickupData->pickupGUID;
    echo $pickupData->pickupID;
} else {
    foreach ($pickupData->errors as $error) {
        echo $error->Code . ': ' . $error->Message;
    }
}
```

### Response
#### Success Response (200)
- **error** (integer) - 0 indicates success
- **pickupGUID** (string) - Unique identifier for the pickup (UUID format)
- **pickupID** (string) - Numeric ID for the pickup

#### Error Response
- **error** (integer) - 1 indicates an error
- **errors** (array) - An array of Aramex error objects

### Throws
- `Exception` — If validation fails on required address fields
```

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

### Set Product Type

Source: https://github.com/moustafa22/laravel-aramex-sdk/blob/master/_autodocs/configuration.md

Specify the service level within the chosen product group. The available codes depend on whether the ProductGroup is 'EXP' (Express) or 'DOM' (Domestic).

```php
'ProductType' => 'PPX'
```