業務システム

KING OF TIME APIの使い方|アクセストークン・日別勤怠と打刻の取得をPythonで実装、レート制限と利用禁止時間帯【2026年11月】

KING OF TIME APIの使い方|アクセストークン・日別勤怠と打刻の取得をPythonで実装、レート制限と利用禁止時間帯【2026年11月】

KING OF TIMEには、勤怠データを外部のシステムから読み書きするためのWebAPIがあります。仕様書は開発者向けのドキュメントとして公開されていて、アクセストークンを1本用意すれば、従業員・日別勤怠・打刻・月別集計・申請のデータをHTTPSとJSONで扱える仕様です。この記事では、2026年11月21日時点の公式仕様をもとに、トークンの疎通確認から、日別勤怠をPythonで取得する実装、打刻の登録、レート制限と利用禁止時間帯で処理を止めない作り方までを順に説明します。最後に、自前で組むべき場面と、給与ソフト側の既製の連携で済ませてよい場面の線引きも示します。

まとめ:KING OF TIMEのAPIはトークン1本で勤怠と打刻を読み書きできる

  • エンドポイントは https://api.kingtime.jp/v1.0、認証は Authorization: Bearer ヘッダにアクセストークンを付ける方式です。
  • 日別勤怠と日別打刻の取得は、1回のリクエストで指定できる期間が最大62日、過去は最大3年前までです。長い期間は区切って取りに行きます。
  • 管理画面で発行したトークンは、企業単位で「直近5分で500リクエスト」(打刻登録は2000)までが目安で、超えると403(code 105)が返ります。
  • 毎日8:30〜10:00と17:30〜18:30(JST)は、トークン系と打刻登録以外のAPIが使えません。夜間バッチはこの時間帯を避けて組みます。
  • 給与ソフトへ月次の勤怠を渡すだけなら、給与ソフト側の既製連携で足ります。基幹・原価管理・BIへ日次で流すなど、既製連携に無い使い方をするときに自前で組みます。

KING OF TIME WebAPIの連携対象:従業員・日別勤怠・打刻・月別集計・申請

公式仕様の連携希望項目とエンドポイントの対応を、実装で使う単位に並べ替えると次のようになります。読み取り(GET)が中心で、書き込みができるのは従業員・打刻・スケジュール・申請の承認に限られます。月別勤怠は読み取りのみで、APIから月次の集計値を書き換えることはできません。

データ 主なエンドポイント 読み書き
企業・管理者 /company ほか 読み取り
従業員・所属・雇用区分 /employees ほか 読み書き
日別勤怠 /daily-workings 読み取り
日別打刻 日別勤怠の打刻エンドポイント 読み書き
月別勤怠・残休暇 /monthly-workings ほか 読み取り
スケジュール 日別スケジュールデータ 読み書き
申請 時間外勤務・打刻申請 ほか 取得と承認・棄却

データはJSONで、日時はISO 8601形式(打刻時刻は 2016-05-10T10:00:00+09:00 のように秒まで、それ以外は分まで)で表します。仕様は日本国内での利用が前提であることは、仕様書に明記済みです。値がnullの項目はレスポンスから省かれるため、受け取る側は「項目が無い」場合の既定値をあらかじめ決めておくことが必要です。また、従業員には変更されうる「従業員コード」と、コードが変わっても変わらない「従業員識別キー(employeeKey)」があります。他システムと突き合わせるキーには識別キーを使う方が安全です。

仕様は継続して改訂されていて、改訂履歴の最新は2026年2月17日の「従業員データ(一括)の登録・更新APIの追加」と「月別勤怠データへの振替出勤・振替休日の追加」です。製品そのものの機能はKING OF TIMEの製品サイトで確認できます。

アクセストークンの発行とcurlでの疎通確認:有効確認APIと企業情報の取得

APIを呼ぶには、すべてのリクエストにアクセストークンを付けます。公式仕様のアクセストークンの節では、発行を希望する場合はサポートセンターへ問い合わせるようにとの案内です。連携サービス各社の手順書では、管理画面のオプションでWebAPI連携の設定を有効にしてからトークンを発行し、その際に用途・付与するAPI権限・接続元のIPアドレスを指定する流れについての説明です。サーバーから呼ぶ場合は、送信元のIPアドレスを固定できる構成にしておきます。

トークンの有効確認と企業情報の取得をcurlで試すコマンド例

トークンを受け取ったら、まず有効確認のエンドポイントと企業情報の取得で疎通を確かめます。

export KOT_TOKEN="発行したアクセストークン"

# トークンが有効か確かめる({"available": true} が返れば有効)
curl -s "https://api.kingtime.jp/v1.0/tokens/${KOT_TOKEN}/available" \
  -H "Authorization: Bearer ${KOT_TOKEN}"

# 企業情報を取得して疎通を確かめる(企業コード・事業年度開始日などが返る)
curl -s "https://api.kingtime.jp/v1.0/company" \
  -H "Authorization: Bearer ${KOT_TOKEN}"

# 従業員一覧(退職者を含め、メールアドレスも返す)
curl -s "https://api.kingtime.jp/v1.0/employees?includeResigner=true&additionalFields=emailAddresses" \
  -H "Authorization: Bearer ${KOT_TOKEN}"

有効なら {"available": true} が返ります。トークンには、同じ設定で新しいトークンを発行し直す再発行(POST)と、利用停止(DELETE)にも、それぞれ専用のエンドポイントが用意されている仕様です。担当者の異動や漏えいの疑いがあるときは、再発行で古いトークンを無効にできます。認証に失敗したときは errors 配列に message と code を持つオブジェクトが入って返るので、ログにはこの2つを残します。

Pythonで日別勤怠データを取得する:62日ごとの分割と1秒間隔の実装

日別勤怠は GET /daily-workings で、所属コード(division)と期間(start・end)を指定して取得します。期間は最大62日、過去は最大3年前まで、未来は最大1年後までです。次のコードは、指定した期間を62日以内に区切り、レート制限に当たったら待って再試行しながら、従業員ごとの労働時間を集めます。公式仕様のパラメータに沿って組んだ例で、実行には requests パッケージと環境変数 KOT_TOKEN が必要です。

import os
import time
import datetime as dt

import requests

BASE = "https://api.kingtime.jp/v1.0"
TOKEN = os.environ["KOT_TOKEN"]  # トークンはコードに書かず環境変数から読む
HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json; charset=utf-8",
}
JST = dt.timezone(dt.timedelta(hours=9))


def in_blocked_window(now):
    """利用禁止時間帯(JST 8:30〜10:00、17:30〜18:30)かを判定する"""
    m = now.hour * 60 + now.minute
    return 510 <= m < 600 or 1050 <= m < 1110


def is_rate_limited(r):
    """403のcode=105(期間内の上限)と429(サーバー側の制限)を見分ける"""
    if r.status_code == 429:
        return True
    if r.status_code == 403:
        try:
            errors = r.json().get("errors", [])
        except ValueError:
            return False
        return any(str(e.get("code")) == "105" for e in errors)
    return False


def get(path, params=None, retries=3):
    for i in range(retries):
        r = requests.get(BASE + path, headers=HEADERS, params=params, timeout=30)
        if is_rate_limited(r):
            time.sleep(60 * (i + 1))  # 直近5分の集計なので分単位で待つ
            continue
        r.raise_for_status()  # 認証エラーなどはそのまま止める
        return r.json()
    raise RuntimeError("レート制限が解けないため中断しました")


def daily_workings(start, end, division=None):
    """start〜endを62日以内の区間に分け、日別勤怠を1区間ずつ取得する"""
    rows, cur = [], start
    while cur <= end:
        to = min(cur + dt.timedelta(days=61), end)
        params = {"start": cur.isoformat(), "end": to.isoformat()}
        if division:
            params["division"] = division
        for day in get("/daily-workings", params):
            for w in day.get("dailyWorkings", []):
                rows.append({
                    "date": w["date"],
                    "employeeKey": w["employeeKey"],
                    # 値がnullの項目はレスポンスに含まれないので既定値を置く
                    "totalWork": w.get("totalWork", 0),  # 労働合計(分)
                    "overtime": w.get("overtime", 0),    # 残業(分)
                    "isClosing": w.get("isClosing", False),
                })
        cur = to + dt.timedelta(days=1)
        time.sleep(1)  # 並列にせず1件ずつ、1秒ほど間隔をあける
    return rows


if __name__ == "__main__":
    if in_blocked_window(dt.datetime.now(JST)):
        raise SystemExit("利用禁止時間帯のため実行しません")
    today = dt.datetime.now(JST).date()
    data = daily_workings(today - dt.timedelta(days=90), today - dt.timedelta(days=1))
    print(len(data), "件", data[:2])

レスポンスは日付ごとの配列で、各日の dailyWorkings に従業員ごとの勤怠が入ります。時間の項目はすべて分単位で、assigned(所定)・overtime(残業)・lateNight(深夜)・breakTime(休憩)・totalWork(労働合計)などが主な項目です。isClosing は締め状況、isError は打刻漏れなどのエラー勤務の有無を表します。給与や原価に使う集計は、締めが済んだ日(isClosing が true)だけを確定値として扱い、締め前の値は速報として別に持つと、後から数字が変わったときに説明がつきます。

月単位の合計だけが要るなら、GET /monthly-workings/{年月}(例:/monthly-workings/2026-10)で従業員ごとの月次集計を1回で取れます。日別を積み上げるよりリクエスト数が少なく、KING OF TIME側の集計ルールと数字がずれません。

日別打刻データの取得と打刻登録:timerecordエンドポイントの使い分け

出退勤の時刻そのものが必要な場合は、勤怠ではなく日別打刻データのエンドポイント /daily-workings/timerecord を使います。取得は employeeKeys(カンマ区切りで複数指定)か division のどちらかで対象を絞り、期間の上限は日別勤怠と同じく62日です。登録は、従業員を指定して1件ずつ送る従業員指定登録と、複数人分をまとめて送る一括登録があります。

# 特定の従業員の打刻を一覧で取得する(employeeKeys はカンマ区切りで複数指定できる)
curl -s "https://api.kingtime.jp/v1.0/daily-workings/timerecord?employeeKeys=<employeeKey>&start=2026-11-01&end=2026-11-20" \
  -H "Authorization: Bearer ${KOT_TOKEN}"

# 打刻を1件登録する(date=勤務日は必須、time は秒まで書く)
curl -s -X POST "https://api.kingtime.jp/v1.0/daily-workings/timerecord/<employeeKey>" \
  -H "Authorization: Bearer ${KOT_TOKEN}" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{"date": "2026-11-20", "time": "2026-11-20T09:00:00+09:00"}'

登録では勤務日(date)の指定が必須で、打刻の種別(出勤・退勤・休憩開始・休憩終了)は省略すると自動で判定されます。緯度・経度を付けて位置情報つきの打刻にすることもでき、値は10進表記で、緯度は-90〜+90、経度は-180〜+180の範囲外にあたる値はエラーです。自社の入退室システムや現場用の端末から打刻を流し込む用途では、打刻登録は利用禁止時間帯の対象外で、レート制限も直近5分で2000リクエストと緩めの設定です。朝夕の打刻が集中する時間帯にも送れるよう、仕様の側で配慮されていると読めます。

レート制限と利用禁止時間帯に当たっても夜間バッチを止めない設計

レート制限は、管理画面で発行したトークンの場合「企業」単位で数えます。同じ企業で複数のトークンを発行していると、すべてのリクエストが合算される点に注意が必要です。部署ごとに別々のバッチを作ると、互いの回数を食い合います。

対象 企業単位の上限 連携サービス単位の上限
打刻登録以外のすべてのAPI 直近5分で500 直近5分で1500
日別打刻データ(POST) 直近5分で2000 直近5分で2000

上限を超えると HTTP 403 と code: 105 のエラーが返ります。これとは別に、サーバーの負荷が高いときには HTTP 429(Too Many Requests)が返ることがあり、レスポンスの形は、公式仕様によると2種類です。リクエストは並列にせず1件ずつ、1秒ほど間隔をあけて送るのが公式の目安で、前の節のコードはこれに合わせています。

もう1つの制約が利用禁止時間帯です。JSTの8:30〜10:00と17:30〜18:30は、アクセストークン関連と打刻登録以外のAPIを呼べません。夜間に前日分を取り込むバッチなら影響しませんが、取り込みが長引いて朝まで続くと、8:30で処理が停止する仕様です。取得期間を区切って途中から再開できるようにし、終わらなかった区間を翌晩に回す作りにしておくと、運用担当による朝の手動での再実行が不要です。なお公式仕様には「WebAPIの動作に関するお問合せは受け付けしておりません」と書かれているため、エラーの切り分けは自社側のログで完結させる前提で設計します。

自社システムと連携する判断:APIを自前で組む条件と既製連携で済ませる場面

給与計算ソフトへ月次の勤怠を渡すだけなら、APIを自前で組む必要はありません。たとえば弥生給与 Nextは、KING OF TIMEの全権管理者IDで認証する形のAPI連携設定を用意していて、従業員コードと締め日を両側で合わせれば勤怠を取り込めます(対象はヒューマンテクノロジーズが直接販売しているKING OF TIMEのみと記載)。こうした既製の連携があるなら、まずそれを使い、足りない部分だけを補う方が保守の手間は小さく済みます。給与ソフトの選び方は給与計算システムの比較で、勤怠連携を含む4つの観点から整理しています。

自前で組むのは、次のような場合です。工数や原価の管理システムへ日別の労働時間を流したい、複数の拠点システムの打刻をKING OF TIMEへ集約したい、残業時間をBIで日次に可視化して上限の手前で警告したい。どれも既製の連携では受け手が用意されていない使い方で、日別勤怠と打刻のAPIがそのまま役に立ちます。外部APIを呼ぶ処理の共通の作り方(認証情報の保管、リトライ、冪等性)はAPI連携の実装方法に、APIとCSV連携のどちらを選ぶかはAPI連携とはにまとめています。

見送る方がよいのは、取り込みの失敗が給与の確定を止めてしまう構成を、APIだけで組もうとする場合です。利用禁止時間帯と5分単位の上限があるため、締め日の朝に一斉に取得する設計は破綻しやすく、CSV出力という逃げ道を残しておく方が安全です。同じ勤怠SaaSでも、ジョブカンは公開されているAPIの範囲と連携の申込方法が大きく違います。比較する場合はジョブカン APIの使い方を参照してください。勤怠データを基幹システムや独自の打刻端末とつなぐ設計から任せたい場合は、一創の勤怠管理システム開発でご相談を受け付けています。

KING OF TIME APIのよくある質問:仕様書・利用制限・連携時の確認事項

KING OF TIMEのAPI仕様書はどこで見られますか?

開発者向けの仕様書が developer.kingoftime.jp で公開されていて、ログインせずに読めます。エンドポイントごとのパラメータ、レスポンスの項目、リクエスト例、改訂履歴まで1ページにまとまっています。仕様は改訂が続いているため、実装前と年に1回程度は改訂履歴を確認してください。

日中にAPIがエラーになるのはなぜですか?

JSTの8:30〜10:00と17:30〜18:30は利用禁止時間帯で、アクセストークン関連と打刻登録以外のAPIを呼べません。この時間帯以外でも、企業単位で直近5分に500リクエストを超えると403(code 105)、サーバーの負荷が高いと429が返ります。エラーの本文にある code を見れば、どの制限に当たったかを区別できます。

従業員コードと従業員識別キーはどう使い分けますか?

従業員コードは管理画面で変更できる番号で、従業員識別キー(employeeKey)はコードが変わっても変わらない値です。打刻の登録や他システムとの突き合わせには識別キーを使い、画面や帳票に出すときに従業員コードを併記すると、コードの付け替えで連携が切れる事故を防げます。

3年より前の勤怠データをAPIで取得できますか?

日別勤怠と日別打刻の取得は、過去日が最大3年前までと定められています。それより古いデータが必要になる可能性があるなら、定期的に取得して自社側に保管しておくか、管理画面からのデータ出力で別途保存しておく運用を決めておきます。

APIの不具合や仕様について問い合わせできますか?

公式仕様には、WebAPIの動作に関する問い合わせは受け付けていないとの記載です。トークンの発行依頼先はサポートセンターですが、実装中のエラーは仕様書とレスポンスのエラーコードから自社で切り分ける前提で進めます。リクエストとレスポンスの内容をログに残しておくと、原因の特定が早くなります。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2025.12.19 コラム アンダーマイニング効果とは?具体例と報酬でやる気が下がる条件、エンハンシング効果との違い
  2. 2026.11.20 テックブログ MAI Code 2とは?Flashとの違い・料金・GitHub Copilotでの使い方【2026年11月】
  3. 2026.11.18 テックブログ 楽天証券の不正アクセス:最大約447万口座の対象確認と、テスト環境に本番データを置かない実装
  4. 2026.11.20 テックブログ 六花亭の不正アクセス:決済画面の改ざんでカード情報約8,000件、対象期間と改ざん検知の手順【11月20日時点】
  5. 2026.11.09 テックブログ teket不正アクセス:ログインできない理由と再開見通し、入場・退会・偽メールの確認【11月16日時点】

RELATED POSTS 関連記事

目次