料金 旧Nipo チェックシートApp 問合せ
アプリを起動 前 次

APIリファレンス

キャラクター

API機能は当面無償で公開しますが将来有料(月額1000円程度)になる予定です

WebAPIは少なくともCURLやJSONあたりが理解できれば利用可能です。WebAPIを使うことで、NipoPlusを起動しなくてもコマンドを叩くだけで日報データやログデータなどを取得することができます。 取得したそれらのデータを基幹システムに取り込んだり、加工して集計や分析に使うことができます。データの出力には他にもCSV出力などがありますが、WebApiはシステムに組み込むことで自動化出来るなどのメリットがあります。

WebAPIへリクエストを投げる基本の形

NipoPlusのWebAPIへリクエストを投げる基本の形は次のようになります。なお本ガイドではCURLを使った方法で解説します。コマンドが苦手な方はPostmanなどのGUIツールで検証するのもオススメです。

curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/【エンドポイント】 \
-H "Content-Type:application/json;charset=UTF-8" \
-H "Authorization: Bearer 【取得したAPIキー（およそ200文字程度)】" \
-d '{ "key": "value", "key2": "value2" }'
キャラクター

Mac/Linux向けのCurl記法です。Windows版は若干形式が変わる可能性があるので注意

ヘッダーのContent-Typeはapplication/jsonである必要があります。APIキーの取得方法についてはこちらを御覧ください。

// URL
https://us-central1-nipo-plus.cloudfunctions.net/v0/

日報の取得に関するWebAPI

WebAPIを使った日報の取得は4種類用意されています。

エンドポイント 概要
/reports/admin 管理者のみ実行可能。全ての日報を取得できるAPI
/reports/outbox 自分が送信した日報のデータのみ取得できるAPI
/reports/inbox 自分が受信した日報のデータのみ取得できるAPI
/report/:日報のID IDを指定して1件の日報を取得できるAPI

上記APIに指定可能なパラメータは次の通りです。

属性名 型 説明
groupId String(必須) 取得するグループのID
size Number 取得する日報の件数。1〜1000の間で指定します。未指定の場合は10が自動で適用されます
from String 期間（開始) 2022/08/01 00:00:00のような形で指定。必ずtoとセットで使用
to String 期間（終了) 2022/09/31 23:59:59のような形で指定。必ずfromとセットで使用
tags String配列 タグのIDを配列で指定
states String配列 日報の状態で絞り込み。[‘承認’, ‘棄却’, ‘修正’, ‘新規’, ‘進行’]のように指定
templates String配列 使用したテンプレートのIDで絞り込み。テンプレートIDの配列で指定
owners String配列 日報作成者IDで絞り込み。スタッフのIDを配列で指定
キャラクター

日報取得系はいずれのAPIもgroupIdの指定必須です

最低限のパラメータだけ指定してリクエストを投げる例文は次のようになります。

curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/reports/admin \
-H "Content-Type:application/json;charset=UTF-8" \
-H "Authorization: Bearer 【取得したAPIキー（およそ200文字程度)】" \
-d '{"groupId": "nipodefaultgroup" }'

日付（fromとto）の指定が無い場合は直近の日報の順に取得されます。上記コマンドの場合は直近の日報10件がAPI経由で取得されます。 全パラメータを指定した記述例。見やすいようにヒアドキュメントで記述しています

# パラメータが多いためヒアドキュメントを使っています
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/reports/admin \
-H "Content-Type:application/json;charset=UTF-8" \
-H "Authorization: Bearer 【取得したAPIキー（およそ200文字程度)】" \
-d @- <<EOS
{
  "groupId": "nipodefaultgroup",
  "size": 1000,
  "from": "2022/08/01 00:00:00",
  "to": "2022/09/30 23:59:59",
  "tags": ["oSGoygpZYCBlldTWGewA", "bo6wwrUSVrE6UbqlJjkf"]
  "states": ["新規", "進行", "棄却"],
  "templates": ["iELPWHa3ZjXYJS62Hn3N"],
  "owners": ["mMSejOQa21d9OtXo1BtjFzrEt6J3"]
}
EOS

この場合は条件が細かく指定されたため、上記の条件に一致する日報のみが取得されます。 取得される日報のデータは生データです。詳しくは日報データ構造を参照してください

グループIDの確認方法

いくつかの方法がありますが、最も手っ取り早く確認するにはURLを見てください。URLは次のような構造になっています

https://nipo-plus.web.app/#/room/組織ID/グループID/テーマカラー/path/to/any...

例えばURLが次のようなデータだった場合

https://nipo-plus.web.app/#/room/BLyx3SG72rId24BnKcGC/eZu8bXFNh73YtVoR83ic/teal/home/PageNameGroupSettingAbout

グループIDは「eZu8bXFNh73YtVoR83ic」となります。

テンプレートの取得API

日報やチェックシートのテンプレートを取得するAPIです。２種類のAPIが用意されています。

エンドポイント 概要
/templtes パラメータで指定したグループ内の全てのテンプレートを取得します
/template/:テンプレートのID IDで指定された1件のテンプレートを取得します

パラメータは次のとおりです。

名称 型 説明 必須
groupId String 取得するグループのID ○
キャラクター

テンプレート取得系はいずれのAPIもgroupIdの指定必須です

# 記述例
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/templates \
-H "Content-Type:application/json" \
-H "Authorization: Bearer 【取得したAPIキー（およそ200文字程度)】" \
-d '{ "groupId": "nipodefaultgroup" }'

取得されるテンプレートのデータは生データです。詳しくは日報データ構造を参照してください。

ログデータ取得API

エンドポイント: /logs

名称 型 説明 必須
groupId String 取得するグループのID ○
size Number 取得する日報の件数。1〜1000の間で指定 ○
from String 取得する日報の期間（開始点) 2022/08/01 00:00:00のような形で指定 ○
to string 取得する日報の期間（終了点) 2022/09/31 23:59:59のような形で指定 ○

ログデータをAPIから取得できます。4つ全てのパラメータが必須です。

# 記述例
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/logs \
-H "Content-Type:application/json" \
-H "Authorization: Bearer 【取得したAPIキー（およそ200文字程度)】" \
-d '{"groupId": "nipodefaultgroup", "size": 1000, "from": "2022/08/01 10:00:00", "to": "2022/08/01 10:59:59"}'

スタッフのデータ取得API

特定グループ内に所属しているスタッフを取得します

エンドポイント: /staffs

名称 型 説明 必須
groupId String 取得するグループのID ○ 
# 記述例
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/staffs \
-H "Content-Type:application/json" \
-H "Authorization: Bearer 【取得したAPIキー（およそ200文字程度)】" \
-d '{ "groupId": "nipodefaultgroup" }'

組織全体に関するAPI

グループの上位階層に位置する組織に対するAPIがいくつか用意されています。組織全体に関する情報のため、アクセスには管理者権限が必要です。

エンドポイント 概要
/staffs/admin 組織に所属している全スタッフのデータを取得します
/group/admin 組織内に作成された全てのグループを取得します

パラメータはありません。

# 記述例
curl -X POST https://us-central1-nipo-plus.cloudfunctions.net/v0/staffs/admin \
-H "Content-Type:application/json" \
-H "Authorization: Bearer 【取得したAPIキー（およそ200文字程度)】" \

その他のAPI

CSV出力など、データを加工したあとで取得できるAPIについては現在開発中です。

エラーの種類と対策

WebAPIにリクエストを投げたとき、戻り値に{ error: true }がかえってきたときは何かしらのエラーが発生しています。 エラーの内容が messageプロパティにセットされていますので、メッセージを確認の上正しいパラメータを設定してください。

以下は代表的なエラーの例です

メッセージ 対策
トークンの更新に失敗 Bearerトークンが失効しています。APIキーの管理から再度取得してください
グループIDが不正です パラメータ groupIdに誤りがあります。groupIdを見直してください
このグループに対する権限がありません 指定したgroupIdに所属していないと権限不足が発生します。グループに所属してください
権限が足りません エンドポイントの中に adminが含まれるものは管理者権限のBearerトークンでアクセスする必要があります
日付不正 パラメータ from / toの指定が誤っています。必ず yyyy/MM/dd hh:mm:ss の形式で指定する必要があります
データベースアクセスエラー 何らかの原因でデータベースへの問い合わせに失敗しました。少し時間を追いてリトライしてください
文法に誤りがあります 正しい文法に修正してください。json最後の , を消し忘れるなど初歩的なミスである場合が多いです
Expected X, received Y パラメータが間違っています。Xの型を要求しているのにY型を渡されたという意味です。正しい型を指定してください
Number must be less than or equal to X 指定された数値が大きすぎます。X以下になるように指定します
更新日: 2023/02/20