楽楽精算サクセスナビ
全体検索
ログイン
ユーザー画像
ログイン

設定・操作手順を調べる

ユーザー画像
楽楽精算CS
2024/09/30 15:00

API連携オプション　仕訳データの自動出力の初期設定

目次

概要
「楽楽精算」でできること
リクエスト方法
APIトークン
　▶APIトークン発行
　▶APIトークン再発行
　▶APIトークンの削除
自動ファイル出力の取得API
　▶接続先URL
　▶パラメータ
　▶「自動処理関連」メニュー
レスポンス
　▶レスポンスコード
　▶エラーコード　
サービスメンテナンス時の注意点
サンプルプログラム


概要

  • 「API連携オプション」（有料）のお申込が必要です。
  • APIを通じて、「楽楽精算」から自動出力されたファイル（仕訳データ）を取得できます。
  • 常に同一のURLで最新のファイルを取得できます。
  • HTTP ヘッダに「楽楽精算」が発行するAPIトークンを埋め込むことで認証を実現します。

 

「楽楽精算」でできること

「楽楽精算」では、仕訳データの自動出力と自動出力の設定、APIトークンの管理ができます。

■仕訳データの自動出力および設定

  • 過去に一度も出力されていない仕訳データの自動出力
  • 出力の頻度、出力開始時間の設定（※）
  • 自動出力時にエラーがあった場合にエラー通知メールを送付する
  • エラー通知メールを送付するアドレスの登録（※）
    　※「自動ファイル出力の設定」から設定、登録が可能です。
     

■APIトークンの管理

  • APIトークンの発行
  • APIのアクセスログの参照
  • API連携で取得できるファイルは、過去に一度も出力されておらず、
    　自動ファイル出力で出力された、出力設定IDごとの最新のデータ（※）です。

    　※「自動ファイル出力履歴」の表示順が以下の場合、
    　　  APIでID：1を指定して取得した場合は、1行目のファイル、
    　　  　　  ID：2を指定して取得した場合は、2行目のファイルが取得されます。
    　　・出力履歴の1行目：「自動ファイル出力設定」のID：1で出力された計上仕訳データ
    　　・出力履歴の2行目：「自動ファイル出力設定」のID：2で出力された支払仕訳データ
     
  • 過去に出力したファイルを取得するAPIは提供されていません。
    　  ※過去にさかのぼって出力ファイルを取得したい場合は、
    　　「自動ファイル出力履歴」画面から取得してください。
     
  • API呼出しには以下の制限が設定されています。
    　  また、これらの設定値は変更される場合があります。
    　・リクエスト数　1アカウント毎に1分間に20リクエスト以下（ユーザー毎ではない）
    　
  • メンテナンス時間中は「楽楽精算」サービスに対するリクエストに対して
    　  メンテナンスページを返却します。
    　  その際、APIでのアクセスにおいてHTTPステータス200でメンテナンスページのHTMLが
    　  返却されます。HTTPステータスコードが200の場合、レスポンスボディを解析して
    　  メンテナンス中か否かを判定する必要がございます。
    　  メンテナンス中の場合はHTMLの一行目に「Status: 503 Maintenance mode」と記載されます。
    　（詳細はこちら）


リクエスト方法

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


▶パラメータ


▶「自動処理関連」メニュー

「API連携オプション」をご契約の環境には、
「管理」タブの右下に「自動処理関連」のメニューが表示されます。

※必要な設定メニューが「管理」タブに表示されていない場合はこちらをご確認ください。


■自動ファイル出力の設定
「自動ファイル出力の設定」では自動出力する対象の仕訳区分や、
出力を行うタイミングなどを設定できます。
APIのパラメータには、「自動ファイル出力の設定」のIDを指定します。


■自動ファイル出力履歴
「自動ファイル出力履歴」では自動出力した履歴の確認ができます。

　自動出力の設定後に手動での連携を行う必要がでてきた場合は、
　  API連携　手動実行する場合の手順を知りたいをご確認ください。

 

レスポンス

本APIでは連携の成功・失敗に関わらず、常に最新の自動ファイル出力の結果が返却されます。

もし、API連携の失敗やエラーの発生により、API連携できなかった過去の出力ファイルを
取得したい場合は、「楽楽精算」の「自動ファイル出力履歴」画面から取得してください。
（過去の出力ファイルを取得するためのAPIは提供されていません。）

また、自動ファイル出力処理は「自動ファイル出力の設定」で設定された
頻度・開始時間で実行されます。
ファイル出力が完了するまでにかかる時間はお客様の環境に依存して前後します。


■API連携に成功した場合
成功した場合は指定した「自動ファイル出力の設定」の最新の仕訳データ出力ファイルが返ります。
出力ファイルのフォーマットは、「楽楽精算」の「仕訳データ出力の設定」に従います。

出力フォーマットがCSV形式やTXT形式の場合には、MS932エンコーディングされたテキストデータが
返り、ZIP形式の場合にはバイナリデータが返ります。

　成功時のレスポンス例

　HTTP/1.1 200 OK
　Content-Disposition: attachment; filename=仕訳データ出力_20150905_020011714.csv
　X-Content-Type-Options: nosniff
　Content-Type: application/octet-stream
　Content-Length: 1454

　(出力ファイルのデータ)


■API連携に失敗した場合
失敗した場合は、JSON形式でエラー内容が返ります。
自動ファイル出力が一度も実行されていない場合や、
直近の自動ファイル出力が異常終了した場合には、エラーが返ります。

　失敗時のレスポンス例

　HTTP/1.1 400 Bad Request
　Content-Type: application/json
　X-Content-Type-Options: nosniff

　{
　　　”status”: “error”,
　　　”code”: “400”,
　　　”url”: “https://your.domain/your_account/api/v1/fileGenerate/1/result”,
　　　”query”: {},
　　　”errors”: {
　　　　　”code”: “200”,
　　　　　”msg”: “対象データが存在しません。”,
　　　　　”description”: []
　　　},
　　　”version”: “v1”,
　　　”accessTime”: “2015-09-16 14:01:14 +0900”
　}

 


▶レスポンスコード

レスポンスのボディ部に書かれたレスポンスコードから、
リクエストの成功・失敗を判別することが可能です。
HTTPのステータスコードも同様の値を返却します。


▶エラーコード　

レスポンスのボディ部に書かれたエラーコードから、エラーの理由を判別することが可能です。



入力エラー(エラーコード：100)は各項目の詳細なエラー情報も確認することが可能です。


サービスメンテナンス時の注意点

「自動ファイル出力の設定」で設定している出力開始時間に以下の条件に該当する
「楽楽精算」のメンテナンスが行われている場合、サービス停止の有無に関わらず、
メンテナンス中は自動ファイル出力処理が実行されません。

【条件】
「影響範囲」に「■「API連携オプション」にて仕訳データの自動出力をご利用中のお客様へ」の
　記載があるもの

なお、メンテナンス時間内で予定されていた自動出力はメンテナンス終了後に自動で実行されます。

※メンテナンス後の自動出力タイミングは、
　サービス稼働状況 に事前掲載しているメンテナンス完了時刻が目安です。
　なお、完了時刻は予定よりも前後する可能性がございますので、予めご了承ください。

　サービス停止なしのメンテナンスの場合は、メンテナンス中でも
「自動ファイル出力の設定」 >「手動実行」ボタンから手動でファイル出力の実行ができます。
「手動実行」で出力されたファイルもAPIで取得することができます。

メンテナンス後に自動出力されたファイルがAPIで取得できない場合

  • 「楽楽精算」のメンテナンス時間と、お客様にて「自動ファイル出力の取得API」を実行する時間
    　との兼ね合いで、メンテナンス後に自動出力されたファイルがAPIで取得できない場合は、
    　以下1.2.のいずれかの対応方法で該当するファイルを取得してください。

    　【対応方法】
    　1.メンテナンス終了後、次の自動ファイル出力が実行される前に、
    　　お客様にて「自動ファイル出力の取得API」を実行してファイルを取得する。

    　2.「自動ファイル出力履歴」から該当のファイルを手動でダウンロードを行い、
     　　手動で連携先にファイルを取り込む。

    　※1.の方法が間に合わなかった場合は、メンテナンス後に自動出力されたファイルはAPIで
    　　取得できません。その場合は、お手数ですが上記2.の方法でご対応ください。
    　（API連携では、自動ファイル出力で出力された最新のファイルのみ自動連携が可能なため）
     
  • お客様の『自動ファイル出力の取得API』実行時に「楽楽精算」がメンテナンス中だった場合は、
    　「楽楽精算」サービスに対するリクエストに対して メンテナンスページを返却します。 
    　  その際、APIでのアクセスにおいてHTTPステータス200でメンテナンスページのHTMLが
    　  返却されます。HTTPステータスコードが200の場合、レスポンスボディを解析して
    　  メンテナンス中か否かを判定する必要がございます。


「手動実行」した場合の注意点

  • APIで取得される仕訳データは、自動出力／手動実行のいずれかによって、
    　直近で出力された仕訳データとなります。
    　そのため手動実行を実施した場合は、以下の点にご注意下さい。

    　【注意点】

　1.手動実行で出力した仕訳データを「自動ファイル出力履歴」から手動でダウンロードして
　　 別のシステムに連携している場合、次の自動出力より前にAPIで取得される仕訳データは、
 　　手動実行で出力された仕訳データとなります。
 　　そのため、同一の仕訳データを重複して連携してしまう可能性がございます。
 

　2.手動実行を実施した後、別のシステムに連携する前に次の自動出力が実施された場合、
 　　APIで取得される仕訳データは、自動出力されたデータとなります。
　　 そのため、手動実行で出力した仕訳データに関しては、「自動ファイル出力履歴」から
 　　手動でダウンロードいただき、別のシステムへ連携する必要がございます。


サンプルプログラム

サンプルプログラムに関しては、サンプルソースを別途用意しております。
ご希望のお客様は「お問い合わせ」メニューよりお問い合わせください。

　なおあくまでサンプルであり、この通りに作ることを推奨しているものではなく、
　動作の保証はしておりません。
　プログラムの内容について具体的なご案内はできないため、予めご了承ください。



（記事ID：1013）

いいね
× 


  

    キャンセル
    OK