# API Cadena

> A API pública das emissoras da Cadena.

A API segue o padrão JSON:API. Os nomes dos campos usam hífen (`start-date`,
`image-url`), e toda resposta bem-sucedida vem com
`Content-Type: application/vnd.api+json`.

Cada token pertence a uma emissora e acessa somente os dados dela. As
permissões de leitura são definidas recurso a recurso, no próprio token.

**A API é somente leitura.** Inscrição em promoção, pedido de música e cadastro
de promoção acontecem no site e no aplicativo da emissora.

Endereço base: https://digital.cadena.com.br

Autenticação: HTTP Basic. Informe o token da emissora no campo de usuário; a senha não é verificada e pode ficar em branco. O token é fornecido pela Cadena e define quais recursos você pode ler.

## Emissora

Os dados da emissora e os recursos habilitados nela.

- [Dados da emissora](https://digital.cadena.com.br/docs/api#list-stations): `GET /api/v1/stations` — Todos os dados da emissora: identidade visual, endereços de transmissão, redes sociais, endereço e quais recursos estão habilitados. Costuma ser a primeira chamada de um aplicativo ao abrir.

## Programação

A grade e quem está no ar.

- [Grade](https://digital.cadena.com.br/docs/api#list-programmings): `GET /api/v1/programmings` — A grade da semana, um item por faixa de horário. Em `days`, `0` é domingo e `6` é sábado. `start-time` e `end-time` trazem a data fixa `2000-01-01`: só o horário é relevante.
- [Locutores](https://digital.cadena.com.br/docs/api#list-speakers): `GET /api/v1/speakers` — Os locutores da emissora, com foto e redes sociais. Redes sociais não preenchidas vêm como texto vazio; o campo nunca é omitido.

## Conteúdo

Podcasts e Mais Tocadas.

- [Podcasts](https://digital.cadena.com.br/docs/api#list-podcasts): `GET /api/v1/podcasts` — Os podcasts publicados pela emissora. `podcast-url` é um caminho relativo: junte-o ao endereço do site da emissora para chegar aos episódios.
- [Mais Tocadas](https://digital.cadena.com.br/docs/api#list-trending-songs): `GET /api/v1/trending-songs` — As músicas mais tocadas, na ordem em que a emissora as publica. Os endereços de prévia e de capa vêm do catálogo de música, não da Cadena.

## Promoções

As promoções no ar e os ganhadores de cada sorteio.

- [Promoções](https://digital.cadena.com.br/docs/api#list-promotions-v3): `GET /api/v3/promotions` — As promoções da emissora, da mais recente para a mais antiga.
- [Detalhe da promoção](https://digital.cadena.com.br/docs/api#get-promotion-v3): `GET /api/v3/promotions/{id}` — A mesma estrutura da lista, com `data` como objeto em vez de array. Use o `id` que vem em cada item da lista.
- [Ganhadores](https://digital.cadena.com.br/docs/api#list-promotion-draw-winners): `GET /api/v1/promotion-draw-winners` — Os ganhadores dos sorteios das promoções da emissora, com os dados de contato informados pelo ouvinte na inscrição. `situation` indica o andamento da entrega do prêmio.

## Legado

Versões anteriores, mantidas para os aplicativos já publicados. Integrações novas não devem usá-las.

- [Promoções (v2)](https://digital.cadena.com.br/docs/api#list-promotions-v2): `GET /api/v2/promotions` — Versão anterior das promoções, mantida para os aplicativos já publicados nas lojas. A resposta não traz `version` nem `image-url`, e a descrição se chama `description-text` em vez de `description`.
- [Inscrições (v2)](https://digital.cadena.com.br/docs/api#list-promotion-entries-v2): `GET /api/v2/promotion-entries` — As inscrições recebidas nas promoções v2, com os dados informados pelo ouvinte. `origin` indica por onde a inscrição foi feita.

## Arquivos

- [Referência navegável](https://digital.cadena.com.br/docs/api): a mesma documentação, em HTML.
- [Especificação OpenAPI](https://digital.cadena.com.br/docs/api/openapi.yaml): o contrato completo, para importar no Postman ou no Insomnia.