# ngauge-delivery-dx

DX Despatch Manager delivery integration for NGauge / Yii2.

Provides a full Yii2 module for creating, managing and tracking consignments through the DX Despatch Manager REST API.

---

## Features

- Token-based authentication with automatic caching (mandatory per DX go-live requirements)
- Create consignments (`POST /Consignment/CreateConsignment`)
- Cancel individual items (`POST /Consignment/CancelItem`)
- Retrieve PDF and ZPL labels
- Get available services for a delivery postcode
- Full consignment and item tracking
- Bootstrap 4 admin UI for configuration and consignment creation
- Async dispatch via Yii2 queue
- Settings stored (encrypted) in `params-local.php`

---

## Installation

```bash
composer require portalpeople/ngauge-delivery-dx
```

Add to `backend/config/params-local.php`:

```php
'plugins' => [
    'dx' => [
        'enabled'     => true,
        'apiUrl'      => 'https://despatch-api.dxdelivery.com',  // use test URL during dev
        'accountCode' => 'YOUR_ACCOUNT_CODE',
        'username'    => 'your@email.com',
        'password'    => \backend\components\Security::encryptSensitiveData('your-password'),
        'debug'       => false,
    ],
],
```

The production API URL requires **IP whitelisting** — contact DX to register your server IP before attempting production use.

---

## API Authentication

DX uses token-based authentication:

1. `POST /Session/CreateToken` with credentials in headers (`accountCode`, `username`, `password`)
2. Response contains `accessToken.key` — include as `Token: {key}` header on all subsequent requests
3. Tokens are cached automatically until expiry; **do not re-authenticate on every request** (a hard go-live requirement)

---

## Module Endpoints

| URL | Action |
|-----|--------|
| `/dx/config` | Configuration settings |
| `/dx/consignment/create` | Create a consignment |
| `/dx/consignment/cancel` | Cancel an item (POST) |
| `/dx/consignment/tracking?trackingNumber=…` | Tracking events |
| `/dx/consignment/services?postcode=…` | Available services |
| `/dx/consignment/label-pdf?trackingNumber=…` | PDF label (Base64) |
| `/dx/consignment/label-zpl?trackingNumber=…` | ZPL label |
| `/dx/config/status` | Module status (JSON) |

---

## Requirements

- PHP 8.0+
- Yii2 ~2.0
- yii2-bootstrap4 ^2.0
- guzzlehttp/guzzle ^7.0
