マネーフォワードクラウド請求書APIによる請求書作成
はじめに
マネーフォワードクラウド請求書APIは、外部プログラムでマネーフォワードサービスを使用できる便利なAPIです。最近お仕事でよく使います。
今回はAPIを使って請求書を作成してみました。
APIのドキュメントについては以下にあります。
しかし、分かりにくい所やそもそも記載が無い部分もあり、その辺をメインに記事にしておきます。
また、APIを使うための準備は以下の記事を参照してください。
請求書作成に必要なマスタ情報
請求書作成APIを叩く前にクラウド請求書APIで請求書を作成するのに関連するマスタ情報が２つあります。
取引先情報を登録する取引先マスタ。請求科目の情報を登録する科目マスタ。
この２つですが、このうち科目マスタは実は登録されていなくても請求書は作成できます。
とりあえず最低限必要な取引先マスタに画面から登録しておきます。
2段で段組みされていて、下段の部門設定という所が実はミソです。「＋」ボタンで複数部門を登録できます。
取引先の部門が複数登録できるので、同一会社だが複数の請求先が有る場合等は、ここで別の部門として登録しておけば、対応可能です。
とはいえ、今回は一つで良いので一つ登録しておきます。
そして、この情報をAPIで取得します。
請求書作成をAPIで実行するために必要な情報を取得します。
取得をPowerShellでやる場合は以下のコマンドで HTTP GET します。
#=================================
# 取引先一覧取得
#=================================
# アクセストークン(read)
$readToken = 'BEARER XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
# HTTPヘッダー
$readAuthHeader = @{'Authorization' = $readToken}
# マネーフォワードURL
$requestHost = 'https://invoice.moneyforward.com'
# 取引先一覧取得
$retPartner = Invoke-RestMethod -Method Get -Headers $readAuthHeader `
-uri $($requestHost + '/api/v2/partners.json?page=1&per_page=10')
ポイントは以下の通り。
- アクセストークンは読込み権限のもの。先頭の「BEARER 」を忘れずに。HTTPヘッダにAuthorizationヘッダとして設定。
- 取引先一覧なので取得するためのリクエストパラメータを設定。（page⇒取得ページ、per_page⇒1ページの取得件数）
取得結果は以下の通り。
src> $retPartner.data[0].attributes
code : P01
name : 鎌形テスト
name_kana :
name_suffix : 御中
memo :
created_at : 2019-11-07T19:32:27.000+09:00
updated_at : 2019-11-08T21:45:45.000+09:00
src> $retPartner.included[0].attributes
zip : 100-0001
tel :
prefecture : 東京都
address1 : 千代田区千代田
address2 :
person_name : 鎌形 稔
person_title :
name :
email :
cc_emails :
created_at : 2019-11-07T19:32:27.000+09:00
updated_at : 2019-11-08T21:45:45.000+09:00
ちょっとデータ構造を分かりやすくするためにPowerShellオブジェクトからJSON形式に変換します。
（ちなみに本来はAPIを叩くとJSON形式で返ってくるのですが、PowerShellは取得すると扱いやすいようにPSCustomObject形式に変換されて返ってきます。）
src> $retPartner | ConvertTo-Json -Depth 6
{
"data": [
{
"id": "AAAAAAAAAAAA",
"type": "partner",
"attributes": {
"code": "P01",
"name": "鎌形テスト",
"name_kana": "",
"name_suffix": "御中",
"memo": "",
"created_at": "2019-11-07T19:32:27.000+09:00",
"updated_at": "2019-11-08T21:45:45.000+09:00"
},
"relationships": {
"departments": {
"data": [
{
"id": "BBBBBBBBBBBB",
"type": "department"
}
]
}
}
}
],
"included": [
{
"id": "BBBBBBBBBBBB",
"type": "department",
"attributes": {
"zip": "100-0001",
"tel": null,
"prefecture": "東京都",
"address1": "千代田区千代田",
"address2": null,
"person_name": "鎌形 稔",
"person_title": null,
"name": null,
"email": null,
"cc_emails": null,
"created_at": "2019-11-07T19:32:27.000+09:00",
"updated_at": "2019-11-08T21:45:45.000+09:00"
}
}
],
"meta": {
"total_count": 1,
"total_pages": 1,
"current_page": 1,
"per_page": 10
}
}
大きく３つの情報に分かれていて一番下のmetaは見れば分かるように取得件数等の情報です。
一番上のdataが取引先マスタ登録画面で言う上段の情報、下段の情報はincludedに有ります。
そして、重要なのがdataとincludedにある「id」です。
dataのidは取引先を一意に表す取引先IDです。includedにあるidが部門IDとなります。
includedのidはdataの relationships 配下にあるidで紐づけられます。
なお、includedのid（部門ID）は取引先マスタ内で一意に部門を表しています。
請求書作成にはこの部門IDを使う事になります。
請求書をAPIで作成する
PowerShellでは以下のようなコマンドでHTTP POSTします。
ここでは最低限必要な項目のみ指定して、とりあえず作成します。
#=================================
# 請求書作成
#=================================
$billingBody = @{
"billing" = @{
"department_id" = "BBBBBBBBBBBBBB";
"title" = "テスト請求書";
}
} | ConvertTo-Json -Depth 4
$billingBodyUtf8 = [System.Text.Encoding]::UTF8.GetBytes($billingBody)
$retBilling = Invoke-RestMethod -Method Post `
-Headers $writeAuthHeader `
-ContentType 'application/json' `
-Uri $($requestHost + '/api/v2/billings.json?excise_type=boolean') `
-Body $billingBodyUtf8
結果は以下の通り。
ポイントは以下の通り。
- 6行目：「department_id」として先ほど取得した部門IDを指定します。請求書作成APIでの必須項目はこの項目のみです。
- 9行目：請求書APIはJSON形式でPOSTする必要があるのでConvertTo-JsonコマンドでJSON形式の文字列に変換します。
- 11行目：PowerShellでは文字コードをUTF8に変換する必要があります。
- 16行目：「excise_type」のクエリパラメータは消費税の項目形式を指定します。「boolean」か「enum 」を指定します。
「excise_type」 のクエリパラメータとは何か？
その前に。
クラウド請求書の請求書作成画面では消費税は明細行毎に設定可能です。
つまり基本は明細行毎に消費税率を指定する必要があるのです。
が、明細行毎に指定できても結局自分のとこは10%しかありえないという方も多いかと思います。
その場合、予め消費税のデフォルト税率が設定できると楽ですね。それがクラウド請求書では帳票設定という画面で設定できます。以下のように。デフォルト税率を選択しておきます。
これで明細毎にデフォルト税率で良い（true）のか、それ以外（false）なのか指定すれば楽ですね。
こういう時にAPIのクエリパラメータで「excise_type=boolean」を指定します。
一方で軽減税率が適用される商品を扱う会社では、明細毎に指定できないといけないわけです。
そういう場合は 「excise_type=enum」とすると、明細行毎に税率を指定できるようになります。
「excise_type=enum」 の場合は以下の明細行の税率に以下の定数が使えます。
| 定数 | 意味 |
| untaxable | 不課税 |
| non_taxable | 非課税 |
| tax_exemption | 免税 |
| five_percent | 5% |
| eight_percent | 8% |
| eight_percent_as_reduced_tax_rate | 8%(軽減税率) |
| ten_percent | 10% |
以上を踏まえ、今度は明細行も有るデータで請求書を作ってみます。
#=================================
# 請求書作成
#=================================
$billingBody = @{
"billing" = @{
"department_id" = "BBBBBBBBBBBBBBBBB";
"title" = "テスト請求書２";
"billing_date" = "2019-11-10";
"due_date" = "2019-12-31";
"items" = @(
@{
"name" = "食料品";
"unit_price" = 100;
"quantity" = 100;
"excise" = "eight_percent_as_reduced_tax_rate";
"disp_order" = 0;
},
@{
"name" = "サービス使用料";
"unit_price" = 3000;
"quantity" = 1;
"excise" = "ten_percent";
"disp_order" = 0;
}
)
}
} | ConvertTo-Json -Depth 4
$billingBodyUtf8 = [System.Text.Encoding]::UTF8.GetBytes($billingBody)
$retBilling = Invoke-RestMethod -Method Post `
-Headers $writeAuthHeader `
-ContentType 'application/json' `
-Uri $($requestHost + '/api/v2/billings.json?excise_type=enum') `
-Body $billingBodyUtf8
- 6行目：部署IDを指定
- 10行目：「items」で明細行データを配列形式で指定。
- 15行目：消費税率を個別指定。
- 16行目：明細行の表示順序を0から始まる整数で指定。（0から昇順。全て0だと配列の順序通りに並ぶ。）
- 34行目：消費税率項目のタイプを指定。個別指定したいのでenumを指定。
結果は以下の通り。
まとめ
請求書APIを叩いて請求書を作成してみました。
ポイントは部門IDと消費税率の所でしょうか。
そこさえ押さえておけばAPIを便利に使いこなせると思います。
- wpmaster
フリーランスシステムエンジニアの鎌形です。
鎌形システムエンジニアリングとして都内で活動中です。
- kintone開発、保守サポートの顧問契約お受けいたします。 2023年2月7日
- グリンテリア観察日記をkintoneアプリで作る 2021年4月22日
- やっぱりPowerShellが好き 2020年12月1日
- Node.js による LINE WORKS トークBot 開発 | JWT 作成と access_token 発行 2020年11月3日
- kintone開発 | グラフをカスタマイズする 2020年7月3日
コメントを投稿するにはログインしてください。