Scratcher REST API를 사용하면 자체 시스템에서 캠페인, 리드, 목록을 읽고, 리드를 추가·업데이트하고, 상품과 플레이스먼트를 관리할 수 있습니다. 이 문서는 API를 설정하는 개발자를 위한 것입니다.
API는 웹훅 및 API가 포함된 요금제(베이직 이상)에 포함됩니다. 다른 요금제에서는 토큰과 앱을 만드는 버튼이 잠겨 있습니다.
개인 액세스 토큰 만들기
개인 액세스 토큰은 자체 스크립트와 시스템에서 API를 호출하는 가장 빠른 방법입니다.
- 설정 > API(개발자 아래)로 이동합니다.
- 개인 액세스 토큰에서 개인 액세스 토큰 만들기를 클릭합니다. 대화 상자에 “API 요청 인증용 토큰을 생성합니다.”라고 표시됩니다.
- 나중에 알아보기 쉬운 이름을 입력합니다. 예: “데이터 웨어하우스”
- 범위에서 토큰이 할 수 있는 작업을 고릅니다(아래 참고). 모두 선택은 모든 범위를 선택합니다. 토큰에는 필요한 권한만 주세요.
- 저장을 클릭합니다. “액세스 토큰이 생성되었습니다”라는 메시지가 표시됩니다.
- 시크릿 아래의 토큰을 복사합니다. “위의 시크릿을 저장하세요. 다시는 볼 수 없습니다.” 비밀번호 관리자 등 안전한 곳에 보관하세요.
- 닫기를 클릭합니다.
토큰은 사용자에게 속합니다. 선택한 범위 내에서 사용자가 구성원으로 있는 모든 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을 요청하세요.
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 참조 문서에 있습니다. 설정 > API 상단의 API 참조 버튼으로도 이동할 수 있습니다.
OAuth로 앱 만들기
다른 Scratcher 사용자가 자신의 계정에 연결하는 앱을 만든다면 개인 토큰 대신 OAuth 앱을 등록하세요.
- 설정 > API로 이동합니다. 내 앱에서 앱 만들기(“API용 OAuth 애플리케이션을 등록합니다.”)를 클릭합니다.
- 애플리케이션 이름(사용자가 앱을 승인할 때 표시됨)과 리디렉션 URI(승인 후 사용자가 돌아갈 위치)를 입력합니다.
- 저장을 클릭합니다. 클라이언트 ID와 클라이언트 시크릿과 함께 “앱이 생성되었습니다!”라는 메시지가 표시됩니다.
- 지금 클라이언트 시크릿을 복사하세요: “위의 클라이언트 시크릿을 저장하세요. 다시는 볼 수 없습니다.” 계속을 클릭합니다.
앱은 클라이언트 ID, 리디렉션 URI, 필요한 범위와 함께 사용자를 https://platform.scratcher.io/oauth/authorize로 보냅니다. 사용자가 Scratcher에 로그인하면 인증 요청이 표시됩니다: “이 애플리케이션이 할 수 있는 작업:” 다음에 범위가 나열됩니다. 사용자는 승인 또는 취소를 클릭합니다. 그런 다음 앱이 https://platform.scratcher.io/oauth/token에서 코드를 토큰으로 교환합니다.
- OAuth 액세스 토큰은 2개월 동안 유효합니다. 리프레시 토큰은 3개월 동안 유효하며, 새 액세스 토큰을 받는 데 사용합니다.
- 이름이나 리디렉션 URI를 바꾸려면 내 앱에서 앱을 클릭해 변경하고 저장을 클릭하세요(“설정이 저장되었습니다”). “시크릿은 나중에 다시 볼 수 없습니다.”
- 앱 삭제는 앱을 제거하며, 모든 사용자의 앱 연결이 작동을 멈춥니다: “이 앱을 삭제하시겠습니까? 되돌릴 수 없습니다!”
승인한 앱
승인된 앱에는 Zapier처럼 계정 액세스 권한을 준 앱이 해당 범위와 함께 나열됩니다. 액세스를 회수하려면 취소를 클릭하세요.
누가 API를 사용할 수 있나요?
API 페이지는 소유자, 관리자, 매니저 역할의 사용자에게 표시됩니다. 토큰은 토큰을 만든 사용자보다 더 많은 작업을 할 수 없습니다.