カスタマーバルクAPI バージョン4

最終更新日：

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

attention.png API連携はサーバーサイドスクリプトのプログラム開発が必要になるため、一定のWeb技術の知識が必要となります。
SATORI APIを利用した貴社システム側との連携方法や実装支援などはサポート範囲外とさせていただいており、
API連携に関してお伝えできる情報としましては、以下マニュアルに掲載されている情報のみとなります。
また、運用開始後にうまく連携されない場合のエラー解析やデバッグ対応についてもサポート範囲外となります。
技術的な知識を有している担当者様、もしくは連携先APIの仕様を理解されている担当者様に相談のうえ実装をご検討ください。

カスタマーバルクAPIについて

カスタマーバルクAPIは通常のカスタマーAPIと違い、一度に多くのデータを登録・更新したい際に利用できるAPIです。

カスタマーデータをCSVファイルに記述し、API呼び出し時にファイルをPOSTすることで、新規もしくは既存のカスタマーをSATORIに登録、更新することができます。

カスタマーバルクAPIの利用方法は下記をご参照ください。

APIキーの取得方法

APIを利用するには以下のAPIキーが必要になります。APIキーはSATORI管理画面より取得できます。

  • user_key: ユーザーアクセスキー
  • user_secret: ユーザーシークレットキー
  • company_key: カンパニーアクセスキー
  • company_secret: カンパニーシークレットキー

取得方法はこちらをご参照ください。

CSVファイルのフォーマット

カスタマーバルクAPIでは、一度に複数のカスタマーデータを登録、更新することができます。登録、更新するカスタマーの内容は、CSVファイルとして作成し、APIを呼び出す際にファイルを指定します。

CSVファイルのフォーマットは以下の項目を含めることができます。また、ファイルの文字エンコーディングはUTF-8にする必要があります。

カスタマーデータ項目

利用できるカスタマーデータの項目は以下の通りになります。

ヘッダー名 日本語名 必須 備考
hashcode ハッシュコード *

SATORIのカスタマーハッシュコード

* APIリクエスト時のパラメータ identity_type に hashcode を指定した場合は必須
email メールアドレス *

メールアドレスに使用できる文字やルール
・メールアドレスとして適切な文字列で半角のみ
・最大255文字
・@の左側に使用できる記号は「-(ハイフン)」「_(アンダースコア)」「.(ドット)」「+(プラス)」
・@の右側（ドメイン）に使用できる記号は「-(ハイフン)」「.(ドット)」

メールアドレスに使用できない文字やルール
・先頭文字に「-(ハイフン)」「.(ドット)」「_(アンダースコア)」は使用できません
NG例：-sample@example.com
          .sample@example.com
          _sample@example.com
・@の直前に「.(ドット)」は使用できません
NG例：sample.@example.com
・@の直後に記号は使用できません
NG例：sample@.example.com
・「.(ドット)」を連続使用はできません
NG例：sample..a@example.com
・日本語は使用できません

* APIリクエスト時のパラメータ identity_type に email を指定した場合は必須
collection_route 情報獲得経路 ◯

最大255文字
lead_company_name 企業名   

最大255文字
department  部署名   

最大255文字
position  役職   

最大255文字
last_name 苗字  

最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
first_name 名前  

最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
last_name_reading 苗字（ふりがな）  

最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
first_name_reading 名前（ふりがな）  

最大255文字
(半角英数字、ひらがな、カタカナ、漢字)
address 住所  

最大255文字 
phone_number 電話番号  

最大255文字 
mobile_phone_number 携帯電話番号  

最大255文字 
web_site Webサイト  

最大255文字 
collection_date 情報獲得日  

日付形式文字列 （yyyy-MM-dd） 
delivery_permission メール配信可否  

以下のいずれかの値を指定
・approval （承認）[デフォルト]
・reject （拒否）
star スター  

以下のいずれかの値を指定
・true （スターを付ける）
・false （スターを付けない）[デフォルト]
status ステータス  

以下のいずれかの値を指定
・regist （未対応）[デフォルト]
・reply （返信済）
・phone （電話済）
・visit （訪問済）
・contract （契約済）
・lost （失注）
memo メモ  

最大500文字
append_tags 追加するタグ  

最大255文字
複数指定する場合は、カンマ区切りで指定
"(" ")" "AND" "NOT" "OR" を含まない文字列
delete_tags 削除するタグ  

最大255文字
複数指定する場合は、カンマ区切りで指定
"(" ")" "AND" "NOT" "OR" を含まない文字列
custom:識別名 カスタマーカスタム項目  

識別名 にはカスタマーカスタム項目管理画面で作成したカスタマーカスタム項目の識別名を指定

入力可能なデータはカスタマーカスタム項目管理画面で設定したデータタイプ、バリデーションタイプに準ずる

 

CSVファイル作成時の注意点

  • CSVファイルを作成する際には必ず1行目にヘッダー行を記載し、2行目以降にカスタマーデータを記載してください。
  • カスタマーデータの任意項目のヘッダー項目は省略することができます。
  • CSVファイルの文字コードはUTF-8にしてください。
  • CSVファイルに含めるカスタマーデータは10,000件以下にしてください。
  • CSVファイルのファイルサイズは10MB程度までにしてください。
  • 大量のデータを処理する場合は一万件以下のデータを複数に分けて直列で「POST処理が正常完了した後、メールでの登録完了通知を待って、又は、処理状況取得APIを使って完了を確認し、次のPOST処理を実行」頂きますようお願いいたします。
  • 初めて実行する場合は、数十件程のデータを用意し作成いただいたCSVデータに問題ないかご確認いただいた後に実行をいただくとスムーズでございます。

CSVファイルのサンプル

作成するCSVファイルのサンプルファイルはこちらからダウンロードできます。CSV作成の際の参考にお使いください。

※Excelで開く場合、文字コードは「UTF-8」を指定してください。

customer_bulk_api_csv_sample.csv

APIの利用方法

新規登録用API

カスタマーバルクAPIの新規登録用APIエンドポイントは、新たなカスタマーを登録したり、既に登録されているカスタマーが存在する可能性があり、そのカスタマーの値を更新したくない場合に利用します。

新規登録用APIでは、登録しようとしているカスタマーが既に存在する場合、以下の項目のみ更新できます。

  • メール配信可否、スター、ステータス
  • タグ
  • まだ値が入っていない項目

リクエスト

URL https://api.satr.jp/api/v4/public/bulk_customers/registration.json
Method POST
Content-Type multipart/form-data
文字コード UTF-8 

 

リクエストパラメータ

パラメータ名 日本語名 必須 備考
user_key ユーザーアクセスキー ◯ 管理画面より取得可能
user_secret ユーザーシークレットキー ◯ 管理画面より取得可能
company_key カンパニーアクセスキー ◯ 管理画面より取得可能
company_secret カンパニーシークレットキー ◯ 管理画面より取得可能
identity_type 識別タイプ ◯ email または hashcode を指定
customer_csv_file CSVファイル ◯ カスタマーデータを記載したCSVファイルを指定

 

customer_csv_file に指定するCSVファイルの文字コードはUTF-8のみ利用できます。CSVファイルに指定できる項目については、上のセクションの「CSVファイルのフォーマット」をご参照ください。

リクエストサンプル

# cURLの例
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/v4/public/bulk_customers/registration.json

 

レスポンス

Content-Type application/json
文字コード UTF-8 

 

成功した場合のレスポンス

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

 

リクエストが成功すると、 process_code が返却されます。この process_code をキーとして処理状況取得APIを呼び出すと、このリクエストの処理状況と処理結果が取得できます。

APIキーが正しくない場合

{
"status": 401,
"message": "Unauthorized"
}

 

リクエストパラメータが正しくない場合

{
"status": 400,
"message": "エラーメッセージ"
}

 

新規登録および更新用API

カスタマーバルクAPIの新規登録および更新用APIエンドポイントは、新たなカスタマーを登録したり、既に登録されているカスタマーの値を更新したい場合に利用します。

リクエスト

URL https://api.satr.jp/api/v4/public/bulk_customers/upsert.json
Method POST
Content-Type multipart/form-data
文字コード UTF-8 

 

リクエストパラメータ

パラメータ名 日本語名 必須 備考
user_key ユーザーアクセスキー ◯ 管理画面より取得可能
user_secret ユーザーシークレットキー ◯ 管理画面より取得可能
company_key カンパニーアクセスキー ◯ 管理画面より取得可能
company_secret カンパニーシークレットキー ◯ 管理画面より取得可能
identity_type 識別タイプ ◯ email または hashcode を指定
customer_csv_file CSVファイル ◯ カスタマーデータを記載したCSVファイルを指定

customer_csv_file に指定するCSVファイルの文字コードはUTF-8のみ利用できます。CSVファイルに指定できる項目については、CSVファイルのフォーマットをご参照ください。

リクエストサンプル

# cURLの例
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/v4/public/bulk_customers/upsert.json

 

レスポンス

Content-Type application/json
文字コード UTF-8 

成功した場合のレスポンス

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

リクエストが成功すると、 process_code が返却されます。この process_code をキーとして処理状況取得APIを呼び出すと、このリクエストの処理状況と処理結果が取得できます。

APIキーが正しくない場合

{
"status": 401,
"message": "Unauthorized"
}

リクエストパラメータが正しくない場合

{
"status": 400,
"message": "エラーメッセージ"
}

 

処理状況取得API

リクエスト

URL https://api.satr.jp/api/v4/public/bulk_customers/status.json
Method GET
Content-Type application/x-www-form-urlencoded
文字コード UTF-8 

 

リクエストパラメータ

パラメータ名 日本語名 必須 備考
user_key ユーザーアクセスキー ◯ 管理画面より取得可能
user_secret ユーザーシークレットキー ◯ 管理画面より取得可能
company_key カンパニーアクセスキー ◯ 管理画面より取得可能
company_secret カンパニーシークレットキー ◯ 管理画面より取得可能
process_code プロセスコード ◯ 登録用API、登録および更新用APIのレスポンスで取得できるプロセスコード
例: csv_customer_process[09aed9d5e940731cde2a3457b506acae]
simply レスポンスの形式   レスポンスの形式を簡易版にする場合 1 を指定

リクエストサンプル

# cURLの例
curl -X GET \
-F "user_key=<ユーザーアクセスキー>" \
-F "user_secret=<ユーザーシークレットキー>" \
-F "company_key=<カンパニーアクセスキー>" \
-F "company_secret=<カンパニーシークレットキー>" \
-F "process_code=csv_customer_process[09aed9d5e940731cde2a3457b506acae]" \
-F "simply=1" \
https://api.satr.jp/api/v4/public/bulk_customers/status.json

レスポンス

Content-Type application/json
文字コード UTF-8 

成功した場合のレスポンス (simply を設定しない場合)

{
"status":200,
"message": "OK",
"body": {
"process_code": "csv_customer_process[09aed9d5e940731cde2a3457b506acae]",
"process_status": "finished",
"requested_at": "2018-02-05T03:04:17Z",
"started_at": "2018-02-05T05:23:50Z",
"finished_at": "2018-02-05T05:23:58Z",
"rows_count": 2,
"processed_count": 2,
"succeeded_count": 1,
"failed_count": 1,
"succeeded_rows": [
{
"row_number": 1,
"customer": {
hashcode: "xxxxxxxx"
}
}
],
"failed_rows": [
{
"row_number": 2,
"message": "validation error: xxx"
}
],
"ttl": 250687
}
}

成功した場合のレスポンス (simply を設定した場合)

{
"status":200,
"message": "OK",
"body": {
"process_code": "csv_customer_process[09aed9d5e940731cde2a3457b506acae]",
"process_status": "finished",
"requested_at": "2018-02-05T03:04:17Z",
"started_at": "2018-02-05T05:23:50Z",
"finished_at": "2018-02-05T05:23:58Z",
"rows_count": 2,
"processed_count": 2,
"succeeded_count": 1,
"failed_count": 1,
"ttl": 250687
}
}

リクエストが成功すると、 process_code の処理状況が返却されます。取得できる項目は以下の通りです。

フィールド名
(カラムは階層を意味します)

 simply 説明
process_code   ◯ プロセスコード 
process_status   ◯ 現在のステータス
・requested （リクエストが受理され、処理の開始を待っています）
・started （登録、更新処理が開始されました）
・finished （すべての処理が終了しました）
requested_at   ◯ ステータスが requested になった時間 
started_at   ◯ ステータスが started になった時間 
finished_at   ◯ ステータスが finished になった時間 
rows_count   ◯ 処理対象の件数 
processed_count   ◯ 処理済みの件数 
succeeded_count   ◯ 成功した件数 
failed_count   ◯ 失敗した件数 
succeeded_rows     登録、更新に成功したカスタマーデータのカスタマー情報がこのキーの配列に格納されます
  row_number    CSV中の行番号（ヘッダーを含む）
  customer     
    hashcode   登録、更新したカスタマーのハッシュコード 
failed_rows     登録、更新に失敗したカスタマーデータがあった場合は、このキーの配列にエラー内容が格納されます 
  row_number    CSV中の行番号（ヘッダーを含む）
  message    エラー内容
ttl   ◯ process_codeの有効期間(秒)

APIキーが正しくない場合

{
"status": 401,
"message": "Unauthorized"
}

process_codeが存在しないか有効期間切れの場合

{
"status": 404,
"message": "NotFound"
}

リクエストパラメータが正しくない場合

{
"status": 400,
"message": "エラーメッセージ"
}

処理状況取得可能期間について

カスタマーバルクAPIの呼び出しが正常に行われると、プロセスコードが発行されます。プロセスコードが発行された直後から処理状況取得APIを呼び出すことが可能です。

プロセスコードには有効期間が設けられており、プロセスコードが発行されてから72時間後に無効化されます。プロセスコードが無効になると、処理状況は取得できなくなります。

また、残りの有効期間を取得するには、処理状況取得APIのレスポンスの ttl フィールドを参照します。

注意事項

・CSV内に同一のメールアドレス（ハッシュコード）が存在していた場合は、最終行に存在するデータのみ反映されます。

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

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

SATORIサポートセンターへ問い合わせる 同じカテゴリーの記事一覧に戻る

関連記事

関連記事