# fixThatMe API REST v1

*Dernière mise à jour : 10 juillet 2026*

API de gestion des feedbacks d'une organisation. Conçue pour être utilisée par des scripts, des intégrations ou des agents IA (lister les bugs signalés, les corriger, mettre à jour leur statut, répondre au rapporteur).

**Base URL** : `https://www.fixthat.me/api/v1`

## Authentification

Toutes les requêtes exigent la clé secrète de l'organisation dans le header :

```
Authorization: Bearer sk_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

La clé se trouve dans le dashboard : **Settings > Sécurité > Clé secrète API** (visible par le propriétaire uniquement). Ne pas confondre avec la clé publique du widget (`sk_live_...`), qui ne fonctionne pas ici.

Réponse `401` si la clé est absente ou invalide. Toutes les réponses sont en JSON.

## Modèle de données

Un **feedback** :

| Champ | Type | Description |
|---|---|---|
| `id` | string (uuid) | Identifiant unique |
| `feedback_number` | number | Numéro séquentiel par organisation (affiché `FEED-<n>`) |
| `title` | string | Titre (généré depuis le commentaire si non défini) |
| `comment` | string \| null | Message laissé par le rapporteur dans le widget |
| `type` | string | `bug` \| `feature` \| `question` \| `improvement` |
| `priority` | string | `low` \| `medium` \| `high` \| `critical` |
| `status` | string | `new` \| `in_review` \| `in_progress` \| `resolved` \| `closed` \| `wont_fix` |
| `labels` | string[] | Étiquettes libres |
| `page_url` | string | URL de la page où le feedback a été créé |
| `selected_screenshot_url` | string | Screenshot de la zone sélectionnée par le rapporteur |
| `full_page_screenshot_url` | string | Screenshot de la page complète |
| `viewport_width` / `viewport_height` | number \| null | Taille de la fenêtre du rapporteur |
| `user_agent` | string | Navigateur du rapporteur |
| `reporter_email` | string \| null | Email du rapporteur (s'il l'a laissé) |
| `created_at` / `updated_at` | string | Dates ISO 8601 |

Cycle de vie recommandé d'un statut : `new` → `in_review` → `in_progress` → `resolved`. Les statuts `closed` et `wont_fix` sont terminaux. Chaque changement de statut notifie automatiquement le rapporteur par email (s'il a laissé son adresse) et alimente sa page de suivi publique.

## Endpoints

### Lister les feedbacks

```
GET /api/v1/feedbacks
```

Paramètres de query (tous optionnels) :

| Paramètre | Description |
|---|---|
| `status` | Filtrer par statut (ex : `status=new`) |
| `type` | Filtrer par type (ex : `type=bug`) |
| `priority` | Filtrer par priorité |
| `since` | Feedbacks créés après cette date ISO (ex : `since=2026-07-01T00:00:00Z`) |
| `page` | Page (défaut 1) |
| `limit` | Résultats par page (défaut 50, max 100) |

Réponse :

```json
{
  "data": [ { "id": "...", "feedback_number": 2, "title": "...", "status": "new", ... } ],
  "pagination": { "page": 1, "limit": 50, "total": 12, "total_pages": 1 }
}
```

Exemple pour récupérer les bugs non traités :

```bash
curl -H "Authorization: Bearer sk_api_xxx" \
  "https://www.fixthat.me/api/v1/feedbacks?status=new&type=bug"
```

### Détail d'un feedback

```
GET /api/v1/feedbacks/:id
GET /api/v1/feedbacks/:id?include_html=true
```

Retourne `{ "data": { ...feedback } }`. Avec `include_html=true`, inclut `page_html` : le HTML complet de la page au moment du signalement (utile pour diagnostiquer, volumineux). Les coordonnées `selection_x/y/width/height` situent la zone sélectionnée par le rapporteur dans la page.

### Mettre à jour un feedback

```
PATCH /api/v1/feedbacks/:id
Content-Type: application/json
```

Body (tous les champs sont optionnels, au moins un est requis) :

```json
{ "status": "in_progress", "priority": "high", "type": "bug", "title": "...", "labels": ["front", "login"] }
```

Effets de bord automatiques d'un changement de `status` : email au rapporteur, mise à jour de sa page de suivi publique, webhooks et intégrations (Slack, Discord...) de l'organisation, historique d'activité (attribué à « API »).

Exemple pour marquer un feedback comme résolu :

```bash
curl -X PATCH -H "Authorization: Bearer sk_api_xxx" -H "Content-Type: application/json" \
  -d '{"status": "resolved"}' \
  "https://www.fixthat.me/api/v1/feedbacks/FEEDBACK_ID"
```

### Commentaires

```
GET  /api/v1/feedbacks/:id/comments
POST /api/v1/feedbacks/:id/comments
```

POST body :

```json
{ "content": "Corrigé dans la version déployée ce matin.", "is_public": true }
```

- `is_public: false` (défaut) : commentaire interne, visible uniquement dans le dashboard.
- `is_public: true` : visible par le rapporteur sur sa page de suivi publique, et il reçoit un email avec le contenu (s'il a laissé son adresse).

Réponse : `201` avec `{ "data": { ...comment } }`.

## Workflow type pour un agent IA

1. `GET /feedbacks?status=new` : récupérer les nouveaux signalements.
2. Pour chaque feedback : `GET /feedbacks/:id?include_html=true` : lire le commentaire, l'URL de la page, la zone sélectionnée et le HTML capturé pour diagnostiquer.
3. `PATCH /feedbacks/:id` avec `{"status": "in_review"}` puis `{"status": "in_progress"}` : tenir le rapporteur informé.
4. Corriger le problème dans le code du site concerné.
5. `POST /feedbacks/:id/comments` avec `{"content": "...", "is_public": true}` : expliquer la correction au rapporteur.
6. `PATCH /feedbacks/:id` avec `{"status": "resolved"}`.
7. Si le signalement n'est pas un bug réel : `{"status": "wont_fix"}` avec un commentaire public expliquant pourquoi.

## Erreurs

| Code | Signification |
|---|---|
| `400` | Paramètre invalide (le body de la réponse liste les valeurs acceptées) |
| `401` | Clé API absente ou invalide |
| `404` | Feedback introuvable (ou appartenant à une autre organisation) |
| `500` | Erreur serveur |

## Limites actuelles

- Pas de rate limiting explicite : restez raisonnable (< 10 req/s).
- Les screenshots sont des URLs publiques directement téléchargeables (PNG).
- Pas de webhook de création via l'API : les feedbacks sont créés par le widget uniquement.