9LINK 주요문서
매체 API 연동문서
리워드 지급형 매체가 클릭 시 media_ref를 9LINK에 전달하고, 전환 결과를 매체 콜백 URL로 받기 위한 연동 기준입니다.
발급값 정리
| 항목 | 의미 | 사용 위치 | 예시 |
|---|---|---|---|
| tracking_code | 추적 코드 | 매체가 광고물을 가져갈 때 생성되는 클릭 URL 코드 | trk_ninez_cp1_kurly_xxxxx |
| media_ref | 매체 리워드 매칭값 | 매체가 클릭 URL에 붙여 보내는 고유값. 전환 후 같은 값이 콜백으로 반환됩니다. | u_7f3a9c_reward_001 |
| media_key | 매체키 | 매체 서버 인증용 비밀값. 클릭 URL에는 넣지 않습니다. | 8g75eHFyYL... |
| callback_url | 매체 콜백 URL | 승인, 거절, 취소 결과를 받을 매체 서버 URL | https://media.example.com/reward |
클릭 URL
매체는 9LINK에서 발급받은 추적 URL로 사용자를 이동시킵니다. 신규 리워드 연동은 media_ref 하나만 전달하는 방식을 권장합니다.
https://9link.co.kr/api/t/{tracking_code}?media_ref={media_ref}&sub1={optional}&sub2={optional}&sub3={optional}&sub4={optional}&sub5={optional}실제 예시
https://9link.co.kr/api/t/trk_ninez_cp1_kurly_a1b2c?media_ref=u_7f3a9c_reward_001&sub1=slot_main&sub2=main_banner| 파라미터 | 필수 여부 | 용도 | 예시 |
|---|---|---|---|
| media_ref | 필수 | 매체의 리워드 대상 또는 리워드 거래를 구분하는 고유값 | u_7f3a9c_reward_001 |
| sub1 | 선택 | 하위매체, 지면, 채널, 슬롯 등 보조 구분값 | slot_main |
| sub2~sub5 | 선택 | 추가 분석이 필요할 때 사용하는 보조 구분값 | channel_app |
media_ref는 사용자 또는 리워드 거래를 식별할 수 있는 매체 측 고유값입니다. 원본 회원번호, 전화번호, 이메일 등 개인정보는 넣지 말고 암호화하거나 난수화한 값을 사용해 주세요.
sub1은 하위매체나 지면을 구분하는 보조값입니다. 하위매체 코드만으로 리워드 대상 한 건을 구분할 수 없다면 media_ref 대신 사용할 수 없습니다.
매체가 받는 콜백 파라미터
전환의 리워드 판정이 완료되면 9LINK가 매체 콜백 URL로 결과를 전송합니다. 매체는 media_ref로 자사 유저 또는 리워드 건을 매칭하면 됩니다. 콜백 방식이 GET이면 아래 필드가 Query String으로, POST이면 JSON Body로 전달됩니다.
POST {callback_url}
Content-Type: application/json
X-9LINK-SIGNATURE: sha256={hmac_sha256}
X-9LINK-TIMESTAMP: 2026-07-08T12:00:01.000Z
{
"transaction_amount": 58500,
"canceled_transaction_amount": 0,
"partial_cancellation": false,
"callback_item_key": "item_8fd9c9ca197f4a4f84955b62fb98482a",
"partner_code": "ninez_cp1",
"media_ref": "u_7f3a9c_reward_001",
"sub1": "dotpitch_submedia_01",
"sub2": "main_banner",
"media_user_id": "u_7f3a9c_reward_001",
"reward_tx_id": "u_7f3a9c_reward_001",
"reward_status": "approved",
"reject_reason": null,
"payout_amount": 2282,
"converted_at": "2026-07-08T12:00:00.000Z"
}복수 상품 주문 및 부분취소 처리
- 같은 주문에 여러 상품이 있으면 상품별 승인 콜백이 각각 전송됩니다.
- 일부 상품만 취소되면 해당 상품 콜백만 reward_status가 canceled로 내려가며, canceled_transaction_amount에 그 상품의 취소 금액이 전달됩니다.
- 같은 주문에 승인 상품이 남아 있으면 partial_cancellation은 true입니다. transaction_amount는 원 발생액이므로 취소 금액으로 덮어쓰지 않습니다.
- 매체는 media_ref로 리워드 건을 찾은 뒤 취소 콜백의 canceled_transaction_amount만 차감하고, 같은 주문의 다른 승인 상품은 유지해야 합니다.
- callback_item_key는 상품 행마다 다르고 승인 후 취소되어도 같은 값입니다. 콜백 재시도 중복 방지와 정확한 상품 취소 매칭에 사용합니다.
payout_amount 계산 기준
- 총관리자에서 해당 광고주·매체 조합의 API 송출을 선택한 경우에만 전달됩니다.
- 승인: 거래액 × 매체 수수료율을 원 단위로 반올림한 양수입니다.
- 전체·부분취소: 취소된 상품 거래액 × 매체 수수료율을 원 단위로 반올림한 음수입니다.
- 거절: 0이며, 매체지급액 송출을 선택하지 않은 조합은 payout_amount 필드 자체가 생략됩니다.
부분취소 콜백 예시
{
"transaction_amount": 7900,
"canceled_transaction_amount": 7900,
"partial_cancellation": true,
"callback_item_key": "item_b24b10bfdd52477c9e897f3e256eb45a",
"partner_code": "ninez_cp1",
"media_ref": "u_7f3a9c_reward_001",
"sub1": "dotpitch_submedia_01",
"sub2": "main_banner",
"reward_status": "canceled",
"reject_reason": null,
"payout_amount": -308,
"converted_at": "2026-08-19T02:55:50.000Z"
}| 필드 | 설명 | 예시 |
|---|---|---|
| transaction_amount | 해당 상품의 발생 거래액. 취소 후에도 원 발생액 유지 | 58500 |
| canceled_transaction_amount | 해당 상품의 취소 거래액. 정상 승인 시 0 | 0 |
| partial_cancellation | 같은 주문에 승인 상태의 다른 상품이 남아 있는지 여부 | false |
| callback_item_key | 상품 콜백별 공개 식별값. 승인·취소 시 같은 값 유지 | item_8fd9... |
| partner_code | 전환이 귀속된 매체 코드 | ninez_cp1 |
| media_ref | 클릭 때 매체가 보낸 리워드 매칭값 | u_7f3a9c_reward_001 |
| sub1 | 클릭 때 매체가 보낸 첫 번째 보조 구분값 | dotpitch_submedia_01 |
| sub2 | 클릭 때 매체가 보낸 두 번째 보조 구분값 | main_banner |
| sub3 | 클릭 때 매체가 보낸 세 번째 보조 구분값 | channel_app |
| sub4 | 클릭 때 매체가 보낸 네 번째 보조 구분값 | null |
| sub5 | 클릭 때 매체가 보낸 다섯 번째 보조 구분값 | null |
| media_user_id | 호환용 매체 유저값. 신규 연동에서는 media_ref와 같을 수 있음 | u_7f3a9c_reward_001 |
| reward_tx_id | 호환용 리워드 거래값. 신규 연동에서는 media_ref와 같을 수 있음 | u_7f3a9c_reward_001 |
| reward_status | 리워드 판정 상태 | approved, rejected, canceled |
| reject_reason | 거절 사유. 승인 시 null | duplicate_user |
| payout_amount | 매체지급액 송출 설정 시 거래액 × 매체별 수수료율로 계산한 지급 예정액. 취소는 음수 | 2282 |
| converted_at | 전환 발생 시각(ISO 8601) | 2026-07-08T12:00:00.000Z |
신규 연동에서는 media_ref를 기준값으로 사용해 주세요. media_user_id와 reward_tx_id는 기존 연동 호환을 위한 필드이며, media_ref 하나만 받은 클릭에서는 세 필드가 같은 값으로 내려갈 수 있습니다. sub1~sub5는 클릭 때 전달된 값만 각각 동일하게 반환하며, 전달하지 않은 항목은 콜백에서 생략됩니다.
보안 권장사항
- 매체키는 클릭 URL에 넣지 말고 매체 서버 환경변수로 보관합니다.
- 클릭 URL에 필요한 필수값은 tracking_code와 media_ref입니다.
- 콜백 수신 시 callback secret으로
HMAC-SHA256(timestamp + "." + raw JSON body)를 계산해 X-9LINK-SIGNATURE을 검증합니다. - X-9LINK-TIMESTAMP가 허용 시간을 벗어난 요청은 거절합니다.
- 동일 media_ref는 한 번만 리워드 지급 처리하는 것을 권장합니다.
- 콜백 실패에 대비해 중복 수신을 허용하되 멱등 처리합니다.