Início rápido

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.

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.

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

Uma chave 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 é 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.

GET /ping é outra forma de verificar. Ele também retorna o seu plano e quantas requisições ainda restam neste minuto. Veja Conta.

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.

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 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. Quando next_cursor não é null, há mais páginas. Veja Paginação.

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.

4. Leia seus ganhos

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

Próximos passos

• Autenticação: escopos, validade, rotação e revogação de chaves.
• Entrega DDEX: os lançamentos entram na HILLS em lotes DDEX ERN. A API não cria nem edita lançamentos avulsos.
• 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: 120 requisições por minuto por chave no Enterprise.