구매 | Blitz Rocket

구매

콘테스트 참가자가 한 구매를 추적합니다. 구매는 콘테스트의 구매 추적 설정에 따라 참가자에게 포인트를 부여할 수 있습니다.

구매 기록

POST/api/v1/contests/:contestId/purchases

Private API Key Required

콘테스트 참가자의 구매를 기록합니다. 참가자는 콘테스트의 구매 추적 설정에 따라 포인트를 부여받습니다. 중복 구매(동일한 orderId)는 감지되어 포인트가 두 번 부여되지 않습니다.

경로 매개변수

contestIdstring required

고유한 콘테스트 식별자

요청 본문

emailstring required

구매자의 이메일 주소 (기존 참가자와 일치해야 함)

orderIdstring required

시스템에서 사용하는 고유 주문 식별자

amountnumber required

구매 금액 (0보다 커야 함)

currencystring

통화 코드 (기본값: 'USD')

요청 예시

bash

curl -X POST https://blitzrocket.com/api/v1/contests/clx1abc123/purchases \
  -H "x-api-key: your_private_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "orderId": "order-12345",
    "amount": 49.99,
    "currency": "USD"
  }'

javascript

const contestId = "clx1abc123";
const response = await fetch(
  `https://blitzrocket.com/api/v1/contests/${contestId}/purchases`,
  {
    method: "POST",
    headers: {
      "x-api-key": "your_private_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      email: "jane@example.com",
      orderId: "order-12345",
      amount: 49.99,
      currency: "USD",
    }),
  }
);

const { data } = await response.json();
console.log(`구매 기록됨: ${data.pointsAwarded} 포인트 부여됨`);

python

import requests

contest_id = "clx1abc123"
response = requests.post(
    f"https://blitzrocket.com/api/v1/contests/{contest_id}/purchases",
    headers={
        "x-api-key": "your_private_key_here",
        "Content-Type": "application/json"
    },
    json={
        "email": "jane@example.com",
        "orderId": "order-12345",
        "amount": 49.99,
        "currency": "USD"
    }
)

data = response.json()["data"]
print(f"구매 기록됨: {data['pointsAwarded']} 포인트 부여됨")

응답 (201 생성됨)

json

{
  "success": true,
  "data": {
    "purchaseId": "purchase_xyz789",
    "entryId": "entry_abc123",
    "pointsAwarded": 50,
    "alreadyExists": false,
    "message": "구매가 성공적으로 기록되었습니다"
  }
}

응답 (200 - 중복)

동일한 orderId의 구매가 이미 존재하는 경우, API는 이미 처리되었음을 나타내기 위해 200 상태를 반환합니다:

json

{
  "success": true,
  "data": {
    "purchaseId": "purchase_xyz789",
    "entryId": "entry_abc123",
    "pointsAwarded": 0,
    "alreadyExists": true,
    "message": "구매가 이미 기록되었습니다"
  }
}

응답 필드

purchaseIdstring

구매 기록의 고유 식별자

entryIdstring

구매가 연동된 참가자 항목

pointsAwardednumber

이 구매에 대해 부여된 포인트 (중복 시 0)

alreadyExistsboolean

이 구매가 이미 기록되었는지 여부

messagestring

사람이 읽을 수 있는 상태 메시지

오류 응답

상태 코드	오류	설명
`400`	잘못된 요청 본문	이메일, orderId 또는 금액이 누락되었거나 유효하지 않음
`400`	금액은 양수여야 함	금액 값은 0보다 커야 합니다
`403`	개인 키 필요	이 엔드포인트는 개인 API 키가 필요합니다
`404`	콘테스트를 찾을 수 없음	주어진 ID의 콘테스트가 존재하지 않음

통합 예제

Shopify 웹훅과 구매 추적을 통합하는 완전한 예제는 다음과 같습니다:

javascript

app.post("/webhooks/shopify/order-created", async (req, res) => {
  const order = req.body;

  try {
    const response = await fetch(
      `https://blitzrocket.com/api/v1/contests/${CONTEST_ID}/purchases`,
      {
        method: "POST",
        headers: {
          "x-api-key": process.env.BLITZROCKET_PRIVATE_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          email: order.email,
          orderId: order.id.toString(),
          amount: parseFloat(order.total_price),
          currency: order.currency,
        }),
      }
    );

    const data = await response.json();
    console.log("구매 추적됨:", data);
    res.status(200).send("OK");
  } catch (error) {
    console.error("구매 추적 실패:", error);
    res.status(500).send("Error");
  }
});