# Smart Mining ERP — API Documentation

## Authentication

- Base URL: `/api/v1`
- Auth: Laravel Sanctum bearer tokens
- Login: `POST /api/v1/auth/login` `{ email, password }` → `{ token, user }`
- Headers: `Authorization: Bearer {token}`, optional `Accept-Language: en|ur`
- Logout: `POST /api/v1/auth/logout`
- Me: `GET /api/v1/auth/me`
- Refresh: `POST /api/v1/auth/refresh`

Rate limits: `login` 5/min, `api` 60/min.

## Common query params

All list endpoints support (via `ApiQuery` / `PaginatesRequests`):

| Param | Description |
|-------|-------------|
| `search` | Free-text search |
| `sort` | Sort column |
| `direction` | `asc` or `desc` |
| `per_page` | Page size (max 100) |
| filter columns | Resource-specific (`status`, `site_id`, …) |

## Modules

| Method | Path | Permission |
|--------|------|------------|
| CRUD | `/sites`, `/materials`, `/operators`, `/machines` | `sites.*`, `materials.*`, … |
| CRUD | `/machine-hours`, `/maintenance` | `machine_hours.*`, `maintenance.*` |
| CRUD | `/drivers`, `/dumpers`, `/trucks`, `/dumping-points` | transport perms |
| CRUD | `/production`, `/trips`, `/challans` | production/trips/challans |
| GET/POST | `/stock`, `/stock/movements` | `stock.*` |
| CRUD | `/factories`, `/customers`, `/suppliers` | party perms |
| CRUD-ish | `/deliveries`, `POST /deliveries/{id}/confirm` | `deliveries.*` |
| GET | `/sales` | `sales.view` |
| GET/POST | `/payments`, `/expenses`, `/fuel`, `/inventory` | matching perms |
| GET | `/accounts`, `/ledger` | `accounting.view` |

## Reports

| Method | Path | Notes |
|--------|------|-------|
| GET | `/reports` | List report keys |
| GET | `/reports/{key}?date_from&date_to&site_id` | Aggregate report |
| GET | `/reports/{key}/export?format=csv\|pdf\|excel` | Requires `reports.export` |

Financial keys require `accounting.view`: `customer-ledger`, `factory-ledger`, `supplier-ledger`, `cash-book`, `bank-book`, `receivables`, `payables`, `profit-loss`, `sales`.

## AI

| Method | Path | Permission |
|--------|------|------------|
| POST | `/ai/chat` `{ message, conversation_id? }` | `ai.use` |
| POST | `/ai/commands/{id}/confirm` | `ai.execute` / `ai.financial_execute` |
| GET | `/ai/conversations`, `/ai/commands` | `ai.use` |

Financial intents require confirmation before execution. AI never runs raw SQL — domain services only.

## Voice

| Method | Path | Permission |
|--------|------|------------|
| POST | `/voice` multipart `audio` | `voice.use` |
| GET | `/voice`, `/voice/{id}` | `voice.use` |

## Company registration (public)

| Method | Path | Auth | Notes |
|--------|------|------|-------|
| POST | `/companies/register` | Public (throttled) | Self-service company registration |
| GET | `/companies/register/status/{code}` | Public | Check registration status |

## Companies (super admin)

| Method | Path | Permission |
|--------|------|------------|
| GET | `/companies` | `super_admin` role |
| POST | `/companies/{id}/approve` | `super_admin` role |
| POST | `/companies/{id}/reject` | `super_admin` role |

## Application templates

| Method | Path | Permission |
|--------|------|------------|
| GET | `/application-templates` | `applications.view` |
| POST | `/application-templates/{key}/generate` `{ locale?, overrides? }` | `applications.generate` |
| GET | `/application-templates/{key}/pdf?locale=` | `applications.generate` |

## Offline sync

| Method | Path | Notes |
|--------|------|-------|
| POST | `/sync/push` `{ endpoint, payload, idempotency_key? }` | Idempotent via `idempotency_keys` |
| GET | `/sync/status?key=` | Sync status |

## Authorization matrix (sample)

| Role | trips.view | accounting.view | reports.view | ai.use |
|------|------------|-----------------|--------------|--------|
| admin | yes | yes | yes | yes |
| driver | yes | no | no | no |
| accountant | no | yes | yes | no |