PCAクラウド Web-API for kintone – cybozu developer network

はじめに

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

連携のシナリオ

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

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

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

動作環境

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

完成形

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/Kon20/
クライアントID	OAuth クライアントID	404d3114b0a24fcd9480506dxxxxxxxx
クライアントシークレット (*1)	OAuth クライアントシークレット	ciX0UmgbVHa9APBwBYQ7zzXRa25HR5kOxxxxxxxxxxxx
リダイレクト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 へのログインボタンを追加します。
ログイン後にレコード一覧に商魂DⅩのデータ領域と店舗 (部門) を選択するドロップダウンを追加します。
データ領域を選択後に商魂DⅩから部門マスター (MasterBumon) と商品マスター (MasterSms) 、得意先マスター (MasterTms) を取得し、localStorage に保存します。
レコード追加画面の表示時 (app.record.create.show) に明細テーブルに商品マスター行を追加します。
レコードの追加時 (app.record.create.submit) に商魂DⅩに売上伝票データを登録します。

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) し、続けて利用可能な商魂DⅩのデータ領域の取得 (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 からレスポンスを受け取ると「レスポンスボディ(文字列), ステータスコード (数値), レスポンスヘッダー (オブジェクト)」の３つを格納した配列が渡されます。(以下コードの args)

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

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

レコード編集画面の内容を商魂DⅩの売上伝票データの 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 と商魂DⅩ間のどちらかにだけ伝票が登録された状態になりません。