API Quickstart

Superfid 외부 API는 workspace 개발자 키를 사용하는 읽기 전용 API입니다. 운영 API base URL은 https://api.superfid.io이며, 키는 서버에서만 보관하세요. 개발·스테이징 환경은 각각 https://dev.api.superfid.io, https://staging.api.superfid.io를 사용합니다.

시작 순서

1. 관리자에게 workspace 개발자 키를 발급받습니다.
2. /v1/external/workspace로 키와 workspace 연결을 확인합니다.
3. /v1/external/locations에서 위치·section ID를 가져옵니다.
4. 재고 목록, 특정 SKU 상세, SKU 변동 이력을 조회합니다.

첫 요청

export API_BASE_URL="https://api.superfid.io"
export SUPERFID_DEVELOPER_KEY="<developer-key>"

curl --fail-with-body "$API_BASE_URL/v1/external/workspace" \
  -H "Authorization: Bearer $SUPERFID_DEVELOPER_KEY" \
  -H "Accept: application/json"

정상 응답은 연결된 workspace와 읽기 전용 scope를 반환합니다.

{
  "workspace": { "id": "org_...", "name": "Superfid" },
  "scope": "read"
}

Endpoint reference

상세 요청·응답·query 조건·페이지네이션은 path 그룹별 reference에서 확인하세요.

• Workspace 연결 확인 — GET /v1/external/workspace
• 위치·section 목록 — GET /v1/external/locations
• 재고현황 목록 — GET /v1/external/inventory-status
• SKU 재고 상세 — GET /v1/external/inventory-status/{skuId}
• SKU 재고 변동 이력 — GET /v1/external/inventory-status/{skuId}/history

공통 규칙

• 모든 요청은 Authorization: Bearer <developer-key>를 사용합니다. query string의 token 인증은 지원하지 않습니다.
• 외부 API는 현재 읽기 전용이며, 개발자 키의 scope는 read입니다.
• 운영 base URL은 https://api.superfid.io를 사용하고, dev/staging URL은 폐기 가능한 테스트 workspace에서만 사용합니다.
• 오류는 { "error": { "code": "...", "message": "..." } } 형태입니다.
• 401은 키 누락·위조·만료·폐기, 429는 인증 전 또는 workspace quota 제한, 503은 인증 저장소·외부 API 장애입니다. Retry-After가 있으면 그 시간만큼 기다립니다.
• 키 원문과 전체 Authorization 헤더는 로그에 남기지 않습니다.

다음으로 인증과 비밀정보와 오류와 재시도를 확인하세요.