실제 행동을 안전하게 연결합니다.

1. 추천 토큰 보관

추천링크가 설정된 광고주 주소로 이동하며 ref 쿼리를 전달합니다. 토큰은 base64url(JSON) + 점 + hex HMAC-SHA256입니다. 캠페인 서명키로 서명을 확인하고 campaign_id·version·clicked_at을 확인하세요. 토큰을 HttpOnly·Secure·SameSite=Lax 쿠키로 보관합니다. 신규 가입 전에만 마지막 클릭을 갱신하고 가입 시 한 번 고정합니다.

2. DB 저장과 전송 대기를 함께 기록

가입 인증과 핵심 행동을 서버에서 확인합니다. 활동 DB 저장과 전환 outbox 생성을 같은 트랜잭션으로 처리하세요. 고객 이름·이메일·게시글 본문은 보내지 마세요. 광고주 범위의 가명 참조를 사용합니다.

3. 서명한 서버 요청 전송

POST https://sairo.pages.dev/api/service/postback
Content-Type: application/json
x-sairo-timestamp: 밀리초 Unix 시각
x-sairo-signature: HMAC_SHA256(secret, timestamp + "." + rawBody)

{
  "campaign_id": "운영자가 발급한 캠페인 ID",
  "conversion_id": "이벤트의 고유 ID",
  "click_id": "추천 토큰의 click_id",
  "user_ref": "광고주 범위 가명 사용자 참조 (16~128자)",
  "event_type": "캠페인에서 정한 이벤트명",
  "registered_at": "ISO 8601 신규 가입 시각",
  "occurred_at": "ISO 8601 목표 행동 시각",
  "verified": true,
  "profile_complete": true,
  "evidence_ref": "광고주 DB 이벤트 참조"
}

사용자 참조에는 영문·숫자·하이픈·밑줄·콜론만 사용할 수 있습니다. 전환 ID는 점도 허용하며 최대 120자입니다. 서명키를 브라우저에 노출하지 마세요. 금액·승인 상태·홍보자 ID는 보낼 수 없습니다.

4. 응답과 재시도

신규 접수 201, 동일 이벤트 재시도 200, 서명 실패 401, 내용 충돌·중복 사용자·예산 부족 409, 유효하지 않은 클릭·시각·행동 422입니다. 응답의 code로 실패 원인을 구분합니다. 5xx·네트워크 오류는 같은 ID와 본문을 유지하여 재시도하고 요청 서명 시각만 갱신합니다. 영구 오류는 별도 검토 대기로 두고 뒤의 이벤트 전송을 막지 않도록 합니다.

5. 실제 캠페인 시작

운영자가 신규 계정의 전체 여정과 광고주 원본 기록을 확인한 뒤 연동 확인을 기록합니다. 선입금 확인과 함께 캠페인을 활성화하면 홍보자가 참여할 수 있습니다. 테스트 이벤트를 실제 수익으로 승인하지 마세요.