# Como fazer requisições

> URL base, JSON de requisição e resposta, headers de resposta, versionamento e descontinuações, e o que enviar ao suporte quando algo dá errado.

A HILLS API é JSON sobre HTTPS. Esta página trata do que toda requisição e toda resposta têm em comum.

## URL base

```
https://api.hillsmusic.com/v1
```

Existe uma única URL base, tanto para testes quanto para entregas. Os portais white label também respondem no próprio domínio.

A base antiga, `https://app.hillsmusic.com/api/v1`, aceita os mesmos caminhos e chaves e dá as mesmas respostas até **30 de abril de 2027**. Depois disso, ela deixa de responder. As respostas da base antiga trazem os headers `Deprecation` e `Sunset`. Migre para `api.hillsmusic.com/v1` agora: só a base muda. Veja a [entrada do changelog](https://developer.hillsmusic.com/pt/changelog/#2026-10-11-api-and-mcp-hosts).

## Autenticação

Toda requisição envia a sua chave:

```
Authorization: Bearer hm_live_…
```

Veja [Autenticação](https://developer.hillsmusic.com/pt/guides/authentication/). Chame a API apenas a partir do seu servidor. Ela não envia headers CORS, então os navegadores não conseguem chamá-la, e uma chave em uma página web é uma chave vazada.

## Leitura de dados

As leituras são requisições `GET` com parâmetros de query:

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

As listas respondem `{ "data": [ … ] }`, às vezes com campos de paginação. Veja [Paginação](https://developer.hillsmusic.com/pt/guides/pagination/). Um objeto único responde `{ "data": { … } }`. Algumas respostas têm campos próprios no nível superior, como `GET /me` e `GET /earnings`. Cada página da referência mostra o formato exato.

## Envio de dados

As requisições `POST` e `PATCH` enviam um corpo JSON com `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
```

Um corpo que não é JSON válido é lido como vazio. A resposta, nesse caso, é `400 invalid`, com `field` indicando o primeiro campo obrigatório.

As entregas DDEX são a exceção: elas enviam um arquivo zip ou XML, não JSON. Veja [Entrega DDEX](https://developer.hillsmusic.com/pt/guides/ddex/).

## O que você pode fazer

A API lê seus membros, seu catálogo, seus ganhos, seus pagamentos e seus smartlinks. Ela grava em três lugares: no convite de artistas e gravadoras, na entrega de lotes DDEX e no gerenciamento de endpoints de webhook.

Criar ou editar um lançamento avulso campo a campo não faz parte da API. Entregue os lançamentos em DDEX ERN (`POST /ddex`, ERN 4.3 recomendado) ou use o app web.

## Formatos

- **Horários** seguem a ISO 8601 em UTC, por exemplo `2026-10-13T09:00:00Z`.
- **Datas** como `release_date` seguem `YYYY-MM-DD`.
- **Valores** são em USD. `GET /earnings` usa valores decimais (`amount_usd`). `GET /payouts` usa centavos inteiros (`earned_cents`, `available_cents`).
- **IDs** são inteiros. Os IDs de eventos de webhook são UUIDs.
- **URLs de capa** (`cover_url`) são assinadas e expiram cerca de 24 horas após a resposta. Busque o lançamento de novo para obter uma URL nova, e não armazene a URL.

## Headers de resposta

| Header | Quando | Significado |
| --- | --- | --- |
| `X-RateLimit-Limit` | Toda resposta | Requisições por minuto que esta chave pode fazer. |
| `X-RateLimit-Remaining` | Toda resposta | Requisições restantes neste minuto. |
| `Retry-After` | `429` | Segundos de espera. Veja [Limites de requisições](https://developer.hillsmusic.com/pt/guides/rate-limits/). |
| `X-HILLS-Environment` | Toda resposta | Sempre `production`. Mantido para integrações que o leem. |
| `Deprecation`, `Sunset`, `Link` | Quando a resposta usa algo que está de saída | Quando foi descontinuado, quando sai e a entrada do changelog. |

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

## Versionamento

A versão fica no caminho: `/v1`. Construa o seu cliente para ignorar os campos que ele não conhece, assim campos novos não o quebram.

Quando algo na v1 precisa sair, isso é anunciado no [changelog](https://developer.hillsmusic.com/pt/changelog/) com uma data de desativação. Até lá, as respostas que usam esse recurso trazem os headers `Deprecation` (RFC 9745) e `Sunset` (RFC 8594), além de um `Link` com `rel="deprecation"` para a entrada do changelog. Por exemplo, o campo antigo `status` dos lançamentos sai em 30 de abril de 2027. Leia `release_status` e `delivery_state` no lugar.

Registre os headers `Deprecation` no log do seu cliente. Assim você fica sabendo de uma mudança antes que ela quebre alguma coisa.

## Erros

Os erros respondem com um código de status e `{ "error": "…", "code": "…" }`. Tome decisões com base em `code`, não no texto. Veja [Erros](https://developer.hillsmusic.com/pt/guides/errors/).

## Como pedir ajuda

As respostas não trazem um ID de requisição. Ao falar com a HILLS Music sobre uma requisição, envie:

- o método e o caminho, por exemplo `GET /v1/releases/812`;
- o horário, em UTC;
- o status e o `code` que você recebeu;
- o prefixo da sua chave (`hm_live_ab12cd34`), nunca a chave completa.

O log de requisições da sua chave, na página **Developers**, mostra esses mesmos detalhes dos últimos 7 dias.

Fonte: https://developer.hillsmusic.com/pt/guides/making-requests/