# Inicio rápido

> Crea una clave de API en la aplicación web de HILLS, compruébala con /me y después lista tus lanzamientos y consulta tus ingresos. Unos cinco minutos.

Esta guía te lleva de no tener clave a tus primeros datos reales. Necesitas una cuenta de socio con el plan Enterprise o Custom, y un terminal con `curl` o Node 18 o posterior.

## 1. Crea una clave de API

1. Inicia sesión en la aplicación web de HILLS y abre **Developers** en la barra lateral (`/dashboard/developers`).
2. Elige **New API key**.
3. Dale un nombre que diga dónde se usa, por ejemplo `ERP sync`.
4. Elige sus ámbitos. Los predeterminados son `members:read`, `catalog:read`, `earnings:read`, `payouts:read` y `links:read`. Añade `ddex:write`, `ddex:validate` o los ámbitos de webhooks solo si los necesitas.
5. Elige cuándo caduca, o déjala sin caducidad.
6. Copia la clave del cuadro de diálogo **Copy your API key now**. Se muestra una sola vez. Después, la lista solo muestra su prefijo.

Ves **Developers** si eres el propietario de la cuenta o si tu rol en el equipo tiene el permiso de claves de API. Si el botón aparece desactivado, tu plan no incluye la API: consulta a tu contacto en HILLS Music.

Guarda la clave en tu servidor. Ponla en una variable de entorno, nunca en una página web ni en una aplicación que la gente descargue.

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

## 2. Comprueba la clave

`GET /me` responde con la cuenta a la que pertenece la clave, el nombre de la clave, sus ámbitos y su caducidad. No necesita ningún ámbito en particular.

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

Una clave que funciona responde `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` siempre es `production`: hay un solo tipo de clave. Si en su lugar recibes `401` o `403`, el `code` de la respuesta indica el motivo. Consulta [Errores](https://developer.hillsmusic.com/es/guides/errors/).

`GET /ping` es otra forma de comprobarla. Además devuelve tu plan y cuántas solicitudes te quedan en este minuto. Consulta [Cuenta](https://developer.hillsmusic.com/es/reference/account/).

## 3. Lista tus lanzamientos

`GET /releases` necesita `catalog:read`. Devuelve los lanzamientos de tus artistas y sellos, del más reciente al más antiguo, 50 por página.

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

Cada lanzamiento tiene `release_status` (en qué punto de la revisión está) y `delivery_state` (en qué punto está en las plataformas). Los valores están en [Estados](https://developer.hillsmusic.com/es/reference/statuses/). Cuando `next_cursor` no es null, hay más páginas. Consulta [Paginación](https://developer.hillsmusic.com/es/guides/pagination/).

Para acotar la lista, añade `status`, `member_id`, `upc` o `q`. Para obtener un lanzamiento con sus pistas y su estado plataforma por plataforma, llama a `GET /releases/{id}`. Consulta [Lanzamientos](https://developer.hillsmusic.com/es/reference/releases/).

## 4. Consulta tus ingresos

`GET /earnings` necesita `earnings:read`. Suma los ingresos de las liquidaciones confirmadas de las plataformas, 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` es tu total. `member_share_usd` es la parte que tus repartos de ingresos asignan a tus artistas y sellos. Consulta [Ingresos](https://developer.hillsmusic.com/es/reference/earnings/).

## Siguientes pasos

- [Autenticación](https://developer.hillsmusic.com/es/guides/authentication/): ámbitos, caducidad, rotación y revocación de claves.
- [Entrega DDEX](https://developer.hillsmusic.com/es/guides/ddex/): los lanzamientos entran en HILLS como lotes DDEX ERN. La API no crea ni edita lanzamientos sueltos.
- [Webhooks](https://developer.hillsmusic.com/es/guides/webhooks/): recibe un aviso cuando un lanzamiento se aprueba o se publica, o cuando se publica una liquidación.
- [Límites de solicitudes](https://developer.hillsmusic.com/es/guides/rate-limits/): 120 solicitudes por minuto y clave en Enterprise.

Fuente: https://developer.hillsmusic.com/es/guides/quickstart/