バッチAPI連携

2025.05.26

注意

Sales Force Assistantシリーズまたはnyoiboxを導入時、表示されます。

バッチAPI連携は、他システム側から要求された任意の情報を送受信する機能です。また送信の際には、他システムから指定された条件に当てはまる情報のみを送信することも可能です。送信または受信した結果は、送受信が終了した際にCSV形式で出力され、確認することができます。運用管理のアクセスログからも、送信、出力の履歴を確認することができます。

送受信可能な情報
Sales Force Assistantシリーズは以下の通りです。
顧客情報、パーソン情報、納入機器（顧客創造R、顧客深耕Rのみ）、フリーフォーム
nyoiboxは以下の通りです。
フォームBOX、Priv.BOX（※BOXのアクセス権が設定されている場合は対象外）
送信のみ可能な情報
商談情報、業務情報
受信のみ可能な情報
売上情報

補足

バッチAPI連携の条件について
本機能は、他システムから要求された情報を送信、また、他システムから送信された情報を受信する機能を提供しています。他システム側に弊社製品のAPIに対応した機能が必要です。また、HTTPまたはHTTPS通信によるPOSTメソッド方式のみの対応となります。送受信される情報やパスワード等の暗号化が必要な場合は、HTTPS通信にてご利用ください。Windows版をIISにてご利用の場合は別途SSL証明書が必要となります。
バッチAPIの「認証ログイン社員」について
Sales Force Assistantシリーズの情報を送受信する場合、「認証ログイン社員」にはSales Force Assistantライセンスを保有している社員を設定してください。Sales Force Assistantライセンスのない社員を設定した場合、バッチAPIを実行すると権限エラーとなります。バッチAPI設定を行う社員についてもSales Force Assistantライセンスを保有しているシステム管理者にて実施してください。

注意

設定項目「文字コード」と、APIの利用元が送信する文字列の文字コードが一致していない場合、システムエラーが発生する可能性があります。

受信バッチAPI

受信バッチAPIを設定する

システム設定の「運用管理」より「バッチAPI連携」の「受信バッチAPI」を選択します。
⇒「バッチAPI連携／受信バッチAPI」画面が表示されます。
受信する情報を選択します。
必要事項を入力し、最後に「保存」ボタンをクリックします。

【例】顧客情報の場合

番号	説明
１	送信元の情報に合わせ文字コードを選択します。
２	送信元の情報と弊社製品の情報を特定する連携キーを選択します。
３	情報を受信する際、このアドレスを他システムに設定します。
４	選択した社員の権限により登録・更新します。
５	データ取込時の登録レイアウトを選択します。
６	受信したい情報にチェックを入れます。
７	受信先のコントロール名を設定します。任意の名前に変更可能です。

項目	説明
使用区分	バッチAPI連携を使用するかしないかを設定します。
受信情報名	※nyoiboxの受信バッチAPIを新規登録する場合に設定する項目です。受信情報を選択します。
受信API名	※nyoiboxの受信バッチAPIを新規登録する場合に設定する項目です。受信バッチAPIの設定名を入力します。
入力言語	入力言語を選択します。
文字コード	送信元の文字コードを選択します。
連携キー設定	送信元の情報と弊社製品の情報を特定する連携キーを選択します。顧客情報またはパーソン情報の場合は「システムID」「コード」、納入機器の場合は「システムID」「機種・機番」「納入機器コード」、売上情報の場合は「システムID」「伝票番号」、フリーフォームの場合は「システムID」、フォームBOXまたはPriv.BOXの場合は「システムID」から選択することができます。
送信先URL	他システムから情報を受信する際に使用する、弊社製品の情報受付用URLです。
APIパスワード	情報受信バッチAPIを使用する際に必要なパスワードを入力します。ここで設定したパスワードを送信元（他システム）から送付し、内容が一致していれば情報を取り込みます。 ※APIパスワードのコントロール名は「apipasswd」となります。
認証ログイン社員	情報受信バッチAPIを利用する社員を選択します。APIパスワードが一致すると、バッチAPI連携にて情報を受信した際の登録・更新処理はこの社員の権限で行なわれます。選択できる社員はシステム管理権限を持つ社員のみとなります。
レイアウト	データ取込時の登録レイアウトを設定します。レイアウトを指定しない場合新規登録時は基本レイアウトで登録されます。更新時はデータ毎の登録レイアウトを維持します。対象業務は、以下の通りです。顧客情報、パーソン情報、納入機器、フリーフォーム
使用	他システムから受信する情報をチェックします。
情報名	情報の名称が表示されます。
コントロール名	HTMLコントロール名を設定します。送信元に合わせた任意の名前に変更します。
標準コントロール名	デフォルトで設定されたコントロール名が表示されます。

補足

バッチAPI連携では、受信項目として使用する、使用しないを選択できます。しかし、登録時に必須の項目がある場合、以下のような制約があります。

「APIパスワード」は、常に選択状態で固定しています。
フォーム設定で必須とした項目は、選択状態で固定しています。設定後、非表示となった場合は、連携時に該当項目の更新は行いません。
「上位会社」を選択時は、「上位会社/顧客コード」、「上位会社/TEL」は選択状態で固定しています。
連携キー設定で「システムID」が選択されている場合は、「システムID」を選択状態で固定しています。
連携キー設定で「コード」が選択されている場合は、「コード」を選択状態で固定しています。
初期状態は、すべてに項目にチェックが入っている状態にしています。
複数の連携設定は使用できません。

受信に関する注意点

■全般

「APIが使用できません。」のエラーについて
送信元（他システム）から情報を送信後に表示される受信APIコール結果画面において、「APIが使用できません。」と表示される場合、対象の情報受信APIが「使用しない」に設定されている場合があります。対象APIの設定を確認してください。また、受信パスワードが一致していない可能性もあります。「受信バッチAPI設定」の「APIパスワード」と共に、送信側の設定でパスワードを設定しなおしてください。
受信した情報の文字化け
送信側から出力されている文字コードと、受信側で設定した文字コードが一致していないことが原因と考えられます。「文字コード」項目をご確認ください。
社員項目に部署のみ指定した場合
部署と社員を指定する社員項目に部署のみ指定した場合、下記のエラーが発生します。
エラーメッセージ例「サービス担当者: 登録済みの社員名を入力してください。」
社員項目に部署を指定する場合は必ず社員名を指定してください。
情報受信バッチAPIの返却値について
情報受信バッチAPIを実行した際の返却値について説明します。
1行目
　1列目：実行されたAPIのURL
　2列目：APIを実行したクライアント情報
　3列目：文字コードナンバー（0：Shift_JIS、1：EUC-JP、2：UTF-8）
　4列目：連携キー設定（0：システムID、1：コード又は機種機番、売上番号）
　5列目：送信された情報数
　6列目：登録又は更新された件数
　7列目：エラー件数
2行目以降は送信された情報に対する処理結果
　1列目：送信された情報の行数
　2列目：連携キー設定がシステムIDの場合はシステムID（システムID以外の場合は空白）
　3列目：処理ステータス（1：正常、0：処理異常）
　4列目：エラーが発生した場合のみ、エラーコード
　5列目：エラーが発生した場合のみ、エラー内容
案件情報を関連情報として取り込む場合について
納入機器に案件情報を関連付けて登録する際に案件名のみ指定して取り込んだ場合、顧客情報をもとに登録されます。取込先の顧客情報と関連情報として取り込む案件情報の顧客情報からデータを特定できなかった場合は取り込めません。詳細は、システム設定マニュアル「CSV入力」＞「案件情報を関連情報として取り込む場合」を参照してください。

■顧客情報

顧客コードについて
送信元に一意な顧客コードが付与されていない場合、顧客情報が正しく更新できない場合があります。重複チェック（システム設定＞Sales Force Assistant＞顧客情報＞重複チェック）の設定の「顧客コード未入力は除外コードと見なす」が未チェックの場合、連携APIを通して顧客コードが未入力の顧客情報を登録すると、2件目以降は常に上書き更新されます。
※顧客名が全く異なる別顧客であっても、顧客コードが未入力同士で一致したと判断いたします。

送信元に一意な顧客コードが存在しない場合は、除外コードを付与して送信してください。除外コードが付与されている顧客情報は顧客名が一致する場合は更新され、一致しない場合は新規登録されます。送信元で顧客名の変更を行い連携した場合は、顧客名が一致しなくなるため新規登録されます。二重登録となってしまった顧客情報は統合機能を利用して統合してください。
当社担当者とサブ担当者について
顧客情報の当社担当者・サブ担当者には登録済みの社員が設定される必要があります。API連携で顧客情報を受信した場合、社員登録されていない社員が担当者として登録されていると、下記のエラーが発生します。
「[当社担当者]は存在しておりません。」
この場合、担当者として登録してある社員情報を受信側にも登録していただく必要があります。

■パーソン情報

未入力項目の顧客情報からの自動補完について
パーソン情報のTEL・FAX・郵便番号・住所・ビル名等・URL・当社担当者のいずれかが未入力の場合、顧客情報から自動補完されます。顧客情報と同じ内容をパーソン情報へ入力する手間を省けます。以下の注意事項をご確認後、ご活用ください。

入力したTEL・FAXのいずれかが顧客情報と異なる場合、未入力のTEL・FAXは自動補完されません。
入力した郵便番号・住所・ビル名等のいずれかが顧客情報と異なる場合、未入力の郵便番号・住所・ビル名等・TEL・FAXは自動補完されません。
未入力のURL・当社担当者はその他の欄に関わらず自動補完されます。

■売上情報

データの集計について
同一の連携キー(伝票番号または、システムID)のデータを受信した場合、データは上書きされます。伝票単位での売上実績データは不要で、顧客別月別の売上実績データだけで良い場合は、顧客別月別に集計された売上実績データを送信側で作成し、一意な伝票番号を設定して連携することで、日次でのデータ更新も可能です。

補足

社員の登録は、以下の画面から登録できます。

システム設定＞基本設定＞社員＞社員一覧　より社員を新規登録
システム設定＞基本設定＞社員＞社員CSV読み込み
または社員情報受信APIを利用しての登録も可能となっております。

■nyoibox（フォームBOX・Priv.BOX）

設定数について
クラウドサービスの場合、設定の上限数は20個です。

送信バッチAPI

送信バッチAPIを設定する

システム設定の「運用管理」より「バッチAPI連携」の「送信バッチAPI」を選択します。
⇒「バッチAPI連携／送信バッチAPI」画面が表示されます。
「新規登録」ボタンをクリックします。
⇒新規登録画面が表示されます。
必要事項を入力し、最後に「保存」ボタンをクリックします。

【例】顧客情報の場合

番号	説明
１	送信先の情報に合わせ文字コードを選択します。
２	閲覧制限を適用するかしないかを設定します。
３	送信したい情報にチェックを入れます。
４	送信先に合わせ任意の名前に変更します。

項目	説明
使用区分	バッチAPI連携を使用するかしないかを設定します。
出力言語	出力言語を選択します。
送信バッチAPI名	送信バッチAPI名を任意に入力します。
送信情報	送信したい情報をプルダウンより選択します。
送信先URL	他システムから弊社製品に情報を送信する際のURLです。
文字コード	送信先の文字コードを選択します。
APIパスワード	送信バッチAPIを使用する際に必要なパスワードを入力します。ここで設定したパスワードを受信元（他システム）から送付し、内容が一致していれば情報を送信します。 ※APIパスワードのコントロール名は「apipasswd」となります。
認証ログイン社員	送信バッチAPIを利用する社員を選択します。選択できる社員はシステム管理権限を持つ社員のみとなります。APIパスワードが一致すると、API送信処理はこの社員の権限で行われます。
閲覧制限	バッチAPI送信時に閲覧制限を適用するかしないかを選択します。適用する：「認証ログイン社員」で選択した社員の閲覧権限にしたがって、情報を抽出し、送信します。適用しない：「認証ログイン社員」で選択した社員の閲覧制限に関わらず、全ての情報を抽出し、送信します。 ※閲覧制限を「適用しない」かつ、送信する項目として「閲覧制限」を使用する場合、制限のかかっているものは「1」、かかっていないものは「0」としてCSVに抽出、送信されます。
レイアウト	送信対象となるレイアウトを選択します。 ※商談の場合のみ表示されます。
使用	他システムへ送信する情報にチェックを入れます。
情報名	情報の名称が表示されます。
コントロール名	送信先のHTMLコントロール名を設定します。送信先に合わせた任意の名前に変更します。
標準コントロール名	デフォルトで設定されたコントロール名が表示されます。
項目追加・除外、追加した項目をすべて除外	※送信情報にnyoiboxを選択している場合、表示されるボタンです。「項目追加・除外」ボタンをクリックして、項目を選択します。BOXにマスター選択を表示している場合、マスター選択先の項目も送信できます。関連情報は5つまで、各情報の項目を10項目まで選択できます。コントロール名は必要に応じて送信先に合わせた任意の名前に変更してください。
追加固定項目	上記の標準コントロール名にある情報以外の項目を追加して送信できます。「行追加」ボタンをクリックして、「情報名」「コントロール名」「送信する値」を入力します。 ※固定項目には、ログイン社員のログインID、パスワード、社員コード、サーバー日時を予約語として指定できます。

補足

他システム側から弊社製品に情報の送信を要求する際、条件を指定できます。指定した期間の商談や、指定した範囲のコード番号内の情報のみを送信するよう要求できます。条件の指定方法は以下の通りです。

APIパスワード
コントロール名：apipasswd
他システム側から弊社製品に情報の送信を要求する際には、APIパスワードに入力された情報を上記コントロール名で必ず送信してください。
システムID
コントロール名：systemid
半角カンマ区切りで、複数の指定がが可能です。
コード（顧客コード、パーソンコード、納入機器コード）
コントロール名：code
半角カンマ区切りで、複数の指定が可能です。また、半角ハイフン（-）区切りにて、範囲を指定できます。ただし、カンマ、ハイフンを交えた複数指定、複数の範囲指定はできません。
更新日From～To
コントロール名（取得開始日)：dateFrom
コントロール名（取得終了日)：dateTo
日付形式は、YYYY/MM/DDの10桁で指定してください。
商談日From～To
コントロール名（取得開始日)：busdateFrom
コントロール名（取得終了日)：busdateTo
日付形式は、YYYY/MM/DDの10桁で指定してください。
業務日From～To
コントロール名（取得開始日)：taskdateFrom
コントロール名（取得終了日)：taskdateTo
日付形式は、YYYY/MM/DDの10桁で指定してください。

※システムID、コード、更新日は、AND条件で絞り込みます。未入力（””）の場合は、未指定となります。

※顧客コードなどのコード情報は、商談情報、業務情報を抽出する場合にはコードが存在しないため指定が無効となります。

※更新日は、商談情報、業務情報の場合のみ秒単位まで指定できます。
　表記例：YYYY/MM/DD hh:mm:dd

出力されるCSVの各列は以下の通りです。
1列目：実行されたAPIのURL
2列目：APIを実行したクライアント情報
3列目：文字コードナンバー（0：Shift_JIS、1：EUC-JP、2：UTF-8）
4列目：検索条件：システムID
5列目：検索条件：コード
6列目：検索条件：取得開始日
7列目：検索条件：取得終了日
8列目：1:正常 0:エラー発生
9列目：出力件数
10列目：エラーコード
11列目：エラー内容

送信に関する注意点

■商談情報

送信する情報について
商談情報を抽出する場合、対象件数が膨大な量になることが予想されるため、必ず商談日を指定して抽出を行ってください。商談日の指定は、商談情報を抽出する場合のみ、業務日の指定は、業務情報を抽出する場合のみ指定できます。