Toggl Trackは、タイマーを使って作業時間を計測することができるサービスです。
マルチデバイスで使用でき、使い心地もとても良く、自分だけで使うには十分な機能が無料で利用できます。
iOSショートカットとしてもタイマーの起動や停止が用意されているのですが、ショートカットをPCで利用しようとすると、iOSアプリから提供されているショートカットを使うことができません。
そのため、API経由でタイマーを開始する方法を調べてみました。
前準備
Toggl TrackのAPIの承認方法はBasic認証で、2通りの方法があります。
1. ユーザー名とパスワードを使う
ログイン時のメールアドレスとパスワードを使って認証する方法です。
$ curl -u <email>:<password> https://api.track.toggl.com/api/v9/me/time_entries
2. APIトークンを使う
APIトークンを使って認証する方法です。
APIトークンは、Toggl TrackのWebサイトにログインして、プロフィール画面から取得できます。
$ curl -u <api_token>:api_token https://api.track.toggl.com/api/v9/me/time_entries
上記のコマンドを実行すると、直近のタイムエントリーの一覧が取得できます。
受け取った情報の中で、workspace_id というkeyがあるので、値をメモしておきます。
タイマーを開始する
さっそくタイマーを開始してみましょう。 リクエストボディのrequiredな値がdocumentだと少し分かりにくかったのですが、以下が最低限必要な値でした。
$ curl 'https://api.track.toggl.com/api/v9/workspaces/<workspace_id>/time_entries' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic <{user}:{pwd}>' \ --data '{ "workspace_id": <workspace_id>, // 追加したいワークスペースのID "start": "2024-09-10T08:58:28Z", // 開始時間. ISO 8601形式. タイムゾーンはUTC "duration": -1, // タイマーの時間 ※詳細は後述 "description": "test from postman", "created_with": "From Postman" // 適当な識別値。このkeyがないとエラーになる。 }'
durationの値は、現在進行系のタイマーを開始する場合はネガティブ値（-1推奨）を指定します。
過去の時間を追加する場合は、stop(こちらもISO 8601形式)とdurationどちらかを指定、もしくは両方を指定します。両方指定するときには、start+duration=stopとなるように指定する必要があります。
タイマーを停止する
タイマーを停止するには、現在進行中のタイムエントリーの情報を取得し、取得したワークスペースIDとタイムエントリーIDに対してPATCHリクエストを実行します。
$ curl 'https://api.track.toggl.com/api/v9/me/time_entries/current' \ --header 'Authorization: Basic <{user}:{pwd}>'
$ curl -X PATCH 'https://api.track.toggl.com/api/v9/workspaces/<workspace_id>/time_entries/<time_entry_id>/stop' \ --header 'Authorization: Basic <{user}:{pwd}>'
