포스트백은 반드시 서버사이드에서 호출해야 합니다. API 키를 브라우저 JS에 넣으면 가짜 전환이 반복 주입될 수 있습니다. 클라이언트는 so_cid만 캡처하고, 전환 API 호출은 서버에서만 수행합니다.

엔드포인트

인증

Authorization: Bearer {API_KEY} 헤더만 사용합니다. 본문에 api_key를 넣지 마세요.

요청

POST /api/v1/conversions
Content-Type: application/json
Authorization: Bearer sk_...

{
  "click_id": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "event": "purchase",
  "value_krw": 29000,
  "test": false
}

필드 설명

필드	타입	필수	설명
click_id	string (UUID)	필수	Trafix가 발급한 클릭 ID. 서버 발급 nonce 역할을 합니다.
event	string (1–64자)	필수	이벤트 이름 (예: purchase, signup, trial)
value_krw	integer	선택	전환 가치 — 정수 KRW만 허용합니다.
test	boolean	선택	테스트 전환. 기록은 되지만 리포트 집계에서 제외됩니다.

value·currency 필드는 존재하지 않습니다. 금액은 반드시 value_krw로 전송하세요.

응답

성공 (200 OK) — 신규 기록

{
  "status": "recorded",
  "conversion_id": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "matched": true,
  "attribution": "confirmed"
}

성공 (200 OK) — 중복(멱등)

{
  "status": "duplicate",
  "matched": true,
  "attribution": "confirmed"
}

응답 필드 설명

필드	설명
status	"recorded" (신규) 또는 "duplicate" (이미 기록된 click_id + event)
conversion_id	신규 기록 시 전환 UUID. 중복 응답에서는 생략됩니다.
matched	click_id가 유효하고 30일 윈도우 이내이면 true
attribution	"confirmed" / "out_of_window" / "귀속불가"

귀속불가는 동일 크리에이터가 여러 캠페인에 동시에 참여해 클릭 출처를 특정할 수 없을 때 반환됩니다.

에러 코드

에러 코드	HTTP	설명
UNAUTHORIZED	401	Authorization: Bearer 헤더 누락, 형식 오류, api_key 불일치
VALIDATION_FAILED	422	요청 본문 zod 검증 실패 — issues 배열 포함
NONCE_INVALID	422	click_id가 서버 발급 기록에 없음. 봇 전환 방어용입니다.
RATE_LIMITED	429	브랜드 api_key 기준 분당 허용량 초과

멱등성

동일 (click_id, event) 조합은 재전송해도 안전합니다. 서버는 중복 요청을 중복 성공으로 처리해야 하며, 재시도 로직에서는 지수 백오프를 사용하세요.

so_cid 캡처는 클라이언트, 호출은 서버

function captureSoCid() {
  const url = new URL(window.location.href)
  const cid = url.searchParams.get("so_cid")
  if (cid) {
    document.cookie = `so_cid=${cid};max-age=${30 * 24 * 3600};path=/;SameSite=Lax`
  }
}

클라이언트는 쿠키만 저장하고, 전환 시점의 POST는 서버가 수행합니다. 자세한 쿠키 생존 시간 차이는 쿠키 정직성 가이드를 확인하세요.

운영 주의

프로덕션 전환 API는 durable rate limit 구성이 없으면 fail closed로 동작해야 합니다. 보호 계층이 없거나 백엔드가 비정상이면 공개 전환 트래픽을 받지 않도록 설정하세요.