9LINK 주요문서

매체 API 연동문서

리워드 지급형 매체가 클릭 시 media_ref를 9LINK에 전달하고, 전환 결과를 매체 콜백 URL로 받기 위한 연동 기준입니다.

발급값 정리

항목	의미	사용 위치	예시
tracking_code	추적 코드	매체가 광고물을 가져갈 때 생성되는 클릭 URL 코드	trk_ninez_cp1_kurly_xxxxx
media_ref	매체 유저/리워드 식별값	매체가 클릭 URL에 붙여 보내는 값. 리워드 지급 매칭 기준입니다.	user1004_reward001
media_key	매체키	매체 서버 인증용 비밀값. 클릭 URL에는 넣지 않습니다.	8g75eHFyYL...
callback_url	매체 콜백 URL	승인, 거절, 취소 결과를 받을 매체 서버 URL	https://media.example.com/reward

광고주에게 전달되는 값은 9LINK가 생성한 click_id입니다. 매체가 보낸 media_ref는 광고주에게 직접 전달하지 않고 9LINK 내부에서 click_id와 매칭합니다.

클릭 URL

매체는 9LINK에서 발급받은 추적 URL로 사용자를 이동시킵니다. 신규 리워드 연동은 media_ref 하나만 전달하는 방식을 권장합니다.

https://9link.co.kr/api/t/{tracking_code}?media_ref={media_ref}&sub1={optional}

실제 예시

https://9link.co.kr/api/t/trk_ninez_cp1_kurly_a1b2c?media_ref=user1004_reward001&sub1=slot_main

media_ref 값은 매체가 중복 지급을 구분할 수 있는 고유값으로 보내 주세요.

매체 콜백 수신 예시

전환이 승인, 거절, 취소되면 9LINK가 매체 콜백 URL로 결과를 전송합니다. 매체는 media_ref로 자사 유저 또는 리워드 건을 매칭하면 됩니다.

POST {callback_url}
Content-Type: application/json
X-9LINK-Signature: {hmac_sha256}

{
  "click_id": "clk_...",
  "conversion_id": "conv_...",
  "advertiser_conversion_id": "order_12345",
  "media_ref": "user1004_reward001",
  "reward_status": "approved",
  "reject_reason": null,
  "payout_amount": 700,
  "converted_at": "2026-07-08T12:00:00.000Z"
}

보안 권장사항

매체키는 클릭 URL에 넣지 말고 매체 서버 환경변수로 보관합니다.
클릭 URL에 필요한 필수값은 tracking_code와 media_ref입니다.
콜백 수신 시 HMAC 서명을 검증합니다.
동일 media_ref는 한 번만 리워드 지급 처리하는 것을 권장합니다.
콜백 실패에 대비해 중복 수신을 허용하되 멱등 처리합니다.