コンテンツへスキップ
AI アシスタントの Rex:面倒な作業はおまかせ、アイデアはあなたのもの 👉 Rex のご紹介

REST APIを使い始める

適切なスコープを持つパーソナルアクセストークンを作成するか、OAuthアプリを登録して、自社のシステムからキャンペーン、リード、リストを読み取りましょう。

Scratcher REST APIを使うと、自社のシステムからキャンペーン、リード、リストの読み取り、リードの追加・更新、商品やプレースメントの管理が行えます。この記事は、APIを設定する開発者向けです。

APIは Webhooks & API を含むプラン(Basic以上)でご利用いただけます。それ以外のプランでは、トークンやアプリを作成するボタンはロックされています。

パーソナルアクセストークンを作成する

パーソナルアクセストークンは、自社のスクリプトやシステムから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 の両方が必要です。プレースメントの作成・変更には、プランに Embed / 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ではエラーが返されます。

制限

リクエストはユーザーごとに1分あたり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 までご連絡いただければ、折り返しご返信します。