API のドキュメント

Shifton タスクでは、プラットフォームでの作業を自動化し、公開 API を通じて外部サービスと連携できます。API では、タスク、クライアント、従業員、チェックリスト、在庫、サービスエリア、財務書類、レポートといった主要な対象がすべて扱えます。そのため Shifton は、HR、給与計算、分析のシステムや、社内のサービスと連携できます。

ドキュメントは 2 つのバージョンで公開されています。

🚀 新しいドキュメント — 構成を刷新し、最新のメソッドを収録した最新版のリファレンスです： 👉 https://api2.shifton.com/openapi/
📄 古いドキュメント — 以前のバージョンです（既存の連携のために引き続きサポートされています）： 👉 https://api2.shifton.com/docs/

どちらのバージョンも、アプリから直接開けます。Developer のセクションの概要のタブにある、「新しいドキュメント」 と 「古いドキュメント」 のボタンです。

ドキュメントは 2 つの言語で利用できます。 新しいドキュメントのページの右上に EN / RU の切り替えがあり、選んだ言語は記憶されます。

API キーの取得方法

API キーは、アプリの中で作成します。

Developer のセクションを開きます。
APIキー（「APIキー」）のタブに移動します。
「APIキーを作成」 をクリックします。

キーの作成時に入力する内容

APIキーを作成 のサイドパネルが開き、次の項目が表示されます。

タイトル — キーの名前で、必須項目です。あとで何を無効にすればよいかがわかるように、用途に合わせた名前を付けてください。「1C への書き出し」「分析用のレポート」のようにします。
有効期限 — この日付を過ぎるとキーは使えなくなります。空欄にしておくと、期限はありません。
アクセス — キーの権限の範囲です。
Full access (act as me) — キーはあなたの名前で、あなたと同じ権限で動作します。
制限された権限 — 自分で選んだ、限られた権限の組み合わせです。

キーを作成するには追加を、パネルを閉じるには キャンセル をクリックします。

📷 *キー作成パネルのスクリーンショット — 本番環境で撮影する*

キーは 特定の会社に対して 作成され、その会社のデータにのみ使えます。キーはいつでも失効させられます。失効はただちに有効になり、そのキーを使った以降のリクエストはすべて 401 のエラーを返します。

重要: 作成したキーが表示されるのは 1 回だけ です。すぐにコピーして安全な場所に保管してください。あとから再表示することはできません。キーを紛失した場合は、新しいキーを作成し、古いキーを失効させてください。

認証

API へのすべてのリクエストは、ヘッダーでキーを付けて署名します。

Authorization: Bearer {your_API_key}

API の基本アドレスは次のとおりです。

https://api2.shifton.com/work/1.0.0

有効なキーがないリクエストは 401 と、本文 {"message":"Unauthenticated."} を返します。

最初のリクエスト

たとえば、会社の従業員の一覧を取得するには、次のようにします（{companyId} の部分は自分の会社の ID に置き換えてください）。

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

curl で同じことをする場合は、次のようにします。

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

会社の ID は、アプリのアドレスバーで確認できます。app.shifton.com/c/8397/... の、/c/ のあとの数字です。

API で利用できる内容

リファレンスは 360 を超えるメソッドを網羅しています。現場サービス向けの主なセクションは次のとおりです。

タスク — /companies/{companyId}/tasks：作成、変更、ステータス、タスクのファイル。
やることリスト (To Do) — /companies/{companyId}/todo。
クライアント — /companies/{companyId}/clients、およびクライアントの住所とカスタムフィールド。
チェックリスト — /companies/{companyId}/checklists。
サービスエリア — /companies/{companyId}/tasks/service-areas。
スキル — /companies/{companyId}/skills。
従業員 — /companies/{companyId}/employees：追加、編集、退職処理、復帰。
在庫 — 品目、カテゴリ、セット、倉庫の在庫数。
財務書類 — 見積書、作業指示書、請求書、領収書、書類のカウンター、ロゴ。
レポート — 業務と勤怠のデータの書き出し。

このほか、スケジュールとシフト、休暇と休暇申請、勤怠、請求と SMS の請求、通知、モジュールも利用できます。

ウェブフック

API に定期的にリクエストを送るのではなく、出来事が発生した時点で受け取りたい場合は、ウェブフック を使います。Developer のセクションの Webhooks のタブです。必要な出来事が発生すると、Shifton の側から指定のアドレスにリクエストを送ります。対応している出来事の一覧は、専用のメソッドが返します。

エラーコード

Shifton の API は、標準の HTTP ステータスコード を使います。

200 — リクエストは正常に処理されました。
201 — オブジェクトが正常に作成されました。
400 — リクエストのパラメーターが正しくありません。
401 — 認証のエラーです。キーが渡されていない、無効、または失効しています。
403 — アクセスが拒否されました。
404 — リソースが見つかりません（多くの場合、メソッドのアドレスの打ち間違いです）。
500 — サーバーのエラーです。

利用のヒント

新しい連携では 新しいドキュメント を使ってください。古いほうは、すでに動いている連携のために残されています。
リクエストの確認には Postman か curl が便利です。コードを 1 行も書かずに応答を確認できます。
キーをコードの中に平文で保存したり、第三者に渡したりしないでください。キーは会社のデータへのアクセスを与えます。
リクエスト頻度の制限（rate limits）を守ってください。超えると、API へのアクセスが一時的にブロックされることがあります。

よくある質問

質問：API キーはどこで取得できますか？ 回答： アプリの Developer のセクション → APIキー のタブ → 「APIキーを作成」 のボタンです。キーは現在の会社に対して発行されます。

質問：ウィンドウを閉じてしまい、キーをコピーしませんでした。どこで確認できますか？ 回答： どこでも確認できません。キーは 1 回だけ表示され、再発行はされません。新しいキーを作成し、古いキーを失効させてください。

質問：キーが他人の手に渡った場合、どうやって失効させますか？ 回答： APIキー のタブで削除してください。失効はただちに有効になり、そのキーを使ったリクエストはすぐに 401 を返し始めます。

質問：「Full access」と「Restricted permissions」は何が違うのですか？ 回答： Full access (act as me) は、あなたと同じ権限をキーに与えます。制限された権限 では、選んだ権限だけをキーに与えられます。データの一部にしかアクセスする必要のない連携では、こちらのほうが安全です。

質問：キーの有効期間を限定できますか？ 回答： はい。作成時の 有効期限 の項目で指定します。入力しなければ、キーは無期限になります。

質問：1 つのキーを複数の会社で使えますか？ 回答： いいえ。キーは作成した会社に紐付いており、その会社のデータにのみ使えます。別の会社では、それ専用のキーを作成してください。

質問：API の基本アドレスは何ですか？ 回答： https://api2.shifton.com/work/1.0.0 です。そのあとにメソッドのパスが続きます。たとえば /companies/{companyId}/tasks です。

質問：リクエストに使う会社の ID はどこで取得できますか？ 回答： アプリのアドレスバーの /c/ の直後にあります。たとえば app.shifton.com/c/8397/tasks であれば、会社の識別子は 8397 です。

質問：どちらのバージョンのドキュメントを使えばよいですか？ 回答： 新しい連携には新しいほう（api2.shifton.com/openapi）を使います。古いほう（api2.shifton.com/docs）は、既存の連携のためにサポートされています。

質問：ロシア語のドキュメントはありますか？ 回答： あります。新しいドキュメントのページの右上に EN / RU の切り替えがあります。

質問：API へのリクエストは何でテストできますか？ 回答： Postman か curl がもっとも便利です。コードを書かずにリクエストを送り、応答を確認できます。

質問：キーをコピーしたのに 401 が返るのはなぜですか？ 回答： キーが Authorization のヘッダーで、前に Bearer を付けて渡されているか、キーが失効していないか、有効期限が切れていないかを確認してください。

質問：404 が返るのはなぜですか？ 回答： 多くの場合はアドレスの間違いです。基本部分は https://api2.shifton.com/work/1.0.0 である必要があり、メソッドのパスには正しい {companyId} が必要です。

質問：API で何を自動化できますか？ 回答： タスクの作成と変更、クライアントとその住所の操作、チェックリスト、サービスエリア、スキル、従業員、在庫、財務書類、レポートの書き出し、さらにスケジュール、シフト、休暇です。

質問：API を定期的に呼び出すのではなく、Shifton から出来事を受け取れますか？ 回答： はい。そのための ウェブフック があります。Developer のセクションの Webhooks のタブです。

質問：パスワードの変更は連携の動作に影響しますか？ 回答： いいえ。連携は API キーで動作し、アカウントのパスワードは使いません。