---
title: "REST API 시작하기"
description: "올바른 범위의 개인 액세스 토큰을 만들거나 OAuth 앱을 등록하고, 자체 시스템에서 캠페인, 리드, 목록을 읽으세요."
url: https://scratcher.io/ko/help/developers/rest-api
language: ko
---

1. [도움말 센터](https://scratcher.io/ko/help)
2. [API, 웹훅, MCP](https://scratcher.io/ko/help/developers)
3. REST API 시작하기

# REST API 시작하기

올바른 범위의 개인 액세스 토큰을 만들거나 OAuth 앱을 등록하고, 자체 시스템에서 캠페인, 리드, 목록을 읽으세요.

Scratcher REST API를 사용하면 자체 시스템에서 캠페인, 리드, 목록을 읽고, 리드를 추가·업데이트하고, 상품과 플레이스먼트를 관리할 수 있습니다. 이 문서는 API를 설정하는 개발자를 위한 것입니다.

API는 **웹훅 및 API**가 포함된 요금제(베이직 이상)에 포함됩니다. 다른 요금제에서는 토큰과 앱을 만드는 버튼이 잠겨 있습니다.

## 개인 액세스 토큰 만들기

개인 액세스 토큰은 자체 스크립트와 시스템에서 API를 호출하는 가장 빠른 방법입니다.

1. **설정** > **API**(**개발자** 아래)로 이동합니다.
2. **개인 액세스 토큰**에서 **개인 액세스 토큰 만들기**를 클릭합니다. 대화 상자에 “API 요청 인증용 토큰을 생성합니다.”라고 표시됩니다.
3. 나중에 알아보기 쉬운 **이름**을 입력합니다. 예: “데이터 웨어하우스”
4. **범위**에서 토큰이 할 수 있는 작업을 고릅니다(아래 참고). **모두 선택**은 모든 범위를 선택합니다. 토큰에는 필요한 권한만 주세요.
5. **저장**을 클릭합니다. “액세스 토큰이 생성되었습니다”라는 메시지가 표시됩니다.
6. **시크릿** 아래의 토큰을 복사합니다. “위의 시크릿을 저장하세요. 다시는 볼 수 없습니다.” 비밀번호 관리자 등 안전한 곳에 보관하세요.
7. **닫기**를 클릭합니다.

토큰은 사용자에게 속합니다. 선택한 범위 내에서 사용자가 구성원으로 있는 모든 Scratcher 계정에 접근할 수 있습니다.

## 범위

- `read:campaigns`(**캠페인 보기**): 캠페인 목록 조회 및 읽기
- `read:lists`(**목록 보기**): 리드 목록 조회 및 읽기
- `read:leads`(**리드 보기**): 리드 읽기
- `write:leads`(**리드 쓰기**): 목록의 리드 생성, 업데이트, 삭제
- `read:placements`(**플레이스먼트 보기**): 플레이스먼트 읽기
- `write:placements`(**플레이스먼트 쓰기**): 플레이스먼트 생성, 업데이트, 삭제
- `read:products`(**상품 보기**): 상품 읽기
- `write:products`(**상품 쓰기**): 상품 생성, 업데이트, 삭제

캠페인의 리드를 읽으려면 토큰에 `read:campaigns`와 `read:leads`가 모두 필요합니다. 플레이스먼트를 만들고 변경하려면 요금제에 **임베드 / URL**도 포함되어 있어야 합니다.

## 토큰 취소하기

목록에서 토큰을 클릭하면 **개인 액세스 토큰 보기**가 열립니다. **이름**과 **범위**가 표시됩니다. **취소**를 클릭하고 확인합니다(“이 토큰을 삭제하시겠습니까? 되돌릴 수 없습니다!”). 이 토큰을 사용하는 모든 것이 즉시 작동을 멈춥니다.

## 요청 보내기

기본 URL은 `https://platform.scratcher.io/api/v1/`입니다. `Authorization` 헤더에 토큰을 담아 보내고 JSON을 요청하세요.

```text
curl https://platform.scratcher.io/api/v1/accounts \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Accept: application/json"
```

## 주요 엔드포인트

- `GET /me`: 토큰 소유 사용자
- `GET /accounts`: 액세스할 수 있는 계정. 다른 호출에서 계정 id를 사용하세요.
- `GET /accounts/{account}/campaigns` 및 `/campaigns/{campaign}`: 캠페인
- `GET /accounts/{account}/campaigns/{campaign}/leads`: 캠페인의 리드(최신순). 필드, 수락한 동의, 당첨자의 경우 경품과 코드 포함
- `GET /accounts/{account}/lists` 및 `/lists/{list}`: 리드 목록
- `/accounts/{account}/lists/{list}/leads`: 목록의 리드. 읽기는 `GET`, 생성은 `POST`, 업데이트는 `PUT`, 삭제는 `DELETE`. 리드에는 `email`, `phone_number`, 선택 사항인 `custom_token`이 있습니다.
- `/accounts/{account}/products`: 상품(`GET`, `POST`, `PUT`, `DELETE`)
- `/accounts/{account}/placements`: 플레이스먼트(`GET`, `POST`, `PUT`, `DELETE`)

목록은 페이지 단위로 제공됩니다. `?page=2` 등을 추가하세요. 구성원으로 있는 계정에만 접근할 수 있으며, 다른 계정 id는 오류를 반환합니다.

## 제한

사용자당 분당 60건의 요청을 보낼 수 있습니다. 초과하면 API가 상태 코드 429로 응답합니다. 잠시 기다렸다가 다시 시도하세요.

## API 참조

모든 필드, 필터, 예시, Postman 컬렉션이 포함된 전체 참조는 [API 참조 문서](https://platform.scratcher.io/docs/index.html)에 있습니다. **설정** > **API** 상단의 **API 참조** 버튼으로도 이동할 수 있습니다.

## OAuth로 앱 만들기

다른 Scratcher 사용자가 자신의 계정에 연결하는 앱을 만든다면 개인 토큰 대신 OAuth 앱을 등록하세요.

1. **설정** > **API**로 이동합니다. **내 앱**에서 **앱 만들기**(“API용 OAuth 애플리케이션을 등록합니다.”)를 클릭합니다.
2. **애플리케이션 이름**(사용자가 앱을 승인할 때 표시됨)과 **리디렉션 URI**(승인 후 사용자가 돌아갈 위치)를 입력합니다.
3. **저장**을 클릭합니다. **클라이언트 ID**와 **클라이언트 시크릿**과 함께 “앱이 생성되었습니다!”라는 메시지가 표시됩니다.
4. 지금 클라이언트 시크릿을 복사하세요: “위의 클라이언트 시크릿을 저장하세요. 다시는 볼 수 없습니다.” **계속**을 클릭합니다.

앱은 클라이언트 ID, 리디렉션 URI, 필요한 범위와 함께 사용자를 `https://platform.scratcher.io/oauth/authorize`로 보냅니다. 사용자가 Scratcher에 로그인하면 **인증 요청**이 표시됩니다: “이 애플리케이션이 할 수 있는 작업:” 다음에 범위가 나열됩니다. 사용자는 **승인** 또는 **취소**를 클릭합니다. 그런 다음 앱이 `https://platform.scratcher.io/oauth/token`에서 코드를 토큰으로 교환합니다.

- OAuth 액세스 토큰은 2개월 동안 유효합니다. 리프레시 토큰은 3개월 동안 유효하며, 새 액세스 토큰을 받는 데 사용합니다.
- 이름이나 리디렉션 URI를 바꾸려면 **내 앱**에서 앱을 클릭해 변경하고 **저장**을 클릭하세요(“설정이 저장되었습니다”). “시크릿은 나중에 다시 볼 수 없습니다.”
- **앱 삭제**는 앱을 제거하며, 모든 사용자의 앱 연결이 작동을 멈춥니다: “이 앱을 삭제하시겠습니까? 되돌릴 수 없습니다!”

## 승인한 앱

**승인된 앱**에는 Zapier처럼 계정 액세스 권한을 준 앱이 해당 범위와 함께 나열됩니다. 액세스를 회수하려면 **취소**를 클릭하세요.

## 누가 API를 사용할 수 있나요?

**API** 페이지는 **소유자**, **관리자**, **매니저** 역할의 사용자에게 표시됩니다. 토큰은 토큰을 만든 사용자보다 더 많은 작업을 할 수 없습니다.

API, 웹훅, MCP

- [REST API 시작하기](https://scratcher.io/ko/help/developers/rest-api)
- [웹훅으로 시스템에 데이터 보내기](https://scratcher.io/ko/help/developers/webhooks)
- [내 AI 도구를 위한 Scratcher MCP](https://scratcher.io/ko/help/developers/mcp)

더 알아보기

## 관련 글

- [웹훅으로 시스템에 데이터 보내기](https://scratcher.io/ko/help/developers/webhooks): 누군가 가입하거나, 참여하거나, 당첨될 때 내 URL로 요청을 받으세요. 서명된 페이로드, 기본 인증, 맞춤 페이로드, 모든 전송 내역 로그를 지원합니다.
- [내 AI 도구를 위한 Scratcher MCP](https://scratcher.io/ko/help/developers/mcp): MCP로 Claude, ChatGPT 등 AI 도구를 Scratcher 계정에 연결하세요. 설정 방법과 AI가 할 수 있는 일을 안내합니다.
- [Zapier로 8,000개 이상의 앱 연결하기](https://scratcher.io/ko/help/integrations/zapier): Zapier를 사용해 Scratcher의 새 가입자를 Google Sheets, Slack, CRM 등 수천 개의 앱으로 보내세요.

도움이 필요하신가요?

## 아직 도움이 필요하신가요?

실제 담당자가 도와드립니다. 이미 Scratcher를 사용 중이라면 플랫폼 안의 채팅이 가장 빠릅니다.

- **[채팅 문의](https://platform.scratcher.io/ko/login)**

    로그인한 뒤 오른쪽 아래의 채팅 버튼을 클릭하세요. Rex가 바로 답하고, 팀과도 클릭 한 번으로 연결됩니다.
- **[미팅 예약](https://scratcher.io/ko/book-a-meeting)**

    팀과의 무료 30분 화상 통화: 둘러보기, 캠페인 아이디어, 설정 지원.
- **[이메일 문의](mailto:contact@scratcher.io)**

    contact@scratcher.io로 연락 주시면 답변드리겠습니다.
