API連携オプション　CSV取込の初期設定

概要

  • 「API連携オプション（有料）」のお申込が必要です。
    ご希望のお客様は画面上部の「お問い合わせ」よりお問い合わせください。

  • お客様がお使いのシステムで生成したCSVファイルを、APIを通じて「楽楽精算」のマスタにCSV取込することができます。また、CSV取込の状況を確認することができます。

  • 「楽楽精算」のマスタに自動でCSV取込を行うためのプログラムを、お客様にご用意していただく必要がございます。（サンプルプログラムはご提供可能です。）

  • 取込む項目はCSVファイル1行目の項目を自動判別します。

  • HTTP ヘッダに「楽楽精算」が発行するAPIトークンを埋め込むことで認証を実現します。


注意

API呼出しには以下の制限が設定されています。
また、これらの設定値は変更される場合があります。

  • リクエスト数　1アカウントごとに1分間に20リクエスト以下（ユーザーごとではない）
  • 取込に利用できるファイルの上限は、ファイルサイズ5MB、ファイル行数50,000行

メンテナンス時間中は「楽楽精算」サービスに対するリクエストに対してメンテナンスページを返却します。
その際、APIでのアクセスにおいてHTTPステータス200でメンテナンスページのHTMLが返却されます。HTTPステータスコードが200の場合、レスポンスボディを解析してメンテナンス中か否かを判定する必要がございます。

メンテナンス中の場合はHTMLの一行目に「Status: 503 Maintenance mode」と記載されます。
（詳細は、「楽楽精算」のサーバーが停止中の場合、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トークンの発行


1246_seihin_01_20251219
「管理」タブ >「システム設定」 >「その他」タブから
APIトークン欄の「生成」ボタンをクリックし、APIトークンを生成します。

APIトークン生成後、「確定」をクリックするとAPIトークンが「楽楽精算」に登録され、
APIが使用できる状態になります。

APIトークンの再発行


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

APIトークンの削除


1246_seihin_03_20251219
「削除」ボタンをクリックします。
「確定」をクリックすると、APIトークンが「楽楽精算」から削除され、
APIが使用できない状態になります。

API基本シーケンス

リクエスト、レスポンスに関する基本シーケンスは以下の通りです。
※お客様システムと「楽楽精算」の間に中間サーバーが存在する場合を想定しています。
中間サーバーとは「楽楽精算」のAPIを実行するためのプログラムが配置されているサーバーを想定しています。
※中間サーバーが存在しない場合は、お客様システムと「楽楽精算」が直接連携することになります。

1246_image_01_20251219

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ファイル例（社員マスタの場合）

1246_seihin_04_20251219

補足

  • ファイルの1行目に取り込む項目名を指定してください。
    取込できる項目名の一覧はマスタテンプレートよりダウンロードいただけます。

  • 項目の並び順には決まりはありません。
    項目名が一致していれば、どんな並び順でも取り込むことができます。

  • マスタデータは2行目から記述してください。

  • 取込に利用できるファイルの上限は、ファイルサイズ5MB、ファイル行数50,000行です。

  • ファイルの文字コードはMS932を指定してください。

 

レスポンス

成功した場合、登録されたCSVの取込処理IDが返ります。
パラメータ名 項目名 属性 内容
processId CSV取込処理ID 文字列
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】

注意

事前に「CSV取込API」を呼び出してパラメータとするCSV取込処理IDを取得してください。

 

ヘッダ

ヘッダ 備考
X-RS-apitoken: {APIトークン}
必ず指定します。
APIトークンについては前述の【APIトークン】を
参照

パラメータ

パラメータ名 項目名 属性 必須 内容
processId CSV取込処理ID 文字列 〇
CSV取込APIで取得した処理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”
}

注意

  • 取込失敗レコードは、「CSV取込API（取込予約）」が正常終了（レスポンスコード：200）し、CSV取込処理が実行された場合に限り、「CSV取込状況」画面にてダウンロード可能な「レポート.txt」で失敗原因を確認できます。

    なお、API実行時点でエラー（レスポンスコード200以外）が発生した場合は、CSV取込処理は実行されないため、「CSV取込状況」および「レポート.txt」は出力されません。

  • 取込処理が1分以上停止しているレコードは、「異常終了」として取込が強制的に終了します。

レスポンス

以下の情報をJSON形式で受け取ることができます。

レスポンス（JSON形式）

パラメータ 名称 説明
status ステータス
リクエストが成功したかどうか （success:成功 error:異常）
code レスポンスコード
「後述する 【レスポンスコード】を参照してください。
url リクエストURL  
query リクエストパラメータ
リクエストパラメータのキーと値のペアをオブジェクトで格納します。
"query": {
masterId: "1",
duplicateKey: "0"
},
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 リクエスト容量超過
最大リクエスト容量を超える容量のリクエストが送信された場合の工ラー
415 対応していない
対応していないファイルタイプでリクエストされた場合のエラー
429 リクエスト回数超過
最大アクセス数を超える回数のリクエストが送信された場合のエラー
500 内部エラー
予期しないエラー
本エラーが発生した時はサポートセンターまでご連絡ください。
 

エラーコード

レスポンスのボディ部に書かれたエラーコードから、エラーの理由を判別できます。
レスポンスコード エラーコード 状態 メッセージ 発生するケース
（CSV取込API）
発生するケース
（CSV取込状況確認API）
200 - 成功 - - -
400 100 入力エラー パラメータが不正です。 不正なリクエストパラメータを送信した場合
不正なリクエストパラメータを送信した場合
400 200 対象データなし 対象データが存在しません。 出力なし
存在しないprocessIdを指定した場合
400 201 重複エラー データが重複しています。 出力なし 出力なし
400 202 フォーマットエラー 正しい%format%の形式ではありません。
メッセージ例: 正しいJSONの形式ではありません。		 パラメータ （JSON部） の形式が正しくない場合 出力なし
400 299 その他のエラー （その他のエラーのメッセージが表示されます。表示されるメッセージに従って対処してください。） 取込ファイルの項目名に不備がある場合
【例】必須項目の項目名が存在しない場合		 出力なし
401 1 認証エラー 認証エラーです。 APIトークンに不備（未指定、未生成、不正）がある場合
APIトークンに不備（未指定、未生成、不正）がある場合
402 2 API未契約 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 範囲外(下限)エラー
下限値(%num%) を超えています。
100 4 範囲外(上限)エラー
上限値(%num%) を超えています。
100 5 桁数不足
桁数(%num%) が不足しています。
100 6 桁数超過
桁数(%num%) が超過しています。
100 7 書式エラー
値の書式が不正です。
100 8 存在しない値(選択肢など)
指定されたデータは存在しません。
100 99 指定できない値
指定された値を設定することはできません。

サンプルプログラム

サンプルプログラムに関しては、サンプルソースを別途用意しております。
ご希望のお客様は画面右上のお問い合わせ > 機能・操作の質問よりお問い合わせください。 

注意

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

（記事ID：1246）