# Automatiser vos annonces avec l’API

L’API pealHQ permet à vos automatisations (pipeline de release, n8n, Zapier, script) de lire les demandes de votre portail, de rédiger l’annonce d’une version et de la publier. Une relance de la même automatisation met à jour l’annonce existante au lieu d’en créer une seconde.

Ce guide peut être partagé avec votre équipe technique ou un agent de développement. Les valeurs des exemples sont fictives.

## Créer une clé API

1. Ouvrez **Paramètres → API** dans l’administration pealHQ.
2. Donnez un nom à la clé (par exemple « Release GitHub Actions »), puis cliquez sur **Créer**.
3. Copiez la clé affichée, qui commence par `peal_`. Elle n’est affichée qu’une fois : pealHQ n’en conserve qu’une empreinte.
4. Enregistrez-la dans les secrets de votre automatisation, jamais dans le code.

Une clé donne accès à un seul workspace et agit au nom du membre de l’équipe qui l’a créée : les annonces créées par l’API lui sont attribuées. Elle cesse de fonctionner dès que ce membre quitte l’équipe. Révoquez une clé depuis la même page ; l’effet est immédiat.

## Appeler l’API

Toutes les URL partent de l’adresse affichée dans **Paramètres → API**, par exemple :

```text
https://pealhq.com/api/v1
```

Chaque appel envoie la clé dans l’en-tête `Authorization`. Les corps de requête et de réponse sont en JSON :

```bash
curl https://pealhq.com/api/v1/changelog \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json"
```

Chaque réponse place la ressource dans une clé `data`. L’API accepte 120 appels par minute et par clé.

### Codes d’erreur

| Code | Signification |
| --- | --- |
| `401` | Clé absente, révoquée, ou dont l’auteur a quitté l’équipe. |
| `403` | Workspace suspendu. |
| `404` | Ressource introuvable dans ce workspace. |
| `409` | Modification refusée : l’annonce est déjà publiée. |
| `422` | Données invalides. Le détail par champ est dans `errors`. |
| `429` | Trop d’appels : réessayez après le délai indiqué par l’en-tête `Retry-After`. |

## Lire une demande

```text
GET /requests/{id}
```

L’identifiant est celui de l’URL d’administration de la demande, `…/admin/requests/{id}`. C’est aussi le lien que pealHQ ajoute aux issues Linear créées ou liées depuis le triage : votre automatisation peut le lire dans les pièces jointes de l’issue.

```json
{
  "data": {
    "id": 42,
    "title": "Exporter les factures en CSV",
    "description": "Nous aimerions exporter toutes les factures du mois…",
    "status": "completed",
    "status_label": "Livrée",
    "votes_count": 18,
    "comments_count": 4,
    "created_at": "2026-09-02T08:15:00.000000Z",
    "archived_at": null,
    "merged_into_id": null,
    "linear_issue": {
      "identifier": "ACME-123",
      "url": "https://linear.app/acme/issue/ACME-123"
    },
    "changelog": null,
    "public_url": "https://acme.pealhq.com/requests/42",
    "admin_url": "https://acme.pealhq.com/admin/requests/42"
  }
}
```

`changelog` indique l’annonce à laquelle la demande est déjà rattachée (`id`, `version`, `status`, `public_url`), ou `null`.

## Créer ou mettre à jour une version

```text
PUT /changelog/versions/{version}
```

La version identifie l’annonce : `2.4.0`, `v2.4.0-beta.1` ou `2026.10.08` (lettres, chiffres, `.`, `_`, `+` et `-`, 50 caractères au plus). Si aucune annonce n’existe pour cette version, elle est créée en brouillon et la réponse a le code `201`. Sinon, son contenu est remplacé et la réponse a le code `200`.

| Champ | Obligatoire | Description |
| --- | --- | --- |
| `title` | Oui | Titre de l’annonce, 3 à 160 caractères. |
| `body` | Oui | Contenu en Markdown, 10 à 10 000 caractères. Un lien YouTube seul sur sa ligne devient une vidéo intégrée. |
| `summary` | Non | Résumé affiché dans les listes et les emails, 10 à 300 caractères. Sans lui, pealHQ reprend le début des paragraphes du contenu. |
| `feature_request_ids` | Non | Identifiants des demandes livrées par cette version. La liste remplace les demandes déjà liées ; `[]` les retire toutes. Sans ce champ, les liens existants sont conservés. |
| `auto_open_widget` | Non | `true` pour ouvrir automatiquement le widget changelog chez vos utilisateurs à la publication. |

```bash
curl -X PUT https://pealhq.com/api/v1/changelog/versions/2.4.0 \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Version 2.4 : exports CSV",
    "body": "## Exports CSV\n\nExportez toutes vos factures du mois en un clic.",
    "feature_request_ids": [42, 57]
  }'
```

```json
{
  "data": {
    "id": 318,
    "version": "2.4.0",
    "status": "draft",
    "title": "Version 2.4 : exports CSV",
    "summary": "Exportez toutes vos factures du mois en un clic.",
    "body": "## Exports CSV\n\nExportez toutes vos factures du mois en un clic.",
    "cover_url": null,
    "auto_open_widget": false,
    "published_at": null,
    "scheduled_for": null,
    "created_at": "2026-10-08T09:30:00.000000Z",
    "updated_at": "2026-10-08T09:30:00.000000Z",
    "public_url": "https://acme.pealhq.com/changelog#entry-318",
    "admin_url": "https://acme.pealhq.com/admin/changelog",
    "feature_requests": [
      { "id": 42, "title": "Exporter les factures en CSV" },
      { "id": 57, "title": "Filtrer les exports par client" }
    ]
  }
}
```

`public_url` est l’adresse de l’annonce sur votre portail. Elle n’est visible par vos clients qu’après publication.

Une demande ne peut être annoncée que dans une seule annonce. Lorsqu’une demande passe au statut livré, pealHQ l’ajoute au brouillon automatique du jour (« Nouveautés du … »). En la liant à votre version, l’API la retire de ce brouillon, avec la section qui avait été générée pour elle ; le brouillon est supprimé s’il ne contient plus rien. Une section modifiée à la main est conservée. Une demande déjà présente dans une autre annonce publiée est refusée avec le code `422`.

## Retrouver une annonce

```text
GET /changelog/versions/{version}
GET /changelog/{id}
```

Renvoient l’annonce au même format, ou `404` si elle n’existe pas.

```text
GET /changelog?status=draft
```

Liste les annonces, des plus récentes aux plus anciennes, 25 par page (`per_page`, jusqu’à 100). Le filtre facultatif `status` vaut `draft`, `scheduled` ou `published`. La réponse contient `data`, `links` et `meta`, pour suivre la pagination avec `links.next`.

## Modifier un brouillon

```text
PATCH /changelog/{id}
```

Ne modifie que les champs envoyés : `title`, `summary`, `body`, `version`, `feature_request_ids` et `auto_open_widget`, avec les mêmes règles que ci-dessus. Utilisez-le notamment pour réécrire un brouillon automatique ou lui attribuer une version.

```bash
curl -X PATCH https://pealhq.com/api/v1/changelog/318 \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Les exports CSV arrivent dans la facturation."}'
```

Une annonce publiée ne peut plus être modifiée par l’API : toute modification renvoie `409`. Rejouer exactement le même contenu reste accepté et ne change rien, ce qui permet de relancer une automatisation déjà terminée. Pour corriger une annonce publiée, repassez-la en brouillon depuis l’administration.

## Publier une annonce

```text
POST /changelog/{id}/publish
```

Publie immédiatement l’annonce sur le portail, dans le widget, et prévient vos clients selon leurs préférences de notification. Une publication programmée depuis l’administration est annulée. Publier une annonce déjà publiée ne change rien, pas même sa date.

```bash
curl -X POST https://pealhq.com/api/v1/changelog/318/publish \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json"
```

## Exemple de workflow de release

1. Votre pipeline rassemble les issues Linear de la release et lit, dans leurs pièces jointes, les liens `…/admin/requests/{id}` ajoutés par pealHQ.
2. Pour chaque identifiant, `GET /requests/{id}` fournit le titre, la description et le nombre de votes, utiles pour rédiger l’annonce.
3. `PUT /changelog/versions/{version}` crée ou met à jour le brouillon avec le titre, le contenu Markdown et les identifiants des demandes.
4. Selon votre processus, un membre de l’équipe relit le brouillon dans l’administration, ou le pipeline appelle `POST /changelog/{id}/publish`.
5. Le pipeline partage `public_url` dans ses notes de version ou sur Slack.

En cas d’échec, relancez le pipeline tel quel : les étapes 3 et 4 ne créent jamais de doublon.

```bash
#!/usr/bin/env bash
set -euo pipefail

API="https://pealhq.com/api/v1"
VERSION="2.4.0"

entry=$(curl -sf -X PUT "$API/changelog/versions/$VERSION" \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d @release-notes.json)

id=$(echo "$entry" | jq -r '.data.id')

curl -sf -X POST "$API/changelog/$id/publish" \
  -H "Authorization: Bearer $PEAL_API_KEY" \
  -H "Accept: application/json" | jq -r '.data.public_url'
```