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

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データに問題ないかご確認いただいた後に実行をいただくとスムーズでございます。