【旧バージョン】BulkAPIバージョン3の利用方法について

2021/11/11のUI刷新第一弾リリースにてカラースキーム(配色設計)とタイポグラフィ(文字の書体、大きさ、配列のしかたなど)を変更しております。オンラインマニュアルに掲載している画面キャプチャと実際の管理画面の配色や文字の状態が異なる場合がございますがご了承いただけますと幸いでございます。

BulkAPIは、通常のAPIと違い、一度に多量のデータを登録・更新したい際に利用できるAPIです。

CSVの形でデータを連携していただくことで、新規もしくは既存のカスタマーデータをSATORIに登録・更新することができます。

BulkAPIを利用する場合には下記をご参照ください。

※本ページに記載している「BulkAPIバージョン3」は旧APIとなり、新APIの「BulkAPIバージョン4」への移行をお願いしております。
詳細につきましてはAPIバージョン4の利用方法についてをご参照くださいませ。

APIリクエスト

データの登録・更新完了時にリクエスト時に指定したAPIキーに紐付くユーザーのメールアドレス宛てにお知らせメールが届きます。CSV内のデータに不備がありエラーが発生した場合は、そのメールに該当のエラー箇所とエラー内容が記載されています。

URL

新規登録用 : https://api.satr.jp/api/v3/public/bulk_customers/registration.json
新規登録および更新用 : https://api.satr.jp/api/v3/public/bulk_customers/upsert.json

ヘッダ

Content-Type : multipart/form-data
文字コード : utf-8

パラメータ

user_key => 'ユーザーアクセスキー', #（管理画面より取得）
user_secret => 'ユーザーシークレットキー', #（管理画面より取得）
company_key => 'カンパニーアクセスキー', #（管理画面より取得）
company_secret => 'カンパニーシークレットキー', #（管理画面より取得）
identity_type => 'email' or 'hashcode'
customer_csv_file => <CSVファイル>

CSVファイル内容

ファイルテンプレート : こちらからダウンロードしてください。

CSVファイルエンコード : UTF-8

カラム	項目名	必須	補足
hashcode	hashcode	-	identity_typeでhashcodeを指定した場合は必須
email	メールアドレス	○
lead_company_name	企業名	-
department	部署名	-
position	役職	-
phone_number	電話番号	-
mobile_phone_number	携帯電話番号	-
delivery_permission	配信許可	-	approval (承認) reject (拒否)
last_name	苗字	-
first_name	名前	-
web_site	Webサイト	-
address	住所	-
collection_route	情報獲得経路	-
collection_date	情報獲得日	-
status	ステータス	-	regist (未対応) reply (返信済) phone (電話済) visit (訪問済) contract (契約済) lost (失注)
star	スター	-	true (有) false (無)
append_tags	追加タグ	-	カンマ区切りで複数指定可
delete_tags	削除タグ	-	カンマ区切りで複数指定可

レスポンスについて

JSONフォーマットでレスポンスが返されます。
この場合に返される失敗とは「CSVファイルが受付されていない」「APIキーが間違っている」等になります。
※CSVデータ内のエラー内容やエラー箇所はお知らせメールにて詳細の記載があり、JSONフォーマットのレスポンスには記載されません。

レスポンスは以下の種類があります。

成功


{
  "status": 202,
  "message": "Accepted",
  "body": {
    "process_code": "csv_customer_process[09aed9d5e940731cde2a3457b506acae]"
  }
}

失敗


{
  "status": 400 or 401,
  "message": "エラー内容"
}


{
  "status": 500,
  "message": "Error"
}

500エラーの場合アップロードされたCSVフォーマットが正しくない可能性がございます。
今一度データの内容のご確認をお願いいたします。

BulkAPIリクエストサンプル

curl -X POST \
     -F "user_key=<ユーザーアクセスキー>" \
     -F "user_secret=<ユーザーシークレットキー>" \
     -F "company_key=<カンパニーアクセスキー>" \
     -F "company_secret=<カンパニーシークレットキー>" \
     -F "identity_type=email" \
     -F "customer_csv_file=@/data/file/customer.csv;type=text/csv" \
     https://api.satr.jp/api/v3/public/bulk_customers/upsert.json

アップロードファイルのテンプレート

こちらからダウンロードしてください。

※中身は適切な記述に変えてご利用下さい。

注意点

・BulkAPIリクエストのサイズは 16MB 以下にしてください。リクエスト全体のサイズが16MB以下となるようCSVのサイズは余裕をもって10MB程度までとしてください。
・一度に登録するCSV内の件数は一万件以下にしてください。
・現在カスタマーカスタム項目には対応しておりません。ご了承くださいませ。
・大量のデータを処理する場合は一万件以下のデータを複数に分けて直列で「POST処理が正常完了した後、メールでの登録完了通知を待って、次のPOST処理を実行」頂きますようお願いいたします。
・初めてBulkAPIを実行する場合は、数十件程のデータを用意し作成いただいたCSVデータに問題ないかご確認いただいた後に実行をいただくとスムーズでございます。