API 인증: CheckoutOS 문서

CheckoutOS API는 API 키로 인증해요. 이 가이드에서는 키 생성, 요청 인증, API 접근을 안전하게 관리하는 방법을 설명해요.

API 키

API 키는 CheckoutOS API의 모든 요청을 인증하는 데 사용해요. 각 키는 스토어에 연결되며 권한을 설정할 수 있어요.

API 키 생성

설정으로 이동

CheckoutOS → Settings → API로 이동하세요.

새 키 만들기

"Create API Key"를 클릭하세요.

키 이름 지정

"프로덕션 서버"처럼 설명이 담긴 이름을 지정하세요.

권한 설정

키가 접근할 수 있는 API 범위를 선택하세요.

키 복사

키는 다시 표시되지 않으므로 즉시 복사하세요.

키 보안

API 키는 생성할 때 한 번만 표시돼요. 안전하게 보관하세요. 분실하면 새 키를 생성해야 해요.

인증 방식

Bearer 토큰(권장)

Authorization 헤더에 API 키를 Bearer 토큰으로 포함하세요.

Bearer 토큰 인증

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

X-API-Key 헤더

대신 X-API-Key 헤더를 사용할 수도 있어요.

X-API-Key 인증

curl -X GET "https://api.chargezen.com/v1/checkoutos/upsells" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

API 권한

API 키의 범위를 특정 권한으로 제한할 수 있어요.

사용 가능한 범위

{
  "scopes": {
    "read:upsells": "View upsell configurations",
    "write:upsells": "Create and modify upsells",
    "read:bundles": "View bundle configurations",
    "write:bundles": "Create and modify bundles",
    "read:analytics": "Access analytics data",
    "read:orders": "View order data",
    "write:orders": "Modify orders (edits)",
    "read:settings": "View CheckoutOS settings",
    "write:settings": "Modify settings",
    "webhooks:manage": "Create and manage webhooks"
  }
}

최소 권한

연동에 필요한 권한만 부여하세요. 분석 대시보드용 키에는 추가 판매를 수정할 권한이 없어야 해요.

요청 속도 제한

공정한 사용을 위해 API 요청 횟수를 제한해요.

요청 한도

{
  "rate_limits": {
    "requests_per_minute": 120,
    "requests_per_hour": 3600,
    "burst_limit": 20
  },
  "headers": {
    "X-RateLimit-Limit": "120",
    "X-RateLimit-Remaining": "115",
    "X-RateLimit-Reset": "1640000000"
  }
}

요청 한도에 도달하면 429 응답을 받아요.

요청 한도 응답

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 45 seconds.",
    "retry_after": 45
  }
}

환경

CheckoutOS는 개발 환경과 프로덕션 환경을 별도로 제공해요.

API 환경

{
  "production": {
    "base_url": "https://api.chargezen.com/v1",
    "key_prefix": "live_"
  },
  "sandbox": {
    "base_url": "https://sandbox.api.chargezen.com/v1",
    "key_prefix": "test_"
  }
}

샌드박스 환경

개발과 테스트에는 샌드박스를 사용하세요. 샌드박스 데이터는 프로덕션과 분리되며 언제든 초기화할 수 있어요.

공식 SDK

공식 SDK는 인증을 자동으로 처리해요.

Node.js SDK

import { CheckoutOS } from '@chargezen/checkoutos-sdk';

const client = new CheckoutOS({
  apiKey: process.env.CHARGEZEN_API_KEY,
  environment: 'production'
});

const upsells = await client.upsells.list();

Python SDK

from chargezen import CheckoutOS

client = CheckoutOS(
    api_key=os.environ['CHARGEZEN_API_KEY'],
    environment='production'
)

upsells = client.upsells.list()

키 관리

권장 방법

환경 변수 사용 — 키를 코드에 직접 넣지 마세요
정기적인 키 교체 — 최소 분기마다 교체하세요
환경별로 별도 키 사용 — 개발, 스테이징, 프로덕션을 구분하세요
사용하지 않는 키 폐기 — 더 이상 사용하지 않는 키를 삭제하세요
키 사용 모니터링 — 비정상적인 패턴을 관찰하세요
최소 범위 사용 — 필요한 권한만 부여하세요

키 폐기

API 설정으로 이동

CheckoutOS → Settings → API로 이동하세요.

키 찾기

목록에서 폐기할 키를 찾으세요.

폐기

"Revoke"를 클릭하고 확인하세요.

즉시 적용

키 폐기는 즉시 적용돼요. 폐기된 키를 사용하는 모든 요청은 실패해요. 폐기하기 전에 애플리케이션을 업데이트했는지 확인하세요.

API 참조

API 엔드포인트

사용 가능한 API 엔드포인트

웹훅

실시간 이벤트 알림