Cómo integrar una API de distribución musical

Integrar una API de distribución musical significa conectar su propio sistema a un proceso que ingiere un catálogo, valida sus metadatos, entrega lanzamientos a las plataformas de streaming y lee de vuelta las regalías y las analíticas. Usted crea sellos, lanzamientos y pistas mediante llamadas HTTP en lugar de un formulario web, envía cada lanzamiento a validación, activa la entrega a los DSP y después recupera las reproducciones y los informes para conciliarlos con sus propios registros. Las llamadas en sí son la parte fácil. El trabajo real consiste en modelar correctamente los metadatos musicales, gestionar los pasos asíncronos y prepararse para el día en que una entrega vuelva rechazada.

Esta guía recorre esa integración en el orden en que realmente la construiría: autenticarse, crear y entregar un lanzamiento, gestionar la validación y los errores, y después leer de vuelta el dinero y las cifras. Los esbozos de endpoints que aparecen a continuación usan la API pública de LabelGrid, pero la forma se aplica a la mayoría de las plataformas de distribución. Los campos exactos, los parámetros y los códigos de error están en la documentación pública de la API, así que esto es el mapa, no la referencia campo por campo.

¿Qué hace realmente una API de distribución musical?

Una API de distribución expone el ciclo de vida del lanzamiento como endpoints. Hay cuatro etapas, y toda integración las recorre en el mismo orden. Primero, la ingesta de catálogo: usted crea los sellos, lanzamientos y pistas que componen su catálogo, y adjunta los metadatos y el audio. Segundo, la validación: comprueba un lanzamiento frente a las normas de las plataformas antes de que vaya a ninguna parte. Tercero, la entrega: distribuye el lanzamiento validado a los servicios de streaming y las plataformas. Cuarto, la lectura de vuelta: recupera analíticas e informes de regalías para que su propio sistema sepa qué ocurrió después de que la música se publicara.

Detrás de la entrega está DDEX, el estándar del sector para describir un lanzamiento y su audio de modo que una plataforma pueda ingerirlo. Casi nunca toca DDEX directamente. La plataforma lo genera a partir del lanzamiento que usted creó mediante la API y lo comunica a cada DSP por usted. Ese es el sentido de usar una API de distribución en lugar de integrar cada plataforma una por una: un único modelo de lanzamiento a la entrada, entrega conforme a DDEX a todos los principales DSP a la salida. La API de distribución de LabelGrid cubre las cuatro etapas, desde la ingesta hasta los informes, bajo una única superficie autenticada.

Los endpoints en los que se apoyará se corresponden claramente con esas etapas:

GET   /api/public/me                        # verificar el token, ver quién es usted
GET   /api/public/releases                  # listar su catálogo
POST  /api/public/releases                  # crear un lanzamiento (ingesta)
POST  /api/public/releases/{id}/validate    # comprobar un lanzamiento frente a las normas de las plataformas
POST  /api/public/releases/{id}/distribute  # entregar a los DSP
GET   /api/public/analytics                 # reproducciones y datos de oyentes
GET   /api/public/statements                # informes de regalías

Trate esa lista como el esqueleto de toda la integración. Todo lo demás son metadatos, reintentos y conciliación que cuelgan de esas siete llamadas.

¿Cómo se autentica?

La autenticación es un token bearer en cada solicitud. Usted se registra, genera una credencial de API y la envía en la cabecera Authorization. No hay que reservar ninguna llamada de demostración ni superar antes ninguna barrera comercial. El registro es de autoservicio, la documentación es pública y, una vez que un plan de API está activo, puede estar realizando llamadas autenticadas esa misma tarde. Los tokens se generan desde la configuración de su cuenta, y opcionalmente puede restringir un token a IP conocidas. La primera llamada que debe hacer es GET /api/public/me, que le indica si el token es válido y a qué cuenta pertenece:

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

Consiga que eso devuelva una respuesta limpia antes de construir nada más. Una llamada a me que funciona demuestra que su credencial, su URL base y su cliente HTTP son correctos, de modo que cualquier fallo posterior tiene que ver con el lanzamiento, no con la fontanería. Guarde el token como un secreto, nunca en el control de versiones ni en un paquete de cliente, y trátelo como una contraseña: rótelo si se filtra, y use credenciales separadas para sandbox y producción para que una ejecución de prueba nunca pueda tocar el catálogo en vivo. El tipo exacto de token, el comportamiento de caducidad y cualquier cabecera adicional están documentados en la referencia de la API; no los adivine, léalos allí una vez y envuélvalos en un pequeño cliente.

¿Cómo se crea y se entrega un lanzamiento?

Tres llamadas llevan un lanzamiento de la nada a estar en vivo. Lo crea, lo valida y lo distribuye:

POST  /api/public/releases                  # 1. crear el lanzamiento y sus metadatos
POST  /api/public/releases/{id}/validate    # 2. comprobarlo frente a las normas de las plataformas
POST  /api/public/releases/{id}/distribute  # 3. entregarlo a los DSP

El paso de creación es donde invertirá la mayor parte de su ingeniería. Un lanzamiento lleva muchos metadatos: título, artistas y colaboradores, fecha de lanzamiento, sello, portada y las pistas con sus propios títulos, créditos y audio. Los campos exactos, los formatos y cuáles son obligatorios están todos en la documentación, y debería modelarlos con exactitud en lugar de aproximarlos. Unos metadatos incorrectos son la razón más común por la que un lanzamiento falla más adelante, así que valide sus propias entradas antes de enviarlas. Compruebe las dimensiones de la portada, confirme que cada pista tiene audio y un ISRC, y normalice los nombres de los artistas de su lado, porque detectar un problema en su código es mucho más barato que detectarlo en un rechazo de la plataforma.

Haga que la creación sea idempotente. Las llamadas de red fallan a mitad de camino, y usted no quiere que un reintento produzca una segunda copia del mismo lanzamiento. Use una clave de idempotencia o compruebe si ya existe un lanzamiento con su propia referencia antes de crear uno nuevo, de modo que una solicitud repetida devuelva el mismo lanzamiento en lugar de duplicarlo. Esto importa sobre todo durante una importación masiva de catálogo, donde una conexión inestable a lo largo de varios miles de lanzamientos hará que algo se reintente sin duda.

La entrega es asíncrona. Cuando llama a distribute, está encolando una tarea, no obteniendo una respuesta instantánea. La API acepta la solicitud y después la plataforma empaqueta el DDEX y lo envía a cada plataforma en segundo plano, lo cual puede llevar tiempo. Diseñe para eso desde el principio: lance la llamada de distribución, registre que la solicitó, y después consulte periódicamente el lanzamiento para conocer su estado de entrega en lugar de bloquearse esperando una respuesta. Cualquier código que asuma que la distribución se completa de forma síncrona fallará la primera vez que una entrega real tarde más de un segundo.

¿Cómo se gestionan la validación y los errores?

La validación es un paso independiente por una razón. Llamar a POST /api/public/releases/{id}/validate comprueba un lanzamiento frente a los requisitos de las plataformas y le devuelve qué está mal antes de comprometerse con la entrega. Valide siempre antes de distribuir. Un lanzamiento que falla la validación y aun así se envía desperdicia un ciclo de entrega y, peor aún, puede acabar en un rechazo de la plataforma que es más lento y más complicado de deshacer que un error de validación corregido de antemano. Construya el bucle como crear, validar, corregir, validar de nuevo, y distribuya solo cuando la validación esté limpia.

Divida su gestión de errores por clase, porque las dos clases necesitan respuestas opuestas. Un 4xx es culpa suya: un campo malformado, un ISRC ausente, una portada demasiado pequeña. Reintentarlo sin cambios simplemente vuelve a fallar, así que muéstrelo, corrija los datos y vuelva a enviarlo. Un 5xx o un tiempo de espera agotado de red es transitorio: reinténtelo, pero con retroceso exponencial y un límite, no con un bucle ajustado que machaque la API. Combine eso con la clave de idempotencia del paso de creación para que un reintento tras un tiempo de espera agotado no pueda duplicar el trabajo por accidente. Lea los códigos de error reales y su significado en la documentación en lugar de inferirlos, y asigne cada uno a una acción clara en su propio sistema: reintentar, corregir y reenviar, o escalar a una persona.

Registre cada solicitud y respuesta con un id de correlación. Cuando un lanzamiento se quede atascado dentro de tres semanas, el registro de lo que envió y lo que recibió será la diferencia entre una corrección de cinco minutos y una tarde entera adivinando.

¿Cómo se leen de vuelta las regalías y las analíticas?

La distribución es solo la mitad del ciclo. Una vez que la música está en vivo, usted lee de vuelta el rendimiento y los ingresos para que su sistema refleje la realidad. Dos endpoints lo cubren:

GET  /api/public/analytics    # reproducciones, oyentes y datos de rendimiento
GET  /api/public/statements   # informes de regalías e ingresos

Las analíticas son para los paneles y las decisiones: reproducciones, datos de oyentes y cómo está rindiendo un lanzamiento en las distintas plataformas. Los informes son para la contabilidad: lo que un periodo realmente ganó, listo para conciliar frente a los repartos y pagos que debe a los artistas. Recupere ambos de forma programada, guárdelos en su propia base de datos vinculados a su catálogo, y concilie en lugar de confiar en una sola consulta. Los datos de reporte se asientan con el tiempo a medida que las plataformas informan con retraso, así que trate cada consulta como la imagen más reciente, no como una definitiva, y deje que una consulta posterior corrija una estimación anterior.

Espere que estas respuestas estén paginadas, y recórralas hasta el final en lugar de leer la primera página y detenerse. Para la actualidad de los datos, decida entre polling y webhooks según lo que necesite. Una tarea de conciliación nocturna funciona bien con polling. Si necesita reaccionar en el momento en que una entrega se publica o llega un informe, y los webhooks están disponibles, suscríbase al evento en lugar de consultar cada minuto. Los parámetros de consulta exactos, los rangos de fechas y las formas de respuesta de ambos endpoints están en la referencia de la API para que pueda recuperar exactamente la ventana que necesita.

¿Cómo debería probar en un sandbox antes de producción?

Nunca construya una integración de distribución directamente contra producción. LabelGrid ofrece un entorno sandbox junto con la documentación pública precisamente para que pueda ejecutar todo el ciclo de creación, validación y distribución sin enviar nada a una plataforma real. Conecte sus pruebas de integración al sandbox desde el primer día, usando una credencial separada, para que una ejecución de prueba nunca pueda entregar por accidente un lanzamiento a medio terminar a Spotify.

Pruebe con datos adversos, no solo con un camino feliz limpio. Alimente el sandbox con lanzamientos con ISRC ausentes, portadas de tamaño insuficiente, nombres de artista vacíos y fechas incorrectas, y confirme que su lógica de validación y reintento hace lo correcto con cada uno. Un lanzamiento limpio demuestra que el proceso conecta; los que fallan demuestran que su gestión de errores realmente funciona, y en la gestión de errores es donde viven los catálogos reales. Haga que el ciclo del sandbox forme parte de su batería de pruebas, para que cada cambio en su cliente se ejercite de principio a fin antes de publicarse.

¿Qué debería construir primero?

Construya un esqueleto funcional antes de construir nada amplio. El objetivo del primer hito es que un lanzamiento pase por todo el ciclo en el sandbox, de principio a fin, para haber probado toda la ruta antes de optimizar cualquier parte de ella. En orden:

• Autentíquese y consiga que GET /api/public/me devuelva una respuesta limpia.
• Cree un lanzamiento con metadatos de forma realista mediante POST /api/public/releases.
• Valídelo, lea los fallos, corrija los datos y vuelva a validar hasta que pase.
• Distribúyalo en el sandbox y consulte periódicamente el lanzamiento hasta que la entrega informe que se ha completado.
• Lea de vuelta las analíticas y un informe, y guárdelos junto a su catálogo.

Una vez que ese esqueleto esté en verde, amplíelo de forma deliberada: ingesta masiva de catálogo con idempotencia, un retroceso y un enrutamiento de errores adecuados, sincronizaciones programadas de analíticas e informes, y webhooks si necesita menor latencia. Resista la tentación de construir todo el importador de catálogo antes de que un solo lanzamiento haya estado en vivo en el sandbox. Las integraciones que se lanzan a tiempo son las que primero llevan un lanzamiento hasta el final por completo y después escalan el patrón que ya funciona.

Dos cosas deciden lo fluido que será el resto de la construcción. Acertar con el modelo de metadatos, para que los lanzamientos pasen la validación a la primera, y tratar la entrega y el reporte como asíncronos desde el principio, para que nada en su código asuma una respuesta instantánea. Acierte con esas dos cosas y una integración de API de distribución es un problema de ingeniería bien entendido. Si está evaluando plataformas, el resumen para desarrolladores y la documentación de white-label y API cubren lo que expone la superficie, y la referencia de endpoints es pública en api.labelgrid.com/docs/api.

Preguntas frecuentes