PCAクラウド Web-API for kintone

フォローする

はじめに

本Tipsでは、kintoneと PCAクラウド Web-API との連携方法をサンプルを交えて紹介します。

連携のシナリオ

今回は、kintone で入力した売上伝票を PCAクラウド Web-API (以下 Web-API と記載)と連携して PCA商魂Ⅹ クラウド (以下 商魂Ⅹ と記載) の売上伝票に登録します。

kintone から売上データのレコードを追加時に、同じ内容の売上伝票データを Web-API 連携で商魂Ⅹに登録します。
今回は簡単のため売上伝票データは追加のみで修正、削除は対応しません。

売上伝票の明細に表示する商品マスターも Web-API で取得します。(最大20件)

動作環境

  • kintone スタンダードコース
  • PCAクラウド Web-API
  • PCA商魂Ⅹ クラウド (事前にデータ領域を作成し、部門マスター、商品マスターを数件、得意先マスターを1件登録して下さい。)

完成形

STEP1: kintone アプリの作成

kintone側で以下のように売上伝票データを保存するためのアプリを作成します。

アプリを新規作成し、次のフィールドを配置します。

フィールド名/フィールドコード フィールドタイプ 必須項目 その他
伝票日付   初期値: レコード登録時の日付
伝票No 数値    
データ領域 文字列(1行)  
ユーザー名 文字列(1行)  
店舗コード 文字列(1行)  
店舗名 文字列(1行)  
合計金額 計算   計算式: SUM(金額)
明細 テーブル   テーブル内のパーツは以下の「テーブル (明細)」を参照

テーブル (明細)

フィールド名/フィールドコード フィールドタイプ 必須項目 その他
商品コード 文字列(1行)  
商品名 文字列(1行)  
単価 数値  
数量 数値  
金額 計算   計算式: 単価 * 数量

作成したアプリのレコード追加画面

STEP2: Developers Console にアプリを登録

デベロッパー向け導入ドキュメントStep1~3 に従って PCAクラウド Web-API の Developers Console に作成した kintone アプリを登録します。

「リダイレクトURL」に STEP1 で作成した kintone アプリのURLを入力してください。(例: "https://mycompany.cybozu.com/k/36/")
「使用するPCAのAPI」に今回は「PCA商魂・商管Ⅹ」を選択します。
それ以外は任意の値を入力します。

STEP3: アプリにプラグインを追加・設定する

kintone のアプリに次の kintone プラグイン「PCAクラウド Web-API for kintone」を追加します。

pcawebapi-plugin.zip

プラグインの追加方法は次の kintone ヘルプを参照して下さい。

アプリにプラグインを追加する

次にプラグインを設定します。

1. アプリ管理画面の [詳細設定] >[プラグイン] を開き、PCAクラウド Web-API for kintone の歯車マークをクリックします。

2. 各項目を設定します。

項目名 説明
PCAクラウド Web-API ルートURL (*1) Web-API のエンドポイントURL https://east02.pcawebapi.jp/v1/Kon10
クライアントID OAuth クライアントID 404d3114b0a24fcd9480506d35395b78
クライアントシークレット (*1) OAuth クライアントシークレット ciX0UmgbVHa9APBwBYQ7zzXRa25HR5kO+OOlpPVObrg=
リダイレクトURL OAuth リダイレクトURL
kintone アプリのURLを設定して下さい。
https://mycompany.cybozu.com/k/36/
サービス認証ID (*1) PCAクラウドサービスに対する認証ID 028920xx
サービス認証パスワード (*1) PCAクラウドサービスに対する認証パスワード xxxxxx

(*1) アプリの画面からはアクセスできない秘密の設定項目です。

3. [保存] をクリックします。

4. [アプリの設定] 画面で [設定完了] をクリックすると、プラグインの設定がアプリに反映されます。

STEP4: サンプルプログラム

サンプルプログラムを追加します。

サンプルプログラムは以下の機能を提供します。

  • レコード一覧に Web-API へのログインボタンを追加します。
  • ログイン後にレコード一覧に商魂Ⅹのデータ領域と店舗 (部門) を選択するドロップダウンを追加します。
  • データ領域を選択後に商魂Ⅹから部門マスター (MasterBumon) と商品マスター (MasterSms) 、得意先マスター (MasterTms) を取得し、localStorage に保存します。
  • レコード追加画面の表示時 (app.record.create.show) に明細テーブルに商品マスター行を追加します。
  • レコードの追加時 (app.record.create.submit) に商魂Ⅹに売上伝票データを登録します。

1. アプリ管理画面の [詳細設定] > [JavaScript / CSSでカスタマイズ] の [PC用のJavaScriptファイル] に次の Javascript を追加します。

追加方法 追加する Javascript
URL指定で追加 https://js.cybozu.com/jquery/2.1.4/jquery.min.js
URL指定で追加 https://js.cybozu.com/momentjs/2.10.3/moment-with-locales.min.js
アップロードして追加 サンプルプログラム (plugin_sample.js) 

※ Javascript はこの順番に設定して下さい。
※「plugin_sample.js」は上記リンクよりダウンロード後zipファイルを展開して、JavaScriptファイルを取り出してください。

2. [保存] をクリックします。

3. [アプリの設定] 画面で [設定完了] をクリックすると、Javascript がアプリに反映されます。

サンプルプログラム 解説

plugin_sample.js の内容を見ていきましょう。

プログラム中の pca.webapi で始まる関数はプラグイン PCAクラウド Web-API for kintone で提供される APIです。
詳細は以下の文書を参照して下さい。

PCAクラウド Web-API for kintone Javascript API

レコード一覧画面の表示時 (app.record.index.show) にヘッダースペースに認証ボタンを追加します。

ボタンクリックで Web-API へログイン (pca.webapi.login) し、続けて利用可能な商魂Ⅹのデータ領域の取得 (pca.webapi.findDataArea) およびログオン中のユーザー情報を取得 (pca.webapi.getLogOnUser) します。
取得した情報は localStorage に保存します。

これらの pca.webapi 関数は kintone.Promise を返す非同期関数なので then() でメソッドチェーンをつないでいます。

最後の updateRecordHeaderSpace は localStorage に保存したマスターの内容からデータ領域の選択ドロップダウンなどのヘッダー要素を追加します。

データ領域のドロップダウン変更時の onAreaChange では使用するデータ領域を選択(pca.webapi.selectDataArea) した後、pca.webapi.send で部門マスターと商品マスター、得意先マスターを取得します。

pca.webapi.send は Web-API へリクエストを送信する基本的な関数です。
プラグイン設定でセットした Web-API のURL にリクエストを送信します。

今回は返り値の kintone.Promise をメソッドチェーンで繋いでいますが、第5引数 callback, 第6引数 error を指定してコールバック型の記述もできます。 なお callback を指定すると kintone.Promise オブジェクトは返されません。

Web-API からレスポンスを受け取ると「レスポンスボディ(文字列), ステータスコード (数値), レスポンスヘッダー (オブジェクト)」の3つを格納した配列が渡されます。(以下コードの args)

レスポンスボディは文字列型なので、JSON データとして扱うには JSON.parse でパースする必要があることに注意して下さい。

次にレコードの追加イベント (app.record.create.submit) です。

レコード編集画面の内容を商魂Ⅹの売上伝票データの JSON オブジェクトに変換 (createInpuSYK) し、Web-API 「Create/InputSYK」 に POST して登録します。
売上伝票データの得意先は得意先マスターの最初の一件が自動的にセットされます。

Create/InputSYK が成功したかを HTTPステータスコード (args[1]) で判定し、OK (200) ならレスポンスボディを売上伝票登録の結果データ BEKonIntegrationResultOfBEInputSYK 型の JSON オブジェクトとして受け取ります。
登録した伝票の伝票番号 (BEKonIntegrationResultOfBEInputSYK.Target.InputSYKH.DenpyoNo) を kintone のレコードにフィードバックします。

エラーの場合は event.error にエラーメッセージを設定します。これにより kintone はレコードの追加をキャンセルするので kintone と商魂Ⅹ間のどちらかにだけ伝票が登録された状態になりません。

動作チェック

事前に商魂Ⅹ クラウドでデータ領域を作成して、部門マスター、商品マスターを数件、得意先マスターを1件登録しておきます。

アプリを開き「PCAクラウド Web-API へログイン」をクリックします。

システムユーザーログイン画面が表示されますのでシステムユーザーIDとパスワードを入力して [ログオン] をクリックします。
システムユーザーログイン画面が表示されない場合はプラグインの設定を確認して下さい。

アプリケーションの承認画面が表示されますので [データの利用を許可する] をクリックします。

ヘッダースペースにデータ領域欄と店舗欄が追加されます。 データ領域と店舗を選択してレコードの追加ボタン(+)をクリックします。

明細テーブルに商魂Ⅹの商品マスターが追加されています。
「数量」を入力して [保存] をクリックします。 商魂Ⅹに売上伝票が登録されます。 (2~5秒かかります)

登録が成功したら商魂Ⅹ クラウドの [販売管理]-[売上]-[売上明細表] で伝票が登録されていることを確認しましょう。

 

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

ログインしてコメントを残してください。
Powered by Zendesk