Como Integrar uma API de Distribuição Musical

Integrar uma API de distribuição musical significa conectar seu próprio sistema a um pipeline que ingere um catálogo, valida seus metadados, entrega lançamentos às lojas de streaming e lê de volta royalties e análises. Você cria gravadoras, lançamentos e faixas por chamadas HTTP em vez de um formulário web, envia cada lançamento para validação, aciona a entrega aos DSPs e depois busca streams e extratos para reconciliar com seus próprios registros. As chamadas em si são a parte fácil. O trabalho de verdade é modelar corretamente os metadados musicais, tratar as etapas assíncronas e construir para o dia em que uma entrega volta rejeitada.

Este guia percorre essa integração na ordem em que você de fato a construiria: autenticar, criar e entregar um lançamento, tratar validação e erros, e depois ler de volta o dinheiro e os números. Os esboços de endpoints abaixo usam a API pública da LabelGrid, mas a estrutura se aplica à maioria das plataformas de distribuição. Os campos, parâmetros e códigos de erro exatos estão na documentação pública da API, então isto é o mapa, não a referência campo a campo.

O Que Uma API de Distribuição Musical Realmente Faz?

Uma API de distribuição expõe o ciclo de vida do lançamento como endpoints. Existem quatro etapas, e toda integração passa por elas na mesma ordem. Primeiro, a ingestão de catálogo: você cria as gravadoras, lançamentos e faixas que compõem seu catálogo, e anexa os metadados e o áudio. Segundo, a validação: você verifica um lançamento contra as regras das lojas antes que ele vá a qualquer lugar. Terceiro, a entrega: você distribui o lançamento validado aos serviços de streaming e lojas. Quarto, a leitura de retorno: você busca análises e extratos de royalties para que seu próprio sistema saiba o que aconteceu depois que a música foi ao ar.

Por baixo da entrega está o DDEX, o padrão da indústria para descrever um lançamento e seu áudio para que uma loja possa ingeri-lo. Você quase nunca toca no DDEX diretamente. A plataforma o gera a partir do lançamento que você construiu pela API e o transmite a cada DSP por você. É esse o objetivo de usar uma API de distribuição em vez de integrar cada loja uma a uma: um modelo de lançamento na entrada, entrega compatível com DDEX para todos os principais DSPs na saída. A API de distribuição da LabelGrid cobre as quatro etapas, da ingestão aos extratos, em uma única superfície autenticada.

Os endpoints que você vai usar se encaixam diretamente nessas etapas:

GET   /api/public/me                        # verifica o token, veja quem você é
GET   /api/public/releases                  # lista seu catálogo
POST  /api/public/releases                  # cria um lançamento (ingestão)
POST  /api/public/releases/{id}/validate    # verifica um lançamento contra as regras das lojas
POST  /api/public/releases/{id}/distribute  # entrega aos DSPs
GET   /api/public/analytics                 # streams e dados de ouvintes
GET   /api/public/statements                # extratos de royalties

Trate essa lista como o esqueleto de toda a integração. Tudo o mais é metadados, retentativas e reconciliação pendurados nessas sete chamadas.

Como Você Se Autentica?

A autenticação é um bearer token em cada requisição. Você se cadastra, gera uma credencial de API e a envia no cabeçalho Authorization. Não há chamada de demonstração para agendar nem barreira de vendas para passar antes. O cadastro é self-service, a documentação é pública, e assim que um plano de API estiver ativo, você pode estar fazendo chamadas autenticadas na mesma tarde. Os tokens são gerados nas configurações da sua conta, e você pode opcionalmente restringir um token a IPs conhecidos. A primeira chamada a fazer é GET /api/public/me, que informa se o token é válido e a qual conta ele pertence:

curl https://api.labelgrid.com/api/public/me \
  -H "Authorization: Bearer <token>"

Faça isso retornar uma resposta limpa antes de construir qualquer outra coisa. Uma chamada me funcionando comprova que sua credencial, sua URL base e seu cliente HTTP estão todos corretos, então qualquer falha posterior é sobre o lançamento, não sobre a encanação. Armazene o token como um segredo, nunca no controle de versão ou em um bundle de cliente, e trate-o como uma senha: rotacione-o se vazar, e use credenciais separadas para sandbox e produção para que uma execução de teste nunca possa tocar o catálogo ao vivo. O tipo exato de token, o comportamento de expiração e quaisquer cabeçalhos adicionais estão documentados na referência da API; não tente adivinhar, leia-os lá uma vez e encapsule-os em um pequeno cliente.

Como Criar e Entregar um Lançamento?

Três chamadas levam um lançamento do zero ao ar. Você o cria, o valida e o distribui:

POST  /api/public/releases                  # 1. cria o lançamento + seus metadados
POST  /api/public/releases/{id}/validate    # 2. verifica contra as regras das lojas
POST  /api/public/releases/{id}/distribute  # 3. entrega aos DSPs

A etapa de criação é onde você gasta a maior parte da sua engenharia. Um lançamento carrega muitos metadados: título, artistas e colaboradores, data de lançamento, gravadora, arte de capa, e as faixas com seus próprios títulos, créditos e áudio. Os campos precisos, os formatos e quais são obrigatórios estão todos na documentação, e você deve modelá-los exatamente, em vez de aproximar. Metadados ruins são o motivo mais comum de um lançamento falhar mais tarde, então valide suas próprias entradas antes de enviá-las. Verifique as dimensões da arte de capa, confirme que cada faixa tem áudio e um ISRC, e normalize os nomes dos artistas do seu lado, porque detectar um problema no seu código é muito mais barato do que detectá-lo em uma rejeição da loja.

Torne a criação idempotente. Chamadas de rede falham no meio do caminho, e você não quer que uma retentativa produza uma segunda cópia do mesmo lançamento. Use uma chave de idempotência ou verifique se já existe um lançamento pela sua própria referência antes de criar um novo, para que uma requisição repetida retorne o mesmo lançamento em vez de duplicá-lo. Isso importa mais durante uma importação em massa de catálogo, onde uma conexão instável ao longo de alguns milhares de lançamentos certamente vai fazer alguma retentativa.

A entrega é assíncrona. Quando você chama distribute, você está enfileirando um job, não recebendo uma resposta instantânea. A API aceita a requisição e, então, a plataforma empacota o DDEX e o envia a cada loja em segundo plano, o que pode levar tempo. Projete para isso desde o início: dispare a chamada de distribuição, registre que você fez a solicitação, e então faça polling do lançamento para seu status de entrega, em vez de bloquear esperando uma resposta. Qualquer código que assuma que a distribuição termina de forma síncrona vai quebrar na primeira vez que uma entrega real levar mais de um segundo.

Como Tratar Validação e Erros?

A validação é uma etapa separada por um motivo. Chamar POST /api/public/releases/{id}/validate verifica um lançamento contra os requisitos das lojas e devolve a você o que está errado antes de você se comprometer com a entrega. Sempre valide antes de distribuir. Um lançamento que falha na validação e é enviado mesmo assim desperdiça um ciclo de entrega e, pior, pode resultar em uma rejeição na loja, que é mais lenta e mais complicada de desfazer do que um erro de validação corrigido de antemão. Construa o ciclo como criar, validar, corrigir, validar novamente, e só distribua quando a validação estiver limpa.

Divida seu tratamento de erros por classe, porque as duas classes exigem respostas opostas. Um 4xx é culpa sua: um campo malformado, um ISRC ausente, uma arte de capa pequena demais. Tentar novamente sem mudar nada só vai falhar de novo, então exponha o erro, corrija os dados e reenvie. Um 5xx ou um timeout de rede é transitório: tente novamente, mas com backoff exponencial e um limite, não um loop apertado que martela a API. Combine isso com a chave de idempotência da etapa de criação, para que uma retentativa após um timeout não duplique o trabalho por acidente. Leia os códigos de erro reais e seus significados na documentação em vez de inferi-los, e mapeie cada um para uma ação clara no seu próprio sistema: tentar novamente, corrigir e reenviar, ou escalar para um humano.

Registre em log cada requisição e resposta com um correlation id. Quando um lançamento estiver travado daqui a três semanas, o log do que você enviou e do que voltou é a diferença entre uma correção de cinco minutos e uma tarde inteira de tentativa e erro.

Como Ler Royalties e Análises de Volta?

A distribuição é apenas metade do ciclo. Depois que a música está ao ar, você lê de volta o desempenho e os ganhos para que seu sistema reflita a realidade. Dois endpoints cobrem isso:

GET  /api/public/analytics    # streams, ouvintes e dados de desempenho
GET  /api/public/statements   # extratos de royalties e ganhos

As análises são para os painéis e decisões: streams, dados de ouvintes e como um lançamento está performando nas lojas. Os extratos são para a contabilidade: o que um período realmente rendeu, prontos para reconciliar com as divisões e os pagamentos que você deve aos artistas. Busque os dois em uma agenda, armazene-os no seu próprio banco de dados vinculados ao seu catálogo, e reconcilie em vez de confiar em uma única busca. Os dados de relatório se assentam ao longo do tempo, à medida que as lojas reportam com atraso, então trate cada busca como o retrato mais recente, não um definitivo, e deixe uma busca posterior corrigir uma estimativa anterior.

Espere que essas respostas sejam paginadas, e percorra as páginas até o fim, em vez de ler a primeira página e parar. Para atualização, decida entre polling e webhooks com base no que você precisa. Um job de reconciliação noturno funciona bem com polling. Se você precisa reagir no momento em que uma entrega vai ao ar ou um extrato chega, e webhooks estão disponíveis, assine o evento em vez de fazer polling a cada minuto. Os parâmetros de consulta exatos, os intervalos de datas e os formatos de resposta para os dois endpoints estão na referência da API, para que você possa buscar exatamente a janela de que precisa.

Como Testar em um Sandbox Antes de Produção?

Nunca construa uma integração de distribuição direto contra produção. A LabelGrid oferece um ambiente de sandbox junto com a documentação pública exatamente para que você possa executar todo o ciclo de criação, validação e distribuição sem enviar nada a uma loja real. Conecte seus testes de integração ao sandbox desde o primeiro dia, usando uma credencial separada, para que uma execução de teste nunca possa entregar acidentalmente um lançamento pela metade ao Spotify.

Teste com dados adversos, não apenas um caminho feliz e limpo. Alimente o sandbox com lançamentos com ISRCs ausentes, arte de capa pequena demais, nomes de artistas vazios e datas erradas, e confirme que sua lógica de validação e retentativa faz a coisa certa em cada caso. Um lançamento limpo prova que o pipeline se conecta; os quebrados provam que seu tratamento de erros realmente funciona, e é no tratamento de erros que vivem os catálogos reais. Faça do ciclo do sandbox parte da sua suíte de testes, para que toda mudança no seu cliente seja exercitada de ponta a ponta antes de ir para produção.

O Que Você Deve Construir Primeiro?

Construa um esqueleto funcional antes de construir qualquer coisa ampla. O objetivo do primeiro marco é um único lançamento passando por todo o ciclo no sandbox, de ponta a ponta, para que você tenha comprovado o caminho inteiro antes de otimizar qualquer parte dele. Em ordem:

• Autentique-se e faça GET /api/public/me retornar de forma limpa.
• Crie um lançamento com metadados no formato real por meio de POST /api/public/releases.
• Valide-o, leia as falhas, corrija os dados e valide até que ele passe.
• Distribua-o no sandbox e faça polling do lançamento até que a entrega seja reportada como concluída.
• Leia de volta as análises e um extrato e armazene-os vinculados ao seu catálogo.

Assim que esse esqueleto estiver verde, amplie-o deliberadamente: ingestão de catálogo em massa com idempotência, backoff e roteamento de erros adequados, sincronizações programadas de análises e extratos, e webhooks se você precisar de menor latência. Resista ao impulso de construir todo o importador de catálogo antes que um único lançamento tenha ido ao ar no sandbox. As integrações que são entregues no prazo são as que levam um lançamento até o fim primeiro, e depois escalam o padrão que já funciona.

Duas coisas decidem o quão tranquilo é o resto da construção. Acertar o modelo de metadados, para que os lançamentos passem na validação de primeira, e tratar entrega e relatórios como assíncronos desde o início, para que nada no seu código assuma uma resposta instantânea. Acerte essas duas coisas e uma integração de API de distribuição é um problema de engenharia bem compreendido. Se você está avaliando plataformas, a visão geral para desenvolvedores e a documentação de white-label e API cobrem o que a superfície expõe, e a referência de endpoints é pública em api.labelgrid.com/docs/api.

Perguntas frequentes