9LINK 주요문서

리포트 API 문서

광고주마다 원본 데이터와 연동 방식은 다르지만, 매체에는 아래의 공통 지표와 동일한 의미로 제공합니다. API Key의 조회 범위는 발급 시 지정된 광고주, 매체 또는 매체대행사로 제한됩니다.

인증

X-9LINK-API-KEY: {issued_api_key}

API Key가 없거나 올바르지 않으면 401, 허용 범위를 벗어난 조건으로 조회하면 403 응답을 반환합니다.

curl --request GET \
  "https://api.9link.co.kr/external/reports/conversions?from=2026-07-01&to=2026-07-20&limit=100" \
  --header "X-9LINK-API-KEY: {issued_api_key}"

브라우저 주소창에서는 인증 헤더를 보낼 수 없어 401이 정상입니다. 매체 서버, Postman 또는 curl에서 발급받은 API Key를 헤더로 전달해 주세요.

공통 집계 필드

필드설명예시
from조회 시작 일시2026-07-01T00:00:00.000Z
to조회 종료 일시2026-07-20T23:59:59.999Z
totals.impressions광고 노출 수1250
totals.clicks광고 클릭 및 유입 수320
totals.conversions전환 이벤트 행 수(구매·취소 포함)18
totals.transactionAmount발생 거래액450000
totals.canceledTransactionAmount취소 거래액(음수)-30000

구매·취소 데이터를 제공하는 광고주는 구매일에 양수, 실제 취소일에 음수로 반영됩니다. transactionAmount는 조회 기간의 구매와 취소를 합산한 거래액이며, canceledTransactionAmount는 취소 거래액을 음수로 표시합니다. 광고주 과금액과 플랫폼 마진은 외부 리포트 API에서 제공하지 않습니다. 매체 지급액은 총관리자가 해당 광고주·매체 조합의 매체지급액 송출을 선택한 경우에만 상세 행의 payout_amount로 제공합니다.

한 주문에 여러 상품이 있으면 상품별 행이 각각 반영됩니다. 일부 상품만 취소되면 구매일의 approved 행과 실제 취소일의 canceled 행이 각각 반환됩니다. 취소 행의 transactionAmount는 음수이며, 같은 주문의 orderStatus는 partially_canceled로 반환되며 나머지 상품은 approved 상태를 유지합니다. 동일한 주문·상품(content_no)이 다시 수신되면 새 행을 만들지 않고 가장 최근 수신 금액과 상태로 갱신하며, 원본 수신 이력은 모두 보존됩니다.

동일 상품이 구매 후 취소되면 구매 행과 취소 행의 conversionId는 동일할 수 있습니다. conversionId만으로 중복을 제거하지 말고 conversionId, status, convertedAt을 함께 사용해 이벤트를 구분해야 합니다. 상품 리포트에서는 content_no도 함께 확인해 주세요.

공통 조회 조건

파라미터설명예시
from조회 시작일2026-07-01
to조회 종료일2026-07-20
advertiserCode광고주 코드kurly
partnerCode매체 코드ninez_cp1
agencyCode매체대행사 코드ninez_agency
campaignCode캠페인 코드cmp_kurly_001
status전환 상태approved, canceled
limit상세 조회 개수100
offset상세 조회 시작 위치0

일별 합산 리포트

GET https://api.9link.co.kr/external/reports/summary?from=2026-07-01&to=2026-07-20&partnerCode=ninez_cp1

전환 상세

GET https://api.9link.co.kr/external/reports/conversions?from=2026-07-01&to=2026-07-20&limit=100

주요 응답값은 conversionId, advertiserConversionId, clickId, advertiserCode, campaignCode, partnerCode, status, orderStatus, transactionAmount, canceledTransactionAmount, mediaRef, sub1, convertedAt, clickAt입니다. 매체지급액 송출이 설정된 조합에는 payout_amount가 추가되며 승인 건은 양수, 취소 건은 음수입니다. 리워드 대상 매칭은 mediaRef를 기준으로 하며, clickId와 sub1~sub5로 매체 내부 값과 상호 대조할 수 있습니다.

구분statustransactionAmountconvertedAt식별 기준
구매approved양수실제 구매일시conversionId + status + convertedAt
취소canceled음수실제 취소일시conversionId + status + convertedAt
  • status=approved 조회는 구매 행, status=canceled 조회는 취소 행을 반환합니다.
  • externalStatus는 광고주 원본 상태이며, 값과 제공 여부는 광고주별 연동 규격에 따라 다를 수 있습니다. 공통 처리 기준은 status를 사용해 주세요.
  • 조회 기간에 구매와 취소가 모두 포함되면 transactionAmount 합계는 순거래액이며, totals.conversions에는 두 이벤트가 각각 집계됩니다.

클릭 및 노출 상세

GET https://api.9link.co.kr/external/reports/clicks?from=2026-07-01&to=2026-07-20GET https://api.9link.co.kr/external/reports/impressions?from=2026-07-01&to=2026-07-20

응답 코드

HTTP 상태의미확인 사항
200정상 조회rows 또는 totals 확인
400조회 조건 오류날짜 형식, from/to, limit 확인
401인증 실패X-9LINK-API-KEY 누락 또는 키 값 확인
403조회 범위 초과발급 키의 광고주·매체·대행사 범위 확인
404경로 오류https://api.9link.co.kr/external/reports/... 경로 확인
500서버 처리 오류응답 시각과 요청 조건을 9LINK에 전달

API Key는 발급된 매체 또는 매체대행사 범위에 자동으로 제한됩니다. 다른 매체가 연동하더라도 같은 URL을 사용하며, 각 매체에는 별도의 API Key를 발급해야 합니다.