API 키

대시보드에서 API 키를 만들고 권한, 계좌 범위, 만료를 정하는 방법과 재발급, 요청 기록, 안전하게 보관하는 방법을 설명해요.

API를 호출하려면 API 키가 필요해요. API 키는 워크스페이스 하나에 속하고, 키로 보낸 요청은 그 워크스페이스의 주문, 입금, 현금영수증만 다뤄요. 요청에 키를 넣는 방법은 API 개요의 인증을 참고하세요.

API 키를 만들고 관리하려면 소유자나 개발자 역할이 필요해요. 만들 수 있는 키 수는 요금제마다 달라요.

파트너 서비스에 워크스페이스 접근을 허용할 때는 API 키를 건네지 말고 연결된 앱으로 연결하세요.

키 만들기

대시보드 API 키에서 키 만들기를 눌러요.

항목	설명
이름	키를 구분할 이름이에요. 2~16자로 입력해요. 예: `쇼핑몰 서버`
권한	읽기·쓰기 또는 읽기 전용 중에서 골라요. 아래 권한을 참고하세요.
계좌 범위	모든 계좌는 나중에 추가하는 계좌도 포함해요. 고른 계좌만은 고른 계좌의 입금과 주문만 다뤄요. 아래 계좌 범위를 참고하세요.
만료	만료 없음, 30일 뒤, 90일 뒤, 1년 뒤, 날짜 지정 중에서 골라요. 날짜를 지정하면 그날 23:59까지 쓸 수 있어요.

API 키는 sk_live_로 시작해요. 페이싱크에는 테스트용 키가 따로 없어서, 모든 키가 실제 계좌의 주문과 입금을 다뤄요.

권한	할 수 있는 일
읽기·쓰기	주문을 만들고, 바꾸고, 결제 완료 처리하고, 취소해요. 현금영수증을 발급하고 취소해요. 조회도 모두 할 수 있어요.
읽기 전용	주문, 입금, 현금영수증 조회만 해요. 쓰기 요청은 `403`, `290007`로 실패해요.

주문 현황을 보여 주는 내부 도구나 정산 배치처럼 조회만 하는 곳에는 읽기 전용 키를 쓰세요.

고른 계좌만으로 만든 키는 고른 계좌로 받는 주문과 그 계좌로 들어온 입금만 다뤄요. 매장이나 지점마다 서버가 따로 있을 때, 서버마다 자기 계좌의 키를 주면 다른 매장의 주문을 건드리지 못해요.

API별 동작은 API 키 계좌 범위를 참고하세요. 주문의 받을 계좌와의 차이는 다중 계좌 라우팅에 정리해 뒀어요.

키 목록의 행 메뉴에서 관리해요.

작업	하는 일
재발급	새 키 값을 만들어요. 이름, 권한, 계좌 범위, 만료는 그대로이고 이전 키는 바로 멈춰요.
수정 > 키 사용 끄기	이 키로 보낸 요청을 모두 거절해요. 다시 켜면 같은 키 값으로 쓸 수 있어요.
삭제	키를 지워요. 이 키로 보낸 요청은 바로 거절하고, 되돌릴 수 없어요.

재발급하면 이전 키를 잠시 함께 쓰는 기간이 없어요. 새 키를 서버에 넣을 준비를 한 뒤에 재발급하세요. 멈춘 키, 꺼진 키, 지운 키, 만료된 키로 보낸 요청은 401, 290006으로 실패해요.

API 키 화면의 요청 기록에서 최근 30일 동안 키로 보낸 요청의 시각, 경로, 결과, 응답 시간을 확인할 수 있어요. 키와 결과(성공, 오류)로 걸러 볼 수 있어요. 연동 중에 어떤 요청이 실패했는지 찾을 때 쓰세요.