FileMaker

FileMakerとクラウド会計ソフトfreeeをAPI接続する7つのステップ

  • このエントリーをはてなブックマークに追加

こんにちは。
ライジングサン・システムコンサルティングの岩佐です。

この記事では、FileMakerプラットフォームで構築されたソリューションと、クラウド会計ソフト freee をWebAPIを用いて連携する方法を解説します。

1.freeeにアカウントを開設する。

まず最初はfreeeにアカウントを登録しましょう。

すでにfreeeを利用中の企業さまは、新たにテスト用の法人をひとつ追加して、そちらの法人を使ってこの先のテストを進めるようにすると良いでしょう。

1-1.テストでもビジネスプランの契約を

新規アカウント開設時には、freeeの契約プランを選択することになります。ここでは無難に「ビジネス」を選択しておけば良いでしょう。ビジネスプランでもアカウント開設から30日は無料で使うことができます。無料期間中でももちろんAPIの実行は可能です。

また、この後の検証作業をスムーズに進めるために、facebookやGoogleアカウント等を使ってのアカウント開設ではなく、少し面倒でもメールアドレスとパスワードで新規アカウントを開設して下さい。

1-2.アカウントを開設する時の注意

ちなみに、freeeに新規でアカウントを開設すると、freee社内のカスタマーサポート部門からほぼ100%電話がかかってきます。

電話の目的は新規導入のサポート案内です。アカウント開設時に電話番号の入力は必須となるのですが、実際にテストに携わらない部門や代表の電話番号を登録すると混乱を招くと思います。

なので、テストを実行する部署の電話番号か、検証者自身の携帯番号などを使うのが無難でしょう。

また、会社名も明らかにテスト用のアカウントとわかるような会社名にしておけば、もしかしたら電話がかかってこないかもしれません(未確認)。

2.テストアプリケーションの登録

freeeのアカウントでログインをしたら、以下のURLにアクセスして、【+新しいアプリケーションを登録】ボタンをクリックして下さい。

https://secure.freee.co.jp/oauth/applications

そうすると、「新しいアプリケーションを登録」のページが表示されます。

2-1.アプリケーションの新規登録

表示されたページにあるアプリケーション名とコールバックURIを入力して下さい。

今回はテストなので、コールバックURIには、ページ内にある「ローカル環境でのテストには…」にある urn:から始まる文字列をそのままコピー&ペーストすればOKです。双方の項目を入力したら保存ボタンを押して下さい。

2-2.App ID と Secret の値を記録

アプリケーションの登録が成功したら、以下のようなページが表示されます。

ここで発行されたAppIDとSecret、そしてWebアプリ認証用URLは、後の作業で使います。
なので、いつでもコピー&ペーストできるように、スニペット目的で、テキストエディタ等に記録しておくと良いでしょう。

3.REST API 検証アプリ::Postmanのインストール

一般的にAPIを実行するには、コードを書くかcURLを使って実行することになります。

しかし、ここはできるだけ手間なく簡単にAPIの実行をトライしていただくために、Postmanというツールを使いたいと思います。

3-1.Postmanのインストール

次の手順に従ってインストールして下さい。

GoogleChromeを起動して、Googleで[Postman]と検索。
 
検索トップに【Postman – Chrome ウェブストア – Google】が表示されるので、そちらをクリック。
 
クリックすると、インストールウインドウが表示されるので、右上にある「CHROMEに追加」ボタンをクリック。

 

Chromeのアプリランチャーに登録されるので、アイコンをクリックして起動。

 

アカウントを作成してログインすると、下のような画面が表示されるので、Collectionをクリック。

Collection登録用のダイヤログウインドウが表示されるので、Nameのテキストボックスに「freee API テスト」と入力して、右下のCreateボタンをクリック。

 

Collectionの作成が成功すると、下のような画面が表示されます。右上の☓アイコンをクリックしてクローズします。

 

クローズすると、下のような画面になるはずです。これでPostmanを使ったfreee APIの検証環境が整いました。

 

4.アクセストークンの取得

Postmanを使ってアクセストークンを取得するAPIを実行します。最初のアクセストークンを取得するには、次の情報が必要なので、いつでもコピー&ペーストできるようにしておいて下さい。

App ID (client_id) アプリの登録で取得したAppID
Secret (client_secret) アプリの登録で取得したSecret
Auth URL https://secure.freee.co.jp/oauth/authorize
Token URL https://api.freee.co.jp/oauth/token

4-1.最初のアクセストークンを取得

まずは上記の値とPostmanを使って、最初のアクセストークンを取得します。

実行すると、次の値が獲得できます。

access_token APIを実行する時に必要な鍵情報
token_type トークンの種類
expires_in 取得したトークンが向こうになるまでの秒数
refresh_token 次回アクセストークンをリフレッシュ(再取得)する時に必要となる鍵情報
scope 該当トークンが許可されたスコープ

 

ここで獲得できた「access_token」と「refresh_token」の値は、後の作業で使うので、テキストエディタ等にコピー&ペーストして必ず記録しておいて下さい。

4-2.アクセストークンのリフレッシュ(再取得)

先程のJSON戻り値には、【expires_in】という要素がありました。こちらは、取得したアクセストークンが期限切れになるまでの時間を秒で現したものです。

86,400秒なので、ちょうど24時間ですね。

実際のアプリケーションに連携機能を組み込む場合は、この有効期限が切れる前にアクセストークンを再取得(リフレッシュ)する機能の組み込みが必須です。

ですので、ここではアクセストークンのリフレッシュ方法も検証しておきましょう。アクセストークンのリフレッシュも、同じくPostmanを使って実行できます。

以降の作業は、ここで取得したアクセストークンを使って進めていきます。もし一気に検証を進められない場合、つまり検証作業が24時間を超える場合は、アクセストークンの再取得が必要になります。

ここでご説明した手順で、改めてアクセストークンのリフレッシュを実行して下さい。

※アクセストークンは、常にリフレッシュトークンとセットで記録しておいて下さい。

5:Postmanを使ってGETメソッドのAPIをコールする。

このステップでは手軽に実行できるGETメソッドを使って、freeeに最初から設定されている各マスター値の取得方法を学習します。

また、取得にあたっては先程インストールしていただいたPostmanを使ってGUI経由で取得します。

5-1.事業所IDを取得する。

まず最初に、事業所IDを取得します。
APIを実行するために必要なパラメータ、及びURIは以下の通りです。”Bearer “の後に続くXXX…には、最後に取得したアクセストークンを設定します。

HTTPメソッド GET
URI https://api.freee.co.jp/api/1/companies
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ なし

 

APIが成功したら、次のようなJSONが取得できます。

{
    "companies" : 
    [
        {
            "display_name" : "株式会社ライジングサン・システムコンサルティング",
            "id" : 9999999,
            "name" : null,
            "name_kana" : null,
            "role" : "admin"
        }
    ]
}

id要素にある数値が、法人を一意に識別する事業所IDとなります。この事業所IDは、この後のAPIをコールする時に、常にパラメータとなる重要なIDです。

ここで取得した事業所IDは、後の作業で使用します。

テキストエディタ等に記録しておいて下さい。

できれば、取得したJSONをテキストエディタにコピー&ペーストして、「事業所マスタ.json」等の分かりやすいファイル名を付けた、プレーンテキストファイルとして保存しておくと良いでしょう。

また、取得できたJSONがcompaniesという要素の配列であることに気が付かれた方もいらっしゃると思います。

事業所が配列になっている理由は、次のユーザデータの取得で解説します。

5-2.ユーザを取得する。

実行パラメータとして必要な情報は以下のとおりです。

HTTPメソッド GET
URI https://api.freee.co.jp/api/1/users/me
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ companies=true

 
ユーザマスタの取得は、GETパラメータに「companies=true」を設定しています。
また、HTTPヘッダに設定するAuthorizationパラメータや、Content-Typeはまったく同じなので、PostmanのDupulicate(複製)機能を使っています。

このように、Postmanの機能をうまく使うと、検証作業を効率よく進めることができます。

ここで取得できたJSONの構造に着目して下さい。

freeeのユーザと事業所の関係をうかがい知ることができます。

{
    "user" : 
    {
        "companies" : 
        [
            {
                "display_name" : "株式会社ライジングサン・システムコンサルティング",
                "id" : 9999999,
                "role" : "admin",
                "use_custom_role" : false
            }
        ],
        "display_name" : "岩佐和紀",
        "email" : "kazuki.iwasa@risingsun-system.net",
        "first_name" : "和紀",
        "first_name_kana" : "カズキ",
        "last_name" : "岩佐",
        "last_name_kana" : "イワサ"
    }
}

このように、1名のユーザに対して、事業所はJSONの配列構造になっています。

ですので、freeeでは、1名のユーザが複数の事業所にログイン可能なことが解ります。

このあたりは複数事業を展開している経営者さんや、幾つもの法人の顧問をされている税理士事務所さんには非常に便利な設計だと思います。

そして、ここで獲得したユーザマスタ情報も後の作業で使用します。

先の事業所マスタと同じように、取得したJSONファイルをテキストエディタにコピー&ペーストして、「ユーザマスタ.json」等の分かりやすいファイル名を付けて保存しておくと良いでしょう。

5-3.勘定科目マスタデータを取得する。

次に勘定科目マスタを取得します。

こちらも、FileMakerからfreeeへ仕訳データを登録(POST)する時に、極めて重要な情報です。

Postmanの操作は先と同じです。

HTTPヘッダの設定値は同じなので、ユーザマスタの取得をした時と同じように、複製コマンドを使うと良いでしょう。

実行パラメータとして必要な情報は以下のとおりです。

HTTPメソッド GET
URI https://api.freee.co.jp/api/1/account_items
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ companies=9999999

 
URIに【company_id=9999999】というパラメータが設定されていることに気をつけて下さい。

この”9999999″には、先に取得した事業所IDを設定します。

APIのコールが成功すると、3000行を超えるかなり大きなJSONが取得できます。

この獲得したJSONも、後の作業で使用します。「勘定科目.json」等、あとで分かりやすいファイル名を付けて保存しておいて下さい。

5-4.税区分コードを取得する

次に税区分コードを取得します。
実行パラメータとして必要な情報は以下のとおりです。

HTTPメソッド GET
URI https://api.freee.co.jp/api/1/taxes/codes
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ なし

 
今回は、GETパラメータを設定する必要はありません。

そしてここで獲得したJSONも、後の作業で使用します。

テキストエディタにコピー&ペーストして「税区分.json」等、あとで分かりやすいファイル名を付けて保存しておいて下さい。

5-5.品目マスタデータを取得する。

次に品目コードを取得します。実行パラメータとして必要な情報は以下のとおりです。

HTTPメソッド GET
URI https://api.freee.co.jp/api/1/items
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ company_id=9999999

 
品目マスタの取得には、GETパラメータに【company_id=9999999】を設定する必要があります。

この”9999999″は、先程と同じくターゲットとなる事業所IDを設定します。

APIが成功すると、freeeに最初から登録されている「介護保険料」や「基本給」といった品目リストを獲得できるはずです。

しかし、今回の最終目標であるFileMakerの請求書データから売掛金仕訳を登録しようとすると、それにふさわしい品目がないことがわかると思います。

ですのでここは、freeeのGUIを使って「商品分類1」と「商品分類2」を登録し、その後にAPIを使って「商品部類3」を登録してみたいと思います。

freeeのGUIを使って商品登録をするには、ログイン後に表示されるヘッダメニューから、設定→品目の設定を実行します。

 

そうすると、以下のようなページが表示されます。
【+新しい品目を追加】ボタンをクリックし、画面の指示に従って「商品分類1」と「商品分類2」を登録して下さい。

 

freee GUIからの登録が完了したら、Postmanに戻って改めて品目マスタのGETメソッドを実行してみましょう。登録した「商品分類1」と「商品分類2」が、JSONデータに含まれているはずです。では次に、APIを使って「商品分類3」を登録します。

 
POSTメソッドが成功すると、動画にようにJSONで登録結果を受け取ることができます。

{
    "item" : 
    {
        "company_id" : 9999999,
        "id" : 152903810,
        "name" : "商品分類3",
        "shortcut1" : null,
        "shortcut2" : null
    }
}

戻ってきたJSONに含まれるid要素は、該当品目を一意に識別できるプライマリキーです。ですので、FileMaker側で作り込んだ商品分類マスタと連携を取る時に照合キーとなる重要となる値です。

このように、品目マスタとAPIでリアルタイム連携が取れることにより、マスタメンテナンス業務を大幅に省力化することが可能です。

HTTPメソッド POST
URI https://api.freee.co.jp/api/1/items
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ
{
  "company_id" : 1078972,
  "name" : "商品分類3"
}

 

5-6.取引先マスタデータを取得する。

次にGETメソッドを使った取引先マスタの登録、及びPOSTメソッドを使った取引先の登録にトライしましょう。

GETメソッドの実行パラメータとして必要な情報は以下のとおりです。

HTTPメソッド GET
URI https://api.freee.co.jp/api/1/partners
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ company_id=9999999

 
Postmanの操作は勘定科目や品目マスタと同じなので動画による操作説明は割愛します。

さて、上記のパラメータでGETメソッドを実行しても、戻ってきたJSONには取引先マスタにデータのないことが確認できると思います。

ですので、ここは新しい登録先をPOSTメソッドで実行しましょう。

POSTメソッド実行時のパラメータは以下のとおりです。

HTTPメソッド POST
URI https://api.freee.co.jp/api/1/partners
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ
{
    "company_id" : 9999999,
    "name" : "株式会社優良企業"
}

POSTメソッドが成功すると、以下のようなレスポンスが取得できるはずです。

{
    "partner" : 
    {
        "company_id" : 9999999,
        "id" : 9236674,
        "name" : "株式会社優良企業",
        "shortcut1" : null,
        "shortcut2" : null
    }
}

ここで取得できたid要素にセットされている数値は、freeeにおける該当取引先を一意に識別できる値です。ですので、FileMaker側で管理する取引先マスタと連携を取る時の照合キーとなる重要となる値です。

それでは、ここで3社ほど適当な企業名で取引先を登録してみて下さい。

その後、GETメソッドを実行すると、登録した取引先が以下のように取得できるはずです。

{
    "partners" : 
    [
        {
            "company_id" : 9999999,
            "id" : 9236674,
            "name" : "株式会社優良企業",
            "shortcut1" : null,
            "shortcut2" : null
        },
        {
            "company_id" : 9999999,
            "id" : 9236720,
            "name" : "超優良企業株式会社",
            "shortcut1" : null,
            "shortcut2" : null
        },
        {
            "company_id" : 9999999,
            "id" : 9236722,
            "name" : "ホワイト企業株式会社",
            "shortcut1" : null,
            "shortcut2" : null
        }
    ]
}

このように、取引先もAPI連携することで、販売管理系や購買管理系のシステムと会計システム間のマスターデータの整合性を取る作業が軽減されます。

また、取引先毎の詳細な取引データを、経営者がリアルタイムに把握できる仕組みにも大きく貢献できる機能なので、FileMakerとの連携を実現する場合には、ぜひリアルタイムの連携にトライしてみて下さい。

5-7.部門マスタデータを取得する。

次に部門データを取得します。

Postmanの操作方法については、GET/POST共に取引先マスタと同じなので、各パラメータのみを記述しておきます。

そして、取引先マスタと同じく部門マスタも、最初は登録データがありません。

なので、先にPOSTメソッドを実行して、2〜3の部門を適当に登録してみて下さい。
 
POSTメソッド実行時のURIとパラメータは以下のとおりです。

HTTPメソッド POST
URI https://api.freee.co.jp/api/1/sections
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ
{
  "company_id" : 9999999,
  "name" : "第1営業部"
}

POSTメソッドの成功後にGETメソッドを実行すると、登録済みの部門マスタを取得することができます。

GETメソッド実行時のURIとパラメータは以下のとおりです。

HTTPメソッド GET
URI https://api.freee.co.jp/api/1/sections
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ company_id=9999999

 
成功すると、次のようなレスポンスが返ってきます。

{
    "sections" : 
    [
        {
            "company_id" : 9999999,
            "id" : 355709,
            "name" : "第1営業部",
            "shortcut1" : null,
            "shortcut2" : null
        },
        {
            "company_id" : 9999999,
            "id" : 355710,
            "name" : "第2営業部",
            "shortcut1" : null,
            "shortcut2" : null
        },
        {
            "company_id" : 9999999,
            "id" : 355711,
            "name" : "第3営業部",
            "shortcut1" : null,
            "shortcut2" : null
        }
    ]
}

6:Postmanを使ってPOSTメソッドのAPIをコールする。

これまでのステップで、仕訳データをPOSTするために必要な各種マスター情報の取得が完了しました。

このステップでは、取得したマスターデータを使って、まずはPostmanからfreeeへ仕訳データを登録します。

仕訳データの登録といっても、手順はこれまでのPOSTメソッドとまったく同じです。

HTTPメソッド POST
URI https://api.freee.co.jp/api/1/deals
HTTPヘッダ Authorization: Bearer xxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
パラメータ
{
    "company_id" : 9999999,
    "due_date" : "2018-01-31",
    "issue_date" : "2017-12-28",
    "partner_id" : 9236674,
    "ref_number" : "1234567",
    "type" : "income",
    "details" : 
    [
        {
            "account_item_id" : 172033592,
            "amount" : 108000,
            "description" : "商品分類1・第1営業部",
            "item_id" : 152903733,
            "section_id" : 355709,
            "tax_code" : 21
        },
        {
            "account_item_id" : 172033592,
            "amount" : 108000,
            "description" : "商品分類2・第2営業部",
            "item_id" : 152903734,
            "section_id" : 355710,
            "tax_code" : 21
        },
        {
            "account_item_id" : 172033592,
            "amount" : 108000,
            "description" : "商品分類3・第3営業部",
            "item_id" : 152903810,
            "section_id" : 355711,
            "tax_code" : 21
        }
    ]
}

JSONパラメータに設定する各要素の意味は以下のとおりです。

  company_id
  事業所ID
  issue_date
  発生日(請求書の場合は請求日)
  partner_id
  freee上の取引先マスタID
  due_date
  支払期限日
  type
  収入(income) / 支出(expense)
  ref_number
  管理番号(例えば請求書No等)
  details.account_item_id
  勘定科目マスタID(上記例は売掛金)
  details.tax_code
  税区分マスタのID値
  details.item_id
  品目マスタのID値
  details.section_id
  部門マスタのID値
  details.amount
  取引金額(税込み)
  details.description
  任意の説明文

このようにJSON構造を見るだけでも、CSV連携だと対応の難しい複合仕訳等に対応しているのが想像できますね。明細行毎に部門設定できる仕様は、特に複雑な取引をしている企業には嬉しい仕様だと思います。

また、このように少し複雑なJSONを手作業で構築する場合、テキストエディタだと構造を壊してしまう恐れもあります。例えばCSVデータでも、少し複雑なものを編集する場合は、Excelを使うように、JSONの編集も専用のエディタを使用することをおすすめします。

私は、Postmanと同じくChormeアプリになっているJSON Editor Onlineというツールを使っています。ついうっかり、カンマの位置を間違えたり、カッコの位置を間違えてもツールがチェックしてくれるので、つまらないミスでAPI検証が進まないと言ったロスを防ぐことができます。

 

仕訳データのPOSTメソッドが成功すると、以下のようなレスポンスが返ってきます。

{
    "deal" : 
    {
        "amount" : 324000,
        "company_id" : 9999999,
        "due_amount" : 324000,
        "due_date" : "2018-01-31",
        "id" : 186946155,
        "issue_date" : "2017-12-28",
        "partner_id" : 9236674,
        "ref_number" : "1234567",
        "type" : "income",
        "details" : 
        [
            {
                "account_item_id" : 172033592,
                "amount" : 108000,
                "description" : "商品分類1・第1営業部",
                "item_id" : 152903733,
                "section_id" : 355709,
                "tag_ids" : [],
                "tax_code" : 21,
                "tax_id" : 85901986,
                "vat" : 5142
            },
            {
                "account_item_id" : 172033592,
                "amount" : 108000,
                "description" : "商品分類2・第2営業部",
                "item_id" : 152903734,
                "section_id" : 355710,
                "tag_ids" : [],
                "tax_code" : 21,
                "tax_id" : 85901986,
                "vat" : 5142
            },
            {
                "account_item_id" : 172033592,
                "amount" : 108000,
                "description" : "商品分類3・第3営業部",
                "item_id" : 152903810,
                "section_id" : 355711,
                "tag_ids" : [],
                "tax_code" : 21,
                "tax_id" : 85901986,
                "vat" : 5142
            }
        ]
    }
}

それでは、freeeに仕訳データが登録されていることを確認しましょう。

freeeにログインし、ページ上部の青いメニューバーから、【取引】→【取引の一覧・登録】をクリックして下さい。表示されたページに、意図する取引データが登録されているはずです。

そしてこちらの取引一覧では、管理番号による検索が可能です。

仕訳登録のAPIを実行する時に、FileMaker側で発行した請求書Noをセットしておけば、該当請求書の仕訳データを直ぐに検索できます。

以上で、Postmanを用いた仕訳データの登録が終了しました。

7:FileMakerからfreee API を実行する。

最後にFileMakerから、アクセストークンをリフレッシュする方法、及び仕訳データをPOSTする手順を説明します。

7-1. ソリューションファイルの準備

まずはAPI連携を動かすためにソリューションファイルを準備しましょう。

  • 適切な場所に「freee連携.fmp12」ファイルを作成する。
  • デフォルトで作成されるfreee連携テーブルに、「access_token」と「refresh_token」フィールドを作成する。

7-2. アクセストークンリフレッシュのスクリプトを組み込む

まずは改めて、Postmanによるアクセストークンのリフレッシュをしましょう。
先にご説明した【4-2.アクセストークンのリフレッシュ】の手順に従って、アクセストークンが正しく再取得されることを確認してください。

次に再取得したアクセストークンとリフレッシュトークンを、7-1.で作成したFileMakerのソリューションファイルに記録します。既にFileMakerがからのレコードを1件作成していると思いますので、freee連携テーブルに作成した「access_token」と「refresh_token」フィールドにそれぞれの値を入力し、レコードを確定して下さい。

次に新しいスクリプトを作成します。スクリプト名は「アクセストークンのリフレッシュ」など、分かりやすい名前をつけておくと良いでしょう。

そして最初のステップに「テキストの挿入」スクリプトステップを挿入します。このスクリプトステップは、Ver6以前の古くから存在するスクリプトステップですが、Ver16より挿入先のターゲットに変数を設定できるようになり、俄然便利さが増しました。

テキストを挿入スクリプトステップのオプションを次の通り設定して下さい。

スクリプトステップ テキストを挿入
ターゲット 変数:$curlOption
挿入するテキスト

-i -X POST 
 -H "Content-Type:application/x-www-form-urlencoded"
 -d "grant_type=refresh_token"
 -d "client_id=@@@client_id@@@"
 -d "client_secret=@@@client_secret@@@"
 -d "refresh_token=@@@refresh_token@@@"

 
ここで、@@@client_id@@@と@@@client_secret@@@の部分を、ご自身がfreeeに登録したアプリの値で上書きして下さい。

次に、@@@refresh_token@@@の文字列を、実際のリフレッシュトークンに置き換える処理を実装しましょう。
こちらは、substitute関数を使えば簡単に実装できますね。

変数を設定 [$curlOption; Substitute ( $curlOption ; "@@@refresh_toaken" ; freee連携::refresh_token )]

 
次に改行文字を、Nullに変換しましょう。
こちらも同じくsubstitute関数を使えば簡単に実装できると思います。

そして、いよいよAPIをコールです。
URLから挿入スクリプトステップを追加し、次のオプションを設定します。

スクリプトステップ URLから挿入
ターゲット 変数:$result
URL https://api.freee.co.jp/oauth/token
cURLオプションの指定 $curlOption

 
このスクリプトステップを実行すると、$result変数にAPIの実行結果がセットされます。実行結果はJSONで戻ってくるので、この$resultから、”access_token”と”refresh_token”を取り出して、それぞれのフィールドにセットし、レコードをコミット(確定)して終了です。

$resultから、JSON要素の”access_token”と”refresh_token”を取り出すには、JSONGetElement関数を使えば簡単に実装できますね。

こちらが作成したスクリプトの全体像です。

こちらのスクリプトを実行すると、その度にaccess_tokenとrefresh_tokenフィールドが更新されるのがご理解いただけると思います。

<重要>
ここではテキストを挿入スクリプトステップに、client_idとclient_secretをべた書きしていますが、この実装方法はセキュリティ的に推奨されない実装方法です。今回は説明の簡易性を優先してこのような形を取りましたが、これらの値は開発者以外に絶対知られたらいけないものなので、実際にソリューションへ実装するときには、完全アクセス権アカウントのみが利用可能なカスタム関数化するなどの対策を施して下さい。

7-3. GET系のAPIを実行する。

次にGET系のAPIを実行してみましょう。手順はほとんど同じです。せっかくなので、パラメータの設定が必要な取引先マスタの取得APIを実行してみましょう。

まずテーブルに、【取引先の取得結果】という名前でフィールドをひとつ追加して下さい。

次に「取引先マスタの取得」という名前でスクリプトを作成し、最初のスクリプトステップに「テキストを挿入」スクリプトステップを追加します。

スクリプトステップ テキストを挿入
ターゲット 変数:$curlOption
挿入するテキスト

-i -X GET
 -H "Authorization:Bearer @@@access_token@@@"
 -H "Content-Type:application/json"

 
次に@@@access_token@@@を、substitute関数で直前に取得したアクセストークン値に変換するスクリプトステップを追加しましょう。

こちらは[変数を設定]スクリプトステップで、簡単に処理できますね。

Substitute関数を使って、$curlOptionにある"@@@access_token@@@"を[freee連携::access_token]で置き換える処理を追加して下さい。

次に[URLから挿入]スクリプトステップでAPIをコールします。スクリプトステップには次のオプションを設定します。

スクリプトステップ URLから挿入
ターゲット 変数:$result
URL https://api.freee.co.jp/api/1/partners?company_id=9999999
cURLオプションの指定 $curlOption

 
URLに引数として設定するcompany_idには、第5ステップで実行した【5-1. 事業所情報を取得】で取得した値をセットします。

最後に、$resultに返ってきたレスポンスを、【取引先の取得結果】フィールドにセットします。この時、JSONFormatElements関数で整形すると、より結果が確認し易いと思います。以下のような値が戻ってきたら成功です。

{
    "partners" : 
    [
        {
            "company_id" : 9999999,
            "id" : 9236674,
            "name" : "株式会社優良企業",
            "shortcut1" : null,
            "shortcut2" : null
        },
        {
            "company_id" : 9999999,
            "id" : 9236720,
            "name" : "超優良企業株式会社",
            "shortcut1" : null,
            "shortcut2" : null
        },
        {
            "company_id" : 9999999,
            "id" : 9236722,
            "name" : "ホワイト企業株式会社",
            "shortcut1" : null,
            "shortcut2" : null
        }
    ]
}

GET系の実行方法は全て同じ手順で実行できます。実際のソリューションでは、品目マスタや部門マスタ等の取得も必要になると思います。今回作成したスクリプトを適切に編集して、それぞれのマスターの取得スクリプトを作成してみて下さい。

7-4. 仕訳データをPOSTする。

ではいよいよ仕訳データをPOSTします。
最初に【仕訳データの登録結果】という名前でフィールドを追加して下さい。

次に「仕訳データの登録」というスクリプトを新しく追加します。
そして、これまでと同じように「テキストを挿入」スクリプトステップを追加し、$curlOptionに次の文字列を追加します。

スクリプトステップ テキストを挿入
ターゲット 変数:$curlOption
挿入するテキスト

-i -X POST
 -H "Authorization:Bearer @@@access_token@@@"
 -H "Content-Type:application/json"
 --data-binary @$jsonBody

次にもうひとつ「テキストを挿入スクリプトステップ」を追加し、$jsonBodyという変数に仕訳データのJSONをセットします。

スクリプトステップ テキストを挿入
ターゲット 変数:$jsonBody
挿入するテキスト
{
    "company_id" : 9999999,
    "details" : 
    [
        {
            "account_item_id" : 172033592,
            "amount" : 108000,
            "description" : "商品分類1・第1営業部",
            "item_id" : 152903733,
            "section_id" : 355709,
            "tax_code" : 21
        },
        {
            "account_item_id" : 172033592,
            "amount" : 108000,
            "description" : "商品分類2・第2営業部",
            "item_id" : 152903734,
            "section_id" : 355710,
            "tax_code" : 21
        },
        {
            "account_item_id" : 172033592,
            "amount" : 108000,
            "description" : "商品分類3・第3営業部",
            "item_id" : 152903810,
            "section_id" : 355711,
            "tax_code" : 21
        }
    ],
    "due_date" : "2018-01-31",
    "issue_date" : "2017-12-28",
    "partner_id" : 9236674,
    "ref_number" : "1234567",
    "type" : "income"
}

こちらは、ステップ6でPostmanから仕訳データを登録したときとまったく同じJSONデータです。
company_idやpartner_id等は、ご自身のソリューションに合わせて適切に編集して下さい。

次に@@@access_token@@@を、substitute関数で直前に取得したアクセストークン値に、そして改行コードをNullに変換するスクリプトステップを追加しましょう。

そして次にURLから挿入スクリプトステップでAPIをコールします。スクリプトステップのオプションは以下のとおりです。

スクリプトステップ URLから挿入
ターゲット 変数:$result
URL https://api.freee.co.jp/api/1/deals
cURLオプションの指定 $curlOption

 
今回は、cURLオプションのパラメータが[-d]ではなく[--data-binary]になっていることに着目して下さい。

こちらは、パラメータを文字列としてではなくバイナリデータとしてPOSTするオプションです。今回はパラメータがJSONなので文字列として送信しても良いのですが、例えば画像や動画、音声データなどをPOSTするときには必須のオプションとなるので、今回はあえてこちらを採用しました。

後は、APIからの戻り値をJSONFormatElementで整形して【仕訳データの登録結果】フィールドに保存すればOKです。

以下のような値が戻ってきたら成功です。

{
    "deal" : 
    {
        "amount" : 3240000,
        "company_id" : 9999999,
        "details" : 
        [
            {
                "account_item_id" : 172033592,
                "amount" : 1080000,
                "description" : "商品分類1・第1営業部",
                "item_id" : 152903733,
                "section_id" : 355709,
                "tag_ids" : [],
                "tax_code" : 21,
                "tax_id" : 85901986,
                "vat" : 51428
            },
            {
                "account_item_id" : 172033592,
                "amount" : 1080000,
                "description" : "商品分類2・第2営業部",
                "item_id" : 152903734,
                "section_id" : 355710,
                "tag_ids" : [],
                "tax_code" : 21,
                "tax_id" : 85901986,
                "vat" : 51428
            },
            {
                "account_item_id" : 172033592,
                "amount" : 1080000,
                "description" : "商品分類3・第3営業部",
                "item_id" : 152903810,
                "section_id" : 355711,
                "tag_ids" : [],
                "tax_code" : 21,
                "tax_id" : 85901986,
                "vat" : 51428
            }
        ],
        "due_amount" : 3240000,
        "due_date" : "2018-01-31",
        "id" : 188484406,
        "issue_date" : "2017-12-28",
        "partner_id" : 9325495,
        "ref_number" : "iv1234567",
        "type" : "income"
    }
}

以下、【仕訳データを登録】スクリプトの全体像です。

8.まとめ

この記事では、FileMakeプラットホームで開発したソリューションから、クラウド会計ソフトfreeeへWebAPIで連携する手順を7つのステップで解説してきました。

FileMakerのcURLオプションを用いたWebAPIコールは、簡易的で非常に便利な反面、エラーが発生した時の原因をつかむことが非常に困難です。

ですので、今回はPostmanという汎用のWebAPI試験ツールを用いて、まずはAPIをコールする時の「作法」もしくは「コツ」のようなものを掴んでいただき、その後にFileMakerからAPIをコールするという手順で解説をさせていただきました。

また、Postmanを使って成功したパラメータを、そのままcURLに置き換えてしまえば、エラーのリスクは極めて低くなります。

FileMakerプラットホームはVer16から搭載されたcURLオプションにより、他システム連携がより柔軟に実装できるようになりました。

世の中には、APIを公開している便利なサービスが多数存在します。

例えばつい先日は、ヤマト運輸がAPIを公開しました。
http://www.yamato-hd.co.jp/news/h29/h29_96_01news.html

これまでは、B2という専用アプリをインストールし、CSVファイルを介在してデータ交換を行う必要があったのですが、今回公開されたAPIを使いこなすことで、このような人手を介在したデータ交換が必要なくなります。

FileMakerを利用している企業には、EC事業を営んでいる会社もたくさんあると思います。このような便利なサービスと自社システムをAPIで連携することにより、より生産性の高い事業を構築することが可能です。

ぜひ、あなたもAPI連携を自在に使いこなして、生産性向上に役立つソリューション開発にトライしてみましょう。
 

このブログ記事では、極めて基本的なAPIのみを解説させて頂きました。
より詳しい情報は、freee公式のAPIリファレンスをご参照下さい。


 

FileMakerのcURLに関する詳細情報はこちらのヘルプページをご参照下さい。

  • このエントリーをはてなブックマークに追加