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

概要
API連携が可能なマスタ
リクエスト方式
APIトークン
API基本シーケンス
CSV取込API
　▶API連携が可能なマスタ
　▶接続先URL
　▶ヘッダ
　▶パラメータ（JSON部）
　▶パラメータ（CSVデータ部）
　▶レスポンス
CSV取込状況確認API
　▶接続先URL
　▶ヘッダ
　▶パラメータ
　▶レスポンス
レスポンス
　▶レスポンス（JSON形式）
　▶レスポンスコード
　▶エラーコード
サンプルプログラム　

概要

「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連携が可能なマスタ

リクエスト方式

■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データ部）

■CSVファイル例（社員マスタの場合）

ファイルの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トークン】を参照

▶パラメータ

▶レスポンス

■ 成功時のレスポンス例

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取込状況」画面からダウンロードできる「レポート.txt」で
　失敗した原因を確認することができます。
取込処理が1分以上停止しているレコードは、「異常終了」として取込が強制的に終了します。

レスポンス

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

▶レスポンス（JSON形式）

▶レスポンスコード

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

▶エラーコード　

レスポンスのボディ部に書かれたエラーコードから、エラーの理由を判別できます。

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

サンプルプログラム

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

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

（記事ID：1023）

設定・操作手順を調べる