XronosLink API (1.0.0)

Download OpenAPI specification:Download

XronosLink はクロノス社製品と外部のアプリケーションを API を通じて連携するサービスです（詳しくはこちら）。
XronosLink API は XronosLink 上の情報を外部のアプリケーションから利用するための API です。

「スタートガイド」も参考にご利用ください。

XronosLink API を利用した製品同士の連携をご検討の事業者様は、こちらからお問い合わせください。
⇒ お問い合わせフォーム

API変更履歴

共通仕様

概要

API の共通仕様は以下です。

項目	説明
プロトコル	HTTPS
文字コード	UTF‒8
Content-Type	application/json
Base URL	https://api.xronos-inc.link/v1

認証

API へのアクセスは、リクエストのヘッダに「アクセストークン」を付加する必要があります。
アクセストークンは XronosLink のメニューにある「アクセストークン」から発行できます。

発行方法の詳細はこちらからご確認ください。
⇒ アクセストークンの発行

「X-Xronos-Access-Token」ヘッダに、発行したアクセストークンを追加し、 API リクエストを行います。
以下に curl で API をリクエストするときの例を示します。
（「XXXXX」の部分は、発行したアクセストークンに置き換えてください）

curl -X GET "https://api.xronos-inc.link/v1/employees" -H "X-Xronos-Access-Token: XXXXX"

ページネーション

リストを返す API では、一度に返せる要素数の上限が決まっています。
上限を超える要素を取得したい場合は、ページを指定する必要があります。指定するクエリパラメータは以下です。

クエリパラメータ	デフォルト値	指定可能値	説明
page	1	1以上の整数値	ページ番号
per	20	1～100の整数値	ページ当たりの件数

ページネーションがある API のレスポンスには、以下のヘッダが含まれます。

ヘッダ	説明
X-Total-Count	総件数
Link	ページ移動に関するリンク情報

Link ヘッダには、以下の rel 属性のリンクが含まれます。

rel 属性	説明
next	次のページ（存在する場合）
prev	前のページ（存在する場合）
first	最初のページ
last	最後のページ

Link: <http://api.xronos-inc.link/v1/employees?page=1&per=20>; rel="first",
      <http://api.xronos-inc.link/v1/employees?page=4&per=20>; rel="prev",
      <http://api.xronos-inc.link/v1/employees?page=6&per=20>; rel="next",
      <http://api.xronos-inc.link/v1/employees?page=10&per=20>; rel="last"

ステータスコード

API リクエストがエラーになった場合は、一部のエラーにおいて、以下の HTTP ステータスコードとエラーコードが返されます。
エラーコードは、レスポンスデータ内に含まれます。
以下に記載されている以外の HTTP ステータスコードは、 HTTP の仕様に準拠します。

HTTP ステータスコード	エラーコード	説明
400	invalid_value	値が不正
	invalid_syntax	構文が不正
	no_required	必須パラメータなし
	duplicate_value	必須パラメータの重複
401	invalid_access_token	アクセストークンが不正
	not_exist_access_token	アクセストークンが未設定
	expired_token	アクセストークンの有効期限切れ
	expired_contract	契約の有効期限切れ
403	no_permission	利用許可がない
404	no_resource	リソースが存在しない
500	-	サーバエラー
503	-	サーバ利用不可

エラー時のレスポンスのデータ

エラー時のレスポンスのデータ形式は以下です。

{
  "errors": [
    {
      "message": "エラーメッセージ [string]",
      "code": "エラーコード [string]"
    }
  ]
}

データ連携時の「空文字/null/プロパティ指定なし」の挙動

XronosLink を利用する際のデータの取り扱いについては以下の通りとなります。

JSON プロパティ指定	値	データ更新挙動
あり	文字列指定	指定した文字列で更新する
あり	空文字指定	初期値に更新する
あり	null 指定	更新しない
なし	-	更新しない

例1：社員情報を更新時、すでに登録済みの役職コードをクリア（初期値に変更）したい場合は以下のように指定してください。

[
  {
    "code": "1",
    "positionCode": ""
  }
]

例2：社員情報を更新時、すでに登録済みの役職コードを更新したくない場合は以下のように指定してください。
以下の2つの例は、どちらも更新しない挙動になります。

[
  {
    "code": "1",
    "positionCode": null
  },
  {
    "code": "2"
  }
]

employees

社員

社員一覧取得

XronosLinkに保存されている社員の一覧を取得します。

Authorizations:

AccessToken

query Parameters

page	integer 取得するページ番号（1以上の整数値）（未指定は1）
per	integer 取得するページ当たりの件数（1～100の整数値）（未指定は20）

Responses

Response samples

200
400
401
403

Content type

application/json

[{"code": "1",
"id": 1,
"name": "黒ノ巣 良子",
"lastName": "黒ノ巣",
"firstName": "良子",
"kana": "ｸﾛﾉｽ ﾘｮｳｺ",
"lastNameKana": "ｸﾛﾉｽ",
"firstNameKana": "ﾘｮｳｺ",
"departmentCode": "23-1",
"positionCode": "45",
"jobCode": "67",
"hireDate": "1999-01-01",
"retirementDate": "2011-12-01",
"gender": "female",
"birthDate": "1970-02-03",
"mail": "example@example.jp",
"idm": "00112233AABBCCDD"
}
]

社員登録

社員情報をXronosLinkに新規登録します。
XronosLinkに保存されている社員データを削除後、POSTされたデータのみを登録します。

Authorizations:

AccessToken

Request Body schema: application/json

社員データ

Array

code required	string <= 9 characters 社員コード半角英数のみ許容。
id	integer <= 9 characters IDコード
name	string <= 64 characters 氏名
lastName	string <= 64 characters 姓
firstName	string <= 64 characters 名
kana	string <= 64 characters 氏名フリガナ半角カタカナのみ許容。
lastNameKana	string <= 64 characters 姓フリガナ半角カタカナのみ許容。
firstNameKana	string <= 64 characters 名フリガナ半角カタカナのみ許容。
departmentCode	string <= 35 characters 所属コード最大9階層まで指定できます。半角英数字と階層のセパレート'-'のみ許容。
positionCode	string <= 3 characters 役職コード半角数字の整数値のみ許容。
jobCode	string <= 3 characters 職種コード半角数字の整数値のみ許容。
hireDate	string <date> 入社年月日（yyyy-mm-dd）
retirementDate	string <date> 退職年月日（yyyy-mm-dd）
gender	string 性別（male：男、female：女、unknown：未入力）
birthDate	string <date> 生年月日（yyyy-mm-dd）
mail	string <= 512 characters メールアドレス
idm	string 非接触IDm 16桁の16進数

Responses

Request samples

Payload

Content type

application/json

[{"code": "1",
"id": 1,
"name": "黒ノ巣 良子",
"lastName": "黒ノ巣",
"firstName": "良子",
"kana": "ｸﾛﾉｽ ﾘｮｳｺ",
"lastNameKana": "ｸﾛﾉｽ",
"firstNameKana": "ﾘｮｳｺ",
"departmentCode": "23-1",
"positionCode": "45",
"jobCode": "67",
"hireDate": "1999-01-01",
"retirementDate": "2011-12-01",
"gender": "female",
"birthDate": "1970-02-03",
"mail": "example@example.jp",
"idm": "00112233AABBCCDD"
}
]

Response samples

200
400
401
403

Content type

application/json

[{"code": "1",
"id": 1,
"name": "黒ノ巣 良子",
"lastName": "黒ノ巣",
"firstName": "良子",
"kana": "ｸﾛﾉｽ ﾘｮｳｺ",
"lastNameKana": "ｸﾛﾉｽ",
"firstNameKana": "ﾘｮｳｺ",
"departmentCode": "23-1",
"positionCode": "45",
"jobCode": "67",
"hireDate": "1999-01-01",
"retirementDate": "2011-12-01",
"gender": "female",
"birthDate": "1970-02-03",
"mail": "example@example.jp",
"idm": "00112233AABBCCDD"
}
]

社員取得

社員コードに紐づく社員を取得します。
XronosLinkにデータがない場合はエラーを返します。

Authorizations:

AccessToken

path Parameters

employeeCode

required

string

社員コード

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"code": "1",
"id": 1,
"name": "黒ノ巣 良子",
"lastName": "黒ノ巣",
"firstName": "良子",
"kana": "ｸﾛﾉｽ ﾘｮｳｺ",
"lastNameKana": "ｸﾛﾉｽ",
"firstNameKana": "ﾘｮｳｺ",
"departmentCode": "23-1",
"positionCode": "45",
"jobCode": "67",
"hireDate": "1999-01-01",
"retirementDate": "2011-12-01",
"gender": "female",
"birthDate": "1970-02-03",
"mail": "example@example.jp",
"idm": "00112233AABBCCDD"
}

departments

所属

所属一覧取得

XronosLinkに保存されている所属の一覧を取得します。

Authorizations:

AccessToken

query Parameters

page	integer 取得するページ番号（1以上の整数値）（未指定は1）
per	integer 取得するページ当たりの件数（1～100の整数値）（未指定は20）

Responses

Response samples

200
400
401
403

Content type

application/json

[{"code": "23-1",
"name": "本社営業部",
"shortName": "本社営業"
}
]

所属登録

所属をXronosLinkに新規登録します。
XronosLinkに保存されている所属データを削除後、POSTされたデータのみを登録します。

Authorizations:

AccessToken

Request Body schema: application/json

所属情報

Array

code required	string <= 35 characters 所属コード最大9階層まで指定できます。半角英数字と階層のセパレート'-'のみ許容。
name	string <= 128 characters 所属名
shortName	string <= 128 characters 所属名略称

Responses

Request samples

Payload

Content type

application/json

[{"code": "23-1",
"name": "本社営業部",
"shortName": "本社営業"
}
]

Response samples

200
400
401
403

Content type

application/json

[{"code": "23-1",
"name": "本社営業部",
"shortName": "本社営業"
}
]

所属取得

所属コードに紐づく所属を取得します。
XronosLinkにデータがない場合はエラーを返します。

Authorizations:

AccessToken

path Parameters

departmentCode

required

string

所属コード

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"code": "23-1",
"name": "本社営業部",
"shortName": "本社営業"
}

positions

役職

役職一覧取得

XronosLinkに保存されている役職の一覧を取得します。

Authorizations:

AccessToken

query Parameters

page	integer 取得するページ番号（1以上の整数値）（未指定は1）
per	integer 取得するページ当たりの件数（1～100の整数値）（未指定は20）

Responses

Response samples

200
400
401
403

Content type

application/json

[{"code": "45",
"name": "主任"
}
]

役職登録

役職をXronosLinkに新規登録します。
XronosLinkに保存されている役職データを削除後、POSTされたデータのみを登録します。

Authorizations:

AccessToken

Request Body schema: application/json

役職情報

Array

code required	string <= 3 characters 役職コード半角数字の整数値のみ許容。
name	string <= 128 characters 役職名

Responses

Request samples

Payload

Content type

application/json

[{"code": "45",
"name": "主任"
}
]

Response samples

200
400
401
403

Content type

application/json

[{"code": "45",
"name": "主任"
}
]

役職取得

役職コードに紐づく役職を取得します。
XronosLinkにデータがない場合はエラーを返します。

Authorizations:

AccessToken

path Parameters

positionCode

required

string

役職コード

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"code": "45",
"name": "主任"
}

jobs

職種

職種一覧取得

XronosLinkに保存されている職種の一覧を取得します。

Authorizations:

AccessToken

query Parameters

page	integer 取得するページ番号（1以上の整数値）（未指定は1）
per	integer 取得するページ当たりの件数（1～100の整数値）（未指定は20）

Responses

Response samples

200
400
401
403

Content type

application/json

[{"code": "67",
"name": "営業業務"
}
]

職種登録

職種をXronosLinkに新規登録します。
XronosLinkに保存されている職種データを削除後、POSTされたデータのみを登録します。

Authorizations:

AccessToken

Request Body schema: application/json

職種情報

Array

code required	string <= 3 characters 職種コード半角数字の整数値のみ許容。
name	string <= 128 characters 職種名

Responses

Request samples

Payload

Content type

application/json

[{"code": "67",
"name": "営業業務"
}
]

Response samples

200
400
401
403

Content type

application/json

[{"code": "67",
"name": "営業業務"
}
]

職種取得

職種コードに紐づく職種を取得します。
XronosLinkにデータがない場合はエラーを返します。

Authorizations:

AccessToken

path Parameters

jobCode

required

string

職種コード

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"code": "67",
"name": "営業業務"
}

salaries

給与関連

給与移行データ処理月・管理領域一覧取得

給与移行データ（給与算出に利用する勤務データ）の処理月・管理領域の一覧を取得します。

Authorizations:

AccessToken

query Parameters

year	integer 処理月（年）未指定の場合は全件を取得します。
month	integer 処理月（月）処理月（年）が指定されていない場合は無効になります。
page	integer 取得するページ番号（1以上の整数値）（未指定は1）
per	integer 取得するページ当たりの件数（1～100の整数値）（未指定は20） year、month、areasを含むオブジェクトを1件とします。

Responses

Response samples

200
400
401
403

Content type

application/json

[{"year": 2021,
"month": 11,
"areas": [{"code": 0,
"name": "本社",
"startDate": "2021-11-01",
"endDate": "2021-11-30",
"description": "2021年11月（11/01～11/30）"
}
]
}
]

給与移行データ取得

処理月、管理領域コードに紐づく給与移行データを取得します。
ヘッダ項目とデータが取得できます。

Authorizations:

AccessToken

path Parameters

year required	integer 処理月（年）：YYYY 例：2021
month required	integer 処理月（月）：MM 例：11
areaCode required	integer 管理領域コード

query Parameters

page	integer 取得するページ番号（1以上の整数値）（未指定は1）
per	integer 取得するページ当たりの件数（1～100の整数値）（未指定は20） dataの配列を1件とします。

Responses

Response samples

200
400
401
403
404

Content type

application/json

{"year": 2021,
"month": 11,
"areas": {"code": 0,
"name": "本社",
"startDate": "2021-11-01",
"endDate": "2021-11-30",
"description": "2021年11月（11/01～11/30）"
},
"header": ["社員CD",
"氏名",
"勤務",
"欠勤",
"有給",
"特給",
"傷病",
"出勤時間",
"残業普通",
"深夜",
"早出",
"公出",
"公深",
"法出",
"法深",
"遅刻早退時間"
],
"data": [["1",
"黒ノ巣 良子",
"20",
"0",
"1",
"0",
"0",
"160",
"10",
"2",
"4",
"0",
"0",
"0",
"0",
"0"
]
]
}