Edgelink
Docs전환 추적전환 추적 API 레퍼런스

전환 추적 API 레퍼런스

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

전환 추적 API 레퍼런스

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

Base URL

https://api.edgelink.me

인증

Authorization: Bearer <키>
키 종류형식용도
publishablepk_live_* / pk_test_*브라우저, lead·커스텀 전용
secretsk_live_* / sk_test_*서버, sale 포함 전체 이벤트

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

POST /api/v1/track

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

Request Headers

헤더값비고
AuthorizationBearer <키>필수
Content-Typeapplication/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"
  }
}
필드타입필수설명
clickIdstringclickId XOR userId단축 링크 클릭 시 발급된 ID. 쿠키 _el_cid에서 추출
externalUserIdstringclickId XOR userId고객사 user ID. clickId 없을 때 사용
eventType'lead' | 'sale' | 'custom'필수이벤트 분류
eventNamestring필수자유 식별자. 예: signup, purchase
externalEventIdstring권장멱등키 — 동일 키 재전송 시 중복 저장 안 됨
valueMinorintegersale 시 필수최소 통화 단위 정수. KRW=원, USD=cents
currencystringsale 시 필수ISO 4217 3자리 코드
customerEmailHashstring(64hex)선택이메일 SHA-256 lowercase. 평문 금지
metadataobject선택임의 키-값. 8KB 초과 시 거부

Response 200

{
  "ok": true,
  "eventId": "evt_abc123",
  "attribution": {
    "method": "direct",
    "clickId": "abc123",
    "linkId": "lnk_xyz"
  }
}
필드타입설명
eventIdstringEdgelink 발급 이벤트 ID
attribution.method'direct' | 'deferred' | 'none'매칭 방식. 본 MVP에서는 direct 또는 none
attribution.clickIdstring?매칭에 사용된 클릭 ID
attribution.linkIdstring?매칭된 단축 링크 ID

에러 코드

HTTPcode설명
400INVALID_PAYLOAD페이로드 형식 오류
400SALE_REQUIRES_SECRET_KEYpublishable 키로 sale 이벤트 시도
401INVALID_KEY키 형식 오류·키 미존재
401KEY_REVOKED키 폐기됨
403ORIGIN_NOT_ALLOWEDOrigin 헤더가 화이트리스트와 불일치
403CONVERSION_TRACKING_NOT_ENABLED워크스페이스 플랜에 전환 추적 미포함 (Pro 필요)
404CLICK_NOT_FOUNDclickId 미존재 또는 다른 워크스페이스 소유
410CLICK_EXPIRED어트리뷰션 윈도우(90일) 만료
429RATE_LIMIT_EXCEEDEDRate limit 초과. Retry-After 헤더 참조
429QUOTA_EXCEEDED플랜 월 quota 초과 (Pro: 1000건/월)
5xxINTERNAL_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회). 그 이상은 알림 후 모니터링.

다음 단계