いつも請求書作成ソフト「MFクラウド請求書」をご利用頂きありがとうございます。

今回は10/23に公開したMFクラウド請求書APIの始め方について紹介します。

MFクラウド請求書APIについて

MFクラウド請求書APIを使用することで、MFクラウド請求書内で提供している機能の一部を他のシステムでもご利用いただけます。自社システムとMFクラウド請求書との連携などにご活用ください。
なお、MFクラウド請求書のアカウント登録が完了していると追加料金なく無料でご利用いただけます。
制限事項としては下記があります。

・Basicプラン以下のプランをご利用の場合、月のAPI経由での請求書作成数を100件までとさせていただきます
・その他、取引先登録数や郵送の可否等は通常のプランごとの制限と同様となります

また、ご利用につきましてはMFクラウド請求書API利用規約をお読みいただき、同意していただく必要があります。

アプリケーションの作成

まずはAPIを利用するアプリケーションの作成をします。画面右上の「？」をクリックして、API連携βをクリックします。

新規作成をクリックします。

各項目を入力します。

名前
アプリケーションの名前です。

Redirect URI
認証の際に使うredirect_uriを入力してください。1行に1URIで複数入力可能です。
入力するURIはhttpsのみ有効です。
テストで試す際はhttps://example.comなどと入れておくとよいです。

Scopes
readまたはwriteから選択できます。
readの場合は以下の権限を与えられます。
・請求書の閲覧・検索・PDFダウンロード
・取引先の閲覧
・品目の閲覧
・送付履歴の閲覧
・事業所情報の閲覧

writeの場合はreadに加えて下記の権限が与えられます。
・請求書の作成・更新・郵送
・取引先の作成・更新
・品目の作成・更新
・事業所情報の更新

入力後、規約に同意のチェックを入れた上でアプリケーションを作成するとClient IDとClient Secretが発行されます。

アクセストークンの発行

発行されたClient IDとClient Secret、redirect_urlを元にブラウザからアクセスします。

https://invoice.moneyforward.com/oauth/authorize?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URL]&response_type=code&scope=[SCOPE]

アクセスするとアプリケーションの承認画面になります。

承認をクリックするとアクセストークンの発行のために必要なcodeが付加されたURLにリダイレクトされます。
なお、付与されたcode（認証コード）の有効期間は、10分間です。

次のコマンドではこのURL末尾に付加されているcodeを使います。
ここからはコマンドラインツールであるcurlを用います。

$ curl -d client_id=[CLIENT_ID] -d client_secret=[CLIENT_SECRET] -d redirect_uri=[REDIRECT_URL] -d grant_type=authorization_code -d code=[認証コード] -X POST https://invoice.moneyforward.com/oauth/token

返却されるjsonデータは、以下となります。

{"access_token":"[アクセストークン]","token_type":"bearer","expires_in":2592000,"refresh_token":"[リフレッシュトークン]","scope":"***","created_at":***}

なお、発行されたアクセストークンの有効期限は、30日間です。
アクセストークンの有効期限が切れた場合には、同時に発行されているリフレッシュトークンを用いて、アクセストークンを再発行してください。

アクセストークンの再発行は以下のコマンドを用います。

$ curl -d client_id=[CLIENT_ID] -d client_secret=[CLIENT_SECRET] -d grant_type=refresh_token -d refresh_token=[REFRESH_TOKEN] -X POST https://invoice.moneyforward.com/oauth/token

請求書を作成してPDFでダウンロードする

ここからAPI利用の例として請求書を作成してPDFでダウンロードするまでを試してみたいと思います。
請求書の作成に先立って取引先の登録が必要なので、まずは取引先を作成します。
ここでは簡単のために必須項目である取引先名のみを指定して作成します。

curl -i -H "Authorization: BEARER [ACCESS_TOKEN]" -H "Content-Type: application/json" -d '{ "partner" : { "name" : "サンプル取引先" }}' -X POST https://invoice.moneyforward.com/api/v1/partners

レスポンスは以下のようになると思います。

HTTP/1.1 201 Created
（略）
{"id":"[PARTNER_ID]","code":null,"name":"サンプル取引先","name_kana":null,"name_suffix":"","memo":null,"created_at":"2015-10-23T00:00:00.000+09:00","updated_at":"2015-10-23T00:00:00.000+09:00","departments":[{"id":"[DEPARTMENT_ID]","zip":null,"tel":null,"prefecture":"東京都","address1":null,"address2":null,"person_name":null,"person_title":null,"name":null,"email":null,"cc_emails":null,"created_at":"2015-10-23T00:00:00.000+09:00","updated_at":"2015-10-23T00:00:00.000+09:00"}]}

この中で[DEPARTMENT_ID]に当たる値を次に使うので控えておいてください。

次はいよいよ請求書の作成になります。以下のようにリクエストしてください。

curl -i -H "Authorization: BEARER [ACCESS_TOKEN]" -H "Content-Type: application/json" -d '{ "billing" : { "department_id" : "[DEPARTMENT_ID]" }}' -X POST https://invoice.moneyforward.com/api/v1/billings

HTTP/1.1 201 Created
（略）

{"id":"[BILLING_ID]","pdf_url":"http://localhost:5000/api/v1/billings/[BILLING_ID].pdf","operator_id":"[OPERATOR_ID]","partner_id":"[PARTNER_ID]","department_id":"[DEPARTMENT_ID]",・・・（略）}

このようなリクエストが返ってきたでしょうか？
うまくいっていれば、返ってきたデータの[BILLING_ID]を使って下記リクエストを投げることでpdfがダウンロードできます。

curl -i -H "Authorization: BEARER [ACCESS_TOKEN]" https://invoice.moneyforward.com/api/v1/billings/[BILLING_ID].pdf -O

詳細・お問い合わせについて

MFクラウド請求書APIドキュメントをご確認ください。
また、MFクラウド請求書のAPI詳細に関するお問い合わせは、GitHubにログインの上、GitHub上のissuesよりお問い合わせください。
※GitHubのアカウントをお持ちでない方は、GitHubにアカウント登録の上お問い合わせください。

まとめ

いかがでしたでしょうか？
今回はコマンドラインから実行しましたが、APIを使うことでプログラマブルに請求書を作成することができます。
自社システムとの連携などにぜひご活用ください！