개발자 문서

스킴은 공유 시크릿 크리덴셜입니다 — HMAC 요청 서명이 아닙니다. 타임스탬프도, 정규화 문자열도, base64(HMAC-SHA256(…)) 서명도 없습니다. 클라이언트가 TLS 위로 시크릿을 직접 보내면 서버는 해시(SHA-256 + pepper)해서 상수시간 비교합니다.

• 테넌트리스 크리덴셜. 크리덴셜(PartnerClient)에는 tenant_key 컬럼이 없습니다 — 마스터 키가 될 수 없습니다. 테넌트 귀속은 오직 인가 엣지(PartnerGrant = client × tenant × site × scope)를 통해서만 이뤄집니다.
• Authorization·X-API-Key 헤더는 다운스트림 도달 전 제거됩니다 — 파트너 인증 호출이 JWT/개인 토큰 필터를 건드릴 수 없습니다. (X-API-Key 는 별개 축 = 로그인 사용자 개인 토큰으로, 이 API 를 인증하지 않습니다.)
• 모든 요청 본문은 siteId (UUID) 를 반드시 포함해야 합니다 — grant 핀 키입니다. 누락 시 400 PARTNER_SITE_REQUIRED.

모든 엔드포인트는 POST, application/json. 모든 응답은 non-null 정직성 라벨(label)과 선택적 notice 를 담습니다. 필드는 camelCase, enum 값은 소문자입니다. 토큰 비용은 상품 리치니스 사다리를 따릅니다.

기간 제한(요청별): audience-fit·conversions/summary·ads ≤ 180일, behavior ≤ 31일, conversions/funnel ≤ 92일, market lookback 1–365일. 응답에는 k-익명 봉인(고유 구매자·세션 임계 미만 시 해당 블록 null + notice)이 적용됩니다.

요청 (conversions/summary · 토큰 8):

curl -X POST https://api.statlane.kr/partner/v1/conversions/summary \
  -H "X-Partner-Client: 3f2a…-uuid" \
  -H "X-Partner-Secret: plk_1a2b3c…(48 hex)" \
  -H "Idempotency-Key: 2026-08-15-summary-01" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "b91c…-uuid",
    "from": "2026-07-01",
    "to":   "2026-07-31"
  }'

응답 — 전역 envelope { success, data, error }. 도메인 결과는 항상 HTTP 200 (과금 확정은 내부 도메인-성공 플래그로 구동, HTTP 상태 아님):

{
  "success": true,
  "data": {
    "from": "2026-07-01",
    "to":   "2026-07-31",
    "visitors": 4820,
    "conversions": 214,
    "conversionRate": 0.0444,
    "orders": 231,
    "revenueTotal": 18734000,
    "aov": 81099,
    "currency": "KRW",
    "notice": null,
    "label": {
      "estimated": false,
      "observational": true,
      "isRelativeIndex": false,
      "methodVersion": "conv-1",
      "dataBasis": "order_id-idempotent first-party",
      "caveats": ["고유 구매자 5 미만 구간은 k-익명 봉인"]
    }
  },
  "error": null
}

응답 (keyword-budget/summary · 토큰 13) — 최상위 상품. 우리 조인(광고비 ↔ 키워드 실적)에 예측 처방을 얹어 절감·증액·미개척 4블록을 반환합니다. 필드는 camelCase, 추정 블록은 estimated: true 라벨로 정직하게 표기됩니다:

{
  "success": true,
  "data": {
    "from": "2026-07-01",
    "to":   "2026-07-31",
    "savings":   { "keywords": 12, "wastedSpend": 1840000, "currency": "KRW" },
    "scaleUp":   { "keywords": 7,  "headroomSpend": 2600000, "currency": "KRW" },
    "untapped":  { "keywords": 23, "estImpressions": 41200 },
    "counts":    { "analyzed": 318, "converting": 96 },
    "notice": null,
    "label": {
      "estimated": true,
      "observational": false,
      "isRelativeIndex": false,
      "methodVersion": "kwbudget-1",
      "dataBasis": "ad-spend ↔ keyword conversions join + forecast",
      "caveats": ["증액·미개척 추정은 예측치 — 실집행 후 실측으로 갱신"]
    }
  },
  "error": null
}

• 1 토큰 = 1 cost_unit. 호출 비용은 상품의 cost_units (append-only 이력, 리프라이스는 UPDATE 가 아닌 새 INSERT). v1 은 call-flat — 서빙 전에 비용이 확정됩니다.
• 2단계 미터링: reserve → settle. 서빙 전 api_usage_month 에 원자적 조건부 증가(used + cost ≤ limit)로 예약, 초과 시 402. 서빙 후 도메인-성공 플래그로 정산 — 성공 시 멱등 원장 INSERT, 실패·취소 시 예약 해제(과금 안 됨).
• 월 쿼터는 fail-CLOSED. plan_limit_units 미설정(=0)이면 즉시 402 — 전역 기본 시드 없음. 월 키는 KST 기준 yyyyMM.
• API 과금 테이블은 웹 티어와 물리적으로 분리. api_usage_month · api_usage_ledger 에는 tenant_key 컬럼이 없습니다 — client_id 축 과금이며, 웹 구독(테넌트 축)과 공유 카운터·행·스필오버가 없습니다.

auth 필터는 표준 ApiResponse 에러 envelope 를 직접 기록합니다(전역 예외 핸들러 밖에서 실행). 본문 검증 오류(기간 초과· 잘못된 steps 등)는 서빙 전 bean validation 으로 표준 검증 envelope 로 반환됩니다.

파트너는 크리덴셜을 셀프서비스로 발급하지 않습니다. 현재는 Statlane 플랫폼 팀이 클라이언트와 grant(테넌트 × 사이트 × 스코프)·월 쿼터를 발급합니다. 셀프 발급 개발자 콘솔은 준비 중입니다.