CData Software Blog

クラウド連携のCData Software の技術ブログです。

請求書作成・見積書発行クラウドサービス board の API の使い方

こんにちは。CData リードエンジニアの杉本です。恒例となりつつある各APIのHowToUse記事、今回は国産請求書作成・見積書発行クラウドサービスである「board」APIの使い方を紹介したいと思います。

the-board.jp

f:id:sugimomoto:20200503172149p:plain

board とは?

請求書作成・見積書発行の機能を提供するクラウドベースの経営管理システムです。 f:id:sugimomoto:20200503172155p:plain

案件管理を軸としながら、見積書・発注書・発注請書・納品書・検収書・請求書・領収書作成がとてもスムーズに実施できるサービスです。

f:id:sugimomoto:20200503172202p:plain

また、以下のリファレンスにもある通り、ほとんどの機能・データをAPI経由で操作できるようになっており、外部とのデータ連携がとても柔軟に実現できるようになっています。

developers.the-board.jp

f:id:sugimomoto:20200503172209p:plain

今回はこの board APIの使い方、認証方法、ページネーションなどについて解説したいと思います。

board API の使い方

認証方式

何はともあれ、まずは認証方式です。

board API は以下のリファレンスでも紹介されている通り、APIキーとAPIトークン、2つの情報を使って、認証・認可を実施しています。

https://developers.the-board.jp/doc/index.html#TOC_827bf054f9c82c4ee14a8c5b6c436c9b

f:id:sugimomoto:20200503172217p:plain

認可といっても OAuth のようなプロセスを行う必要は無く、管理画面から必要な権限を付与したAPIトークンを発行するだけなので、そこまで認証周りの敷居は高くありません。

なお、APIキーはアカウントで一つだけ発行されて、APIトークンは複数発行することができます。その複数のAPIトークンに必要な権限がそれぞれ紐付いて、セキュアかつ事故の心配を軽減できるように設計されています。

個人的にはちょっとめずらしいタイプだなと思いますが、APIトークンが1種類かつ1つしか発行できないタイプも存在しますので、OAuthを利用するほど敷居も高くなく、なかなかありがたい柔軟設計だなと感じます。

APIキーとAPIトークンは board へログインし、「歯車アイコン」から「API設定」に移動して、確認できます。

f:id:sugimomoto:20200503172224p:plain

API設定画面では、予めAPIキーが提供されています。APIトークンは、「新規トークン生成」ボタンから個別に発行します。

f:id:sugimomoto:20200503172230p:plain

APIトークン生成画面は以下のようになっていて、かなり柔軟に権限を管理することができます。

f:id:sugimomoto:20200503172236p:plain

保存すると、以下のようにAPIトークンが発行されます。

APIトークンの権限は後からでも変更できますが、APIトークンはこれ以降再表示されることは無いので、注意しましょう。

f:id:sugimomoto:20200503172244p:plain

なお、board APIを利用するには有償のプラン契約が必要になるので注意しましょう。無償版ではAPI設定画面が表示できません。

f:id:sugimomoto:20200503172249p:plain

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}}

f:id:sugimomoto:20200503172256p:plain

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

f:id:sugimomoto:20200503172304p:plain

f:id:sugimomoto:20200503172310p:plain

なお、per_pageのデフォルトは10件、最大100件まで指定できます。

リクエスト制限は3000リクエスト / 1日なので、単純計算で1日300万レコードまでは取得できそうです。

https://developers.the-board.jp/doc/index.html#TOC_03fee78535c1e174a20eea44595f322a

ただし、3リクエスト / 秒 (100バーストまで可能)の秒間リクエスト制限もあるので、並列でページネーションを一括で回す際は注意が必要ですね。

リスト取得時のパラメータ指定方法

フィルタリングなどを行うためのパラメータ指定方法はURLパラメータ方式です。

各リソース毎で受け付けるパラメータが違います。

例えば、顧客リストの取得の場合は以下の5種類。

f:id:sugimomoto:20200503172316p:plain

以下のようにリクエストします。

GET https://api.the-board.jp/v1/clients/?updated_at_gteq=2020-04-01 00:00:00

f:id:sugimomoto:20200503172322p:plain

なお、単一レコードだけ取得したい場合は、URLで「clients/:id」指定でも取得できます。書類関係で明細を取得する場合は必ずidが必須だったりもするので、注意しましょう。

GET https://api.the-board.jp/v1/clients/52126932

f:id:sugimomoto:20200503172329p:plain

案件に紐づく各種書類(見積書,発注書,納品書,請求書,領収書,案件原価)の取得方法

board APIの中で外のAPIには無い特性は、この各種書類(見積書,発注書,納品書,請求書,領収書,案件原価)の取得方法でしょう。

board上で書類を作る場合、案件の作成後、以下のような画面で実施します。

f:id:sugimomoto:20200506105600p:plain

API上でもこの紐付けは存在しており、以下のような関係性で成り立っています。(APIではさらにこれに対して、案件原価も存在しますが)

f:id:sugimomoto:20200506110644p:plain

board API では、以下のように書類情報を取得するためのエンドポイントも提供されていますが、これには必ずIDが必要なので、まずIDを特定しなければいけません。

f:id:sugimomoto:20200506110837p:plain

さて、このIDをどのように取得するのか? というと、案件データを取得する際に「response_group」というパラメータを使うことで、その案件に紐づく各種処理を取得できるという仕組みになっています。

例えば、「response_group=delivery」パラメータを付与していない場合とした場合を比較すると、以下のようなレスポンスになります。

GET https://api.the-board.jp/v1/projects?response_group=delivery

f:id:sugimomoto:20200506111314p:plain

これでIDを特定してから、各種書類のエンドポイントを実行することができるようになります。

なお、指定できるパラメータは以下のとおりです。

https://developers.the-board.jp/doc/index.html#TOC_fabd2c27985eb34d3066c6f60fbfbbe7

f:id:sugimomoto:20200506111451p:plain

データ登録時のパラメータ指定方法

データの登録や更新では、「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": "サンプル"
}

f:id:sugimomoto:20200503172336p:plain

なお、Updateする際はメソッドをPATCHリクエストにして、URLで対象のIDを指定します。更新しないプロパティは指定する必要が無いですが、

f:id:sugimomoto:20200503172342p:plain

見積書などの更新は明細行を一緒に指定する必要があるので、注意しましょう。

f:id:sugimomoto:20200503172348p:plain

プログラムから実行する(C#

最後にC#から board APIを触ってみます。

といっても、特に小難しいことはしません。PostmanのCodeSnippetから

f:id:sugimomoto:20200503172355p:plain

C# RestSharp」のコードを実行するだけです。

f:id:sugimomoto:20200503172400p:plain

とは言いつつも、これだけだと寂しいので、ちゃんとClientを格納するクラスを定義して、JsonConvertで取得しました。

gist.github.com

f:id:sugimomoto:20200503172405p:plain

おわりに

次回は CData Driver から board の API を扱ってみます。

www.cdatablog.jp