概要
- 「API連携オプション(有料)」のお申込が必要です。
ご希望のお客様は画面上部の「お問い合わせ」よりお問い合わせください。
- お客様がお使いのシステムで生成したCSVファイルを、APIを通じて「楽楽精算」のマスタにCSV取込することができます。また、CSV取込の状況を確認することができます。
- 「楽楽精算」のマスタに自動でCSV取込を行うためのプログラムを、お客様にご用意していただく必要がございます。(サンプルプログラムはご提供可能です。)
- 取込む項目はCSVファイル1行目の項目を自動判別します。
- HTTP ヘッダに「楽楽精算」が発行するAPIトークンを埋め込むことで認証を実現します。
API連携が可能なマスタ
取込可能な項目は、APIで取り込める項目一覧(Excel形式)をダウンロードの上ご確認ください。
リクエスト方式
| 通信方式 |
HTTPS |
| メソッド |
POST |
| 文字コード |
UTF-8 |
| URL |
https://【ドメイン】/【アカウント】/api/v1/【API名】
|
| ヘッダ |
X-RS-apitoken:{APIトークン} ※上記のリクエストヘッダを必ず指定してください。 ※APIトークンについてはAPIトークンの発行をご確認ください。
|
■URL例
https://xxxxx.xxxxxx.jp/abcdef/api/v1/csvimport
◆xxxxx.xxxxxx.jp →利用するドメインです。
◆abcdef →利用するアカウントです。
◆api/v1 →APIバージョンの指定です。
◆csvimport →API名です。
※この例において、「csvimport」がAPIの名称です。
APIトークン
「楽楽精算」のAPIの利用時に認証用キーとして使用する文字列です。
APIトークンは、「楽楽精算」の管理者(admin)ユーザーだけが発行できます。
APIトークンの発行

「管理」タブ >「システム設定」 >「その他」タブから
APIトークン欄の「生成」ボタンをクリックし、APIトークンを生成します。
APIトークン生成後、「確定」をクリックするとAPIトークンが「楽楽精算」に登録され、
APIが使用できる状態になります。
APIトークンの再発行

「再生成」ボタンをクリックします。
「確定」をクリックすると、再生成後のAPIトークンが「楽楽精算」に登録されます。
APIトークンの削除

「削除」ボタンをクリックします。
「確定」をクリックすると、APIトークンが「楽楽精算」から削除され、
APIが使用できない状態になります。
API基本シーケンス
リクエスト、レスポンスに関する基本シーケンスは以下の通りです。
※お客様システムと「楽楽精算」の間に中間サーバーが存在する場合を想定しています。
中間サーバーとは「楽楽精算」のAPIを実行するためのプログラムが配置されているサーバーを想定しています。
※中間サーバーが存在しない場合は、お客様システムと「楽楽精算」が直接連携することになります。
CSV取込API
CSV取込予約を行うためのAPIです。
ファイルフォーマットはCSV形式で、ファイル行頭で指定した項目(※)を取り込みます。
(※)詳細は後述の【パラメータ(CSVデータ部)】をご確認ください。
API連携が可能なマスタ
このAPI連携を使用して、「楽楽精算」にCSV取込が可能なマスタは以下の通りです。
接続先URL
POST https://【ドメイン】/【アカウント】/api/v1/csvimport
ヘッダ
※ヘッダに「Content-Type: multipart/form-data」以外は指定しないでください。
| ヘッダ |
備考 |
| X-RS-apitoken: {APIトークン} |
必ず指定します。 APIトークンについては前述の【APIトークン】を参照
|
| Content-Type: multipart/form-data; |
固定 |
パラメータ(JSON部)
パラメータはJSON形式で指定してください。
パラメータ(CSVデータ部)
| ヘッダ |
備考 |
| Content-Disposition: form-data; name="uploadFile";filename="<ファイル名>" |
<ファイル名>にCSVファイルのファイル名を指定します。
|
| Content-Type: application/octet-stream |
固定 |
CSVファイル例(社員マスタの場合)

レスポンス
成功した場合、登録されたCSVの取込処理IDが返ります。
| パラメータ名 |
項目名 |
属性 |
内容 |
| processId |
CSV取込処理ID |
文字列 |
|
成功時のレスポンス例
HTTP/1.1 200 OK Content-Type: application /json { “status”: “success”, “code”: “200”, “url”: ” https://your.domain/your_account/api/v1/csvimport/ “, “query”: { “masterId”: “0”, “duplicateKey”: “1”, “sendPasswordEmail”: “0” }, “processId”: “10”, “version”: “v1”, “accessTime”: “2017-06-22 11:12:18 +0900” } |
失敗時のレスポンス例
HTTP/1.1 400 Bad Request Content-Type: application/json { “status”: “error”, “code”: “400”, “url”: “https://your.domain/your_account/api/v1/csvimport/ “, “query”: { “duplicateKey”: “1”, “sendPasswordEmail”: “0” }, “errors”: { “code”: “100”, “msg”: “パラメータが不正です。”, “description”: [ { “name”: “masterId”, “value”: “”, “code”: “1”, “msg”: “必須項目です” } ] }, “version”: “v1”, “accessTime”: “2016-07-01 14:01:14 +0900” } |
CSV取込状況確認API
CSV取込の状況確認を行うためのAPIです。
接続先URL
GET https://【ドメイン】/【アカウント】/api/v1/csvimportprocess/【processId】
ヘッダ
| ヘッダ |
備考 |
| X-RS-apitoken: {APIトークン} |
必ず指定します。 APIトークンについては前述の【APIトークン】を 参照
|
パラメータ
| パラメータ名 |
項目名 |
属性 |
必須 |
内容 |
| processId |
CSV取込処理ID |
文字列 |
〇 |
|
レスポンス
| パラメータ名 |
項目名 |
属性 |
内容 |
| processStatus |
処理状況 |
文字列 |
wait:未処理 active:実行中 complete:完了 abort:強制終了 error:異常終了 |
| successCount |
成功したレコード数 |
数値 |
|
| failureCount |
失敗したレコード数 |
数値 |
|
成功時のレスポンス例
HTTP/1.1 200 OK Content-Type: application/json { “status”: “success”, “code”: “200”, “url”: ” https://your.domain/your_account/api/v1/csvimportprocess/10/”, “query”: {}, “processStatus”: “complete”, “items”: { “successCount”: “10”, “failureCount”: “1” }, “version”: “v1”, “accessTime”: “2017-06-22 11:12:18 +0900” |
失敗時のレスポンス例
HTTP/1.1 400 Bad Request Content-Type: application/json { “status”: “error”, “code”: “400”, “url”: ” https://your.domain/your_account/api/v1/csvimportprocess/10/”, “query”: {}, “errors”: { “code”: “200”, “msg”: “対象データが存在しません。”, “description”: [] }, “version”: “v1”, “accessTime”: “2016-07-01 14:01:14 +0900” } |
レスポンス
以下の情報をJSON形式で受け取ることができます。
レスポンス(JSON形式)
| パラメータ |
名称 |
説明 |
| status |
ステータス |
リクエストが成功したかどうか (success:成功 error:異常)
|
| code |
レスポンスコード |
「後述する 【レスポンスコード】を参照してください。
|
| url |
リクエストURL |
|
| query |
リクエストパラメータ |
リクエストパラメータのキーと値のペアをオブジェクトで格納します。 "query": { masterId: "1", duplicateKey: "0" },
|
| version |
|
|
| accessTime |
アクセス日時 |
|
| errors |
エラー情報 |
|
| ├code |
エラーコード |
|
| ├msg |
エラー状態 |
|
| └description |
詳細情報 |
入力エラーの場合、各入力項目の詳細なエラー情報を格納します。
|
| ├name |
パラメータ名 |
|
| ├value |
パラメータ値 |
|
| ├code |
詳細コード |
|
| └msg |
|
|
レスポンスコード
レスポンスのボディ部に書かれたレスポンスコードから、リクエストの成功・失敗を判別できます。
HTTPのステータスコードも同様の値を返却します。
| レスポンスコード |
状態 |
備考 |
| 200 |
成功 |
|
| 400 |
通常エラー |
|
| 401 |
認証エラー |
|
| 402 |
API未契約 ライセンス無効 |
|
| 403 |
操作権限なし アクセス権なし |
|
| 404 |
対象URIなし |
|
| 405 |
対応していない メソッド |
対応していないHTTPメソッドでリクエストされた場合のエラー
|
| 413 |
リクエスト容量超過 |
最大リクエスト容量を超える容量のリクエストが送信された場合の工ラー
|
| 415 |
対応していない |
対応していないファイルタイプでリクエストされた場合のエラー
|
| 429 |
リクエスト回数超過 |
最大アクセス数を超える回数のリクエストが送信された場合のエラー
|
| 500 |
内部エラー |
予期しないエラー 本エラーが発生した時はサポートセンターまでご連絡ください。
|
エラーコード
レスポンスのボディ部に書かれたエラーコードから、エラーの理由を判別できます。
| レスポンスコード |
エラーコード |
状態 |
メッセージ |
発生するケース (CSV取込API) |
|
| 200 |
- |
成功 |
- |
- |
- |
| 400 |
100 |
入力エラー |
パラメータが不正です。 |
不正なリクエストパラメータを送信した場合 |
|
| 400 |
200 |
対象データなし |
対象データが存在しません。 |
出力なし |
|
| 400 |
201 |
重複エラー |
データが重複しています。 |
出力なし |
出力なし |
| 400 |
202 |
フォーマットエラー |
正しい%format%の形式ではありません。 メッセージ例: 正しいJSONの形式ではありません。 |
パラメータ (JSON部) の形式が正しくない場合 |
出力なし |
| 400 |
299 |
その他のエラー |
(その他のエラーのメッセージが表示されます。表示されるメッセージに従って対処してください。) |
取込ファイルの項目名に不備がある場合 【例】必須項目の項目名が存在しない場合 |
出力なし |
| 401 |
1 |
認証エラー |
認証エラーです。 |
APIトークンに不備(未指定、未生成、不正)がある場合 |
APIトークンに不備(未指定、未生成、不正)がある場合
|
| 402 |
2 |
API未契約 |
API連携オプションが未契約です。 |
API連携オプションを契約していない場合 |
|
| 402 |
9 |
ライセンス無効 |
ライセンスが無効です。 |
「楽楽精算」の契約期間外の場合 |
|
| 403 |
7 |
アクセス権なし |
アクセスが拒否されました。 |
IPアドレス制限OPによって許可されていないIPアドレスから接続した場合 |
IPアドレス制限OPによって許可されていないIPアドレスから接続した場合
|
| 403 |
4 |
操作権限なし |
アクセスが拒否されました。 |
出力なし |
出力なし |
| 404 |
3 |
対象URLなし |
URLが存在しません。 指定されたバージョンのAPIは存在しません。 |
存在しないAPIのURLに接続した場合 【例】https://ドメイン/アカウント/api/v1/unknown |
存在しないAPIのURLに接続した場合 【例】https://ドメイン/アカウント/api/v1/unknown
|
| 405 |
8 |
対応していないメソッド |
対応していないHTTPメソッドです。 |
対応していないHTTPメソッド(GET)のリクエストを送信した場合 ※本APIが対応しているメソッドはPOST |
対応していないHTTPメソッド(GET)のリクエストを送信した場合 ※本APIが対応しているメソッドはPOST
|
| 413 |
5 |
リクエスト容量超過 |
1回の実行で送信できる容量を超えました。 |
取込ファイルが上限(ファイルサイズ5MB、ファイル行数50,000行)を超過している場合 |
出力なし |
| 415 |
10 |
対応していないファイルタイプ |
対応していないファイルタイプです。 |
対応していないファイルタイプのリクエストを送信した場合 ※本APIが対応しているファイルタイプ (Content-Type) はmultipart/form-data |
出力なし |
| 429 |
6 |
リクエスト回数超過 |
APIの実行回数が制限を超えました。 |
1分間のリクエスト回数制限 (20リクエスト))を超過した場合 |
1分間のリクエスト回数制限 (20リクエスト)を超過した場合
|
| 500 |
999 |
内部エラー |
内部エラーが発生しました。 |
通常時は連携できている場合:上記以外のエラーが発生した場合 設定中に発生した場合: ①boundaryの設定に誤りがある②マルチパートフォームデータの形式が崩れている |
通常時は連携できている場合:上記以外のエラーが発生した場合 設定中に発生した場合: ①boundaryの設定に誤りがある②マルチパートフォームデータの形式が崩れている
|
入力エラー(エラーコード:100)については各項目の詳細なエラー情報も確認することができます。
| エラーコード |
詳細コード |
状態 |
メッセージ |
| 100 |
1 |
必須エラー |
必須項目です。 |
| 100 |
2 |
型エラー |
|
| 100 |
3 |
範囲外(下限)エラー |
|
| 100 |
4 |
範囲外(上限)エラー |
|
| 100 |
5 |
桁数不足 |
|
| 100 |
6 |
桁数超過 |
|
| 100 |
7 |
書式エラー |
|
| 100 |
8 |
存在しない値(選択肢など) |
|
| 100 |
99 |
指定できない値 |
|
サンプルプログラム
サンプルプログラムに関しては、サンプルソースを別途用意しております。
ご希望のお客様は画面右上のお問い合わせ > 機能・操作の質問よりお問い合わせください。
(記事ID:1246)