전환 추적 API 레퍼런스

Edgelink 전환 추적 HTTP API의 엔드포인트, 페이로드, 에러 코드 전체 명세

@edgelinkapp/sdk-web/@edgelinkapp/sdk-node 없이 직접 HTTP 호출이 필요할 때 사용하는 API 명세입니다.

Base URL

https://api.edgelink.me

인증

Authorization: Bearer <키>

키 종류	형식	용도
publishable	`pk_live_` / `pk_test_`	브라우저, `lead`·커스텀 전용
secret	`sk_live_` / `sk_test_`	서버, `sale` 포함 전체 이벤트

publishable 키는 평문 그대로 노출돼도 무방하지만, secret 키는 절대 클라이언트에 노출하지 마세요.

POST /api/v1/track

전환 이벤트를 1건 기록합니다.

Request Headers

헤더	값	비고
`Authorization`	`Bearer <키>`	필수
`Content-Type`	`application/json`	필수
`Origin`	브라우저 호출 시 자동	publishable 키는 Origin 화이트리스트 검사

Request Body

{
  "clickId": "abc123",
  "externalUserId": "user-1234",
  "eventType": "sale",
  "eventName": "purchase",
  "externalEventId": "order-2026-05-30-001",
  "valueMinor": 49900,
  "currency": "KRW",
  "customerEmailHash": "b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475857",
  "metadata": {
    "plan": "pro"
  }
}

필드	타입	필수	설명
`clickId`	string	clickId XOR userId	단축 링크 클릭 시 발급된 ID. 쿠키 `_el_cid`에서 추출
`externalUserId`	string	clickId XOR userId	고객사 user ID. clickId 없을 때 사용
`eventType`	`'lead' \| 'sale' \| 'custom'`	필수	이벤트 분류
`eventName`	string	필수	자유 식별자. 예: `signup`, `purchase`
`externalEventId`	string	권장	멱등키. 동일 키 재전송 시 중복 저장 안 됨
`valueMinor`	integer	sale 시 필수	최소 통화 단위 정수. KRW=원, USD=cents
`currency`	string	sale 시 필수	ISO 4217 3자리 코드
`customerEmailHash`	string(64hex)	선택	이메일 SHA-256 lowercase. 평문 금지
`metadata`	object	선택	임의 키-값. 8KB 초과 시 거부

Response 200

{
  "ok": true,
  "eventId": "evt_abc123",
  "attribution": {
    "method": "direct",
    "clickId": "abc123",
    "linkId": "lnk_xyz"
  }
}

필드	타입	설명
`eventId`	string	Edgelink 발급 이벤트 ID
`attribution.method`	`'direct' \| 'deferred' \| 'none'`	매칭 방식. 본 MVP에서는 `direct` 또는 `none`
`attribution.clickId`	string?	매칭에 사용된 클릭 ID
`attribution.linkId`	string?	매칭된 단축 링크 ID

에러 코드

HTTP	code	설명
400	`INVALID_PAYLOAD`	페이로드 형식 오류
400	`SALE_REQUIRES_SECRET_KEY`	publishable 키로 `sale` 이벤트 시도
401	`INVALID_KEY`	키 형식 오류·키 미존재
401	`KEY_REVOKED`	키 폐기됨
403	`ORIGIN_NOT_ALLOWED`	Origin 헤더가 화이트리스트와 불일치
403	`CONVERSION_TRACKING_NOT_ENABLED`	워크스페이스 플랜에 전환 추적 미포함 (Pro 필요)
404	`CLICK_NOT_FOUND`	clickId 미존재 또는 다른 워크스페이스 소유
410	`CLICK_EXPIRED`	어트리뷰션 윈도우(90일) 만료
429	`RATE_LIMIT_EXCEEDED`	Rate limit 초과. `Retry-After` 헤더 참조
429	`QUOTA_EXCEEDED`	플랜 월 quota 초과 (Pro: 1000건/월)
5xx	`INTERNAL_ERROR`	서버 일시 장애. 재시도 권장

cURL 예시

curl -X POST https://api.edgelink.me/api/v1/track \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "clickId": "abc123",
    "eventType": "sale",
    "eventName": "purchase",
    "externalEventId": "order-001",
    "valueMinor": 49900,
    "currency": "KRW"
  }'

재시도 가이드

4xx: 즉시 폐기. 페이로드 또는 키 설정 점검 필요.
429: Retry-After 헤더의 초 후 재시도. 헤더 없으면 2^n 지수 백오프.
5xx: 2^n 지수 백오프(최대 3회). 그 이상은 알림 후 모니터링.

다음 단계

자주 묻는 질문

SDK를 쓰지 않고 직접 HTTP로 호출해도 되나요?

됩니다. SDK가 없는 언어(Go, PHP, Ruby 등)에서는 본 문서의 명세대로 직접 POST 요청을 보내세요. 재시도·멱등성·헤더 처리를 직접 구현해야 합니다.

동일 이벤트를 두 번 보내면 두 번 카운트되나요?

`externalEventId`를 지정하면 동일 키 재전송 시 기존 eventId가 반환되고 카운트는 1회로 유지됩니다. 결제 webhook 중복 도달에 안전합니다.

Rate limit는 어떻게 적용되나요?

모든 키 종류 공통으로 분당 300건, 시간당 5,000건이 기본값입니다. 키 종류별 분리는 후속 spec에서 도입됩니다. 초과 시 429와 `Retry-After` 헤더가 반환됩니다.

어떤 통화가 지원되나요?

KRW·USD·EUR·JPY 등 ISO 4217 3자리 코드를 받습니다. `valueMinor`는 반드시 최소 통화 단위 정수여야 하며, KRW=원, USD=cents 입니다.