README

This PHP library allows for easy integration with the Aramex shipping API. It provides a set of models and a client to interact with the API for creating shipments, generating labels, and more.

Requirements

PHP 8 or higher
Composer

Installation

Install the library using Composer:

composer require aboodma/aramex-integration

Usage

Configuration

Create a configuration object with your Aramex account details:

use Aboodma\AramexIntegration\Config;

$config = (new Config())
    ->setUsername("your_username")
    ->setPassword("your_password")
    ->setVersion("v1.0")
    ->setAccountNumber("your_account_number")
    ->setAccountPin("your_account_pin")
    ->setAccountEntity("your_account_entity")
    ->setAccountCountryCode("your_account_country_code")
    ->setSource(24);

Creating a Shipment

use Aboodma\AramexIntegration\Models\Address;
use Aboodma\AramexIntegration\Models\Contact;
use Aboodma\AramexIntegration\Models\Party;
use Aboodma\AramexIntegration\Models\Dimensions;
use Aboodma\AramexIntegration\Models\Weight;
use Aboodma\AramexIntegration\Models\Amount;
use Aboodma\AramexIntegration\Models\ShipmentDetails;
use Aboodma\AramexIntegration\Models\Shipment;
use Aboodma\AramexIntegration\Models\LabelInfo;
use Aboodma\AramexIntegration\Models\ClientInfo;
use Aboodma\AramexIntegration\AramexClient;
use Aboodma\AramexIntegration\Exceptions\AramexException;

// Shipper details
$shipperAddress = (new Address())
    ->setLine1("Test Shipper Address Line1")
    ->setLine2("Test Shipper Address Line2")
    ->setCity("Dubai")
    ->setPostCode("000000")
    ->setCountryCode("AE");

$shipperContact = (new Contact())
    ->setPersonName("Test Shipper Name")
    ->setCompanyName("Test Shipper Company Name")
    ->setPhoneNumber1("048707766")
    ->setCellPhone("971556893100")
    ->setEmailAddress("test@aramex.com");

$shipper = (new Party())
    ->setReference1("Shipper Reference")
    ->setAccountNumber("45796")
    ->setPartyAddress($shipperAddress)
    ->setContact($shipperContact);

// Consignee details
$consigneeAddress = (new Address())
    ->setLine1("Test Consignee Address Line1")
    ->setLine2("Test Consignee Address Line2")
    ->setLine3("Test Consignee Address Line3")
    ->setCity("Dubai")
    ->setStateOrProvinceCode("FU")
    ->setCountryCode("AE");

$consigneeContact = (new Contact())
    ->setPersonName("Test Consignee Name")
    ->setCompanyName("Test Consignee Company Name")
    ->setPhoneNumber1("048707766")
    ->setCellPhone("971556893100")
    ->setEmailAddress("tets@hotmail.com");

$consignee = (new Party())
    ->setAccountNumber("0")
    ->setPartyAddress($consigneeAddress)
    ->setContact($consigneeContact);

// Shipment details
$dimensions = (new Dimensions())
    ->setLength(0)
    ->setWidth(0)
    ->setHeight(0)
    ->setUnit("CM");

$actualWeight = (new Weight())
    ->setUnit("KG")
    ->setValue(0.1);

$chargeableWeight = (new Weight())
    ->setUnit("KG")
    ->setValue(0);

$amount = (new Amount())
    ->setCurrencyCode("AED")
    ->setValue(10);

$details = (new ShipmentDetails())
    ->setDimensions($dimensions)
    ->setActualWeight($actualWeight)
    ->setChargeableWeight($chargeableWeight)
    ->setDescriptionOfGoods("Items")
    ->setGoodsOriginCountry("AE")
    ->setNumberOfPieces(1)
    ->setProductGroup("DOM")
    ->setProductType("ONP")
    ->setPaymentType("P")
    ->setPaymentOptions("ACCT")
    ->setCustomsValueAmount($amount);

$shipment = (new Shipment())
    ->setShipper($shipper)
    ->setConsignee($consignee)
    ->setDetails($details)
    ->setReference1("Shipment Reference");

// Label info
$labelInfo = (new LabelInfo())
    ->setReportID(9729)
    ->setReportType("URL");

// Client info
$clientInfo = (new ClientInfo())
    ->setUserName("testingapi@aramex.com")
    ->setPassword('R123456789$r')
    ->setVersion("v1.0")
    ->setAccountNumber("45796")
    ->setAccountPin("116216")
    ->setAccountEntity("DXB")
    ->setAccountCountryCode("AE")
    ->setSource(24);

// Initialize AramexClient and make the request
$client = new AramexClient($config);

try {
    $response = $client->createShipment($shipment, $labelInfo, $clientInfo);
    echo json_encode($response, JSON_PRETTY_PRINT);
} catch (AramexException $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
    echo 'HTTP Status Code: ' . $e->getHttpStatusCode() . PHP_EOL;
    echo 'Error Details: ' . print_r($e->getErrorDetails(), true);
}

Models

Address

Represents an address.

setLine1(string $line1): self
setLine2(string $line2): self
setLine3(string $line3): self
setCity(string $city): self
setStateOrProvinceCode(string $stateOrProvinceCode): self
setPostCode(string $postCode): self
setCountryCode(string $countryCode): self

Contact

Represents a contact.

setPersonName(string $personName): self
setCompanyName(string $companyName): self
setPhoneNumber1(string $phoneNumber1): self
setPhoneNumber1Ext(string $phoneNumber1Ext): self
setPhoneNumber2(string $phoneNumber2): self
setPhoneNumber2Ext(string $phoneNumber2Ext): self
setFaxNumber(string $faxNumber): self
setCellPhone(string $cellPhone): self
setEmailAddress(string $emailAddress): self
setType(string $type): self

Party

Represents a party involved in the shipment (shipper or consignee).

setReference1(string $reference1): self
setReference2(string $reference2): self
setAccountNumber(string $accountNumber): self
setPartyAddress(Address $partyAddress): self
setContact(Contact $contact): self

Dimensions

Represents the dimensions of a shipment.

setLength(float $length): self
setWidth(float $width): self
setHeight(float $height): self
setUnit(string $unit): self

Weight

Represents the weight of a shipment.

setUnit(string $unit): self
setValue(float $value): self

Amount

Represents a monetary amount.

setCurrencyCode(string $currencyCode): self
setValue(float $value): self

ShipmentDetails

Represents the details of a shipment.

setDimensions(Dimensions $dimensions): self
setActualWeight(Weight $actualWeight): self
setChargeableWeight(Weight $chargeableWeight): self
setDescriptionOfGoods(string $descriptionOfGoods): self
setGoodsOriginCountry(string $goodsOriginCountry): self
setNumberOfPieces(int $numberOfPieces): self
setProductGroup(string $productGroup): self
setProductType(string $productType): self
setPaymentType(string $paymentType): self
setPaymentOptions(string $paymentOptions): self
setCustomsValueAmount(Amount $customsValueAmount): self
setCashOnDeliveryAmount(Amount $cashOnDeliveryAmount): self
setInsuranceAmount(Amount $insuranceAmount): self
setCashAdditionalAmount(Amount $cashAdditionalAmount): self
setCashAdditionalAmountDescription(string $cashAdditionalAmountDescription): self
setCollectAmount(Amount $collectAmount): self
setServices(string $services): self
setItems(array $items): self
setDeliveryInstructions(string $deliveryInstructions): self
setAdditionalProperties(string $additionalProperties): self
setContainsDangerousGoods(bool $containsDangerousGoods): self

Shipment

Represents a shipment.

setReference1(string $reference1): self
setReference2(string $reference2): self
setReference3(string $reference3): self
setShipper(Party $shipper): self
setConsignee(Party $consignee): self
setThirdParty(Party $thirdParty): self
setShippingDateTime(\DateTime $shippingDateTime): self
setDueDate(\DateTime $dueDate): self
setComments(string $comments): self
setPickupLocation(string $pickupLocation): self
setOperationsInstructions(string $operationsInstructions): self
setAccountingInstructions(string $accountingInstructions): self
setDetails(ShipmentDetails $details): self
setAttachments(array $attachments): self
setForeignHAWB(string $foreignHAWB): self
setTransportType(string $transportType): self
setPickupGUID(string $pickupGUID): self
setNumber(string $number): self
setScheduledDelivery(\DateTime $scheduledDelivery): self

LabelInfo

Represents label information for the shipment.

setReportID(int $reportID): self
setReportType(string $reportType): self

ClientInfo

Represents client information.

setUserName(string $userName): self
setPassword(string $password): self
setVersion(string $version): self
setAccountNumber(string $accountNumber): self
setAccountPin(string $accountPin): self
setAccountEntity(string $accountEntity): self
setAccountCountryCode(string $accountCountryCode): self
setSource(int $source): self

Error Handling

If the API request fails, an AramexException will be thrown. This exception contains the error message, HTTP status code, and error details returned by the API.

try {
    $response = $client->createShipment($shipment, $labelInfo, $clientInfo);
    echo json_encode($response, JSON_PRETTY_PRINT);
} catch (AramexException $e) {
    echo 'Error: ' . $e->getMessage() . PHP_EOL;
    echo 'HTTP Status Code: ' . $e->getHttpStatusCode() . PHP_EOL;
    echo 'Error Details: ' . print_r($e->getErrorDetails(), true);
}

Logging

The library logs request payloads, response payloads, and error responses to log files for debugging purposes.

Contributing

Please submit issues and pull requests on the GitHub repository.

License

This project is licensed under the MIT License.

aboodma / aramex-integration

Maintainers

Details