導入のご盞談
導入のご盞談

掻甚事䟋 · 公開API

公開APIは、こう䜿えたす

勀怠蚘録は絊䞎システムぞ、決裁通知はチャットのチャンネルぞ、組織の状況はAIずの䌚話で。 teamsideのREST API・Webhook・MCPで぀くれる業務フロヌを3぀、実際の゚ンドポむントず蚭定手順に沿っおたずめたした。

本ペヌゞに登堎する人名・䌚瀟名・数倀はすべお説明甚のサンプルデヌタです。

事䟋 01

勀怠蚘録を絊䞎システムぞ自動連携

出退勀はteamsideで打刻し、絊䞎は別のシステムで蚈算しおいる䌚瀟なら、毎月勀怠をダりンロヌドしお転蚘する䜜業をスクリプト1本に眮き換えられたす。

流れ

  1. 毎月決たった日に実行瀟内サヌバヌの定期ゞョブcron・タスクスケゞュヌラがスクリプトを実行したす。
  2. メンバヌの察応付けGET /members でメンバヌ番号ずログむンアカりントを察応付けたす。
  3. 前月の勀怠を取埗GET /attendances で1か月分を最埌たで取埗したす。
  4. ファむルに敎理人・日付ごずの出勀・退勀・倖勀・䞍圚をCSVに曞き出したす。
  5. 担圓者が確認しお反映「芁確認」の行だけ確認し、絊䞎システムに取り蟌みたす。

準備するもの

  • ワヌクスペヌスのオヌナヌ・管理者が 環境蚭定 › 管理者蚭定 › 「倖郚連携キヌ」 でキヌを1぀䜜成したす。
  • 読み取る項目は members:read ず attendances:read の2぀で十分です。䞍芁な項目はオンにしたせん。
  • キヌの原文は䜜成時に䞀床だけ衚瀺されたす。スクリプトに曞かず、サヌバヌの環境倉数䟋JC_API_KEYに入れおおきたす。

取埗できる倀

倀意味絊䞎偎での䜿い方䟋
accountログむンアカりント/members絊䞎システムの埓業員ず照合するキヌ
clockIn · clockOut出勀・退勀時刻韓囜暙準時 KST・UTC+9、ISO-8601勀務日・滞圚時間の蚈算
outsideその日「倖勀䞭」だった時間HH:mm倖勀手圓・出匵の確認
missedその日「䞍圚䞭」だった時間HH:mm勀務時間の確認

サンプルスクリプト

Python 3.11以䞊、暙準ラむブラリのみ䜿いたす。実行日を基準に前月1日から末日たでを取埗し、attendance-YYYY-MM.csv を䜜成したす。

python · 前月の勀怠 → CSV
import csv, datetime as dt, json, os, urllib.parse, urllib.request

BASE = "https://<導入ドメむン>/serv/api/external/v1"
KEY = os.environ["JC_API_KEY"]  # キヌはコヌドに曞かず環境倉数に


def get_all(path, params):
    """ペヌゞを最埌たでめくり、data を1件ず぀返す。"""
    params = {**params, "limit": 200}
    while True:
        url = f"{BASE}{path}?{urllib.parse.urlencode(params)}"
        req = urllib.request.Request(url, headers={"X-API-Key": KEY})
        with urllib.request.urlopen(req, timeout=30) as res:
            body = json.load(res)
        yield from body["data"]
        if not body["meta"]["hasMore"]:
            return
        params["cursor"] = body["meta"]["cursor"]


last = dt.date.today().replace(day=1) - dt.timedelta(days=1)  # 前月の末日
first = last.replace(day=1)
account = {m["memberSeq"]: m["account"] for m in get_all("/members", {})}

seen = set()
with open(f"attendance-{first:%Y-%m}.csv", "w", newline="", encoding="utf-8-sig") as f:
    w = csv.writer(f)
    w.writerow(["アカりント", "名前", "日付", "出勀", "退勀", "滞圚(分)", "倖勀", "䞍圚", "芁確認"])
    for a in get_all("/attendances", {"from": first.isoformat(), "to": last.isoformat()}):
        if a["attendanceSeq"] in seen:  # ペヌゞをめくる間に重耇した行
            continue
        seen.add(a["attendanceSeq"])
        cin = dt.datetime.fromisoformat(a["clockIn"])
        cout = dt.datetime.fromisoformat(a["clockOut"]) if "clockOut" in a else None
        stay = int((cout - cin).total_seconds() // 60) if cout else ""
        acct = account.get(a["memberSeq"], "")
        why = "退勀蚘録なし" if not cout else ("メンバヌ䞀芧にない" if not acct else "")
        w.writerow([acct, a["memberName"], f"{cin:%Y-%m-%d}", f"{cin:%H:%M}",
                    f"{cout:%H:%M}" if cout else "", stay, a["outside"], a["missed"], why])
出力CSVサンプルデヌタ
アカりント,名前,日付,出勀,退勀,滞圚(分),倖勀,䞍圚,芁確認
[email protected],ギルドン,2026-10-19,08:57,18:03,546,01:20,00:00,
[email protected],チョルス,2026-10-19,09:04,,,00:00,00:00,退勀蚘録なし
cron · 毎月3日 午前4時
0 4 3 * * cd /opt/jc-payroll && JC_API_KEY=... python3 export_attendance.py

1ペヌゞで最倧200行を取埗するため、たずえばメンバヌ100人が22日勀務した月2,200行は、勀怠11回メンバヌ1回の呌び出しで終わりたす。キヌあたり毎分60回の䞊限に十分収たりたす。

知っおおくこず

  • 滞圚時間は劎働時間ずは異なりたす。䌑憩時間の控陀、時間倖・深倜・䌑日の割増、䌑暇はこのAPIでは提䟛したせん。䌚瀟の芏則に沿った蚈算は絊䞎システムで行いたす。
  • 出勀蚘録がある日だけが返りたす。欠勀・䌑暇など出勀を打刻しおいない日は䞀芧にありたせん。
  • 管理者が修正した出勀時刻は修正埌の倀で返りたす。勀怠の締めが終わった埌䞊の䟋のように毎月3日に実行すれば修正内容たで反映されたす。
  • メンバヌ䞀芧から倖れた人退䌚などの蚘録はアカりント欄が空になり、「芁確認」ず衚瀺されたす。
  • 読み取りだけなので、䜕床実行し盎しおもteamsideのデヌタは倉わりたせん。倱敗したら゚ラヌを確認しお再実行しおください。
  • 勀怠の備考メモは個人情報が含たれる可胜性があるため、APIでは出力したせん。
事䟋 02

決裁通知をTeams・Slackのチャンネルぞ

チャットはTeamsやSlack、決裁はteamsideで行っおいる䌚瀟なら、決裁䟝頌を芋逃さないようチヌムのチャンネルに1行の通知を流せたす。開発は䞍芁で、管理者の蚭定だけでできたす。

チャンネルにはこう衚瀺されたす

画面䟋です。チャンネル名・時刻・文曞タむトルはサンプルデヌタで、文の圢は実際ず同じです。通知の文は珟圚、韓囜語で送信されたす。

蚭定手順

  1. チャンネルのURLを䜜成Slackは「Incoming Webhooks」でチャンネルを遞び、Teamsはチャンネルの「ワヌクフロヌ」から「Webhook 芁求を受信したずきにチャネルに投皿する」でURLを䜜成したす。
  2. 送信先を登録環境蚭定 › 管理者蚭定タブの「通知の倖郚送信」にURLを貌り付けたす。Slack・TeamsはURLから自動で刀別されたす。
  3. 範囲・通知を遞ぶ範囲「党䜓」たたは「決裁フォヌム」ず送る決裁通知を遞びたす。
  4. テストしお保存「テスト送信」でチャンネルにテストメッセヌゞが届くこずを確認しお保存したす。

構成䟋

送信先はワヌクスペヌスごずに20か所たで登録できるので、チャンネルごずに範囲ず通知を倉えられたす。

チャンネル䟋範囲送る通知タむトル
#決裁通知党䜓決裁䟝頌 approval.requested
決裁の順番 approval.forwarded
期限間近 approval.due
衚瀺
#経理チヌム決裁フォヌム経費申請曞承認 approval.approved
差し戻し approval.rejected
非衚瀺

決裁通知は䟝頌・順番・参照・承認・差し戻し・取り䞋げ・取り消し・削陀・コメント・期限間近の10皮類です。勀怠週52時間の接近・超過・䌚議・リ゜ヌス予玄・掲瀺板・アンケヌトの通知も同じ画面で遞べたす。䞀芧はリファレンス11章にありたす。

知っおおくこず

  • 蚭定できるのはオヌナヌ・管理者のみです。
  • 1行の通知には誰の順番かは含たれたせん。チヌム・フォヌムごずにチャンネルを分けるず、受け取る人が明確になりたす。
  • チャンネルのURLを知っおいる人は誰でもそのチャンネルに投皿できたす。URLは倖郚に共有しないでください。
  • 送信に倱敗するず、間隔を広げながら合蚈5回たで詊みたす。連続で倱敗しおも自動ではオフにならないため、画面の状態をずきどき確認しおください。
  • スむッチをオフにしおいる間の通知は蓄積されず、オンに戻した埌の通知から送られたす。
  • Teamsの以前の「コネクタ」方匏のURLはTeams偎で廃止されたした。新しいURLは「ワヌクフロヌ」で䜜成しおください。
  • 自瀟サヌバヌで受け取っお凊理する堎合は、䞀般のJSONのURLを登録し、X-JC-Signature 眲名を怜蚌したすリファレンス11章。
  • オンプレミス版では、teamsideのサヌバヌがSlack・TeamsのURLぞむンタヌネット接続できる必芁がありたす。瀟内で倖郚接続を制限しおいる堎合は、そのアドレスだけを蚱可しおください。
事䟋 03

AIに話しかけお勀怠・組織の状況を確認

いく぀もの画面を開いお衚を突き合わせる代わりに、AIのチャットで「今日ただ出勀蚘録がない人は」ず尋ねるず、AIがteamsideのデヌタを読んで答えたす。読み取りのみで、デヌタは倉曎したせん。

説明甚の䌚話䟋です実際の顧客デヌタずは無関係です。どのツヌルを呌ぶかは、質問に応じおAIが遞びたす。

2぀の接続方法

「AIサヌビスの連携」— メンバヌ各自

Claude.aiなどAIサヌビスのWeb画面からコネクタで接続 · 開発䞍芁

  • 接続したその人の暩限で読み取りたす。アプリで芋られないものはAIも芋られたせん。
  • メンバヌ・スペヌス郚眲䞀芧、蚱可した堎合は出退勀蚘録
  • 管理者がオンにするずタスク list_my_tasks · 決裁䞀芧 list_approvals · 連絡先 list_contacts · 党瀟掲瀺板 list_board_posts
  • メンバヌのメヌルアドレスは枡したせん。

APIキヌ — 䌚瀟単䜍

Claude Code・Claude API・OpenAI API・Gemini CLI・CursorなどにURLずキヌを蚭定しお接続

  • 事䟋01ず同じ「倖郚連携キヌ」を䜿いたす。キヌでオンにした項目だけがツヌルずしお衚瀺されたす。
  • メンバヌ list_members · スペヌス list_spaces · get_space · 勀怠 list_attendances
  • 䌚瀟党䜓を読み取るため、瀟内の分析・レポヌト自動化に向いおいたす。キヌ接続ではメンバヌ䞀芧にログむンアカりントが含たれたす。

接続手順

「AIサヌビスの連携」

  1. 管理者がオンにする環境蚭定 › 管理者蚭定タブの「AIサヌビス連携䌚瀟蚭定」でオンにし、蚱可するAIサヌビス・出退勀蚘録の蚱可・読める項目を遞びたす。オンにする際、枡る情報をもう䞀床確認したす。
  2. URLを案内同じカヌドの「メンバヌ向け — コネクタのURL」をコピヌしおメンバヌに知らせたす。
  3. メンバヌが接続AIサヌビスのコネクタ远加画面Claude.aiでは「カスタムコネクタ」にURLを入力し、teamsideのアカりントでログむンしたす。
  4. 同意画面で蚱可接続するワヌクスペヌスず読み取る情報を確認し、「蚱可」を抌したす。

オンプレミス版ではこの機胜は初期状態でオフで、オンにするかどうかは䌚瀟が決めたす。AIサヌビスのWeb画面から接続するには、teamsideのサヌバヌのアドレスにむンタヌネットから到達できる必芁がありたす。瀟内ネットワヌク専甚のサヌバヌなら、䞋のAPIキヌの方法をお䜿いください。

APIキヌ䟋Claude Code

claude code
claude mcp add --transport http teamside https://<導入ドメむン>/serv/api/external/v1/mcp \
  --header "Authorization: Bearer ${JC_API_KEY}"

ほかのツヌルの接続方法ずMCPのルヌルはリファレンス12章にありたす。

安心のしくみ

心配しくみ
AIがデヌタを倉えないかこの事䟋のツヌルはすべお読み取り専甚です。登録・修正・削陀のツヌルはありたせん。
芋おはいけないものを芋ないか「AIサヌビスの連携」は接続した人の暩限のたた刀定したす。決裁䞀芧は本文・添付・金額を枡さず、「セキュリティ」衚瀺の文曞はそもそも出おきたせん。連絡先はメヌル・䜏所を枡したせん。
接続が残り続けないか30日間䜿わないか90日が過ぎるず切れ、パスワヌドを倉えおも切れたす。メンバヌは「連携䞭のAIサヌビス」、管理者は「AI連携の管理」で接続ず盎近30日の呌び出し蚘録を確認し、すぐに解陀できたす。
誰かが勝手に接続しないか接続は本人がログむンしお「蚱可」を抌したずきだけ䜜られ、管理者が蚱可したAIサヌビスだけが接続できたす。

AIツヌルで読み取った情報はそのAIサヌビスの運営䌚瀟に枡っお凊理されたす。オンにする前に、瀟内の個人情報の取り扱い基準メンバヌぞの案内・同意、委蚗契玄などを確認しおください。

さらに詳しく

  • 公開APIリファレンス — ゚ンドポむントごずのパラメヌタ・レスポンス・゚ラヌコヌド・Webhook眲名怜蚌

自瀟システムずの連携方法に぀いお、お気軜にお問い合わせください。

連携のお問い合わせ

最終曎新 2026-11-07 · API v1