# Início rápido

> Crie uma chave de API no app web da HILLS, verifique-a com /me, depois liste seus lançamentos e leia seus ganhos. Cerca de cinco minutos.

Este guia leva você de nenhuma chave aos seus primeiros dados reais. Você precisa de uma conta de cliente no plano Enterprise ou Custom e de um terminal com `curl` ou Node 18 ou posterior.

## 1. Crie uma chave de API

1. Entre no app web da HILLS e abra **Developers** na barra lateral (`/dashboard/developers`).
2. Escolha **New API key**.
3. Dê a ela um nome que diga onde ela roda, por exemplo `ERP sync`.
4. Escolha os escopos. Os padrões são `members:read`, `catalog:read`, `earnings:read`, `payouts:read` e `links:read`. Adicione `ddex:write`, `ddex:validate` ou os escopos de webhook só se precisar deles.
5. Escolha quando ela expira, ou deixe sem validade.
6. Copie a chave na caixa de diálogo **Copy your API key now**. Ela aparece uma única vez. Depois disso, a lista mostra só o prefixo.

Você vê **Developers** se for o proprietário da conta ou se a sua função na equipe tiver a permissão de chaves de API. Se o botão estiver desativado, o seu plano não inclui a API: fale com o seu contato na HILLS Music.

Mantenha a chave no seu servidor. Guarde-a em uma variável de ambiente, nunca em uma página web ou em um app que as pessoas baixam.

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

## 2. Verifique a chave

`GET /me` responde com a conta por trás da chave, o nome da chave, seus escopos e sua validade. Não exige nenhum escopo específico.

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

Uma chave 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` é sempre `production`. Existe um único tipo de chave. Se em vez disso você receber `401` ou `403`, o `code` na resposta diz o motivo. Veja [Erros](https://developer.hillsmusic.com/pt/guides/errors/).

`GET /ping` é outra forma de verificar. Ele também retorna o seu plano e quantas requisições ainda restam neste minuto. Veja [Conta](https://developer.hillsmusic.com/pt/reference/account/).

## 3. Liste seus lançamentos

`GET /releases` exige `catalog:read`. Ele retorna os lançamentos dos seus artistas e gravadoras, dos mais recentes para os mais antigos, 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 lançamento tem `release_status` (em que ponto da revisão ele está) e `delivery_state` (em que ponto ele está nas plataformas). Os valores estão em [Status](https://developer.hillsmusic.com/pt/reference/statuses/). Quando `next_cursor` não é null, há mais páginas. Veja [Paginação](https://developer.hillsmusic.com/pt/guides/pagination/).

Para filtrar a lista, adicione `status`, `member_id`, `upc` ou `q`. Para obter um lançamento com as faixas e o status plataforma por plataforma, chame `GET /releases/{id}`. Veja [Lançamentos](https://developer.hillsmusic.com/pt/reference/releases/).

## 4. Leia seus ganhos

`GET /earnings` exige `earnings:read`. Ele soma a receita dos relatórios consolidados das plataformas, em 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` é o seu total. `member_share_usd` é a parte que os seus splits de receita destinam aos seus artistas e gravadoras. Veja [Ganhos](https://developer.hillsmusic.com/pt/reference/earnings/).

## Próximos passos

- [Autenticação](https://developer.hillsmusic.com/pt/guides/authentication/): escopos, validade, rotação e revogação de chaves.
- [Entrega DDEX](https://developer.hillsmusic.com/pt/guides/ddex/): os lançamentos entram na HILLS em lotes DDEX ERN. A API não cria nem edita lançamentos avulsos.
- [Webhooks](https://developer.hillsmusic.com/pt/guides/webhooks/): seja avisado quando um lançamento for aprovado, entrar no ar ou quando um relatório de royalties for publicado.
- [Limites de requisições](https://developer.hillsmusic.com/pt/guides/rate-limits/): 120 requisições por minuto por chave no Enterprise.

Fonte: https://developer.hillsmusic.com/pt/guides/quickstart/