# Schnellstart

> API-Schlüssel in der HILLS Web-App erstellen, mit /me prüfen, dann Releases auflisten und Erlöse lesen. In etwa fünf Minuten.

Diese Anleitung bringt Sie ohne vorhandenen Schlüssel bis zu Ihren ersten echten Daten. Sie brauchen ein Kundenkonto im Tarif Enterprise oder Custom und ein Terminal mit `curl` oder Node 18 oder neuer.

## 1. API-Schlüssel erstellen

1. Melden Sie sich in der HILLS Web-App an und öffnen Sie in der Seitenleiste **Developers** (`/dashboard/developers`).
2. Wählen Sie **New API key**.
3. Geben Sie ihm einen Namen, der sagt, wo er läuft, zum Beispiel `ERP sync`.
4. Wählen Sie seine Scopes. Voreingestellt sind `members:read`, `catalog:read`, `earnings:read`, `payouts:read` und `links:read`. Fügen Sie `ddex:write`, `ddex:validate` oder die Webhook-Scopes nur hinzu, wenn Sie sie brauchen.
5. Legen Sie fest, wann er abläuft, oder lassen Sie ihn ohne Ablaufdatum.
6. Kopieren Sie den Schlüssel aus dem Dialog **Copy your API key now**. Er wird nur einmal angezeigt. Danach zeigt die Liste nur noch sein Präfix.

**Developers** sehen Sie, wenn Sie Kontoinhaber sind oder Ihre Teamrolle die Berechtigung für API-Schlüssel hat. Ist die Schaltfläche ausgegraut, enthält Ihr Tarif die API nicht: Wenden Sie sich an Ihren Ansprechpartner bei HILLS Music.

Bewahren Sie den Schlüssel auf Ihrem Server auf. Legen Sie ihn in einer Umgebungsvariablen ab, niemals in einer Webseite oder einer App, die andere herunterladen.

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

## 2. Schlüssel prüfen

`GET /me` antwortet mit dem Konto hinter dem Schlüssel sowie Name, Scopes und Ablaufdatum des Schlüssels. Ein bestimmter Scope ist dafür nicht nötig.

```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());
```

Ein funktionierender Schlüssel antwortet mit `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` ist immer `production`, denn es gibt nur eine Art von Schlüssel. Erhalten Sie stattdessen `401` oder `403`, nennt der `code` in der Antwort den Grund. Siehe [Fehler](https://developer.hillsmusic.com/de/guides/errors/).

`GET /ping` ist eine weitere Prüfung. Sie liefert zusätzlich Ihren Tarif und wie viele Anfragen Ihnen in dieser Minute noch bleiben. Siehe [Konto](https://developer.hillsmusic.com/de/reference/account/).

## 3. Releases auflisten

`GET /releases` braucht `catalog:read`. Der Endpunkt liefert die Releases Ihrer Artists und Labels, die neuesten zuerst, 50 pro Seite.

```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);
```

Jedes Release hat `release_status` (wo es in der Prüfung steht) und `delivery_state` (wo es in den Stores steht). Die Werte finden Sie unter [Statuswerte](https://developer.hillsmusic.com/de/reference/statuses/). Ist `next_cursor` nicht null, gibt es weitere Seiten. Siehe [Paginierung](https://developer.hillsmusic.com/de/guides/pagination/).

Um die Liste einzugrenzen, ergänzen Sie `status`, `member_id`, `upc` oder `q`. Ein einzelnes Release mit seinen Tracks und dem Status Store für Store erhalten Sie mit `GET /releases/{id}`. Siehe [Releases](https://developer.hillsmusic.com/de/reference/releases/).

## 4. Erlöse lesen

`GET /earnings` braucht `earnings:read`. Der Endpunkt summiert die Erlöse aus verbuchten Store-Abrechnungen in 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` ist Ihre Gesamtsumme. `member_share_usd` ist der Teil, den Ihre Erlös-Splits Ihren Artists und Labels zuweisen. Siehe [Erlöse](https://developer.hillsmusic.com/de/reference/earnings/).

## Nächste Schritte

- [Authentifizierung](https://developer.hillsmusic.com/de/guides/authentication/): Scopes, Ablaufdatum, Schlüssel rotieren und widerrufen.
- [DDEX-Auslieferung](https://developer.hillsmusic.com/de/guides/ddex/): Releases kommen als DDEX-ERN-Batches zu HILLS. Einzelne Releases legt die API nicht an und bearbeitet sie nicht.
- [Webhooks](https://developer.hillsmusic.com/de/guides/webhooks/): Lassen Sie sich benachrichtigen, wenn ein Release freigegeben wird, live geht oder eine Abrechnung veröffentlicht wird.
- [Rate Limits](https://developer.hillsmusic.com/de/guides/rate-limits/): 120 Anfragen pro Minute und Schlüssel bei Enterprise.

Quelle: https://developer.hillsmusic.com/de/guides/quickstart/