aramex-pillvery/README.md

A simple wrapper for Aramex (JSON) API to manage shipments, tracking, and printing labels.

# Aramex Create Shipments API Wrapper

A Node.js wrapper for the Aramex Shipping API that simplifies creating shipments. It supports both testing and production environments and offers an easy-to-use interface for mapping required parameters.

---

## 📦 Installation

Install the package using npm:

```bash
npm install aramex-pillvery
```

---

## 🚀 Usage

### Import the Package

```javascript
const Aramex = require('aramex-pillvery');
```

### Initialize the Class

Create a new instance of the Aramex API wrapper with your credentials and environment settings.

```javascript
const aramex = new Aramex({
  UserName: "your_username",
  Password: "your_password",
  AccountNumber: "your_account_number",
  AccountPin: "your_account_pin",
  isTesting: true, // Set to false for production
});
```

### Create a Shipment

Call the `createShipment` method to create a new shipment.

```javascript
(async () => {
  try {
    const response = await aramex.createShipment({
      client_order_id: "12345",
      value: 50,
      customer_name: "John Doe",
      customer_phone: "962790123456",
      pickup_lat: 31.963158,
      pickup_lng: 35.930359,
      lat: 31.95,
      lng: 35.91,
      preparation_time: 15, // Default: 1 minute
      payment_type: 1, // 1 = CASH, 2 = CREDIT
    });

    console.log("Shipment created successfully:", response);
  } catch (error) {
    console.error("Error:", error);
  }
})();
```

---

## 📋 Parameters

### Constructor Parameters

| Parameter         | Type    | Description                                                                                      |
|-------------------|---------|--------------------------------------------------------------------------------------------------|
| `UserName`        | String  | Your Aramex API username.                                                                        |
| `Password`        | String  | Your Aramex API password.                                                                        |
| `AccountNumber`   | String  | Your Aramex account number.                                                                      |
| `AccountPin`      | String  | Your Aramex account PIN.                                                                         |
| `isTesting`       | Boolean | Set to `true` for the testing environment and `false` for production.                            |

### `createShipment` Method Parameters

| Parameter         | Type     | Description                                                                                 |
|-------------------|----------|---------------------------------------------------------------------------------------------|
| `client_order_id` | String   | Client's order ID. Mapped to `Reference1`.                                                  |
| `value`           | Number   | Value of the shipment. Mapped to `CustomsValueAmount.Value`.                                |
| `customer_name`   | String   | Name of the customer. Mapped to `Consignee.Contact.PersonName`.                             |
| `customer_phone`  | String   | Customer's phone number. Mapped to `Consignee.Contact.PhoneNumber1`.                        |
| `pickup_lat`      | Number   | Latitude for the shipper's pickup location. Mapped to `Shipper.PartyAddress.Latitude`.       |
| `pickup_lng`      | Number   | Longitude for the shipper's pickup location. Mapped to `Shipper.PartyAddress.Longitude`.     |
| `lat`             | Number   | Latitude for the consignee's address. Mapped to `Consignee.PartyAddress.Latitude`.           |
| `lng`             | Number   | Longitude for the consignee's address. Mapped to `Consignee.PartyAddress.Longitude`.         |
| `preparation_time`| Number   | Time in minutes to add to the current time for shipment. Defaults to `1`.                    |
| `payment_type`    | Number   | Payment type: `1` for CASH and `2` for CREDIT. Defaults to `1`.                              |

---

## 📤 Response

The `createShipment` method returns the response from the Aramex API. Handle the response or errors as needed.

---

## 📘 Example Response

Below is an example of a successful response:

```json
{
  "Transaction": {
    "Reference1": "12345",
    "Reference2": "",
    "Reference3": ""
  },
  "HasErrors": false,
  "Shipments": [
    {
      "ID": "123456789",
      "LabelURL": "https://aramex.com/label/123456789.pdf",
      "ShipmentTrackingNumber": "123456789"
    }
  ]
}
```

---

## 👤 Author

- **Your Name**  
  GitHub: [@abedjaradat2017](https://github.com/abedjaradat2017)  
  Email: abedjaradat2014@gmail.com