Scratcher REST APIを使うと、自社のシステムからキャンペーン、リード、リストの読み取り、リードの追加・更新、商品やプレースメントの管理が行えます。この記事は、APIを設定する開発者向けです。
APIは Webhooks & API を含むプラン(Basic以上)でご利用いただけます。それ以外のプランでは、トークンやアプリを作成するボタンはロックされています。
パーソナルアクセストークンを作成する
パーソナルアクセストークンは、自社のスクリプトやシステムからAPIを呼び出す最も手軽な方法です。
- 設定 > API(開発者の下)に移動します。
- パーソナルアクセストークンで、パーソナルアクセストークンを作成をクリックします。ダイアログに「APIリクエストを認証するためのトークンを生成します。」と表示されます。
- 後で見分けやすい名前(例:「データウェアハウス」)を付けます。
- スコープで、トークンに許可する操作を選択します(下記参照)。すべて選択ですべてのスコープが選ばれます。トークンには必要最小限のアクセス権のみを付与してください。
- 保存をクリックします。「アクセストークンが作成されました」と表示されます。
- シークレットの下に表示されたトークンをコピーします。「上記のシークレットを保存してください。表示されるのはこの一度だけです。」パスワードマネージャーなど、安全な場所に保管してください。
- 閉じるをクリックします。
トークンはユーザーに紐づきます。選択したスコープの範囲で、あなたがメンバーになっているすべての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アプリを登録してください。
- 設定 > 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 ページは、オーナー、管理者、マネージャーのロールを持つユーザーに表示されます。トークンが作成したユーザーの権限を超える操作を行うことはできません。