Inicio rápido

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.

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.

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

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:

{
  "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.

GET /ping es otra forma de comprobarla. Además devuelve tu plan y cuántas solicitudes te quedan en este minuto. Consulta Cuenta.

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.

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

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. Cuando next_cursor no es null, hay más páginas. Consulta Paginación.

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.

4. Consulta tus ingresos

GET /earnings necesita earnings:read. Suma los ingresos de las liquidaciones confirmadas de las plataformas, en USD.

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

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

{
  "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.

Siguientes pasos

• Autenticación: ámbitos, caducidad, rotación y revocación de claves.
• Entrega DDEX: los lanzamientos entran en HILLS como lotes DDEX ERN. La API no crea ni edita lanzamientos sueltos.
• Webhooks: recibe un aviso cuando un lanzamiento se aprueba o se publica, o cuando se publica una liquidación.
• Límites de solicitudes: 120 solicitudes por minuto y clave en Enterprise.