### Install and Publish Laravel Biteship Package

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Installs the cloudenum/laravel-biteship package via Composer and publishes its configuration file using Artisan. This is the initial setup step for using the package.

```bash
composer require cloudenum/laravel-biteship
php artisan vendor:publish --tag="biteship-config"
```

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

### Biteship Configuration File Example (PHP)

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This is the content of the published configuration file for the Biteship package. It defines the API base URL and requires an API key to be set in the environment variables.

```php
return [
    'base_url' => env('BITESHIP_BASE_URL', 'https://api.biteship.com'),
    'api_key' => env('BITESHIP_API_KEY'),
];
```

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

### Install cloudenum/laravel-biteship Package (Bash)

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

Instructions for installing the Biteship Laravel package using Composer. This command adds the package as a dependency to your project.

```bash
composer require cloudenum/laravel-biteship
```

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

### Retrieve Courier Rates with Specific Parameters (PHP)

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This example shows how to retrieve courier rates by providing origin postal code, destination postal code, a comma-separated string of courier codes, and item details. It's a core function for calculating shipping costs.

```php
$items = [
    [
        'name' => 'Black L',
        'description' => 'White Shirt',
        'category' => 'fashion',
        'value' => 165000,
        'quantity' => 1,
        'height' => 10,
        'length' => 10,
        'weight' => 200,
        'width' => 10,
    ]
];

$destination = 55510;
$origin = 12440;
$availableCouriers = \Cloudenum\Biteship\Courier::all();

$rates = \Cloudenum\Biteship\CourierPricing::Rates([
    'origin_postal_code' => $origin,
    'destination_postal_code' => $destination,
    'couriers' => implode(',', $availableCouriers->pluck('courier_code')->unique()->toArray()),
    'items' => $items,
]);
```

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

### Area::doubleSearchSecondRequest() - Get Detailed Area Information

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Performs the second request in a double search flow to retrieve more detailed area information or to get specific area details by ID.

```APIDOC
## GET /areas/double-search

### Description
Perform the second request in a double search flow to get more detailed area information. This is used when you need more precise location data by first performing a broad search, then drilling down into a specific area using its ID. Also useful for retrieving area details directly by ID.

### Method
GET

### Endpoint
`/areas/double-search`

### Query Parameters
- **area_id** (string) - Required - The ID of the area to retrieve detailed information for.

### Request Example
```php
use Cloudenum\Biteship\Area;

// First request: broad search with double mode enabled
$initialResults = Area::search("Lebak Bulus", "ID", true);
$selectedArea = $initialResults->first();

// Second request: get detailed sub-areas for the selected area
$detailedAreas = Area::doubleSearchSecondRequest($selectedArea->id);

foreach ($detailedAreas as $area) {
    echo "Area: ". $area->name . "\n";
    echo "Postal Code: ". $area->postal_code . "\n";
    echo "District: ". $area->administrative_division_level_3_name . "\n";
    echo "---\n";
}

// Can also be used to retrieve a specific area by known ID
$specificArea = Area::doubleSearchSecondRequest("IDNP6IDNC148IDND837IDNS2685");
```

### Response
#### Success Response (200)
- **data** (array) - A list of detailed Area objects, potentially including sub-areas or specific area details.
  - **id** (string) - The unique identifier for the area.
  - **name** (string) - The name of the area.
  - **postal_code** (string) - The postal code for the area.
  - **country_name** (string) - The name of the country.
  - **country_code** (string) - The ISO 3166-1 alpha-2 country code.
  - **administrative_division_level_1_name** (string) - The name of the first administrative division.
  - **administrative_division_level_2_name** (string) - The name of the second administrative division.
  - **administrative_division_level_3_name** (string) - The name of the third administrative division.
  - **administrative_division_level_4_name** (string) - The name of the fourth administrative division.

#### Response Example
```json
{
  "data": [
    {
      "id": "IDNP6IDNC148IDND837IDNS2685",
      "name": "Lebak Bulus, Cilandak, Kota Jakarta Selatan, DKI Jakarta, Indonesia",
      "postal_code": "12440",
      "country_name": "Indonesia",
      "country_code": "ID",
      "administrative_division_level_1_name": "DKI Jakarta",
      "administrative_division_level_2_name": "Kota Jakarta Selatan",
      "administrative_division_level_3_name": "Cilandak",
      "administrative_division_level_4_name": "Lebak Bulus"
    }
  ]
}
```
```

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

### Biteship::api() - Custom API Requests

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Access the underlying BiteshipApi instance for making custom API requests using GET, POST, PUT, or DELETE methods. This is useful for accessing endpoints not covered by the high-level model classes.

```APIDOC
## POST /v1/rates/couriers

### Description
Make a custom POST request to get shipping rates from couriers.

### Method
POST

### Endpoint
/v1/rates/couriers

### Parameters
#### Query Parameters
None

#### Request Body
- **origin_postal_code** (integer) - Required - The postal code of the origin.
- **destination_postal_code** (integer) - Required - The postal code of the destination.
- **couriers** (string) - Required - A comma-separated string of courier codes (e.g., 'jne,sicepat').
- **items** (array) - Required - An array of item objects, each with:
  - **weight** (integer) - Required - The weight of the item in grams.
  - **length** (integer) - Required - The length of the item in centimeters.
  - **width** (integer) - Required - The width of the item in centimeters.
  - **height** (integer) - Required - The height of the item in centimeters.

### Request Example
```json
{
    "origin_postal_code": 12440,
    "destination_postal_code": 55510,
    "couriers": "jne,sicepat",
    "items": [
        {"weight": 500, "length": 10, "width": 10, "height": 10}
    ]
}
```

### Response
#### Success Response (200)
- **rates** (array) - A list of available shipping rates from the specified couriers.

#### Response Example
```json
{
    "rates": [
        {
            "courier_id": "jne",
            "courier_name": "JNE",
            "service_name": "OKE",
            "price": 15000,
            "duration": 3,
            "description": "Ongkos Kirim Regular"
        }
    ]
}
```

## GET /v1/couriers

### Description
Retrieve a list of available couriers.

### Method
GET

### Endpoint
/v1/couriers

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **couriers** (array) - A list of available courier objects.

#### Response Example
```json
{
    "couriers": [
        {
            "id": "jne",
            "name": "JNE"
        },
        {
            "id": "sicepat",
            "name": "SiCepat"
        }
    ]
}
```

## General Request Method

### Description
Make a general API request using a specified HTTP method.

### Method
GET, POST, PUT, DELETE, or any other valid HTTP method.

### Endpoint
Any valid Biteship API endpoint path.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **method** (string) - Required - The HTTP method to use (e.g., 'get', 'post').
- **endpoint** (string) - Required - The API endpoint path.
- **payload** (array) - Optional - The request body payload for POST, PUT, etc.
- **headers** (array) - Optional - Custom headers to include in the request.

### Request Example
```php
$response = $api->request('get', '/v1/orders', [], [
    'X-Custom-Header' => 'custom-value'
]);
```

### Response
#### Success Response (200)
- **response** (object) - The API response object.

#### Response Example
```json
{
    "data": "..."
}
```
```

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

### Get Shipping Order By ID using PHP

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This snippet shows how to retrieve a specific shipping order using its unique identifier. The `CloudenumBiteshipOrder::find()` method is used, requiring the order's ID as an argument. This is useful for checking the status or details of an existing order.

```php
$biteshipOrder = CloudenumBiteshipOrder::find("ID");
```

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

### Get Shipment Tracking By ID using PHP

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This snippet illustrates how to track a shipment using its tracking ID. The `CloudenumBiteshipTracking::find()` method is employed, which takes the tracking ID as input. Note that this ID is distinct from the Waybill ID issued by couriers.

```php
$tracking = CloudenumBiteshipTracking::find("TrackingId");
```

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

### Perform Double Search Request with Area::doubleSearchSecondRequest() in PHP

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Executes the second part of a double search flow to retrieve detailed area information using an area ID. This method is useful for getting more precise location data or fetching specific area details when the ID is known.

```php
use Cloudenum\Biteship\Area;

// First request: broad search with double mode enabled
$initialResults = Area::search("Lebak Bulus", "ID", true);
$selectedArea = $initialResults->first();

// Second request: get detailed sub-areas for the selected area
$detailedAreas = Area::doubleSearchSecondRequest($selectedArea->id);

foreach ($detailedAreas as $area) {
    echo "Area: {$area->name}\n";
    echo "Postal Code: {$area->postal_code}\n";
    echo "District: {$area->administrative_division_level_3_name}\n";
    echo "---\n";
}

// Can also be used to retrieve a specific area by known ID
$specificArea = Area::doubleSearchSecondRequest("IDNP6IDNC148IDND837IDNS2685");
```

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

### Get Shipment Tracking By Waybill ID using PHP

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This snippet shows how to retrieve shipment tracking information using the courier's Waybill ID and the courier company name. The `CloudenumBiteshipTracking::findPublicTracking()` method is used for this purpose. This is useful for tracking shipments when you only have the Waybill ID.

```php
$tracking = CloudenumBiteshipTracking::findPublicTracking("WaybillId", "jne");
```

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

### Publish Biteship Configuration File (Bash)

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This command publishes the configuration file for the Biteship package, allowing you to customize settings like the base URL and API key.

```bash
php artisan vendor:publish --tag="biteship-config"
```

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

### Create a Shipping Order using PHP

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This snippet demonstrates how to create a new shipping order by providing detailed information about the shipper, origin, destination, courier, and items. It utilizes the `CloudenumBiteshipOrder::create()` method. Ensure all required fields are correctly populated for successful order creation.

```php
$data = [
    'shipper_contact_name' => 'Amir',
    'shipper_contact_phone' => '088888888888',
    'shipper_contact_email' => 'biteship@test.com',
    'shipper_organization' => 'Biteship Org Test',
    'origin_contact_name' => 'Amir',
    'origin_contact_phone' => '088888888888',
    'origin_address' => 'Plaza Senayan, Jalan Asia Afrika',
    'origin_note' => 'Deket pintu masuk STC',
    'origin_postal_code' => 12440,
    'destination_contact_name' => 'John Doe',
    'destination_contact_phone' => '088888888888',
    'destination_address' => 'Lebak Bulus MRT',
    'destination_postal_code' => 12950,
    'destination_note' => 'Near the gas station',
    'courier_company' => 'jne',
    'courier_type' => 'reg',
    'courier_insurance' => 500000,
    'delivery_type' => 'now',
    'order_note' => 'Please be careful',
    'metadata' => [],
    'items' => [
        [
            'name' => 'Black L',
            'description' => 'White Shirt',
            'category' => 'fashion',
            'value' => 165000,
            'quantity' => 1,
            'height' => 10,
            'length' => 10,
            'weight' => 200,
            'width' => 10,
        ]
    ]
];

$biteshipOrder = CloudenumBiteshipOrder::create($data);
```

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

### Configure Biteship API Credentials in .env

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Sets up the necessary Biteship API key and base URL in the Laravel application's environment file. These credentials are used by the package for authentication and API communication.

```properties
BITESHIP_API_KEY=your_api_key_here
BITESHIP_BASE_URL=https://api.biteship.com
```

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

### Add Biteship API Key to .env File (Properties)

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This shows how to add your Biteship API key to your project's .env file for authentication. Replace `<YourApiKey>` with your actual API key obtained from Biteship.

```properties
BITESHIP_API_KEY=<YourApiKey>
```

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

### Exception Handling

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Details on how to handle `InvalidArgumentException` for configuration errors and `RequestException` for API communication failures.

```APIDOC
## Exception Handling

### Description
Properly handle potential exceptions thrown by the Biteship package during configuration or API requests.

### Exceptions
- **InvalidArgumentException**: Thrown for invalid configuration parameters (e.g., missing API key).
- **RequestException**: Thrown for errors during API communication (e.g., network issues, API errors).

### Handling InvalidArgumentException

```php
use Cloudenum\Biteship\Biteship;
use Cloudenum\Biteship\Exceptions\InvalidArgumentException;

try {
    $api = Biteship::api([
        'api_key' => '', // Empty API key will throw exception
    ]);
} catch (InvalidArgumentException $e) {
    echo "Configuration Error: " . $e->getMessage() . "\n";
    // "api_key must be provided"
}
```

### Handling RequestException

```php
use Cloudenum\Biteship\Order;
use Cloudenum\Biteship\Exceptions\RequestException;

try {
    $order = Order::create([
        'origin_postal_code' => 12440,
        'destination_postal_code' => 55510,
        // Missing required fields will cause API error
    ]);
} catch (RequestException $e) {
    $response = $e->response;
    $statusCode = $response->status();
    $errorBody = $response->json();

    echo "API Error (" . $statusCode . "): " . $errorBody['error'] . "\n";

    // Log the full error for debugging
    logger()->error('Biteship API Error', [
        'status' => $statusCode,
        'body' => $errorBody,
    ]);
}
```

### Complete Error Handling Example

```php
use Cloudenum\Biteship\Area;
use Cloudenum\Biteship\Biteship;
use Cloudenum\Biteship\Exceptions\InvalidArgumentException;
use Cloudenum\Biteship\Exceptions\RequestException;

try {
    $areas = Area::search("Invalid Location XYZ123");

    if ($areas->isEmpty()) {
        throw new \Exception("No areas found for the given search");
    }

    $area = $areas->first();
    echo "Found: " . $area->name . "\n";

} catch (RequestException $e) {
    // API returned an error response
    report($e);
    return response()->json(['error' => 'Shipping service unavailable'], 503);

} catch (InvalidArgumentException $e) {
    // Configuration issue
    report($e);
    return response()->json(['error' => 'Service configuration error'], 500);

} catch (\Exception $e) {
    // Other errors
    return response()->json(['error' => $e->getMessage()], 400);
}
```
```

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

### Create a New Shipping Order with Biteship (PHP)

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

The Order::create() method sends shipment details to Biteship to create a new order. It requires comprehensive data including shipper, origin, destination, courier, and item information. The method returns an Order object containing tracking details and status.

```php
use Cloudenum\Biteship\Order;

$orderData = [
    // Shipper information
    'shipper_contact_name' => 'John Doe Store',
    'shipper_contact_phone' => '081234567890',
    'shipper_contact_email' => 'store@example.com',
    'shipper_organization' => 'My E-Commerce Store',

    // Origin (pickup) address
    'origin_contact_name' => 'Warehouse Staff',
    'origin_contact_phone' => '081234567890',
    'origin_address' => 'Plaza Senayan, Jalan Asia Afrika No. 8',
    'origin_note' => 'Lobby entrance, ask for security',
    'origin_postal_code' => 12440,
    // Alternative: use origin_area_id for accuracy
    // 'origin_area_id' => 'IDNP6IDNC148IDND837IDNS2685',

    // Destination (delivery) address
    'destination_contact_name' => 'Jane Customer',
    'destination_contact_phone' => '089876543210',
    'destination_contact_email' => 'jane@customer.com',
    'destination_address' => 'Jalan Malioboro No. 52',
    'destination_postal_code' => 55510,
    'destination_note' => 'Red gate, ring doorbell twice',

    // Courier selection (from rates query)
    'courier_company' => 'jne',
    'courier_type' => 'reg',
    'courier_insurance' => 500000,  // Insurance value in IDR

    // Delivery options
    'delivery_type' => 'now',       // 'now' or 'scheduled'
    // 'delivery_date' => '2024-12-01', // For scheduled delivery

    // Order details
    'order_note' => 'Handle with care - fragile items',
    'reference_id' => 'ORDER-12345', // Your internal order ID

    // Metadata for your reference
    'metadata' => [
        'internal_id' => 'INV-2024-001',
        'customer_tier' => 'premium',
    ],

    // Items to ship
    'items' => [
        [
            'name' => 'Black T-Shirt L',
            'description' => 'Premium Cotton T-Shirt',
            'category' => 'fashion',
            'value' => 165000,
            'quantity' => 1,
            'height' => 10,
            'length' => 10,
            'weight' => 200,
            'width' => 10,
        ],
        [
            'name' => 'Gift Box',
            'description' => 'Decorative gift packaging',
            'category' => 'fashion',
            'value' => 25000,
            'quantity' => 1,
            'height' => 15,
            'length' => 15,
            'weight' => 100,
            'width' => 15,
        ]
    ]
];

$order = Order::create($orderData);

// Access order details
echo "Order ID: {$order->id}\n";
echo "Short ID: {$order->short_id}\n";
echo "Status: {$order->status}\n";
echo "Price: Rp " . number_format($order->price) . "\n";
echo "Tracking ID: {$order->courier['tracking_id']}\n";
echo "Waybill ID: {$order->courier['waybill_id']}\n";
echo "Tracking Link: {$order->courier['link']}\n";

```

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

### Search for an Area using Biteship API (PHP)

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This snippet demonstrates how to search for a specific area using the Biteship API. It takes a search query string as input and returns matching area information.

```php
\Cloudenum\Biteship\Area::search("Lebak Bulus");
```

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

### Retrieve Shipping Costs with Biteship API (PHP)

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This snippet demonstrates how to retrieve shipping costs by defining items, origin, and destination. It utilizes the `CourierPricing::Rates` method, requiring item details and postal codes. The `Courier::all()` method is used to fetch available couriers.

```php
// First you must define the items to ship 
$items = [
    [
        'name' => 'Black L',
        'description' => 'White Shirt',
        'category' => 'fashion',
        'value' => 165000,
        'quantity' => 1,
        'height' => 10,
        'length' => 10,
        'weight' => 200,
        'width' => 10,
    ]
];

// Then specify the destination and the origin
// You could use Postal Code but Biteship recommends you to use 
// their's Area ID, because it is more accurate.
$destination = 12950;
$origin = 12440;
$availableCouriers = \Cloudenum\Biteship\Courier::all();

$rates = \Cloudenum\Biteship\CourierPricing::Rates([
    'origin_postal_code' => $origin,
    'destination_postal_code' => $destination,
    'couriers' => implode(',', $availableCouriers->pluck('courier_code')->unique()->toArray()),
    'items' => $items,
]);
```

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

### Perform Double Search for Area with Biteship API (PHP)

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This demonstrates a two-step process to find an area using the Biteship API. First, `Area::search()` is used, and then `Area::doubleSearchSecondRequest()` is called with the ID obtained from the first search to refine the results.

```php
$area = \Cloudenum\Biteship\Area::search("Lebak Bulus")->first();

\Cloudenum\Biteship\Area::doubleSearchSecondRequest($area->id);
```

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

### Access Biteship API Directly

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Allows direct communication with any Biteship API endpoint using various HTTP methods. Useful for accessing endpoints not covered by high-level models. It returns a GuzzleHttpClient instance for making requests.

```php
use Cloudenum\Biteship\Biteship;

// Get the API instance with default config
$api = Biteship::api();

// Make a custom GET request
$response = $api->get('/v1/couriers');
$couriers = $response->json()['couriers'];

// Make a custom POST request
$response = $api->post('/v1/rates/couriers', [
    'origin_postal_code' => 12440,
    'destination_postal_code' => 55510,
    'couriers' => 'jne,sicepat',
    'items' => [
        ['weight' => 500, 'length' => 10, 'width' => 10, 'height' => 10]
    ]
]);
$rates = $response->json();

// Override config for a specific request
$api = Biteship::api([
    'api_key' => 'different_api_key',
    'base_url' => 'https://api.biteship.com',
]);

// Make request with custom headers
$response = $api->request('get', '/v1/orders', [], [
    'X-Custom-Header' => 'custom-value'
]);

// Available methods: get(), post(), put(), delete(), request()
```

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

### Retrieve All Couriers with Laravel Biteship

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Fetches all available courier services from Biteship. It returns a collection of Courier objects, each containing details like service codes, COD availability, POD availability, and estimated shipment duration. This can be used to list available couriers or filter them based on specific criteria.

```php
use Cloudenum\Biteship\Courier;

// Get all available couriers
$couriers = Courier::all();

foreach ($couriers as $courier) {
    echo "Courier: {$courier->courier_name}\n";
    echo "Code: {$courier->courier_code}\n";
    echo "Service: {$courier->courier_service_name} ({$courier->courier_service_code})\n";
    echo "Type: {$courier->service_type}\n";
    echo "Duration: {$courier->shipment_duration_range} {$courier->shipment_duration_unit}\n";
    echo "COD Available: " . ($courier->available_for_cash_on_delivery ? 'Yes' : 'No') . "\n";
    echo "POD Available: " . ($courier->available_for_proof_of_delivery ? 'Yes' : 'No') . "\n";
    echo "---\n";
}

// Get unique courier codes for rate queries
$courierCodes = $couriers->pluck('courier_code')->unique()->implode(',');
// Result: "jne,jnt,sicepat,anteraja,pos,tiki,ninja,...";

// Filter couriers supporting COD
$codCouriers = $couriers->filter(fn($c) => $c->available_for_cash_on_delivery);

// Get only instant delivery couriers
$instantCouriers = $couriers->filter(fn($c) => $c->service_type === 'instant');
```

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

### Retrieve an Existing Shipping Order by ID (PHP)

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

The Order::find() method retrieves an existing shipping order using its unique ID. It returns an Order object containing the current status, courier details, tracking information, and all shipment data. This is useful for checking order status or displaying details.

```php
use Cloudenum\Biteship\Order;

// Find order by Biteship order ID
$order = Order::find("60bafXXXXXXXXXXXX");

// Access order information
echo "Order ID: {$order->id}\n";
echo "Short ID: {$order->short_id}\n";
echo "Status: {$order->status}\n";
echo "Price: Rp " . number_format($order->price) . "\n";

// Shipper details
echo "Shipper: {$order->shipper['name']}\n";
echo "Organization: {$order->shipper['organization']}\n";

// Origin details
echo "From: {$order->origin['address']}\n";
echo "Origin Contact: {$order->origin['contact_name']}\n";

// Destination details
echo "To: {$order->destination['address']}\n";
echo "Recipient: {$order->destination['contact_name']}\n";

// Courier and tracking
echo "Courier: {$order->courier['company']}\n";
echo "Waybill: {$order->courier['waybill_id']}\n";
echo "Tracking Link: {$order->courier['link']}\n";

// Items
foreach ($order->items as $item) {
    echo "- {$item['name']} x {$item['quantity']}\n";
}

// Convert to array or JSON
$orderArray = $order->toArray();
$orderJson = json_encode($order);

```

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

### Courier Pricing API

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Retrieve shipping rates from multiple couriers for specified origin, destination, and item details. This endpoint is crucial for displaying shipping options and costs to customers during checkout.

```APIDOC
## POST /courier-pricing/rates

### Description
Retrieves shipping rates from multiple couriers for a given origin, destination, and item specifications. This method queries available courier services and returns pricing information including delivery cost, estimated duration, and insurance options. Essential for displaying shipping options to customers during checkout.

### Method
POST

### Endpoint
/courier-pricing/rates

### Parameters
#### Query Parameters
None

#### Request Body
- **origin_postal_code** (string) - Required - The postal code of the origin.
- **destination_postal_code** (string) - Required - The postal code of the destination.
- **origin_area_id** (string) - Optional - The Biteship Area ID of the origin (more accurate than postal code).
- **destination_area_id** (string) - Optional - The Biteship Area ID of the destination (more accurate than postal code).
- **couriers** (string) - Required - A comma-separated string of courier codes to query (e.g., 'jne,sicepat').
- **items** (array) - Required - An array of item objects to be shipped.
  - **name** (string) - Required - The name of the item.
  - **description** (string) - Optional - The description of the item.
  - **category** (string) - Optional - The category of the item.
  - **value** (integer) - Required - The value of the item in IDR.
  - **quantity** (integer) - Required - The quantity of the item.
  - **height** (integer) - Required - The height of the item in cm.
  - **length** (integer) - Required - The length of the item in cm.
  - **weight** (integer) - Required - The weight of the item in grams.
  - **width** (integer) - Required - The width of the item in cm.

### Request Example
```php
use Cloudenum\Biteship\CourierPricing;

$items = [
    [
        'name' => 'Black T-Shirt L',
        'description' => 'Cotton T-Shirt',
        'category' => 'fashion',
        'value' => 165000,
        'quantity' => 1,
        'height' => 10,
        'length' => 10,
        'weight' => 200,
        'width' => 10,
    ]
];

$rates = CourierPricing::Rates([
    'origin_postal_code' => 12440,
    'destination_postal_code' => 55510,
    'couriers' => 'jne,sicepat,anteraja',
    'items' => $items,
]);
```

### Response
#### Success Response (200)
- **origin** (object) - Information about the origin.
  - **postal_code** (string) - The postal code of the origin.
- **destination** (object) - Information about the destination.
  - **postal_code** (string) - The postal code of the destination.
- **pricing** (array) - A list of pricing options from different couriers.
  - **courier_name** (string) - The name of the courier.
  - **courier_service_name** (string) - The name of the courier service.
  - **courier_service_code** (string) - The code of the courier service.
  - **price** (integer) - The shipping price in IDR.
  - **duration** (integer) - The estimated delivery duration in days.
  - **currency** (string) - The currency of the price (e.g., 'IDR').
  - **service_type** (string) - The type of service.
  - **recommended_package** (string) - The recommended package for the shipment.
  - **insurance_available** (boolean) - Indicates if insurance is available.
  - **cod_available** (boolean) - Indicates if Cash on Delivery is available.

#### Response Example
```json
{
  "origin": {
    "postal_code": "12440"
  },
  "destination": {
    "postal_code": "55510"
  },
  "pricing": [
    {
      "courier_name": "JNE",
      "courier_service_name": "JNE REG",
      "courier_service_code": "jne_reg",
      "price": 15000,
      "duration": 2,
      "currency": "IDR",
      "service_type": "express",
      "recommended_package": "",
      "insurance_available": true,
      "cod_available": true
    }
    // ... more pricing options
  ]
}
```
```

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

### Handle Biteship Package Exceptions

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

The package throws `InvalidArgumentException` for configuration errors and `RequestException` for API communication failures. Proper error handling is crucial for managing API issues and providing user feedback.

```php
use Cloudenum\Biteship\Area;
use Cloudenum\Biteship\Order;
use Cloudenum\Biteship\Biteship;
use Cloudenum\Biteship\Exceptions\InvalidArgumentException;
use Cloudenum\Biteship\Exceptions\RequestException;

// Handle configuration errors
try {
    $api = Biteship::api([
        'api_key' => '', // Empty API key will throw exception
    ]);
} catch (InvalidArgumentException $e) {
    echo "Configuration Error: {$e->getMessage()}\n";
    // "api_key must be provided"
}

// Handle API request errors
try {
    $order = Order::create([
        'origin_postal_code' => 12440,
        'destination_postal_code' => 55510,
        // Missing required fields will cause API error
    ]);
} catch (RequestException $e) {
    $response = $e->response;
    $statusCode = $response->status();
    $errorBody = $response->json();

    echo "API Error ({$statusCode}): {$errorBody['error']}\n";

    // Log the full error for debugging
    logger()->error('Biteship API Error', [
        'status' => $statusCode,
        'body' => $errorBody,
    ]);
}

// Complete error handling example
try {
    $areas = Area::search("Invalid Location XYZ123");

    if ($areas->isEmpty()) {
        throw new \Exception("No areas found for the given search");
    }

    $area = $areas->first();
    echo "Found: {$area->name}\n";

} catch (RequestException $e) {
    // API returned an error response
    report($e);
    return response()->json(['error' => 'Shipping service unavailable'], 503);

} catch (InvalidArgumentException $e) {
    // Configuration issue
    report($e);
    return response()->json(['error' => 'Service configuration error'], 500);

} catch (\Exception $e) {
    // Other errors
    return response()->json(['error' => $e->getMessage()], 400);
}
```

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

### Courier API

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Retrieve a list of all available courier services from Biteship. This endpoint provides details for each courier, including service codes, delivery types, COD availability, POD availability, and estimated shipment duration.

```APIDOC
## GET /couriers

### Description
Retrieves all available courier services from Biteship. Returns a collection of Courier objects containing detailed information about each courier including service codes, delivery types, availability for cash on delivery, proof of delivery, and estimated shipment duration.

### Method
GET

### Endpoint
/couriers

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```php
use Cloudenum\Biteship\Courier;

$couriers = Courier::all();
```

### Response
#### Success Response (200)
- **couriers** (array) - A collection of Courier objects.
  - **courier_name** (string) - The name of the courier.
  - **courier_code** (string) - The unique code for the courier.
  - **courier_service_name** (string) - The name of the courier service.
  - **courier_service_code** (string) - The unique code for the courier service.
  - **service_type** (string) - The type of service (e.g., 'express', 'instant').
  - **shipment_duration_range** (string) - The estimated duration range for shipment.
  - **shipment_duration_unit** (string) - The unit for the shipment duration (e.g., 'days').
  - **available_for_cash_on_delivery** (boolean) - Indicates if COD is available.
  - **available_for_proof_of_delivery** (boolean) - Indicates if POD is available.

#### Response Example
```json
{
  "couriers": [
    {
      "courier_name": "JNE",
      "courier_code": "jne",
      "courier_service_name": "JNE REG",
      "courier_service_code": "jne_reg",
      "service_type": "express",
      "shipment_duration_range": "1-2",
      "shipment_duration_unit": "days",
      "available_for_cash_on_delivery": true,
      "available_for_proof_of_delivery": true
    }
    // ... more couriers
  ]
}
```
```

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

### Calculate Shipping Rates with Laravel Biteship

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Calculates shipping rates from multiple couriers for a given origin, destination, and item specifications. This method requires origin and destination postal codes or area IDs, courier codes, and detailed item information. It returns pricing details, estimated delivery duration, and insurance options.

```php
use Cloudenum\Biteship\Courier;
use Cloudenum\Biteship\CourierPricing;

// Define items to ship
$items = [
    [
        'name' => 'Black T-Shirt L',
        'description' => 'Cotton T-Shirt',
        'category' => 'fashion',
        'value' => 165000,        // Item value in IDR
        'quantity' => 1,
        'height' => 10,           // cm
        'length' => 10,           // cm
        'weight' => 200,          // grams
        'width' => 10,            // cm
    ],
    [
        'name' => 'Blue Jeans',
        'description' => 'Denim Jeans',
        'category' => 'fashion',
        'value' => 250000,
        'quantity' => 2,
        'height' => 5,
        'length' => 30,
        'weight' => 400,
        'width' => 20,
    ]
];

// Get all available courier codes
$availableCouriers = Courier::all();
$courierCodes = $availableCouriers->pluck('courier_code')->unique()->implode(',');

// Using postal codes
$rates = CourierPricing::Rates([
    'origin_postal_code' => 12440,
    'destination_postal_code' => 55510,
    'couriers' => $courierCodes,
    'items' => $items,
]);

// Using Biteship Area IDs (more accurate)
$rates = CourierPricing::Rates([
    'origin_area_id' => 'IDNP6IDNC148IDND837IDNS2685',
    'destination_area_id' => 'IDNP5IDNC128IDND766IDNS2321',
    'couriers' => 'jne,sicepat,anteraja',
    'items' => $items,
]);

// Access pricing results
echo "Origin: {$rates->origin['postal_code']}\n";
echo "Destination: {$rates->destination['postal_code']}\n";

foreach ($rates->pricing as $option) {
    echo "Courier: {$option['courier_name']} - {$option['courier_service_name']}\n";
    echo "Price: Rp " . number_format($option['price']) . "\n";
    echo "Duration: {$option['duration']} days\n";
    echo "---\n";
}
```

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

### Search for Areas using Area::search() in PHP

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Searches for geographic areas using a query string. This method queries the Biteship Maps API and returns a collection of Area objects. It supports specifying a country code and enabling a double search mode for more accurate results.

```php
use Cloudenum\Biteship\Area;

// Search for areas matching "Lebak Bulus"
$areas = Area::search("Lebak Bulus");

// Access the first result
$area = $areas->first();

echo $area->id;                                    // "IDNP6IDNC148IDND837IDNS2685"
echo $area->name;                                  // "Lebak Bulus, Cilandak, Kota Jakarta..."
echo $area->postal_code;                           // "12440"
echo $area->country_name;                          // "Indonesia"
echo $area->country_code;                          // "ID"
echo $area->administrative_division_level_1_name; // "DKI Jakarta"
echo $area->administrative_division_level_2_name; // "Kota Jakarta Selatan"
echo $area->administrative_division_level_3_name; // "Cilandak"
echo $area->administrative_division_level_4_name; // "Lebak Bulus"

// Search in a different country
$areas = Area::search("Kuala Lumpur", "MY");

// Enable double search mode for more accurate results
$areas = Area::search("Jakarta", "ID", true);
```

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

### Cancel a Shipping Order using PHP

Source: https://github.com/cloudenum/laravel-biteship/blob/main/README.md

This snippet demonstrates how to cancel an existing shipping order. After retrieving an order object, you can call the `cancel()` method on it, passing a reason for cancellation as a string argument. This action is typically irreversible.

```php
// The reason could be a message why it is cancelled.
$biteshipOrder->cancel($reason);
```

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

### Retrieve Shipment Tracking by Waybill ID and Courier Code

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Retrieves shipment tracking information using the courier's waybill ID (AWB/resi number) and the courier code. This is useful when the Biteship tracking ID is not available. It requires both the waybill number and a valid courier code to identify the shipment. Dependencies: Cloudenum\Biteship\Tracking.

```php
use Cloudenum\Biteship\Tracking;

// Track using JNE waybill number
$tracking = Tracking::findPublicTracking("JNE1234567890", "jne");

echo "Waybill: {$tracking->waybill_id}\n";
echo "Status: {$tracking->status}\n";
echo "Courier: {$tracking->courier['company']}\n";

// Track using SiCepat waybill
$tracking = Tracking::findPublicTracking("000123456789", "sicepat");

// Track using AnterAja waybill
$tracking = Tracking::findPublicTracking("10001234567890", "anteraja");

// Display tracking history
foreach ($tracking->history as $event) {
    $date = date('Y-m-d H:i', strtotime($event['updated_at']));
    echo "[{$date}] {$event['status']}: {$event['note']}\n";
}

// Available courier codes include:
// jne, jnt, sicepat, anteraja, pos, tiki, ninja, lion,
// wahana, rpx, sap, ncs, pcp, jet, rex, first, idl, etc.
```

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

### Update Shipping Order using Order ID or Object

Source: https://context7.com/cloudenum/laravel-biteship/llms.txt

Updates an existing shipping order with new details. This can be done using either the order ID string or an existing Order object. It allows modification of destination, notes, and other order-specific information before pickup. Dependencies: Cloudenum\Biteship\Order.

```php
use Cloudenum\Biteship\Order;

// Update using order ID string
$updatedOrder = Order::update("60bafXXXXXXXXXXXX", [
    'destination_contact_name' => 'Jane Smith',
    'destination_contact_phone' => '089999888777',
    'destination_address' => 'Jalan Malioboro No. 100',
    'destination_note' => 'New address - blue building',
    'order_note' => 'Updated delivery instructions',
]);

// Or update using existing Order object
$order = Order::find("60bafXXXXXXXXXXXX");
$updatedOrder = Order::update($order, [
    'origin_note' => 'Pickup from back entrance',
    'metadata' => [
        'updated_at' => now()->toISOString(),
        'updated_by' => 'admin',
    ],
]);

echo "Order Updated: {$updatedOrder->id}\n";
echo "New Destination: {$updatedOrder->destination['address']}\n";
```