고객사와 연동 계정

정의

고객사는 공개 API에서 상품·입고·재고·출고를 구분하는 범위입니다. 고객사 시스템은 해당 범위의 업무를 요청하고 결과를 조회합니다.

연동 계정(Service Principal)은 외부 시스템이 Maybox API를 호출할 때 사용하는 계정입니다. 사람이 관리 화면에 로그인하는 계정과 구분합니다.

API 인증 정보(credential)는 연동 계정이 자신을 인증하기 위해 요청에 보내는 비밀 값입니다. 계정 자체와 인증에 사용하는 값은 서로 다른 개념입니다.

다른 개념과의 관계

API 인증 정보는 고객사 하나에 고정됩니다. 요청에 tenantId를 넣어 다른 고객사를 선택하지 않습니다.
같은 고객사의 상품·입고·재고·출고를 연결할 때는 해당 고객사의 API 인증 정보를 사용합니다.
여러 고객사를 연결하는 서비스는 고객사별로 API 인증 정보를 구분합니다.
API 인증 정보와 웹훅 서명 키는 별개의 값입니다. API 인증 정보는 고객사가 Maybox에 요청할 때, 서명 키는 고객사가 받은 웹훅을 검증할 때 사용합니다.

발급과 환경 구분

연동 계정과 API 인증 정보는 Maybox 담당자에게 요청합니다. 테스트 환경의 접속 주소·사용 범위와 창고 작업 진행 방법도 함께 협의합니다.

테스트와 운영의 API 인증 정보·웹훅 서명 키·수신 URL은 구분해 관리합니다. 접속하는 환경과 인증 정보가 서로 맞아야 합니다.

연동 규칙

고객사 서버에서 API를 호출하고 인증 정보는 비밀 관리 도구에 보관합니다. 브라우저·모바일 앱·소스 코드에 넣지 않습니다.
API 인증 정보는 Authorization: Bearer <credential> 헤더로 전달합니다.
고객사 시스템에 저장한 Maybox ID도 고객사 범위와 함께 관리합니다. 다른 고객사의 ID로 조회하거나 변경하지 않습니다.
웹훅 본문에는 tenantId가 없습니다. 이벤트가 어느 고객사의 데이터인지는 검증한 서명 키와 수신 서버의 설정으로 판단합니다.
문의나 오류 로그에 API 인증 정보·웹훅 서명 키를 포함하지 않습니다.

관련 문서

연결 준비와 첫 호출: 계정·환경 요청과 인증 정보 설정
인증과 공통 규칙: 요청 헤더와 공통 계약
웹훅 서명 검증: 원문 바이트와 서명 키를 이용한 검증
API 레퍼런스: 각 API의 인증·요청·응답 구조