Solicitudes a la API

URL base, formato JSON de solicitudes y respuestas, cabeceras de respuesta, versiones y obsolescencias, y qué enviar a soporte cuando algo falla.

Actualizado el 18 de octubre de 2026

La HILLS API es JSON sobre HTTPS. Esta página explica lo que tienen en común todas las solicitudes y respuestas.

URL base

https://api.hillsmusic.com/v1

Hay una sola URL base, tanto para las pruebas como para las entregas. Los portales de marca blanca también responden en su propio dominio.

La base antigua, https://app.hillsmusic.com/api/v1, acepta las mismas rutas y claves, y da las mismas respuestas, hasta el 30 de abril de 2027. Después deja de responder. Las respuestas de la base antigua llevan las cabeceras Deprecation y Sunset. Cámbiate ya a api.hillsmusic.com/v1: solo cambia la base. Consulta la entrada del registro de cambios.

Autenticación

Cada solicitud envía tu clave:

Authorization: Bearer hm_live_…

Consulta Autenticación. Llama a la API solo desde tu servidor. No envía cabeceras CORS, así que los navegadores no pueden llamarla, y una clave en una página web es una clave filtrada.

Leer datos

Las lecturas son solicitudes GET con parámetros de consulta:

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

const url = new URL("https://api.hillsmusic.com/v1/releases");
url.searchParams.set("status", "approved");
url.searchParams.set("limit", "20");
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.HILLS_API_KEY}` },
});
const { data } = await res.json();

Las listas responden { "data": [ … ] }, a veces con campos de paginación. Consulta Paginación. Un único objeto responde { "data": { … } }. Algunas respuestas tienen sus propios campos de primer nivel, como GET /me y GET /earnings. Cada página de la referencia muestra la forma exacta.

Enviar datos

Las solicitudes POST y PATCH envían un cuerpo JSON con Content-Type: application/json:

curl -X POST "https://api.hillsmusic.com/v1/members/invite" \
  -H "Authorization: Bearer $HILLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"luna@example.com","fname":"Luna","kind":"artist"}'

const res = await fetch("https://api.hillsmusic.com/v1/members/invite", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HILLS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "luna@example.com", fname: "Luna", kind: "artist" }),
});
console.log(res.status, await res.json()); // 201 on success

Un cuerpo que no es JSON válido se lee como vacío. La respuesta es entonces 400 invalid, con field indicando el primer campo obligatorio.

Las entregas DDEX son la excepción: envían un archivo zip o XML, no JSON. Consulta Entrega DDEX.

Qué puedes hacer

La API lee tus miembros, tu catálogo, tus ingresos, tus pagos y tus smart links. Escribe en tres casos: al invitar a artistas y sellos, al entregar lotes DDEX y al gestionar endpoints de webhook.

La API no permite crear ni editar un lanzamiento campo a campo. Entrega los lanzamientos como DDEX ERN (POST /ddex, se recomienda ERN 4.3) o usa la aplicación web.

Formatos

Las horas van en ISO 8601 y en UTC, por ejemplo 2026-10-13T09:00:00Z.
Las fechas, como release_date, van en YYYY-MM-DD.
Los importes van en USD. GET /earnings usa importes decimales (amount_usd). GET /payouts usa centavos enteros (earned_cents, available_cents).
Los ID son enteros. Los ID de los eventos de webhook son UUID.
Las URL de las portadas (cover_url) están firmadas y caducan unas 24 horas después de la respuesta. Vuelve a pedir el lanzamiento para obtener una nueva, y no guardes la URL.

Cabeceras de respuesta

Cabecera	Cuándo	Significado
`X-RateLimit-Limit`	En todas las respuestas	Solicitudes por minuto que puede hacer esta clave.
`X-RateLimit-Remaining`	En todas las respuestas	Solicitudes que quedan en este minuto.
`Retry-After`	`429`	Segundos que hay que esperar. Consulta Límites de solicitudes.
`X-HILLS-Environment`	En todas las respuestas	Siempre `production`. Se mantiene para las integraciones que la leen.
`Deprecation`, `Sunset`, `Link`	Cuando la respuesta usa algo que va a desaparecer	Cuándo quedó obsoleto, cuándo desaparece y la entrada del registro de cambios.

Versiones

La versión va en la ruta: /v1. Haz que tu cliente ignore los campos que no conoce, para que los campos nuevos no lo rompan.

Cuando algo de la v1 tiene que desaparecer, se anuncia en el registro de cambios con una fecha de baja. Hasta entonces, las respuestas que lo usan llevan las cabeceras Deprecation (RFC 9745) y Sunset (RFC 8594), además de un Link con rel="deprecation" que apunta a la entrada del registro de cambios. Por ejemplo, el antiguo campo status de los lanzamientos desaparece el 30 de abril de 2027. Lee en su lugar release_status y delivery_state.

Registra en tu cliente las cabeceras Deprecation. Así te enterarás de un cambio antes de que rompa nada.

Errores

Los errores responden con un código de estado y { "error": "…", "code": "…" }. Decide según code, no según el texto. Consulta Errores.

Pedir ayuda

Las respuestas no llevan un ID de solicitud. Cuando contactes con HILLS Music por una solicitud, envía:

el método y la ruta, por ejemplo GET /v1/releases/812;
la hora, en UTC;
el estado y el code que recibiste;
el prefijo de tu clave (hm_live_ab12cd34), nunca la clave completa.

El registro de solicitudes de tu clave, en la página Developers, muestra los mismos datos de los últimos 7 días.