概要
- 「API連携オプション」（有料）のお申込が必要です。
- APIを通じて、「楽楽精算」から自動出力されたファイル（仕訳データ）を取得できます。
- 常に同一のURLで最新のファイルを取得できます。
- HTTP ヘッダに「楽楽精算」が発行するAPIトークンを埋め込むことで認証を実現します。
「楽楽精算」でできること
「楽楽精算」では、仕訳データの自動出力と自動出力の設定、APIトークンの管理ができます。
仕訳データの自動出力および設定
- 過去に一度も出力されていない仕訳データの自動出力
- 出力の頻度、出力開始時間の設定（※）
- 自動出力時にエラーがあった場合にエラー通知メールを送付する
- エラー通知メールを送付するアドレスの登録（※）
※「自動ファイル出力の設定」から設定、登録ができます。
APIトークンの管理
- APIトークンの発行
- APIのアクセスログの参照
リクエスト方法
APIへのリクエストを行う際の基本的な情報は以下の通りです。
- 通信方式 ：HTTPS
- メソッド ：GET
- 文字コード：UTF-8
- URL ：https://【ドメイン】/【アカウント】/api/v1/【API名】
※詳細については、別途記載されている「URL例」をご参照ください。 - ヘッダ ：X-RS-apitoken: {APIトークン}
※上記のAPIトークンを含むリクエストヘッダを必ず指定してください。
※APIトークンは、別途記載されている「APIトークンの発行」をご確認ください。
■URL例
https://xxxxx.xxxxxx.jp/abcdef/api/v1/fileGenerate/1/result
◆xxxxx.xxxxxx.jp → 利用するドメイン
◆abcdef → 利用するアカウント
◆api/v1 → APIバージョンの指定
◆fileGenerate/1/result → API名（およびそれに付随するパラメータ）
※この例では「fileGenerate」がAPIの名称、「/1/result」がパラメータです。
APIトークン
「楽楽精算」のAPIの利用時に認証用キーとして使用する文字列です。APIトークンは、「楽楽精算」の管理者ユーザー（ログインID：admin）のみ発行できます。
APIトークンの発行
「管理」タブ >「システム設定」 >「その他」タブからAPIトークン欄の「生成」ボタンをクリックし、APIトークンを生成します。
APIトークン生成後、「確定」をクリックするとAPIトークンが「楽楽精算」に登録され、
APIが使用できる状態になります。
APIトークンの再発行
「再生成」ボタンをクリックします。
「確定」をクリックすると、再生成後のAPIトークンが「楽楽精算」に登録されます。
APIトークンの削除
「削除」ボタンをクリックします。
「確定」をクリックすると、APIトークンが「楽楽精算」から削除され、
APIが使用できない状態になります。
自動ファイル出力の取得API
「自動ファイル出力の設定」に従って生成された仕訳データファイルを取得するためのAPIです。接続先URL
GET https://【ドメイン】/【アカウント】/api/v1/fileGenerate/【fileGenerateId】/resultパラメータ
| パラメータ名 | 項目名 | 属性 | 必須 | 設定内容 |
| fileGenerateId |
自動ファイル出力設定ID |
整数 | 〇 | 自動ファイル出力設定IDを指定します。 |
「自動処理関連」メニュー
「API連携オプション」をご契約の環境には、「管理」タブの右下に「自動処理関連」のメニューが表示されます。
※必要な設定メニューが「管理」タブに表示されていない場合はオプション機能を契約したが、設定に必要なメニューが表示されないをご確認ください。
自動ファイル出力の設定
「自動ファイル出力の設定」では自動出力する対象の仕訳区分や、出力を行うタイミングなどを設定できます。
APIのパラメータには、「自動ファイル出力の設定」のIDを指定します。
自動ファイル出力履歴
「自動ファイル出力履歴」では自動出力した履歴の確認ができます。
レスポンス
本APIでは連携の成功・失敗に関わらず、常に最新の自動ファイル出力の結果が返却されます。
もし、API連携の失敗やエラーの発生により、API連携できなかった過去の出力ファイルを取得したい場合は、「楽楽精算」の「自動ファイル出力履歴」画面から取得してください。
（過去の出力ファイルを取得するためのAPIは提供されていません。）
また、自動ファイル出力処理は「自動ファイル出力の設定」で設定された頻度・開始時間で実行されます。
ファイル出力が完了するまでにかかる時間はお客様の環境に依存して前後します。
API連携に成功した場合
成功した場合は指定した「自動ファイル出力の設定」の最新の仕訳データ出力ファイルが返ります。
出力ファイルのフォーマットは、「楽楽精算」の「仕訳データ出力の設定」に従います。
出力フォーマットがCSV形式やTXT形式の場合には、MS932エンコーディングされたテキストデータが返り、ZIP形式の場合にはバイナリデータが返ります。
なお、ファイル名の取得が必要な場合、日本語のファイル名だと文字化けするため、ファイル名を英数字にしてください。
API連携に失敗した場合
失敗した場合は、JSON形式でエラー内容が返ります。
自動ファイル出力が一度も実行されていない場合や、
直近の自動ファイル出力が異常終了した場合には、エラーが返ります。
| パラメータ | 名称 | 説明 |
| status | ステータス | リクエストが成功したかどうか （success：成功 error：異常） |
| code | レスポンスコード | 後述する【レスポンスコード】を参照してください。 |
| url | リクエストURL | |
| query |
リクエスト |
リクエストパラメータのキーと値のペアをオブジェクトで格納します。 "query": { "limit"："2", "page"："2" }, |
| version | APIのバージョン | |
| accessTime | アクセス日時 | |
| errors | エラー情報 | エラー情報を格納します。 |
| ├code |
エラーコード |
後述する【エラーコード】を参照してください。 |
| ├msg | エラー状態 | |
| └ description | 詳細情報 | 入力エラーの場合、各入力項目の詳細はエラー情報を格納します。 |
| ├name | パラメータ名 | |
| ├value | パラメータ値 | |
| ├code | 詳細コード | |
| └ msg | エラーメッセージ |
レスポンスコード
レスポンスのボディ部に書かれたレスポンスコードから、リクエストの成功・失敗を判別することができます。
HTTPのステータスコードも同様の値を返却します。
| レスポンスコード | 状態 | 備考 |
| 200 | 成功 | ー |
| 400 | 通常エラー | 入力エラーなど、アプリケーションが検出するエラー |
| 401 | 認証エラー | 認証失敗、必要な権限がない場合のエラー |
| 402 | API未契約 ライセンス無効 |
API機能が利用できない場合のエラー |
| 403 | 操作権限なし アクセス権なし |
対象となるデータを取得できない場合のエラー |
| 404 | 対象URIなし | URIの指定が間違っている場合のエラー |
| 405 | 対応していない メソッド |
対応していないHTTPメソッドでリクエストされた場合のエラー |
| 413 | リクエスト容量超過 | 最大リクエスト容量を超える容量のリクエストが送信された場合のエラー |
| 429 | リクエスト回数超過 | 最大アクセス数を超える回数のリクエストが送信された場合のエラー |
| 500 | 内部エラー | 予期しないエラー 本エラーが発生した時はお問い合わせフォームからご連絡ください。 |
エラーコード
レスポンスのボディ部に書かれたエラーコードから、エラーの理由を判別することができます。
| レスポンスコード | エラーコード | 状態 | メッセージ |
発生するケース(自動ファイル出力の取得API)
|
| 200 | - | 成功 | - | - |
| 400 | 100 | 入力エラー | パラメータが不正です。 |
不正なリクエストパラメータを送信した場合【例】"fileGenerateId"にブランクや数値以外を指定した場合
|
| 400 | 200 | 対象データなし | 対象データが存在しません。 |
■自動ファイル出力が一度も実行されていない場合
一度でも自動ファイル出力が実行されたことがあれば、このケースでの該当エラーは発生しなくなります。 ただし「データ全削除」で「自動ファイル出力履歴」を削除した場合は、「自動ファイル出力が一度も実行されていない」状態となるため、この場合は該当 エラーが発生するようになります。 ■直近の自動ファイル出力が異常終了した場合 【例】 ①出力上限50万行を超えている時 ②午前2時の「自動出力時にエラー」となった後に「自動ファイル出力の取得API」を実行した時 ■仕訳データ取得APIの接続URLで"fileGenerateId"に存在しない自動ファイル出力設定IDを指定した場合 ■CSV取込状況確認APIの接続URLで"processId"にCSV取込APIのレスポンスパラメータ"processId"で返却されたIdを指定していない場合 |
| 400 | 201 | 重複エラー | データが重複しています。 | 出力なし |
| 400 | 202 | フォーマットエラー |
正しい%format%の形式ではありません。 |
出力なし |
| 400 | 299 | その他のエラー | （その他のエラーのメッセージが表示されます。表示されるメッセージに従って対処してください。） | 出力なし |
| 401 | 1 | 認証エラー | 認証エラーです。 |
APIトークンに不備（未指定、未生成、不正）がある場合
|
| 402 | 2 | API未契約 | API連携オプションが未契約です。 |
API連携オプションを契約していない場合
|
| 402 | 9 | ライセンス無効 | ライセンスが無効です。 |
楽楽精算の契約期間外の場合
|
| 403 | 7 | アクセス権なし | アクセスが拒否されました。 |
IPアドレス制限OPによって許可されていないIPアドレスから接続した場合
|
| 403 | 4 | 操作権限なし | アクセスが拒否されました。 | 出力なし |
| 404 | 3 | 対象URLなし | URLが存在しません。 指定されたバージョンのAPIは存在しません。 |
存在しないAPIのURLに接続した場合
【例】https://ドメイン/アカウント/api/v1/unknown |
| 405 | 8 | 対応していないメソッド | 対応していないHTTPメソッドです。 |
対応していないHTTPメソッド（POST）のリクエストを送信した場合
※本APIが対応しているメソッドはGET |
| 413 | 5 | リクエスト容量超過 | 1回の実行で送信できる容量を超えました。 | 出力なし |
| 415 | 10 | 対応していないファイルタイプ | 対応していないファイルタイプです。 | 出力なし |
| 429 | 6 | リクエスト回数超過 | APIの実行回数が制限を超えました。 |
1分間のリクエスト回数制限（20リクエスト）を超過した場合
|
| 500 | 999 | 内部エラー | 内部エラーが発生しました。 |
上記以外のエラーが発生した場合
|
入力エラー(エラーコード：100)は各項目の詳細なエラー情報も確認することができます。
| エラー コード |
詳細コード | 状態 | メッセージ |
| 100 | 1 | 必須エラー | 必須項目です。 |
| 100 | 2 | 型エラー |
型が正しくありません。
|
| 100 | 3 | 範囲外(下限)エラー |
下限値 (%num%) を超えています。
|
| 100 | 4 | 範囲外(上限)エラー |
上限値 (%num%) を超えています。
|
| 100 | 5 | 桁数不足 |
桁数 (%num%) が不足しています。
|
| 100 | 6 | 桁数超過 |
桁数 (%num%) が超過しています。
|
| 100 | 7 | 書式エラー |
値の書式が不正です。
|
| 100 | 8 | 存在しない値(選択肢など) |
指定されたデータは存在しません。
|
| 100 | 99 | 指定できない値 |
指定された値を設定することはできません。
|
サービスメンテナンス時の注意点
「自動ファイル出力の設定」で設定している出力開始時間に以下の条件に該当する「楽楽精算」のメンテナンスが行われている場合、サービス停止の有無に関わらず、メンテナンス中は自動ファイル出力処理が実行されません。
【条件】
「影響範囲」に「■「API連携オプション」にて仕訳データの自動出力をご利用中のお客様へ」の記載があるもの
なお、メンテナンス時間内で予定されていた自動出力はメンテナンス終了後に自動で実行されます。
※メンテナンス後の自動出力タイミングは、サービス稼働状況に事前掲載しているメンテナンス完了時刻が目安です。
なお、完了時刻は予定よりも前後する可能性がございますので、予めご了承ください。
サービス停止なしのメンテナンスの場合は、メンテナンス中でも「自動ファイル出力の設定」 >「手動実行」ボタンから手動でファイル出力の実行ができます。
「手動実行」で出力されたファイルもAPIで取得することができます。
サンプルプログラム
サンプルプログラムに関しては、サンプルソースを別途用意しております。
ご希望のお客様は画面右上のお問い合わせ > 機能・操作の質問よりお問い合わせください。
（記事ID:1236）
