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/:日報のIDIDを指定して1件の日報を取得できるAPI

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

属性名説明
groupIdString(必須)取得するグループのID
sizeNumber取得する日報の件数。1〜1000の間で指定します。未指定の場合は10が自動で適用されます
fromString期間(開始) 2022/08/01 00:00:00のような形で指定。必ずtoとセットで使用
toString期間(終了) 2022/09/31 23:59:59のような形で指定。必ずfromとセットで使用
tagsString配列タグのIDを配列で指定
statesString配列日報の状態で絞り込み。[‘承認’, ‘棄却’, ‘修正’, ‘新規’, ‘進行’]のように指定
templatesString配列使用したテンプレートのIDで絞り込み。テンプレートIDの配列で指定
ownersString配列日報作成者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です。2種類のAPIが用意されています。

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

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

名称説明必須
groupIdString取得するグループの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

名称説明必須
groupIdString取得するグループのID
sizeNumber取得する日報の件数。1〜1000の間で指定
fromString取得する日報の期間(開始点) 2022/08/01 00:00:00のような形で指定
tostring取得する日報の期間(終了点) 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

名称説明必須
groupIdString取得するグループの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以下になるように指定します
nipoplusアプリ起動ボタン

一切の企業情報を入力せずに手軽に体験できます

  • メール・パスワードの設定なしで体験可能(匿名機能
  • クレジットカードの登録も不要
  • Webアプリだからインストール不要
nipoplusアプリ起動ボタン
ios App Store
Android Google Play Store
本記事の更新日: 2022/11/13