내 사이트의 매출과 판매 정보를
사이트딜에 연결하세요.

사이트딜에서 사이트를 등록하고 전용 키를 발급한 뒤, 운영 중인 홈페이지의 서버에서 아래 API를 호출합니다. 다른 결제사의 API 키를 사이트딜에 제출할 필요는 없습니다.

1. 사이트 등록과 키 발급

1. 사이트딜 홈에서 계정을 만들고 내 사이트 등록을 선택합니다.
2. 사이트 주소·카테고리·매출 수집 시작일을 입력합니다. 원하면 판매 상태와 희망 매각가를 입력합니다.
3. 내 관리 → API 키에서 필요한 권한을 선택해 발급합니다. 사이트 ID와 키를 서버 환경변수에 저장합니다.
4. 등록 화면의 공개 항목을 선택하면 사이트 정보와 매출이 랭킹에 나타납니다. 공개하지 않은 사이트는 본인만 관리합니다.

키 원문은 발급 시 한 번만 표시하고, 사이트딜 데이터베이스에는 해시만 저장합니다. 브라우저 JavaScript, 공개 저장소, URL 쿼리에는 키를 넣지 마세요. 분실 시 기존 키를 폐기하고 새 키를 발급할 수 있습니다.

2. 인증과 권한

Authorization: Bearer YOUR_SITE_API_KEY
Content-Type: application/json

키는 발급받은 사이트 하나에만 사용할 수 있습니다. 사이트당 활성 키는 최대 5개이며, 내 관리에서 폐기하면 즉시 사용할 수 없게 됩니다.

3. 결제 매출 등록

POST /api/v1/sites/SITE_ID/revenue

{
  "eventId": "order-20261105-001",
  "kind": "payment",
  "amount": 10000,
  "occurredAt": "2026-11-05T10:00:00+09:00"
}

• amount: 부가세 포함 원화(KRW) 정수. 1원 이상 1조 원 이하입니다.
• occurredAt: 시간대가 있는 ISO 날짜. 실제 결제 시각을 보내며, 미래 매출은 등록할 수 없습니다.
• eventId: 사이트 내에서 고유한 주문·거래 식별자. 고객 이름·이메일 등 개인정보를 넣지 마세요.
• 결제가 실제로 완료된 후 전송하세요. 대기·실패·테스트 결제는 실제 매출로 전송하지 마세요.

서버 환경변수를 사용하는 JavaScript 예시:

const response = await fetch(
  `${process.env.SITEDEAL_BASE_URL}/api/v1/sites/${process.env.SITEDEAL_SITE_ID}/revenue`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SITEDEAL_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      eventId: 'your-unique-order-id',
      kind: 'payment',
      amount: 10000,
      occurredAt: new Date().toISOString()
    })
  }
);
if (!response.ok) throw new Error(`SiteDeal API: ${response.status}`);

SITEDEAL_BASE_URL은 현재 접속한 사이트딜 주소를 사용하세요. 도메인 이전 후에는 대표 주소로 변경합니다.

4. 환불·부분 환불 등록

{
  "eventId": "refund-20261105-001",
  "kind": "refund",
  "amount": 3000,
  "occurredAt": "2026-11-05T11:00:00+09:00",
  "originalEventId": "order-20261105-001"
}

환불은 먼저 등록한 결제를 가리켜야 하며, 원결제 이전 시각으로 등록할 수 없습니다. 여러 부분 환불의 합계가 원결제 금액을 넘으면 거절합니다. 위 예시에서는 매출이 10,000원에서 7,000원으로 집계됩니다.

5. 희망 매각가·판매 상태 수정

PATCH /api/v1/sites/SITE_ID

{
  "askingPrice": 30000000,
  "onSale": true,
  "published": true
}

제공한 항목만 수정합니다. askingPrice는 희망 매각가이며 매출과 별개입니다. onSale: true에는 매각가가 필요합니다. 판매를 멈추려면 { "onSale": false }, 랭킹에서 숨기려면 { "published": false }를 보내세요.

소유자는 로그인 후 내 관리 → 판매 중지 신청으로 즉시 중지할 수 있습니다. 소유자가 직접 중지한 사이트는 내 관리 → 판매 재개에서만 다시 판매할 수 있으며 API의 재개 요청은 409로 거절합니다. 중지 중에도 매출·환불 전송과 매각가 수정은 가능합니다.

수정 가능한 나머지 필드: name, url, category, description, historyStart. 소유자·사이트 ID·검증 상태는 수정할 수 없습니다. GET /api/v1/sites/SITE_ID로 변경 결과를 확인할 수 있습니다.

6. 중복·성장률·집계 기준

• 같은 eventId와 같은 내용을 재전송하면 200, duplicate: true를 반환하며 매출을 중복 집계하지 않습니다.
• 같은 번호로 다른 금액·시각을 보내면 409를 반환합니다. 확정된 결제 기록의 금액은 덮어쓰지 않으며, 필요한 취소·정정 내역을 별도 이벤트로 기록하세요.
• 매출은 한국 시간의 결제 발생일에 더하고 환불 발생일에 차감합니다. 광고비·상품 원가 등을 차감한 순이익과 다릅니다.
• 최근 30일은 이전 30일과 비교합니다. 진행 중인 월·년은 이전 기간의 같은 경과일까지 비교합니다.
• historyStart는 누락 없이 매출·환불을 전송한 최초 날짜입니다. 해당 날짜보다 이전 기간과는 성장률을 비교하지 않습니다.
• 이전 기간 0원·현재 매출 있음은 ‘신규’, 양쪽 0원은 ‘—’, 비교 기간 데이터가 부족하면 ‘비교 없음’으로 표시합니다.

7. 오류와 재시도

기본 쓰기 제한은 키 또는 계정별 분당 약 120회이며 Cloudflare 처리 위치별로 적용됩니다. 로그인·가입에는 별도 제한이 있습니다.