API 호출

연결된 앱의 액세스 토큰으로 v2 API를 호출하는 방법과 오류 코드, API 키와 다른 동작, 고객이 연결을 끊거나 다시 연결할 때의 동작을 설명해요.

액세스 토큰을 Authorization: Bearer 헤더에 넣어 /v2 API를 호출해요. 요청과 응답 형식, 오류 코드는 API 레퍼런스와 같아요.

토큰은 연결된 워크스페이스 하나에 속해요. X-Workspace-Id 헤더는 보내지 않아요. 여러 고객을 연결했다면 고객의 워크스페이스마다 토큰을 골라 보내요.

요청 예시

invoices:read 스코프를 받은 토큰으로 주문 목록을 조회해요.

curl "https://api.paysync.kr/v2/invoices?offset=0&limit=20" \
  -H "Authorization: Bearer $PAYSYNC_ACCESS_TOKEN"

const res = await fetch("https://api.paysync.kr/v2/invoices?offset=0&limit=20", {
  headers: { Authorization: `Bearer ${accessToken}` },
});
const { code, items, totalItems } = await res.json();

import requests

res = requests.get(
    "https://api.paysync.kr/v2/invoices",
    params={"offset": 0, "limit": 20},
    headers={"Authorization": f"Bearer {access_token}"},
)
print(res.json())

응답은 주문 목록 조회와 같아요. 토큰이 멈췄으면 401, 토큰에 필요한 스코프가 없으면 403이 와요.

{
  "code": "380009"
}

{
  "code": "380010"
}

API 키와 다른 점

토큰에 허용된 스코프의 API만 호출할 수 있어요.
/v2 API만 호출할 수 있어요. /v1 API에 보내면 401, NOT_AUTHORIZED가 와요.
계좌 범위가 없어요. 워크스페이스의 모든 계좌의 주문과 입금을 다뤄요.
고객의 API 키 화면 요청 기록에 남지 않아요. 고객의 연결된 앱 화면에는 마지막 사용 시각만 보이고, 최대 1분 간격으로 갱신돼요.
앱이 만든 주문이나 결제 완료 처리한 주문의 주체(createdBy, paidBy, canceledBy)는 type이 CONNECTED_APP이고 name이 앱 이름이에요. 주문의 source는 API예요.

오류

HTTP	`code`	발생 조건
401	`380009`	토큰이 틀렸거나, 고객이 연결을 끊었거나, 다시 연결해서 이전 토큰이 됐어요.
403	`380010`	토큰에 이 API에 필요한 스코프가 없어요. 대시보드 전용 API를 호출해도 `380010`이나 `80008` 같은 오류가 와요.

나머지 코드는 에러 코드를 참고하세요.

연결이 끊기거나 다시 연결될 때

일	결과
연결 끊기	고객이 연결된 앱 화면에서 연결 끊기를 누르면 토큰이 바로 멈추고 `401`, `380009`가 와요. 다시 쓰려면 고객이 인가 요청부터 다시 허용해야 해요.
다시 연결	고객이 같은 워크스페이스에 앱을 다시 연결하면 기존 연결이 그대로 이어지고, 새 토큰과 이번에 허용한 스코프로 바뀌어요. 이전 토큰은 바로 멈춰요.
토큰 폐기	앱이 토큰을 폐기하면 연결이 끊겨요. 고객의 연결된 앱 화면에서도 사라져요.
워크스페이스 삭제	고객이 워크스페이스를 삭제하면 연결이 지워지고 토큰이 멈춰요.
시크릿 재발급	페이싱크가 클라이언트 시크릿을 재발급해도 발급한 토큰은 그대로 동작해요. 새 토큰을 받을 때만 새 시크릿을 써요.

401, 380009를 받으면 그 워크스페이스의 토큰을 지우고, 고객에게 다시 연결하도록 안내하세요. 재시도해도 같은 토큰은 다시 동작하지 않아요.