음원 유통 API 연동 방법

음원 유통 API를 연동한다는 것은 카탈로그를 입력하고 메타데이터를 검증하며 릴리스를 스트리밍 스토어로 전송한 뒤, 로열티와 애널리틱스 데이터를 다시 불러오는 파이프라인에 자신의 시스템을 연결하는 작업을 뜻합니다. 웹 양식 대신 HTTP 호출로 레이블, 릴리스, 트랙을 생성하고, 각 릴리스를 검증한 뒤 DSP로 전송을 요청하며, 이후 스트리밍 수치와 정산서를 가져와 자체 기록과 대조합니다. 호출 자체는 쉬운 부분입니다. 진짜 어려운 작업은 음원 메타데이터를 정확하게 모델링하고, 비동기 단계를 처리하며, 전송이 거부되어 돌아오는 날을 대비해 미리 구조를 만들어두는 것입니다.

이 가이드는 실제로 구축하는 순서 그대로 연동 과정을 살펴봅니다. 인증, 릴리스 생성과 전송, 검증 및 오류 처리, 그리고 정산 데이터와 수치를 다시 불러오는 순서입니다. 아래 제시하는 엔드포인트 예시는 LabelGrid의 공개 API를 기준으로 하지만, 그 구조는 대부분의 유통 플랫폼에도 적용됩니다. 정확한 필드, 파라미터, 오류 코드는 공개 API 문서에 있으므로, 이 글은 필드 하나하나를 다루는 레퍼런스가 아니라 전체 지도 역할을 합니다.

음원 유통 API는 실제로 무엇을 하나요?

유통 API는 릴리스 생명주기를 엔드포인트 형태로 노출합니다. 단계는 총 네 가지이며, 모든 연동은 같은 순서로 이 단계를 거칩니다. 첫 번째는 카탈로그 입력입니다. 카탈로그를 구성하는 레이블, 릴리스, 트랙을 생성하고 메타데이터와 오디오를 첨부합니다. 두 번째는 검증입니다. 릴리스를 어디로도 보내기 전에 스토어 규정에 맞는지 확인합니다. 세 번째는 전송입니다. 검증을 통과한 릴리스를 스트리밍 서비스와 스토어로 유통합니다. 네 번째는 데이터 조회입니다. 음원이 공개된 이후 어떤 일이 일어났는지 시스템이 파악할 수 있도록 애널리틱스와 로열티 정산서를 가져옵니다.

전송 뒤편에는 스토어가 릴리스를 처리할 수 있도록 릴리스와 오디오를 기술하는 업계 표준인 DDEX가 자리하고 있습니다. DDEX를 직접 다룰 일은 거의 없습니다. API를 통해 만든 릴리스를 바탕으로 플랫폼이 DDEX를 생성하고, 각 DSP에 맞게 전달해줍니다. 스토어를 하나씩 개별 연동하는 대신 유통 API를 사용하는 이유가 바로 여기에 있습니다. 릴리스 모델 하나를 입력하면 모든 주요 DSP에 DDEX 규격을 준수한 전송이 이루어집니다. LabelGrid의 유통 API는 입력부터 정산서까지 네 단계 전체를 하나의 인증된 인터페이스로 다룹니다.

자주 사용하게 될 엔드포인트는 이 단계들과 깔끔하게 대응됩니다.

GET   /api/public/me                        # 토큰을 확인하고 자신의 계정 정보를 조회합니다
GET   /api/public/releases                  # 카탈로그 목록을 조회합니다
POST  /api/public/releases                  # 릴리스를 생성합니다 (입력)
POST  /api/public/releases/{id}/validate    # 릴리스를 스토어 규정에 따라 검증합니다
POST  /api/public/releases/{id}/distribute  # DSP로 전송합니다
GET   /api/public/analytics                 # 스트리밍 및 청취자 데이터를 조회합니다
GET   /api/public/statements                # 로열티 정산서를 조회합니다

이 목록을 전체 연동의 뼈대로 생각하면 됩니다. 나머지는 모두 이 일곱 개 호출에 딸린 메타데이터, 재시도, 정합성 처리일 뿐입니다.

인증은 어떻게 하나요?

인증은 모든 요청에 Bearer 토큰을 포함하는 방식으로 이루어집니다. 가입 후 API 자격 증명을 발급받아 Authorization 헤더에 담아 보내면 됩니다. 데모 통화를 예약할 필요도, 먼저 영업 절차를 거칠 필요도 없습니다. 가입은 셀프서비스로 진행되고 문서는 누구나 볼 수 있게 공개되어 있어, API 플랜이 활성화되면 그날 오후부터 바로 인증된 호출을 보낼 수 있습니다. 토큰은 계정 설정에서 발급하며, 원한다면 특정 IP로 토큰 사용을 제한할 수도 있습니다. 가장 먼저 호출해볼 것은 GET /api/public/me로, 토큰이 유효한지와 어느 계정에 속해 있는지를 알려줍니다.

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

다른 무엇을 만들기 전에 이 호출이 깨끗하게 응답하는지부터 확인하세요. me 호출이 정상적으로 동작한다는 것은 자격 증명, 기본 URL, HTTP 클라이언트가 모두 올바르다는 뜻이므로, 이후 발생하는 오류는 연결 문제가 아니라 릴리스 자체의 문제라고 판단할 수 있습니다. 토큰은 비밀 정보로 저장하고 소스 코드나 클라이언트 번들에는 절대 넣지 마세요. 비밀번호처럼 다뤄서 유출되면 즉시 재발급하고, 샌드박스와 프로덕션의 자격 증명을 분리해 테스트 실행이 실제 카탈로그에 영향을 주지 않도록 하세요. 정확한 토큰 유형, 만료 동작, 추가 헤더는 API 레퍼런스에 문서화되어 있으니 추측하지 말고 한 번 읽어본 뒤 작은 클라이언트로 감싸서 사용하세요.

릴리스는 어떻게 생성하고 전송하나요?

세 번의 호출만으로 릴리스를 처음부터 실제 공개 상태까지 끌고 갈 수 있습니다. 생성하고, 검증하고, 전송하면 됩니다.

POST  /api/public/releases                  # 1. 릴리스와 메타데이터를 생성합니다
POST  /api/public/releases/{id}/validate    # 2. 스토어 규정에 따라 검증합니다
POST  /api/public/releases/{id}/distribute  # 3. DSP로 전송합니다

생성 단계에 가장 많은 엔지니어링 노력이 들어갑니다. 릴리스에는 제목, 아티스트와 참여자, 발매일, 레이블, 아트워크, 그리고 각자의 제목과 크레딧, 오디오를 가진 트랙까지 많은 메타데이터가 담깁니다. 정확한 필드, 형식, 필수 항목 여부는 모두 문서에 정리되어 있으므로, 대략 맞추기보다는 정확하게 그대로 모델링해야 합니다. 잘못된 메타데이터는 릴리스가 나중에 실패하는 가장 흔한 원인이므로, 전송하기 전에 자체적으로 입력값을 검증하세요. 아트워크 크기를 확인하고, 모든 트랙에 오디오와 ISRC가 있는지 확인하며, 아티스트 이름을 자체적으로 정규화하세요. 코드 안에서 문제를 잡아내는 편이 스토어 거부로 문제를 발견하는 것보다 훨씬 저렴합니다.

생성 요청은 멱등성을 갖도록 만드세요. 네트워크 호출은 중간에 실패하기도 하는데, 재시도로 인해 같은 릴리스의 사본이 또 만들어지는 상황은 피해야 합니다. 멱등성 키를 사용하거나, 새 릴리스를 생성하기 전에 자체 참조값으로 기존 릴리스가 있는지 확인해서 같은 요청이 반복되더라도 중복 생성이 아니라 동일한 릴리스가 반환되도록 하세요. 이는 대량 카탈로그 임포트에서 특히 중요합니다. 수천 건의 릴리스를 처리하는 동안 불안정한 연결이라면 어딘가에서 반드시 재시도가 발생하기 때문입니다.

전송은 비동기로 처리됩니다. distribute를 호출하면 즉시 결과를 받는 것이 아니라 작업이 큐에 등록됩니다. API는 요청을 받아들이고, 그 뒤에 플랫폼이 백그라운드에서 DDEX를 패키징해 각 스토어로 보내는데, 이 과정은 시간이 걸릴 수 있습니다. 처음부터 이를 고려해 설계하세요. 전송 호출을 보내고, 요청했다는 사실을 기록한 뒤, 응답을 기다리며 블로킹하는 대신 릴리스의 전송 상태를 폴링하세요. 전송이 동기적으로 완료된다고 가정하는 코드는 실제 전송이 1초 이상 걸리는 순간 곧바로 문제를 일으킵니다.

검증과 오류는 어떻게 처리하나요?

검증이 별도 단계로 분리되어 있는 데는 이유가 있습니다. POST /api/public/releases/{id}/validate를 호출하면 릴리스가 스토어 요구사항을 충족하는지 확인하고, 전송을 확정하기 전에 무엇이 잘못되었는지 알려줍니다. 전송하기 전에는 반드시 검증하세요. 검증에 실패한 릴리스를 그대로 전송하면 전송 주기를 낭비할 뿐 아니라, 사전에 고쳤을 검증 오류보다 훨씬 되돌리기 번거로운 스토어 거부로 이어질 수 있습니다. 생성, 검증, 수정, 재검증의 흐름을 만들고, 검증이 완전히 통과한 뒤에만 전송하세요.

오류 처리는 종류별로 나누어 대응하세요. 두 종류는 정반대의 대응이 필요합니다. 4xx는 여러분 쪽의 문제입니다. 잘못된 필드, 누락된 ISRC, 너무 작은 아트워크 같은 경우입니다. 수정 없이 그대로 재시도하면 다시 실패할 뿐이므로, 문제를 드러내고 데이터를 고친 뒤 다시 제출하세요. 5xx나 네트워크 타임아웃은 일시적인 문제입니다. 재시도하되, API를 몰아치듯 반복 호출하지 말고 지수 백오프와 상한을 두고 재시도하세요. 여기에 생성 단계의 멱등성 키를 함께 사용하면 타임아웃 이후 재시도가 실수로 작업을 중복시키는 일을 막을 수 있습니다. 실제 오류 코드와 그 의미는 추측하지 말고 문서에서 확인하고, 각각을 재시도, 수정 후 재제출, 담당자 에스컬레이션 중 명확한 대응으로 매핑해두세요.

모든 요청과 응답을 상관관계 ID와 함께 로그로 남기세요. 3주 뒤 어떤 릴리스가 멈춰 있을 때, 무엇을 보냈고 무엇이 돌아왔는지에 대한 로그가 있느냐 없느냐가 5분 만에 해결하는 것과 오후 내내 추측만 하는 것의 차이를 만듭니다.

로열티와 애널리틱스 데이터는 어떻게 다시 불러오나요?

유통은 전체 흐름의 절반일 뿐입니다. 음원이 공개된 뒤에는 성과와 수익 데이터를 다시 가져와야 시스템이 실제 상황을 반영합니다. 이를 담당하는 엔드포인트는 두 가지입니다.

GET  /api/public/analytics    # 스트리밍, 청취자, 성과 데이터
GET  /api/public/statements   # 로열티 정산서 및 수익 데이터

애널리틱스는 대시보드와 의사결정을 위한 데이터입니다. 스트리밍 수치, 청취자 데이터, 스토어별 릴리스 성과를 보여줍니다. 정산서는 회계를 위한 데이터로, 특정 기간에 실제로 발생한 수익을 아티스트에게 지급할 분배금 및 정산액과 대조할 수 있게 해줍니다. 두 데이터 모두 일정한 주기로 가져와 카탈로그 기준으로 자체 데이터베이스에 저장하고, 한 번의 조회 결과만 믿지 말고 지속적으로 대조하세요. 스토어가 뒤늦게 보고하는 경우가 있어 리포팅 데이터는 시간이 지나며 정리되므로, 매번의 조회 결과를 최종 값이 아니라 현재까지의 최신 상태로 취급하고, 이후 조회가 이전 추정치를 보정하도록 하세요.

이 응답들은 페이지네이션되어 있다고 가정하고, 첫 페이지만 읽고 멈추지 말고 끝까지 페이지를 넘기며 가져오세요. 최신성이 필요한 경우에는 상황에 맞게 폴링과 webhook 중 하나를 선택하면 됩니다. 야간 정합성 작업이라면 폴링으로 충분합니다. 전송이 완료되거나 정산서가 도착하는 순간 즉시 대응해야 한다면, webhook이 제공되는 경우 매분 폴링하는 대신 이벤트를 구독하세요. 두 엔드포인트의 정확한 쿼리 파라미터, 날짜 범위, 응답 형식은 API 레퍼런스에 있으므로 필요한 기간을 정확히 가져올 수 있습니다.

프로덕션 전에 샌드박스에서는 어떻게 테스트해야 하나요?

유통 연동을 처음부터 프로덕션 환경에서 직접 구축하지 마세요. LabelGrid는 공개 문서와 함께 샌드박스 환경을 제공하는데, 이는 실제 스토어로 아무것도 보내지 않고도 생성, 검증, 전송 전체 생명주기를 그대로 실행해볼 수 있게 하기 위한 것입니다. 처음부터 별도의 자격 증명을 사용해 통합 테스트를 샌드박스에 연결해두면, 테스트 실행이 실수로 미완성 릴리스를 Spotify에 전송하는 일을 막을 수 있습니다.

정상적인 경로만이 아니라 까다로운 데이터로도 테스트하세요. 샌드박스에 ISRC가 누락되거나, 아트워크가 너무 작거나, 아티스트 이름이 비어 있거나, 날짜가 잘못된 릴리스를 넣어보고, 각 경우에 검증 및 재시도 로직이 올바르게 동작하는지 확인하세요. 정상적인 릴리스는 파이프라인이 제대로 연결되어 있음을 증명하고, 문제가 있는 릴리스는 오류 처리가 실제로 동작함을 증명합니다. 그리고 실제 카탈로그를 운영하다 보면 결국 이 오류 처리 능력이 관건이 됩니다. 클라이언트에 변경이 생길 때마다 배포 전에 전 과정을 처음부터 끝까지 검증할 수 있도록, 샌드박스 생명주기를 테스트 스위트에 포함시키세요.

가장 먼저 무엇을 구축해야 하나요?

무언가를 폭넓게 만들기 전에 먼저 워킹 스켈레톤(최소 동작 골격)을 구축하세요. 첫 번째 마일스톤의 목표는 릴리스 한 건이 샌드박스에서 전체 흐름을 처음부터 끝까지 통과하는 것입니다. 그렇게 해야 어느 한 부분을 최적화하기 전에 전체 경로가 제대로 동작함을 증명할 수 있습니다. 순서는 다음과 같습니다.

• 인증을 수행하고 GET /api/public/me가 깨끗하게 응답하는지 확인하세요.
• POST /api/public/releases를 통해 실제와 유사한 메타데이터로 릴리스 하나를 생성하세요.
• 검증하고, 실패 내용을 확인하고, 데이터를 수정한 뒤 통과할 때까지 다시 검증하세요.
• 샌드박스에서 전송하고, 전송 상태가 완료로 표시될 때까지 릴리스를 폴링하세요.
• 애널리틱스와 정산서를 다시 불러와 카탈로그와 연결해 저장하세요.

이 골격이 정상적으로 동작하면, 그때부터 신중하게 범위를 넓혀가세요. 멱등성을 갖춘 대량 카탈로그 입력, 제대로 된 백오프와 오류 라우팅, 예약된 애널리틱스 및 정산서 동기화, 그리고 더 낮은 지연이 필요하다면 webhook까지 순서대로 확장하면 됩니다. 샌드박스에서 릴리스 한 건도 제대로 공개해보기 전에 전체 카탈로그 임포터부터 만들고 싶은 충동은 참으세요. 제때 출시되는 연동은 릴리스 한 건을 끝까지 통과시킨 뒤, 이미 검증된 패턴을 확장해나간 연동입니다.

이후 개발이 얼마나 순조로운지는 두 가지에 달려 있습니다. 첫 번째로 검증을 처음부터 통과할 수 있도록 메타데이터 모델을 정확히 잡는 것, 두 번째로 코드 어디에서도 즉각적인 응답을 가정하지 않도록 전송과 리포팅을 처음부터 비동기로 다루는 것입니다. 이 두 가지만 제대로 해두면 유통 API 연동은 충분히 익숙하게 다룰 수 있는 엔지니어링 과제가 됩니다. 플랫폼을 검토 중이라면 개발자 개요와 화이트라벨 및 API 문서에서 API가 제공하는 범위를 확인할 수 있고, 엔드포인트 레퍼런스는 api.labelgrid.com/docs/api에 공개되어 있습니다.

자주 묻는 질문