# Démarrage rapide

> Créez une clé d’API dans l’application web HILLS, vérifiez-la avec /me, puis listez vos sorties et consultez vos revenus. Environ cinq minutes.

Ce guide vous mène de l’absence de clé à vos premières données réelles. Il vous faut un compte client sur l’offre Enterprise ou Custom, et un terminal avec `curl` ou Node 18 ou plus récent.

## 1. Créer une clé d’API

1. Connectez-vous à l’application web HILLS et ouvrez **Developers** dans la barre latérale (`/dashboard/developers`).
2. Choisissez **New API key**.
3. Donnez-lui un nom qui indique où elle sera utilisée, par exemple `ERP sync`.
4. Choisissez ses scopes. Par défaut : `members:read`, `catalog:read`, `earnings:read`, `payouts:read` et `links:read`. N’ajoutez `ddex:write`, `ddex:validate` ou les scopes webhook que si vous en avez besoin.
5. Choisissez sa date d’expiration, ou laissez-la sans expiration.
6. Copiez la clé depuis la fenêtre **Copy your API key now**. Elle n’est affichée qu’une fois. Ensuite, la liste n’en montre que le préfixe.

La page **Developers** s’affiche si vous êtes le propriétaire du compte, ou si votre rôle dans l’équipe dispose de la permission API keys. Si le bouton est grisé, votre offre n’inclut pas l’API : adressez-vous à votre interlocuteur HILLS Music.

Gardez la clé sur votre serveur. Placez-la dans une variable d’environnement, jamais dans une page web ou une application que l’on télécharge.

```bash
export HILLS_API_KEY="hm_live_…"
```

## 2. Vérifier la clé

`GET /me` renvoie le compte auquel appartient la clé, le nom de la clé, ses scopes et son expiration. Aucun scope particulier n’est nécessaire.

```bash
curl "https://api.hillsmusic.com/v1/me" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```js
const res = await fetch("https://api.hillsmusic.com/v1/me", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(res.status, await res.json());
```

Une clé valide renvoie `200` :

```json
{
  "partner": { "id": 12, "name": "Nova Records", "email": "ops@novarecords.com" },
  "environment": "production",
  "key": {
    "id": 3,
    "name": "ERP sync",
    "prefix": "hm_live_ab12cd34",
    "environment": "production",
    "scopes": ["catalog:read", "earnings:read"],
    "expires_at": null,
    "created_at": "2026-10-01T09:00:00Z"
  }
}
```

`environment` vaut toujours `production` : il n’existe qu’un seul type de clé. Si vous obtenez plutôt `401` ou `403`, le `code` de la réponse en donne la raison. Voir [Erreurs](https://developer.hillsmusic.com/fr/guides/errors/).

`GET /ping` est une autre façon de vérifier. Il renvoie aussi votre offre et le nombre de requêtes qu’il vous reste pour la minute en cours. Voir [Compte](https://developer.hillsmusic.com/fr/reference/account/).

## 3. Lister vos sorties

`GET /releases` nécessite `catalog:read`. Il renvoie les sorties de vos artistes et labels, de la plus récente à la plus ancienne, 50 par page.

```bash
curl "https://api.hillsmusic.com/v1/releases?limit=10" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```js
const res = await fetch("https://api.hillsmusic.com/v1/releases?limit=10", {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data, next_cursor } = await res.json();
for (const r of data) console.log(r.id, r.title, r.release_status, r.delivery_state);
```

Chaque sortie a un `release_status` (où elle en est dans la vérification) et un `delivery_state` (où elle en est sur les plateformes). Les valeurs possibles figurent sur la page [Statuts](https://developer.hillsmusic.com/fr/reference/statuses/). Tant que `next_cursor` ne vaut pas `null`, il reste des pages. Voir [Pagination](https://developer.hillsmusic.com/fr/guides/pagination/).

Pour affiner la liste, ajoutez `status`, `member_id`, `upc` ou `q`. Pour obtenir une sortie avec ses titres et son statut plateforme par plateforme, appelez `GET /releases/{id}`. Voir [Sorties](https://developer.hillsmusic.com/fr/reference/releases/).

## 4. Consulter vos revenus

`GET /earnings` nécessite `earnings:read`. Il totalise les revenus issus des relevés de plateformes comptabilisés, en USD.

```bash
curl "https://api.hillsmusic.com/v1/earnings?by=store&months=6" \
  -H "Authorization: Bearer $HILLS_API_KEY"
```

```js
const url = new URL("https://api.hillsmusic.com/v1/earnings");
url.searchParams.set("by", "store"); // month (default), release or store
url.searchParams.set("months", "6"); // 1–60, default 12
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
console.log(await res.json());
```

```json
{
  "by": "store",
  "months": 6,
  "currency": "USD",
  "data": [
    { "key": "Spotify", "label": "Spotify", "amount_usd": 1520.42, "member_share_usd": 1064.29, "units": 412003 }
  ]
}
```

`amount_usd` est votre total. `member_share_usd` est la part que vos répartitions de revenus attribuent à vos artistes et labels. Voir [Revenus](https://developer.hillsmusic.com/fr/reference/earnings/).

## Étapes suivantes

- [Authentification](https://developer.hillsmusic.com/fr/guides/authentication/) : scopes, expiration, rotation et révocation des clés.
- [Livraison DDEX](https://developer.hillsmusic.com/fr/guides/ddex/) : les sorties entrent dans HILLS sous forme de lots DDEX ERN. L’API ne crée ni ne modifie de sorties à l’unité.
- [Webhooks](https://developer.hillsmusic.com/fr/guides/webhooks/) : soyez prévenu quand une sortie est approuvée, passe en ligne ou qu’un relevé est publié.
- [Limites de débit](https://developer.hillsmusic.com/fr/guides/rate-limits/) : 120 requêtes par minute et par clé sur Enterprise.

Source: https://developer.hillsmusic.com/fr/guides/quickstart/