Toutes les URLs ci-dessous sont relatives à la base **`https://votredomaine.com/api/v1`**.

## Lister les tickets

```http
GET /v1/support/tickets
Authorization: Bearer kh_live_xxxx
```

Pagination Laravel standard : **20** tickets par page (paramètres de requête `page` pris en charge par le framework).

### Réponse

```json
{
  "success": true,
  "data": [
    {
      "id": 1,
      "uuid": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "user_id": 1,
      "subject": "Question technique",
      "department": "technical",
      "status": "open",
      "priority": "normal",
      "messages_count": 2,
      "created_at": "2024-06-15T09:00:00.000000Z",
      "updated_at": "2024-06-15T10:30:00.000000Z"
    }
  ],
  "meta": {
    "total": 5,
    "per_page": 20,
    "current_page": 1
  }
}
```

Les statuts possibles pour un ticket : `open`, `in_progress`, `resolved`, `closed`.

**Permission :** `support:read`

---

## Créer un ticket

```http
POST /v1/support/tickets
Content-Type: application/json
```

```json
{
  "subject": "Erreur 500 sur mon site",
  "message": "Depuis ce matin, le site renvoie une erreur 500…",
  "department": "technical",
  "priority": "high",
  "service_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

| Champ | Type | Requis | Description |
|-------|------|--------|-------------|
| `subject` | string | Oui | Sujet (max 255 caractères) |
| `message` | string | Oui | Premier message (max 5000) |
| `department` | string | Oui | `technical`, `billing`, `sales`, `abuse`, `general` |
| `priority` | string | Non | `low`, `normal`, `high`, `urgent` (défaut : `normal`) |
| `service_id` | UUID | Non | UUID d’un **votre** service ; sinon ignoré |

### Réponse (201)

```json
{
  "success": true,
  "data": {
    "ticket_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "subject": "Erreur 500 sur mon site",
    "department": "technical",
    "priority": "high",
    "status": "open"
  }
}
```

**Permission :** `support:write`

---

## Détail d’un ticket

```http
GET /v1/support/tickets/{ticket_uuid}
```

Le corps JSON renvoie le modèle `Ticket` sérialisé, avec la relation `messages` (messages **non internes** uniquement, triés par date).

**Permission :** `support:read`

---

## Ajouter un message

```http
POST /v1/support/tickets/{ticket_uuid}/messages
Content-Type: application/json
```

```json
{
  "message": "Merci pour votre retour, j’ai appliqué la correction."
}
```

Impossible d’ajouter un message si le ticket est **`closed`** (erreur `422`, code `invalid_state`).

**Réponse (201) :** objet contenant au minimum `id`, `message`, `created_at`.

**Permission :** `support:write`

> L’API ne gère pas les pièces jointes sur ce endpoint (contrairement au formulaire web). Utilisez le portail client si vous devez joindre des fichiers.

---

## Fermer un ticket

```http
PATCH /v1/support/tickets/{ticket_uuid}/close
```

**Permission :** `support:write`

```json
{
  "success": true,
  "data": {
    "ticket_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "closed"
  }
}
```

---

## Rouvrir un ticket

```http
PATCH /v1/support/tickets/{ticket_uuid}/reopen
```

Rouvre un ticket à partir d’un statut **`closed`** ou **`resolved`** (repasse à `open`).

**Permission :** `support:write`

```json
{
  "success": true,
  "data": {
    "ticket_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "open"
  }
}
```

## Sandbox

Avec une clé **`kh_test_`**, les méthodes d’écriture (`POST`, `PATCH`, `DELETE` sur l’API) renvoient **`403 Forbidden`** :

```json
{
  "success": false,
  "error": {
    "code": "sandbox_read_only",
    "message": "Les tokens sandbox (kh_test_) sont en lecture seule. Utilisez un token live (kh_live_) pour les opérations d'écriture."
  }
}
```

## Permissions

| Action | Scope |
|--------|--------|
| Liste, détail | `support:read` |
| Création, message, fermer, rouvrir | `support:write` |