Wie Sie eine Musikvertrieb-API integrieren

Eine Musikvertrieb-API zu integrieren bedeutet, das eigene System in eine Pipeline einzubinden, die einen Katalog erfasst, dessen Metadaten validiert, Releases an Streaming-Stores ausliefert und Tantiemen sowie Analysen zurückliest. Sie erstellen Labels, Releases und Tracks über HTTP-Aufrufe statt über ein Webformular, reichen jedes Release zur Validierung ein, lösen die Auslieferung an die DSPs aus und lesen anschließend Streams und Abrechnungen aus, um sie mit Ihren eigenen Aufzeichnungen abzugleichen. Die Aufrufe selbst sind der einfache Teil. Die eigentliche Arbeit besteht darin, die Musik-Metadaten korrekt zu modellieren, die asynchronen Schritte zu behandeln und für den Tag vorzusorgen, an dem eine Auslieferung abgelehnt zurückkommt.

Dieser Leitfaden führt durch diese Integration in der Reihenfolge, in der Sie sie tatsächlich aufbauen würden: authentifizieren, ein Release erstellen und ausliefern, Validierung und Fehler behandeln und dann das Geld und die Zahlen zurücklesen. Die Endpoint-Skizzen unten nutzen die öffentliche API von LabelGrid, aber die Struktur gilt für die meisten Vertriebsplattformen. Genaue Felder, Parameter und Fehlercodes finden Sie in der öffentlichen API-Dokumentation, dies ist also die Landkarte, nicht die Feld-für-Feld-Referenz.

Was macht eine Musikvertrieb-API eigentlich?

Eine Vertriebs-API stellt den Release-Lebenszyklus als Endpoints bereit. Es gibt vier Phasen, und jede Integration durchläuft sie in derselben Reihenfolge. Erstens Katalogerfassung: Sie erstellen die Labels, Releases und Tracks, aus denen Ihr Katalog besteht, und fügen die Metadaten und Audiodateien hinzu. Zweitens Validierung: Sie prüfen ein Release gegen die Store-Regeln, bevor es irgendwohin geht. Drittens Auslieferung: Sie vertreiben das validierte Release an Streaming-Dienste und Stores. Viertens Rücklesen: Sie rufen Analysen und Tantiemenabrechnungen ab, damit Ihr eigenes System weiß, was nach der Veröffentlichung der Musik passiert ist.

Unter der Auslieferung liegt DDEX, der Industriestandard zur Beschreibung eines Releases und seiner Audiodateien, damit ein Store es einlesen kann. Sie fassen DDEX so gut wie nie direkt an. Die Plattform erzeugt es aus dem Release, das Sie über die API angelegt haben, und spricht es für Sie mit jedem DSP. Das ist der Sinn einer Vertriebs-API gegenüber der Einzelintegration jedes Stores: ein Release-Modell hinein, DDEX-konforme Auslieferung an alle großen DSPs hinaus. Die Vertriebs-API von LabelGrid deckt alle vier Phasen ab, von der Erfassung bis zu den Abrechnungen, über eine einzige authentifizierte Oberfläche.

Die Endpoints, auf die Sie sich stützen werden, bilden diese Phasen sauber ab:

GET   /api/public/me                        # Token prüfen, sehen wer Sie sind
GET   /api/public/releases                  # Ihren Katalog auflisten
POST  /api/public/releases                  # ein Release erstellen (Erfassung)
POST  /api/public/releases/{id}/validate    # ein Release gegen Store-Regeln prüfen
POST  /api/public/releases/{id}/distribute  # an die DSPs ausliefern
GET   /api/public/analytics                 # Streams und Hörerdaten
GET   /api/public/statements                # Tantiemenabrechnungen

Betrachten Sie diese Liste als das Skelett der gesamten Integration. Alles andere sind Metadaten, Retries und Abgleiche, die sich an diese sieben Aufrufe hängen.

Wie authentifizieren Sie sich?

Die Authentifizierung erfolgt über einen Bearer-Token bei jeder Anfrage. Sie registrieren sich, erzeugen ein API-Credential und senden es im Authorization-Header. Es gibt keinen Demo-Call zu buchen und kein Vertriebsgate, das Sie zuerst passieren müssen. Die Registrierung erfolgt im Self-Service, die Dokumentation ist öffentlich, und sobald ein API-Plan aktiv ist, können Sie noch am selben Nachmittag authentifizierte Aufrufe tätigen. Tokens werden in Ihren Kontoeinstellungen erzeugt, und Sie können einen Token optional auf bekannte IPs beschränken. Der erste Aufruf, den Sie tätigen sollten, ist GET /api/public/me, der Ihnen mitteilt, dass der Token gültig ist und zu welchem Konto er gehört:

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

Sorgen Sie dafür, dass dieser Aufruf eine saubere Antwort liefert, bevor Sie irgendetwas anderes bauen. Ein funktionierender me-Aufruf beweist, dass Ihr Credential, Ihre Basis-URL und Ihr HTTP-Client alle korrekt sind, sodass jeder spätere Fehler am Release liegt und nicht an der Verkabelung. Speichern Sie den Token als Secret, niemals in der Versionskontrolle oder einem Client-Bundle, und behandeln Sie ihn wie ein Passwort: rotieren Sie ihn, wenn er durchsickert, und verwenden Sie getrennte Credentials für Sandbox und Produktion, damit ein Testlauf niemals den Live-Katalog berühren kann. Der genaue Token-Typ, das Ablaufverhalten und etwaige zusätzliche Header sind in der API-Referenz dokumentiert; raten Sie nicht danach, lesen Sie sie dort einmal nach und kapseln Sie sie in einem kleinen Client.

Wie erstellen und liefern Sie ein Release aus?

Drei Aufrufe bringen ein Release von null bis live. Sie erstellen es, validieren es und vertreiben es:

POST  /api/public/releases                  # 1. das Release + seine Metadaten erstellen
POST  /api/public/releases/{id}/validate    # 2. gegen die Store-Regeln prüfen
POST  /api/public/releases/{id}/distribute  # 3. an die DSPs ausliefern

Der Erstellungsschritt ist der Punkt, an dem Sie den Großteil Ihrer Entwicklungsarbeit investieren. Ein Release trägt viele Metadaten: Titel, Künstler und Mitwirkende, Veröffentlichungsdatum, Label, Artwork sowie die Tracks mit ihren eigenen Titeln, Credits und Audiodateien. Die genauen Felder, Formate und welche davon erforderlich sind, stehen alle in der Dokumentation, und Sie sollten sie exakt modellieren, statt sie nur anzunähern. Fehlerhafte Metadaten sind der mit Abstand häufigste Grund, warum ein Release später scheitert, validieren Sie also Ihre eigenen Eingaben, bevor Sie sie überhaupt senden. Prüfen Sie die Artwork-Abmessungen, stellen Sie sicher, dass jeder Track Audio und eine ISRC hat, und normalisieren Sie Künstlernamen auf Ihrer Seite, denn ein Problem in Ihrem Code zu erkennen ist weit günstiger, als es in einer Store-Ablehnung zu erkennen.

Machen Sie die Erstellung idempotent. Netzwerkaufrufe scheitern auf halbem Weg, und Sie wollen nicht, dass ein Retry eine zweite Kopie desselben Releases erzeugt. Verwenden Sie einen Idempotency-Key oder prüfen Sie anhand Ihrer eigenen Referenz auf ein bereits existierendes Release, bevor Sie ein neues erstellen, sodass eine wiederholte Anfrage dasselbe Release zurückgibt, statt es zu duplizieren. Das ist besonders bei einem Massenimport des Katalogs wichtig, wo eine instabile Verbindung über einige tausend Releases hinweg garantiert irgendetwas erneut versucht.

Die Auslieferung ist asynchron. Wenn Sie distribute aufrufen, reihen Sie einen Job ein, statt eine sofortige Antwort zu erhalten. Die API nimmt die Anfrage an, und die Plattform verpackt anschließend DDEX und sendet es im Hintergrund an jeden Store, was Zeit kosten kann. Planen Sie das von Anfang an ein: lösen Sie den distribute-Aufruf aus, protokollieren Sie, dass Sie ihn ausgelöst haben, und fragen Sie dann den Lieferstatus des Releases per Polling ab, statt auf eine Antwort zu warten. Jeder Code, der annimmt, dass die Auslieferung synchron abgeschlossen wird, bricht beim ersten Mal, wenn eine echte Auslieferung länger als eine Sekunde dauert.

Wie behandeln Sie Validierung und Fehler?

Die Validierung ist aus gutem Grund ein eigener Schritt. Der Aufruf POST /api/public/releases/{id}/validate prüft ein Release gegen die Store-Anforderungen und liefert Ihnen zurück, was nicht stimmt, bevor Sie sich auf die Auslieferung festlegen. Validieren Sie immer, bevor Sie ausliefern. Ein Release, das die Validierung nicht besteht und trotzdem gesendet wird, verschwendet einen Auslieferungszyklus und kann schlimmstenfalls beim Store zu einer Ablehnung führen, die langsamer und aufwendiger rückgängig zu machen ist als ein Validierungsfehler, den Sie vorab behoben hätten. Bauen Sie die Schleife als Erstellen, Validieren, Beheben, erneut Validieren auf, und liefern Sie erst aus, sobald die Validierung sauber ist.

Teilen Sie Ihre Fehlerbehandlung nach Klasse auf, denn die beiden Klassen brauchen entgegengesetzte Reaktionen. Ein 4xx ist Ihr eigener Fehler: ein fehlerhaftes Feld, eine fehlende ISRC, ein zu kleines Artwork. Ein unveränderter Retry scheitert einfach erneut, also zeigen Sie den Fehler an, korrigieren Sie die Daten und reichen Sie erneut ein. Ein 5xx oder ein Netzwerk-Timeout ist vorübergehend: wiederholen Sie den Aufruf, aber mit exponentiellem Backoff und einer Obergrenze, nicht in einer engen Schleife, die die API bombardiert. Kombinieren Sie das mit dem Idempotency-Key aus dem Erstellungsschritt, damit ein Retry nach einem Timeout keine Arbeit versehentlich dupliziert. Lesen Sie die tatsächlichen Fehlercodes und ihre Bedeutungen aus der Dokumentation, statt sie zu erraten, und ordnen Sie jeden einer klaren Aktion in Ihrem eigenen System zu: erneut versuchen, beheben und erneut einreichen, oder an einen Menschen eskalieren.

Protokollieren Sie jede Anfrage und jede Antwort mit einer Correlation-ID. Wenn ein Release in drei Wochen feststeckt, macht das Protokoll dessen, was Sie gesendet haben und was zurückkam, den Unterschied zwischen einer Fünf-Minuten-Lösung und einem Nachmittag des Ratens.

Wie lesen Sie Tantiemen und Analysen zurück?

Der Vertrieb ist nur die halbe Schleife. Sobald die Musik live ist, lesen Sie Performance und Einnahmen zurück, damit Ihr System die Realität widerspiegelt. Zwei Endpoints decken das ab:

GET  /api/public/analytics    # Streams, Hörer und Performance-Daten
GET  /api/public/statements   # Tantiemenabrechnungen und Einnahmen

Analysen sind für die Dashboards und Entscheidungen gedacht: Streams, Hörerdaten und wie ein Release über die Stores hinweg performt. Abrechnungen sind für die Buchhaltung: was ein Zeitraum tatsächlich eingebracht hat, bereit zum Abgleich mit den Splits und Auszahlungen, die Sie Künstlern schulden. Rufen Sie beides nach Zeitplan ab, speichern Sie es in Ihrer eigenen Datenbank verknüpft mit Ihrem Katalog, und gleichen Sie ab, statt einem einzelnen Abruf zu vertrauen. Reporting-Daten setzen sich mit der Zeit, da Stores verspätet melden, behandeln Sie also jeden Abruf als das aktuellste Bild, nicht als endgültiges, und lassen Sie einen späteren Abruf eine frühere Schätzung korrigieren.

Rechnen Sie damit, dass diese Antworten paginiert sind, und blättern Sie bis zum Ende durch, statt nur die erste Seite zu lesen und aufzuhören. Für die Aktualität entscheiden Sie zwischen Polling und Webhooks je nach Bedarf. Ein nächtlicher Abgleichs-Job ist mit Polling völlig ausreichend. Wenn Sie in dem Moment reagieren müssen, in dem eine Auslieferung live geht oder eine Abrechnung eintrifft, und Webhooks verfügbar sind, abonnieren Sie das Ereignis, statt jede Minute abzufragen. Die genauen Query-Parameter, Zeiträume und Antwortformate für beide Endpoints stehen in der API-Referenz, damit Sie genau das Zeitfenster abrufen können, das Sie brauchen.

Wie sollten Sie in einer Sandbox testen, bevor Sie in Produktion gehen?

Bauen Sie eine Vertriebsintegration niemals direkt gegen die Produktion. LabelGrid stellt neben der öffentlichen Dokumentation genau deshalb eine Sandbox-Umgebung bereit, damit Sie den vollständigen Erstellungs-, Validierungs- und Auslieferungszyklus durchlaufen können, ohne irgendetwas an einen echten Store zu senden. Verdrahten Sie Ihre Integrationstests von Tag eins an gegen die Sandbox, mit einem separaten Credential, damit ein Testlauf niemals versehentlich ein halbfertiges Release an Spotify ausliefern kann.

Testen Sie mit widrigen Daten, nicht nur mit einem sauberen Idealpfad. Füttern Sie die Sandbox mit Releases, denen ISRCs fehlen, mit zu kleinem Artwork, leeren Künstlernamen und fehlerhaften Daten, und bestätigen Sie, dass Ihre Validierungs- und Retry-Logik bei jedem einzelnen das Richtige tut. Ein sauberes Release beweist, dass die Pipeline verbunden ist; die fehlerhaften beweisen, dass Ihre Fehlerbehandlung tatsächlich funktioniert, und genau dort leben echte Kataloge. Machen Sie den Sandbox-Zyklus zu einem Teil Ihrer Test-Suite, damit jede Änderung an Ihrem Client end-to-end durchgetestet wird, bevor sie ausgeliefert wird.

Was sollten Sie zuerst bauen?

Bauen Sie zuerst ein lauffähiges Grundgerüst, bevor Sie irgendetwas in die Breite bauen. Das Ziel des ersten Meilensteins ist ein Release, das die gesamte Schleife in der Sandbox end-to-end durchläuft, sodass Sie den gesamten Pfad bewiesen haben, bevor Sie irgendeinen Teil davon optimieren. In dieser Reihenfolge:

• Authentifizieren Sie sich, und bringen Sie GET /api/public/me dazu, sauber zu antworten.
• Erstellen Sie ein Release mit realistisch geformten Metadaten über POST /api/public/releases.
• Validieren Sie es, lesen Sie die Fehler, korrigieren Sie die Daten und validieren Sie erneut, bis es besteht.
• Vertreiben Sie es in der Sandbox und fragen Sie das Release per Polling ab, bis die Auslieferung als abgeschlossen gemeldet wird.
• Lesen Sie Analysen und eine Abrechnung zurück und speichern Sie sie zu Ihrem Katalog.

Sobald dieses Grundgerüst grün ist, erweitern Sie es gezielt: Massenerfassung des Katalogs mit Idempotenz, sauberes Backoff und Fehlerrouting, geplante Analytics- und Abrechnungs-Syncs sowie Webhooks, falls Sie geringere Latenz brauchen. Widerstehen Sie dem Drang, den gesamten Katalog-Importer zu bauen, bevor auch nur ein einziges Release in der Sandbox live gegangen ist. Die Integrationen, die pünktlich ausgeliefert werden, sind diejenigen, bei denen zuerst ein Release den gesamten Weg durchläuft und dann das bereits funktionierende Muster skaliert wird.

Zwei Dinge entscheiden darüber, wie reibungslos der restliche Aufbau verläuft. Ihr Metadatenmodell richtig hinzubekommen, damit Releases die Validierung beim ersten Mal bestehen, und Auslieferung sowie Reporting von Anfang an als asynchron zu behandeln, sodass nichts in Ihrem Code eine sofortige Antwort voraussetzt. Bekommen Sie diese beiden Dinge richtig hin, ist eine Vertriebs-API-Integration ein gut verstandenes technisches Problem. Wenn Sie Plattformen evaluieren, deckt die Entwicklerübersicht und die Dokumentation zu White-Label und API ab, was die Oberfläche bereitstellt, und die Endpoint-Referenz ist öffentlich unter api.labelgrid.com/docs/api verfügbar.

Häufig gestellte Fragen