# Connect Vehicle to LinkByCar API

Connect a vehicle to the LinkByCar telematics platform. This registers the vehicle with LinkByCar using its VIN and updates its local connection status.

---

## Endpoint

```
POST /api/admin/vehicles/{vehicle_id}/connect-linkbycar
```

## Authentication

- **Method:** Bearer token (Sanctum)
- **Required role:** `superadministrator`

## Path Parameters

| Parameter    | Type    | Description              |
|--------------|---------|--------------------------|
| `vehicle_id` | integer | The ID of the vehicle    |

## Request Body

None. The endpoint uses the vehicle's existing VIN, numberplate, and company to register with LinkByCar.

## Responses

### 200 OK - Vehicle connected

```json
{
  "status": true,
  "message": "Vehicle successfully connected to LinkByCar.",
  "data": null
}
```

### 409 Conflict - Vehicle already connected

Returned when the vehicle is already connected to LinkByCar.

```json
{
  "status": false,
  "message": "This vehicle is already connected to LinkByCar."
}
```

### 422 Unprocessable Entity - Vehicle not eligible

Returned when the vehicle cannot be connected (e.g. vehicle not found, missing VIN).

```json
{
  "status": false,
  "message": "This vehicle is not eligible for LinkByCar connection."
}
```

### 503 Service Unavailable - LinkByCar is down

Returned when the LinkByCar API is unreachable or returns an error. This is transient — retry after a short delay.

```json
{
  "status": false,
  "message": "LinkByCar connection service is temporarily unavailable."
}
```

### 401 Unauthorized

Returned if the bearer token is missing or invalid.

### 403 Forbidden

Returned if the authenticated user does not have the `superadministrator` role.

---

## Example Request

```bash
curl -X POST "https://{host}/api/admin/vehicles/42/connect-linkbycar" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
```

---

## Frontend Integration Notes

- **Action placement:** Add a "Connect to LinkByCar" button/action in the admin vehicles table, per vehicle row.
- **Eligibility:** Only show the action for vehicles where `connection_status != 'C'` or `telematics_provider != 'linkbycar'`. Vehicles already connected should show a "Connected" badge instead.
- **VIN required:** Vehicles without a VIN will return 422. Consider disabling the button or showing a tooltip for vehicles with no VIN.
- **Loading state:** The call may take a few seconds (upstream API call to LinkByCar). Show a spinner on the button during the request.
- **After success:** Refresh the vehicle row to reflect the updated `connection_status` (`C`) and `telematics_provider` (`linkbycar`).
- **Error handling:**
  - `409` — Show inline message: vehicle is already connected.
  - `422` — Show inline message: vehicle is not eligible (likely missing VIN).
  - `503` — Show a toast/notification suggesting to retry later.