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

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

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

## 요청 예시

`invoices:read` 스코프를 받은 토큰으로 [주문 목록](/api-reference/invoices/list)을 조회해요.

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

```js Node.js
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();
```

```python Python
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())
```

응답은 [주문 목록 조회](/api-reference/invoices/list#응답)와 같아요. 토큰이 멈췄으면 `401`, 토큰에 필요한 스코프가 없으면 `403`이 와요.

```json title="401 Unauthorized"
{
  "code": "380009"
}
```

```json title="403 Forbidden"
{
  "code": "380010"
}
```

## API 키와 다른 점

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

## 오류

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

나머지 코드는 [에러 코드](/api-reference/error-codes)를 참고하세요.

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

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

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