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

この記事は役に立ちましたか?

0人中0人がこの記事が役に立ったと言っています