# 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.

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](https://developer.hillsmusic.com/es/changelog/#2026-10-11-api-and-mcp-hosts).

## Autenticación

Cada solicitud envía tu clave:

```
Authorization: Bearer hm_live_…
```

Consulta [Autenticación](https://developer.hillsmusic.com/es/guides/authentication/). 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:

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

```js
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](https://developer.hillsmusic.com/es/guides/pagination/). 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`:

```bash
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"}'
```

```js
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](https://developer.hillsmusic.com/es/guides/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](https://developer.hillsmusic.com/es/guides/rate-limits/). |
| `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. |

<a id="versioning"></a>

## 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](https://developer.hillsmusic.com/es/changelog/) 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](https://developer.hillsmusic.com/es/guides/errors/).

## 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.

Fuente: https://developer.hillsmusic.com/es/guides/making-requests/