invox API ドキュメント (1.7.0)

APIエンドポイント

https://api.invox.jp/api/public/

• 認証方法
  OAuth2.0 ( https://oauth.net/2/ )
  認可を経て発行されたアクセストークンを使用してinvoxの機能を利用することができます。(手順の概要)

認可エンドポイント

https://api.invox.jp/oauth2/authorize/
リクエストメソッド: GET
認可コードを取得するために使用します。（認可コードはトークンの取得に必要です）

パラメータ

名前	内容
response_type	レスポンスタイプ。code を指定します。
client_id	クライアントID。弊社から発行いたします。
redirect_uri	コールバックURI。認可レスポンスをリダイレクトするURLです。
state	クライアントが初期リクエストに追加する OPAQUE 値。認可サーバはクライアントにリダイレクトして戻るときに、この値を含めます。
scope	認可される権限。利用されるAPIによって異なります。

リクエストイメージ

GET https://api.invox.jp/oauth2/authorize/?
response_type=code&
client_id=CLIENT_ID&
redirect_uri=https://YOUR_APP/REDIRECT_URI&
state=STATE&
scope=read write

レスポンス内容

HTTP/1.1 302 Found
Location: https://YOUR_APP/REDIRECT_URI?code=AUTHORIZATION_CODE&state=STATE

※認可コード(AUTHORIZATION_CODE)の有効期限は1分間であるため、取得後、1分以内にトークンを取得する必要があります。

トークンエンドポイント（トークンの取得、リフレッシュ、取り消し）

• トークンの取得
  https://api.invox.jp/oauth2/token/
  リクエストメソッド: POST
  トークンの初回取得に使用します。

  ヘッダー
  

  • Authorization
    Basic Base64Encode(CLIENT_ID:CLIENT_SECRET)
    クライアントIDとクライアントシークレットをコロン（:）でつないだ文字列をBase64でエンコードした値を、ベーシックHTTP認証を介して認証ヘッダー（Authorization）に渡します。
    クライアントID(CLIENT_ID)およびクライアントシークレット(CLIENT_SECRET)は弊社から発行いたします。
  • Content-Type
    application/x-www-form-urlencoded
    

  パラメータ

  名前	内容
  grant_type	付与タイプ。authorization_code を指定します。
  client_id	クライアントID
  redirect_uri	コールバックURL。認可エンドポイントで使用された redirect_uri と同じ文字列を指定します。
  code	認可コード

  リクエストイメージ

  POST https://api.invox.jp/oauth2/token >
  Content-Type='application/x-www-form-urlencoded'&
  Authorization=Basic ENCODED_CLIENT_ID_AND_SECRET
  
  grant_type=authorization_code&
  client_id=CLIENT_ID&
  code=AUTHORIZATION_CODE&
  redirect_uri=https://YOUR_APP/REDIRECT_URI
  

  レスポンス内容

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "access_token": "ACCESS_TOKEN",
      "expires_in": 36000,
      "token_type": "Bearer",
      "scope": "read write",
      "refresh_token": "REFRESH_TOKEN
  }
  

  ※アクセストークンの有効期限はexpires_inで返却された値(秒)です。 　リフレッシュトークン（更新トークン）の有効期限はありません。

• トークンのリフレッシュ
  https://api.invox.jp/oauth2/token/
  リクエストメソッド: POST
  トークンのリフレッシュ（有効なアクセストークンの再取得）に使用します。

  ヘッダー
  

  • Authorization
    Basic Base64Encode(CLIENT_ID:CLIENT_SECRET)
    クライアントIDとクライアントシークレットをコロン（:）でつないだ文字列をBase64でエンコードした値を、ベーシックHTTP認証を介して認証ヘッダー（Authorization）に渡します。
    

  • Content-Type
    application/x-www-form-urlencoded

  パラメータ

  名前	内容
  grant_type	付与タイプ。refresh_token を指定します。
  client_id	クライアントID
  refresh_token	更新トークン

  リクエストイメージ

  POST https://api.invox.jp/oauth2/token >
  Content-Type='application/x-www-form-urlencoded'
  Authorization=Basic ENCODED_CLIENT_ID_AND_SECRET
  
  grant_type=refresh_token&
  client_id=CLIENT_ID&
  refresh_token=REFRESH_TOKEN
  

  レスポンス内容

  HTTP/1.1 200 OK
  Content-Type: application/json
  
  {
      "access_token": "ACCESS_TOKEN",
      "expires_in": 36000,
      "token_type": "Bearer",
      "scope": "read write",
      "refresh_token": "REFRESH_TOKEN"
  }
  

  ※リフレッシュされたアクセストークンの有効期限はexpires_inで返却された値(秒)です。 　リフレッシュトークン（更新トークン）の有効期限はありません。

• トークンの取り消し
  https://api.invox.jp/oauth2/revoke_token/
  リクエストメソッド: POST
  不要となったアクセストークンの取り消しに使用します。

  ヘッダー
  

  • Content-Type
    application/x-www-form-urlencoded

  パラメータ

  名前	内容
  token	アクセストークン
  client_id	クライアントID
  client_secret	クライアントシークレット

  リクエストイメージ

  POST https://api.invox.jp/oauth2/revoke_token >
  Content-Type='application/x-www-form-urlencoded'
  
  token=ACCESS_TOKEN
  client_id=CLIENT_ID
  client_secret=CLIENT_SECRET
  

  レスポンス内容

  HTTP/1.1 200 OK
  

ヘッダー

トークン

Bearerスキームでトークン認証を行います。

データフォーマット

Content-Type='application/json'

API接続の事前準備（invox電子帳簿保存の場合）

1. invox電子帳簿保存のご契約内容を確認します

プロフェッショナルプランによるご契約が必要です。

設定 ＞ サービス ＞ サービス・プラン設定 よりご確認ください。

2. 接続用ユーザーの用意します

invox電子帳簿保存にログイン可能なユーザーを登録してください。該当ユーザーによりアップロードされた書類として扱われます（接続用ユーザーを削除するとAPI接続ができなくなります）。

設定 ＞ スタッフ より設定・確認可能です。

3. 企業IDを確認します

API接続時に「企業ID」が必要となります。

設定 ＞ 会社 より確認可能です（システムが自動採番します。任意の値に変更はできません）。

APIを使った認証から登録（invox電子帳簿保存の場合）

1. 認可コード取得（初回のみ必要）

1-1. アクセス用URL（赤字部分含め弊社より提供）にアクセスします

https://api.invox.jp/oauth2/authorize/?response_type={response_type}&client_id={クライアントID}&redirect_uri={リダイレクトURI}&scope={scope}&state={state}

1-2. 事前準備で確認した接続用ユーザーでログオンします

1-3. アクセス許可を行います（invox電子帳簿保存の「書類の登録」が表示されていることを確認してください）

1-4. 認可コードを取得します

リダイレクト先に遷移した後、アドレスバーに表示された内容を保存してください（code=以降の文字列が認可コードです）。

認可コードは1分程度で失効しますので、すぐに「2.トークンの取得」を実施してください。

失効した場合は、再度1-1. からやり直して認可コードを取得してください。

2. トークンの取得

2-a. アクセストークンの取得例

curlコマンドの実行サンプル

curl -X POST -H "Authorization: Basic {クライアントIDとクライアントシークレットをコロン（:）でつないだ文字列をBase64でエンコードした値}"
  -H "Content-Type: application/x-www-form-urlencoded" "https://api.invox.jp/oauth2/token/"
  -d "grant_type=authorization_code"
  -d "client_id={クライアントID}"
  -d "redirect_uri={リダイレクトURI}"
  -d "code={1.で取得した認可コード}"

実行例

応答例（「アクセストークン」と「リフレッシュトークン」が返されます）

2-b. トークンのリフレッシュ例（トークンの期限切れ時に行ってください）

curlコマンドの実行サンプル

curl -X POST -H "Authorization: Basic {クライアントIDとクライアントシークレットをコロン（:）でつないだ文字列をBase64でエンコードした値}"
  -H "Content-Type: application/x-www-form-urlencoded" "https://api.invox.jp/oauth2/token/"
  -d "grant_type=refresh_token"
  -d "client_id={クライアントID}"
  -d "refresh_token={リフレッシュトークン}"

2. と同様に「アクセストークン」と「リフレッシュトークン」が返されます

3. APIによる電子帳簿保存の書類登録

2. で取得した「トークン」と事前準備で確認した「企業ID」が必要となります。

以下、python3 による簡易スクリプト例です。別途「sample.pdf」ファイルを用意します。

import base64
import json
import requests

def main():
  headers = {
    "Authorization": "Bearer {アクセストークン}",
    "content-type": "application/json",
  }
  url = "https://api.invox.jp/api/public/e_storage"

  file_content = open("sample.pdf", "rb").read()
  data = {
    "invox_company_code": "{企業ID}",
    "e_storage": {
      "doc_type": "見積書（受領）",
      "entry_method": "user",
      "file_name": "sample.pdf",
      "file_content": base64.b64encode(file_content).decode("utf-8"),
      "partner_name": "partner_name",
      "transaction_date": "2023/07/01",
      "transaction_amount": "123456",
      "currency_code": "JPY",
      "staff_name": "staff",
    }
  }
  res = requests.post(url, headers=headers, data=json.dumps(data))

if __name__ == "__main__":
  main()

レスポンス例：書類IDと書類URLが返却されます

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "DOCUMENT_ID",
  "url": "DOCUMENT_URL",
}

4. 登録の確認

invox電子帳簿保存にログオンして書類が登録されていることを確認してください。

検索条件の「取込経路」が「API」で検索される書類がAPIによって登録されたものになります。

• Q. invox APIのOAth2.0の利用方法について教えてください

  • A. 以下手順となります。（事前にクライアントIDとクライアントシークレットを取得してください）
    1. クライアントIDを使用して、認可コードを取得
    2. 認可コード、クライアントID、シークレットを使用して、アクセストークンを取得
    3. アクセストークンを使ってAPIを利用
    4. アクセストークンの利用期限が切れた場合は、リフレッシュトークン、クライアントID、シークレットを使用してトークンのリフレッシュを行い、アクセストークンを更新
    • 以後3.および4.を繰り返しご利用ください（1.,2.の手順は初回のみ）

• Q. コールバックURI（redirect_uri）はどのように指定すればよいですか？

  • A. ご希望されるURIがある場合は、API利用時にお申し出ください。特にない場合は、invoxのログイン画面を設定いたします。

• Q. トークンの有効期限はどのくらいですか？

  • A. アクセストークンの有効期限は36000秒（10時間）です。リフレッシュトークン（更新トークン）の有効期限はありません。

• Q. トークンの有効期限が切れた場合はどうすればよいですか？

  • A. トークンのリフレッシュにより有効なアクセストークン（有効期限10時間）を取得することができます。

• Q. invox電子帳簿保存 書類登録を利用するにはどのようなプランが必要ですか？

  • A. プロフェッショナルプランのご契約が必要です。

• Q. invox電子帳簿保存 書類登録で複数の書類を1度に登録することはできますか？

  • A. できません。1度に1書類の登録となります。

• Q. invox電子帳簿保存 書類登録で登録可能なファイルの種類に制限はありますか？

  • A. ファイルの種類に制限はありません。ただし、画像ファイル（jpg、png、gif、bmp、tiff）とPDF以外はinvox電子帳簿保存上で画像イメージを表示することはできません。

• Q. invox電子帳簿保存 書類登録で登録可能なファイルサイズの制限はありますか？

  • A. ファイル含め、リクエストの最大サイズを50メガバイトに制限しております。

• Q. invox電子帳簿保存に登録済みの書類データを取得するAPIはありますか？

  • A. ありません。書類データの確認はinvox電子帳簿保存上で行ってください。

invox受取請求書の機能を提供します。
利用例（受取請求書）

invox発行請求書の機能を提供します。