マネーフォワードクラウド請求書API スタートアップガイド（v1,v2ご利用者さま向け）

このガイドでは、「マネーフォワードクラウド請求書API v1,v2」を利用する流れについてご説明します。

2023年2月22日に「マネーフォワードクラウド請求書API v3」をリリースしました。
クラウド請求書API v1,v2をご利用の場合は、順次API v3への移行が必要です。
詳細はこちらをご確認ください。

対象ページ

API連携β（開発者向け）

対象のお客さま

マネーフォワードクラウド請求書をご利用中のお客さま

利用の流れ

1.アプリケーションの作成

はじめに、APIを利用するアプリケーションを作成します。

画面右上の歯車のアイコンをクリックし、「API連携」をクリックします。

「OAuthアプリケーション一覧」画面で「新規作成」をクリックします。

表示された項目をそれぞれ入力します。
項目についての詳細はこちらをご確認ください。

各項目の入力が完了したら「マネーフォワードクラウド」API利用規約を確認し、問題がなければチェックを入れます。

「作成」をクリックしてアプリケーションを作成します。

アプリケーションを作成すると、「Client ID」と「Client Secret」が発行されます。

入力項目の詳細

名前
アプリケーションの名前を入力します。

Redirect URI
認証の際に使う「redirect_uri」を入力してください。
なお、1行に1URIで複数入力可能です。
URIは必ず「https」で入力してください。

Scopes
「read」または「write」から選択できます。
「read」の場合は以下の権限を与えられます。
・請求書の閲覧・検索
・取引先の閲覧
・品目の閲覧
・送付履歴の閲覧
・事業者情報の閲覧
「write」の場合は、「read」に加えて以下の権限が与えられます。
・請求書の作成・更新・郵送
・取引先の作成・更新
・品目の作成・更新
・事業者情報の更新

2.アクセストークンの発行

発行された「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

※リフレッシュトークンには有効期限はありません。
※リフレッシュトークンはアクセストークンの再発行ごとに発行されるため、使い回しはできません。

3.請求書を作成する

本項では、請求書を作成する場合を例に説明します。

請求書の作成に必要な取引先を作成します。
以下は必須項目である取引先のみを指定しています。

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

以下のようなレスポンスが表示されるので、[DEPARTMENT_ID]にあたる値を控えます。

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"}]}

以下のようなリクエストを行い、請求書を作成します。

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