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

カスタマーバルク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文字
(メールアドレスとして適切な文字列で半角のみ)

* 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処理が正常完了した後、メールでの登録完了通知を待って、次のPOST処理を実行」頂きますようお願いいたします。
  • 初めて実行する場合は、数十件程のデータを用意し作成いただいたCSVデータに問題ないかご確認いただいた後に実行をいただくとスムーズでございます。

CSVファイルのサンプル

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

customer_bulk_api_csv_sample-2018-02-14.txt

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_sercret ユーザーシークレットキー 管理画面より取得可能
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_sercret ユーザーシークレットキー 管理画面より取得可能
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_sercret ユーザーシークレットキー 管理画面より取得可能
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 フィールドを参照します。