# Android API Documentation

This project now exposes a mobile-friendly JSON API under:

- Base URL: `/api/v1`
- Auth: Laravel Sanctum Bearer tokens
- Header: `Authorization: Bearer {token}`
- Content type: `application/json`

## OpenAPI Spec

Machine-readable OpenAPI 3.0 spec:

- [docs/openapi.yaml](docs/openapi.yaml)

You can import this file into Postman/Insomnia or generate a client SDK from it.

## Quick Start

1. Login to get a token:

```bash
curl -X POST http://localhost/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"your-user@example.com","password":"your-password","device_name":"android-dev"}'
```

2. Use the token for authenticated calls:

```bash
curl http://localhost/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"
```

3. Logout when needed:

```bash
curl -X POST http://localhost/api/v1/auth/logout \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Authentication Endpoints

- `POST /api/v1/auth/login`
  - Body: `email`, `password`, optional `device_name`
  - Returns: `access_token`, `token_type`, `user`
- `GET /api/v1/auth/me`
  - Returns current user, teams, and current team
- `POST /api/v1/auth/switch-team`
  - Body: `team_id`
  - Switches `current_team_id`
- `POST /api/v1/auth/logout`
  - Revokes current token

## Health Check

- `GET /api/v1/health`

## Lookup Endpoints

- `GET /api/v1/lookups/vehicle-types`
- `GET /api/v1/lookups/job-card-types`
- `GET /api/v1/lookups/job-card-statuses`
- `GET /api/v1/lookups/file-types`

## Core Resource Endpoints

All resource endpoints below support standard REST patterns unless noted.

- `GET /api/v1/customers`
- `POST /api/v1/customers`
- `GET /api/v1/customers/{id}`
- `PUT /api/v1/customers/{id}`
- `DELETE /api/v1/customers/{id}`
- `GET /api/v1/customers/datatables`

- `GET /api/v1/vehicles`
- `POST /api/v1/vehicles`
- `GET /api/v1/vehicles/{id}`
- `PUT /api/v1/vehicles/{id}`
- `DELETE /api/v1/vehicles/{id}`
- `GET /api/v1/vehicles/datatables`

- `GET /api/v1/job-cards`
- `POST /api/v1/job-cards`
- `GET /api/v1/job-cards/{id}`
- `PUT /api/v1/job-cards/{id}`
- `DELETE /api/v1/job-cards/{id}`

- `GET /api/v1/parts`
- `POST /api/v1/parts`
- `GET /api/v1/parts/{id}`
- `PUT /api/v1/parts/{id}`
- `DELETE /api/v1/parts/{id}`

- `GET /api/v1/suppliers`
- `POST /api/v1/suppliers`
- `GET /api/v1/suppliers/{id}`
- `PUT /api/v1/suppliers/{id}`
- `DELETE /api/v1/suppliers/{id}`

- `GET /api/v1/tasks`
- `POST /api/v1/tasks`
- `GET /api/v1/tasks/{id}`
- `PUT /api/v1/tasks/{id}`
- `DELETE /api/v1/tasks/{id}`

- `GET /api/v1/files`
- `POST /api/v1/files` (multipart upload)
- `GET /api/v1/files/{id}`
- `PUT /api/v1/files/{id}`
- `DELETE /api/v1/files/{id}`

- `GET /api/v1/inspection-categories`
- `POST /api/v1/inspection-categories`
- `GET /api/v1/inspection-categories/{id}`
- `PUT /api/v1/inspection-categories/{id}`
- `DELETE /api/v1/inspection-categories/{id}`

- `GET /api/v1/job-card-types`
- `GET /api/v1/job-card-types/{id}`

- `GET /api/v1/users`
- `GET /api/v1/users/{id}`

## Additional Mobile Resources

### Notes

- `GET /api/v1/notes`
  - Optional query filters:
    - `noteable_type`: `vehicle`, `job_card`, `customer`
    - `noteable_id`: integer id
- `POST /api/v1/notes`
  - Body:
    - `note` (required)
    - `noteable_type` (`vehicle`, `job_card`, `customer`)
    - `noteable_id`
- `GET /api/v1/notes/{id}`
- `PUT /api/v1/notes/{id}`
- `DELETE /api/v1/notes/{id}`

### Stock

- `GET /api/v1/stocks`
- `POST /api/v1/stocks`
  - Body:
    - `part_id` (required)
    - `quantity` (required)
    - `location` (optional)
    - `supplier_id` (optional)
- `GET /api/v1/stocks/{id}`
- `PUT /api/v1/stocks/{id}`
- `DELETE /api/v1/stocks/{id}`

### MOT Records

- `GET /api/v1/vehicle-mots`
  - Optional: `vehicle_id`, `per_page`
- `POST /api/v1/vehicle-mots`
- `GET /api/v1/vehicle-mots/{id}`
- `PUT /api/v1/vehicle-mots/{id}`
- `DELETE /api/v1/vehicle-mots/{id}`

### Vehicle Defects

- `GET /api/v1/vehicle-defects`
  - Optional: `vehicle_id`, `vehicle_mot_id`, `per_page`
- `POST /api/v1/vehicle-defects`
- `GET /api/v1/vehicle-defects/{id}`
- `PUT /api/v1/vehicle-defects/{id}`
- `DELETE /api/v1/vehicle-defects/{id}`

### Plans

- `GET /api/v1/plans`
- `GET /api/v1/plans/{slug}`

## Pagination

Many list endpoints return Laravel paginator JSON with:

- `data`
- `current_page`
- `last_page`
- `per_page`
- `total`

`per_page` is accepted on the mobile-only resources and clamped to max `100`.

## Error Format

Validation failures return HTTP `422` with Laravel standard payload:

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "field": ["Error message"]
  }
}
```

Auth failures return `401`.
Forbidden operations return `403`.

## Customer Portal Behavior

If a user has customer portal access, writes may be blocked by `customer.portal` middleware. Android clients should handle `403` and present a read-only UI.

## Android Integration Tips

- Store token securely (EncryptedSharedPreferences).
- Add `Authorization` header via OkHttp interceptor.
- Refresh current user/team via `GET /api/v1/auth/me` on app launch.
- After team switch, refetch list screens because team-scoped data changes.