본문으로 건너뛰기
AI 어시스턴트 Rex: 번거로운 일은 맡기고, 아이디어는 여러분의 것으로 👉 Rex 만나기

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을 요청하세요.

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 앱을 등록하세요.

  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 페이지는 소유자, 관리자, 매니저 역할의 사용자에게 표시됩니다. 토큰은 토큰을 만든 사용자보다 더 많은 작업을 할 수 없습니다.

도움이 필요하신가요?

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

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

  • 채팅 문의

    로그인한 뒤 오른쪽 아래의 채팅 버튼을 클릭하세요. Rex가 바로 답하고, 팀과도 클릭 한 번으로 연결됩니다.

  • 미팅 예약

    팀과의 무료 30분 화상 통화: 둘러보기, 캠페인 아이디어, 설정 지원.

  • 이메일 문의

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