# REST API (v1)

Base path: `/api/v1` · JSON in/out · designed for a future mobile / partner app.

## Authentication

All `/api/v1/*` endpoints (except the public track route) require a **Bearer token**.

1. In the app: **Settings → API Tokens → Create Token**.
2. Copy the plaintext token shown **once** (only its SHA-256 hash is stored).
3. Send it on every request:

```
Authorization: Bearer <your-token>
Accept: application/json
```

An invalid/expired/revoked token returns `401`.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/v1/me` | Current token's user + company context |
| GET | `/api/v1/bookings` | List bookings (paginated) |
| POST | `/api/v1/bookings` | Create a booking |
| GET | `/api/v1/consignments/{lr}/track` | Full tracking timeline for an LR |
| POST | `/api/v1/scan` | Record a package scan |
| GET | `/api/v1/dashboard/stats` | KPI snapshot |
| GET | `/api/v1/public/track/{lr}` | **Public** track by LR (no token) |

## Examples

**Track a consignment (public):**
```bash
curl https://<domain>/api/v1/public/track/RD%2FHO%2F2026%2F000001
```
```json
{
  "success": true,
  "consignment": { "lr_number": "RD/HO/2026/000001", "status": "in_transit", "origin_city": "Pune", "dest_city": "Mumbai" },
  "timeline": [
    { "status": "booked",     "location": "Pune", "event_time": "2026-07-01 09:15:00" },
    { "status": "picked_up",  "location": "Pune", "event_time": "2026-07-01 11:40:00" },
    { "status": "in_transit", "location": "Pune → Mumbai", "event_time": "2026-07-01 16:20:00" }
  ]
}
```

**Create a booking:**
```bash
curl -X POST https://<domain>/api/v1/bookings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"customer_id":1,"booking_date":"2026-07-06","pickup_city":"Pune","delivery_city":"Mumbai","no_of_packages":5,"weight_kg":300,"service_type":"standard"}'
```

**Record a scan:**
```bash
curl -X POST https://<domain>/api/v1/scan \
  -H "Authorization: Bearer <token>" \
  -d '{"package_code":"RDHO2026000001-P01","scan_type":"loaded","warehouse_id":1}'
```

## Notes

- Responses are always `{ "success": true|false, ... }`.
- List endpoints return `data`, `total`, `page`, `per_page`, `pages`.
- Mutations are company-scoped to the token owner's company.
- CSRF does **not** apply to `/api/v1` (token auth replaces it); it **does** apply to all browser POSTs.