2021/11/11のUI刷新 第一弾リリースにてカラースキーム(配色設計)とタイポグラフィ(文字の書体、大きさ、配列のしかたなど)を変更しております。オンラインマニュアルに掲載している画面キャプチャと実際の管理画面の配色や文字の状態が異なる場合がございますがご了承いただけますと幸いでございます。
SATORI APIを利用した貴社システム側との連携方法や実装支援などはサポート範囲外とさせていただいており、
API連携に関してお伝えできる情報としましては、以下マニュアルに掲載されている情報のみとなります。
また、運用開始後にうまく連携されない場合のエラー解析やデバッグ対応についてもサポート範囲外となります。
技術的な知識を有している担当者様、もしくは連携先APIの仕様を理解されている担当者様に相談のうえ実装をご検討ください。
目次
- カスタマーバルクAPIについて
- CSVファイルのフォーマット
- 新規登録用API (registration.json)
- 新規登録および更新用API (upsert.json)
- 処理状況取得API (status.json)
- レスポンスについて
- 処理状況取得可能期間について
- 注意事項
カスタマーバルクAPIについて
カスタマーバルクAPIは通常のカスタマーAPIと違い、一度に多くのデータを登録・更新したい際に利用できるAPIです。
カスタマーデータをCSVファイルに記述し、API呼び出し時にファイルをPOSTすることで、新規もしくは既存のカスタマーをSATORIに登録、更新することができます。
カスタマーバルクAPIの利用方法は下記をご参照ください。
前提事項
カスタマーバルクAPI バージョン4では以下3種類のAPIを提供しています。
- 新規登録用API : registration.json
- 新規登録および更新用AP : upsert.json
- 処理状況取得API : status.json
管理画面から取得する項目
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 を指定した場合は必須 |
| メールアドレス | * |
メールアドレスに使用できる文字やルール メールアドレスに使用できない文字やルール * 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 | メール配信可否 |
以下のいずれかの値を指定 |
|
| star | スター |
以下のいずれかの値を指定 |
|
| status | ステータス |
以下のいずれかの値を指定 |
|
| memo | メモ |
最大500文字 |
|
| append_tags | 追加するタグ |
最大255文字 |
|
| delete_tags | 削除するタグ |
最大255文字 |
|
| 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 (registration.json)
カスタマーバルクAPIの新規登録用APIエンドポイントは、新たなカスタマーを登録したり、既に登録されているカスタマーが存在する可能性があり、そのカスタマーの値を更新したくない場合に利用します。
新規登録用APIでは、登録しようとしているカスタマーが既に存在する場合、以下の項目のみ更新できます。
- メール配信可否、スター、ステータス
- タグ
- まだ値が入っていない項目
リクエストについて
- Content-Type : multipart/form-data
- 文字コード : UTF-8
- APIのURL : https://api.satr.jp/api/v4/public/bulk_customers/registration.json
- Method : POST
- 送信するパラメータリスト
| パラメータ名 | 日本語名 | 必須 | 備考 |
| 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
新規登録および更新用API (upsert.json)
カスタマーバルクAPIの新規登録および更新用APIエンドポイントは、新しいカスタマーを登録する場合や、既存のカスタマー情報を更新する場合に利用します。
※ただし、既に値が登録されている項目について、CSVデータ内で空白値が指定されている場合、登録済みの値はそのまま保持され、空白値で上書きされません。
リクエストについて
- Content-Type : multipart/form-data
- 文字コード : UTF-8
- APIのURL : https://api.satr.jp/api/v4/public/bulk_customers/upsert.json
- Method : POST
- 送信するパラメータリスト
| パラメータ名 | 日本語名 | 必須 | 備考 |
| 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
処理状況取得API (status.json)
リクエストについて
- Content-Type : application/x-www-form-urlencoded
- 文字コード : UTF-8
- APIのURL : https://api.satr.jp/api/v4/public/bulk_customers/status.json
- Method : GET
- 送信するパラメータリスト
| パラメータ名 | 日本語名 | 必須 | 備考 |
| 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 |
成功時のレスポンス
- 新規登録用API （registration.json） ・ 新規登録および更新用API （upsert.json）
リクエストが成功すると、 process_code が返却されます。この process_code をキーとして処理状況取得APIを呼び出すと、このリクエストの処理状況と処理結果が取得できます。{
"status": 202,
"message": "Accepted",
"body": {
"process_code": "csv_customer_process[09aed9d5e940731cde2a3457b506acae]"
}
} - 処理状況取得API (status.json)
・ 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 （registration.json） ・ 新規登録および更新用API （upsert.json）
APIキーが正しくない場合
{
"status": 401,
"message": "Unauthorized"
}リクエストパラメータが正しくない場合
{
"status": 400,
"message": "エラーメッセージ"
} - 処理状況取得API (status.json)
APIキーが正しくない場合
{
"status": 401,
"message": "Unauthorized"
}process_codeが存在しないか有効期間切れの場合
{
"status": 404,
"message": "NotFound"
}リクエストパラメータが正しくない場合
{
"status": 400,
"message": "エラーメッセージ"
}
処理状況取得可能期間について
カスタマーバルクAPIの呼び出しが正常に行われると、プロセスコードが発行されます。プロセスコードが発行された直後から処理状況取得APIを呼び出すことが可能です。
プロセスコードには有効期間が設けられており、プロセスコードが発行されてから72時間後に無効化されます。プロセスコードが無効になると、処理状況は取得できなくなります。
また、残りの有効期間を取得するには、処理状況取得APIのレスポンスの ttl フィールドを参照します。
注意事項
CSV内に同一のメールアドレス（ハッシュコード）が存在していた場合は、最終行に存在するデータのみ反映されます。