マネーフォワードクラウド請求書API スタートアップガイド

いつも請求書作成ソフト「マネーフォワードクラウド請求書」をご利用頂きありがとうございます。
今回は、マネーフォワードクラウド請求書APIの始め方について説明します。

マネーフォワードクラウド請求書APIについて

マネーフォワードクラウド請求書APIを使用することで、マネーフォワードクラウド請求書内で提供している機能の一部を他のシステムでもご利用いただけます。
自社システムとマネーフォワードクラウド請求書との連携などにご活用ください。

なお、マネーフォワードクラウド請求書へアカウント登録が完了していると追加料金なく無料でご利用いただけますが、一部プランをご利用中の場合、API経由での見積書・請求書作成数を月100件までとさせていただきます。

個人

プラン	各帳票作成リクエスト上限
無料	100
パーソナルミニ	100
パーソナル	なし
パーソナルプラス	なし

法人

プラン	各帳票作成リクエスト上限
無料	100
スモールビジネス	100
ビジネス	なし

プロダクトキーをご利用中の場合

プラン	各帳票作成リクエスト上限
ベーシック	100
プロ	なし

※その他、取引先登録数や郵送の可否等は通常のプランごとの制限と同様となります。

また、ご利用につきましては「マネーフォワードクラウド」API利用規約をお読みいただき、同意していただく必要があります。

アプリケーションの作成

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

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

各項目を入力します。

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

Redirect URI
認証の際に使うredirect_uriを入力してください。1行に1URIで複数入力可能です。
入力するURIはhttpsのみ有効です。

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

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

請求書を作成する

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

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]",・・・（略）}

このようなレスポンスが返ってきたら成功です。