API 연동 시작하기

ERP, 재고 관리 시스템, 사내 보고서에서 Superfid의 위치와 재고를 조회할 수 있습니다. 외부 API는 읽기 전용이며 재고를 변경하지 않습니다.

요청 주소는 https://api.superfid.io입니다. 연동할 워크스페이스의 개발자 키를 준비하고, 키는 서버에서만 보관하세요.

시작 순서

1. 워크스페이스 관리자에게 개발자 키를 발급받습니다. 관리자는 대시보드의 설정 → 개발자 키에서 발급할 수 있습니다.
2. /v1/external/workspace로 원하는 워크스페이스에 연결되었는지 확인합니다.
3. /v1/external/locations에서 조회할 위치·구역의 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.name과 workspace.id가 연동할 워크스페이스와 일치하는지 확인하세요. scope: "read"는 조회 권한을 뜻합니다.

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

위치와 재고 조회하기

연결을 확인했으면 아래 문서의 요청 예시를 실행하세요. 예시에 사용하는 API_BASE_URL과 SUPERFID_DEVELOPER_KEY는 위에서 설정한 값을 사용합니다. LOCATION_ID는 위치 목록의 id, SKU_ID는 재고현황 목록의 items[].id로 설정하세요.

• 워크스페이스 연결 확인 — GET /v1/external/workspace
• 위치·구역 목록 — GET /v1/external/locations
• 위치별 재고 이벤트 — GET /v1/external/events
• 이벤트 수량 라인 — GET /v1/external/events/{eventId}/lines
• 확정된 재고 실사 — GET /v1/external/counts
• 재고현황 목록 — GET /v1/external/inventory-status
• SKU 재고 상세 — GET /v1/external/inventory-status/{skuId}
• SKU 재고 변동 이력 — GET /v1/external/inventory-status/{skuId}/history

공통 규칙

• 모든 요청은 Authorization: Bearer <developer-key>를 사용합니다. 쿼리 문자열의 token 인증은 지원하지 않습니다.
• 개발자 키는 발급된 워크스페이스에만 사용할 수 있고, 권한은 read입니다.
• 오류는 { "error": { "code": "...", "message": "..." } } 형태입니다.
• 외부 API 조회 제한은 개발자 키별 분당 60회, 워크스페이스별 분당 120회입니다. 제한은 같은 워크스페이스의 REST·MCP 조회가 공유하며, 초과 시 Retry-After를 따릅니다.
• 403과 billing_access_restricted가 반환되면 워크스페이스 이용이 정지된 상태입니다. 자동 재시도하지 말고 조직 관리자에게 대시보드 정산에서 정지 사유와 필요한 조치를 확인해 달라고 요청하세요. 이용 복구를 확인한 뒤 다시 조회합니다.
• 401이면 키를 확인합니다. 429 또는 503이면 오류와 재시도에 따라 대응합니다. Retry-After가 있으면 지정된 시간만큼 기다립니다.
• 키 원문과 전체 Authorization 헤더는 로그에 남기지 않습니다.

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