こんにちは。CData リードエンジニアの杉本です。恒例となりつつある各APIのHowToUse記事、今回は国産請求書作成・見積書発行クラウドサービスである「board」APIの使い方を紹介したいと思います。
board とは？
請求書作成・見積書発行の機能を提供するクラウドベースの経営管理システムです。
案件管理を軸としながら、見積書・発注書・発注請書・納品書・検収書・請求書・領収書作成がとてもスムーズに実施できるサービスです。
また、以下のリファレンスにもある通り、ほとんどの機能・データをAPI経由で操作できるようになっており、外部とのデータ連携がとても柔軟に実現できるようになっています。
今回はこの board APIの使い方、認証方法、ページネーションなどについて解説したいと思います。
board API の使い方
認証方式
何はともあれ、まずは認証方式です。
board API は以下のリファレンスでも紹介されている通り、APIキーとAPIトークン、2つの情報を使って、認証・認可を実施しています。
https://developers.the-board.jp/doc/index.html#TOC_827bf054f9c82c4ee14a8c5b6c436c9b
認可といっても OAuth のようなプロセスを行う必要は無く、管理画面から必要な権限を付与したAPIトークンを発行するだけなので、そこまで認証周りの敷居は高くありません。
なお、APIキーはアカウントで一つだけ発行されて、APIトークンは複数発行することができます。その複数のAPIトークンに必要な権限がそれぞれ紐付いて、セキュアかつ事故の心配を軽減できるように設計されています。
個人的にはちょっとめずらしいタイプだなと思いますが、APIトークンが1種類かつ1つしか発行できないタイプも存在しますので、OAuthを利用するほど敷居も高くなく、なかなかありがたい柔軟設計だなと感じます。
APIキーとAPIトークンは board へログインし、「歯車アイコン」から「API設定」に移動して、確認できます。
API設定画面では、予めAPIキーが提供されています。APIトークンは、「新規トークン生成」ボタンから個別に発行します。
APIトークン生成画面は以下のようになっていて、かなり柔軟に権限を管理することができます。
APIトークンの権限は後からでも変更できますが、APIトークンはこれ以降再表示されることは無いので、注意しましょう。
なお、board APIを利用するには有償のプラン契約が必要になるので注意しましょう。無償版ではAPI設定画面が表示できません。
Postman から実行する
それでは Postman から board APIを実行してみましょう。
board API は REST ful なデザインのAPIなので、各HTTPメソッド（GET、POST、PATCH、DELETE）、エンドポイントURL（https://api.the-board.jp/v1/）＋リソース名（clients等）でリクエストします。
例えば、顧客リストの取得 の場合、以下のようなリクエストになります。
GET /v1/clients HTTP/1.1 Host: api.the-board.jp Authorization: Bearer XXXX x-api-key: XXXXX
認証用に取得していたAPIキーとAPIトークンはヘッダーに以下のように指定します。この際、AuthorizationにはBearerを付与するのを忘れないようにしましょう。
Authorization: Bearer {{APIToken}}
x-api-key: {{APIKey}}
JSONのレスポンスが取得できました。
ページネーションの指定方法
ページネーションはURLパラメータで「per_page」「page」を指定するOFFSET方式です。
リクエスト例
GET https://api.the-board.jp/v1/clients?page=1&per_page=1
また、レスポンスに次のページのURL、トータルレコード数も入ってくるのがいいですね。
https://developers.the-board.jp/doc/index.html#TOC_38a9b39dbff49abb68df842b81a81a27
なお、per_pageのデフォルトは10件、最大100件まで指定できます。
リクエスト制限は3000リクエスト / 1日なので、単純計算で1日300万レコードまでは取得できそうです。
https://developers.the-board.jp/doc/index.html#TOC_03fee78535c1e174a20eea44595f322a
ただし、3リクエスト / 秒 （100バーストまで可能）の秒間リクエスト制限もあるので、並列でページネーションを一括で回す際は注意が必要ですね。
リスト取得時のパラメータ指定方法
フィルタリングなどを行うためのパラメータ指定方法はURLパラメータ方式です。
各リソース毎で受け付けるパラメータが違います。
例えば、顧客リストの取得の場合は以下の5種類。
以下のようにリクエストします。
GET https://api.the-board.jp/v1/clients/?updated_at_gteq=2020-04-01 00:00:00
なお、単一レコードだけ取得したい場合は、URLで「clients/:id」指定でも取得できます。書類関係で明細を取得する場合は必ずidが必須だったりもするので、注意しましょう。
GET https://api.the-board.jp/v1/clients/52126932
案件に紐づく各種書類（見積書,発注書,納品書,請求書,領収書,案件原価）の取得方法
board APIの中で外のAPIには無い特性は、この各種書類（見積書,発注書,納品書,請求書,領収書,案件原価）の取得方法でしょう。
board上で書類を作る場合、案件の作成後、以下のような画面で実施します。
API上でもこの紐付けは存在しており、以下のような関係性で成り立っています。（APIではさらにこれに対して、案件原価も存在しますが）
board API では、以下のように書類情報を取得するためのエンドポイントも提供されていますが、これには必ずIDが必要なので、まずIDを特定しなければいけません。
さて、このIDをどのように取得するのか？ というと、案件データを取得する際に「response_group」というパラメータを使うことで、その案件に紐づく各種処理を取得できるという仕組みになっています。
例えば、「response_group=delivery」パラメータを付与していない場合とした場合を比較すると、以下のようなレスポンスになります。
GET https://api.the-board.jp/v1/projects?response_group=delivery
これでIDを特定してから、各種書類のエンドポイントを実行することができるようになります。
なお、指定できるパラメータは以下のとおりです。
https://developers.the-board.jp/doc/index.html#TOC_fabd2c27985eb34d3066c6f60fbfbbe7
データ登録時のパラメータ指定方法
データの登録や更新では、「Content-Type: application/json」でJSONをBodyに指定してリクエストします。
POST /v1/clients HTTP/1.1
Host: api.the-board.jp
Authorization: Bearer XXXX
x-api-key: XXXX
Content-Type: application/json
{
"name": "サンプル株式会社",
"name_disp": "サンプル"
}
なお、Updateする際はメソッドをPATCHリクエストにして、URLで対象のIDを指定します。更新しないプロパティは指定する必要が無いですが、
見積書などの更新は明細行を一緒に指定する必要があるので、注意しましょう。
プログラムから実行する（C#）
といっても、特に小難しいことはしません。PostmanのCodeSnippetから
「C# RestSharp」のコードを実行するだけです。
とは言いつつも、これだけだと寂しいので、ちゃんとClientを格納するクラスを定義して、JsonConvertで取得しました。
おわりに
次回は CData Driver から board の API を扱ってみます。
