boardとは

受託ベンチャーを支えるバックオフィス業務システム

ソース：boardが目指しているもの〜バックオフィス業務のために起業したのではない

その公式提供APIをRubyで叩きます。

算出したいデータ

[1] 見積中の案件について、合計額を算出する
→ 見込み売上
見積には「確度低/中/高」という区別がつけられるので、それで仕分けもする

[2] 受注後〜請求前の案件について、合計額を算出する
→ 確定売上

[3] 請求済みの請求について、合計額を算出する
→ 売掛金

出力例

見積中(高): ¥  1,000,000
見積中(中): ¥  2,000,000
見積中(低): ¥ 13,000,000
確定売上:   ¥  4,000,000
売掛金:   　¥  5,000,000

APIキー、APIトークンの取得

公式解説：https://the-board.jp/helps/help_common_api

APIキー

＜APIキー＞
アカウントで1つ発行され、リクエスト制限のためのリクエスト数は、このAPIキー単位にカウントされます。アカウントの識別キーのため、変更・削除はありません。

発行方法

API設定でAPIを有効にすると表示されます。

APIトークン

＜APIトークン＞
任意の数生成することができ、APIトークンごとに可能な操作（例：顧客の新規登録）を定義することができます。
セキュリティのため、可能な操作は最低限に範囲は限定することをお勧めします。そのため、用途に合わせてAPIトークンを登録し、必要な操作のみ有効にしてください。

発行方法

まず「新規トークン作成」

今回必要な
[1] 案件→リストの取得
[2] 請求→リストの取得
の 2つのみ チェックを入れ、発行。

APIトークン登録後、生成したトークンが表示されますが、APIトークンは登録直後の一度しか表示されませんので、忘れずに安全な場所に保管してください。

とのことなので注意して保存しましょう。

コードと解説

httpヘルパ

http_request_helper

require 'jwt'
require 'net/http'
require 'openssl'

module HttpRequestHelper
  def get_request(url, headers, params = nil)
    uri = URI.parse(url)
    uri.query = URI.encode_www_form(params) if params
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = uri.scheme === 'https'
    req = Net::HTTP::Get.new(uri)
    req.initialize_http_header(headers)
    response = http.request(req)

    response
  end

  def post_request(url, headers, params)
    uri = URI.parse(url)
    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = uri.scheme === 'https'

    req = Net::HTTP::Post.new(uri.path)
    req.body = params.to_json
    req.initialize_http_header(headers)
    response = http.request(req)

    response
  end

  def success?(response_code)
    response_code && (200 <= response_code.to_i && response_code.to_i < 300)
  end
end

見込み売上

進行中の案件のうち、「見積中(低/中/高)」ステータスのもの。
案件リストをorder_statusが1,2,3のものを取得します。
注意して欲しいのは配列的クエリの送信方法です。僕がphpサーバ等でよく見かける形式とは少し違いました。

require 'http_request_helper'

class BoardReporter
  include HttpRequestHelper
  BOARD_API_BASE = 'https://api.the-board.jp'
  BOARD_API_HEADER = {
    'Authorization' => 'Bearer ' + ENV['BOARD_API_TOKEN'],
    'x-api-key' => ENV['BOARD_API_KEY']
  }
  PER_PAGE = 100

  def run()
    estimated_sales_group = []
    page = 1
    has_next_page = true
    while has_next_page
      result, has_next_page = fetch_estimating_projects(page)
      page += 1
      estimated_sales_group.push(*result)
    end

    high_estimated_total = estimated_sales_group.select { |project| project[:order_status] == 1 }.inject(0) { |total, project| total + project[:total].to_i }.to_s(:delimited)
    midium_estimated_total = estimated_sales_group.select { |project| project[:order_status] == 2 }.inject(0) { |total, project| total + project[:total].to_i }.to_s(:delimited)
    low_estimated_total = estimated_sales_group.select { |project| project[:order_status] == 3 }.inject(0) { |total, project| total + project[:total].to_i }.to_s(:delimited)

    puts "見積中(高): ¥ #{high_estimated_total}"
    puts "見積中(中): ¥ #{midium_estimated_total}"
    puts "見積中(低): ¥ #{low_estimated_total}"
  end

  def fetch_estimating_projects(page) # 見積中 高/中/低, 見積もり確度別の見込み売上
    params = {
      'order_status_in[]' => '1,2,3',
      'per_page' => PER_PAGE.to_s,
      'page' => page
    }
    response = get_request(BOARD_API_BASE + '/v1/projects', BOARD_API_HEADER, params)

    if success?(response.code)
      [
        JSON.parse(response.body).map do |project|
          {
            order_status: project['order_status'],
            project_no: project['project_no'],
            total: project['total']
          }
        end,
        next_page?(page, response)
      ]
    else
      puts '見積中の案件が取得できませんでした'
      [[], false]
    end
  end

  def next_page?(current_page, response)
    response['X-Total-Count'].to_i >= current_page * 100
  end
end

確定売上

確定売上は少し複雑です。
進行中の案件のうち「受注確定/受注済」ステータスで、かつ請求前のものです。
つまり請求済のものは計上したくないわけですが、boardでは案件と請求は 別々に管理されている ため、別途請求リストAPIから請求一覧を取得して案件No（project_no）別に差し引く必要があります。

  def run()
    invoiced_sales = []
    page = 1
    has_next_page = true
    while has_next_page
      result, has_next_page = fetch_issued_invoices(page)
      page += 1
      invoiced_sales.push(*result)
    end

    receivable_sales = []
    page = 1
    has_next_page = true
    while has_next_page
      result, has_next_page = fetch_receivable_invoices(page)
      page += 1
      receivable_sales.push(*result)
    end

    billable_total = confirmed_sales.map do |project|
      invoiced_total = invoiced_sales.select { |invoice| invoice[:project_no] == project[:project_no] }.inject(0) { |total, invoice| total + invoice[:total].to_i }
      # 1つの保守案件を毎月請求している場合などはマイナスになるので、ここで止める
      [(project[:total].to_i - invoiced_total), 0].max
    end.inject(0) {|total, billable| total + (billable ? billable : 0) }.to_s(:delimited)

    puts  "確定売上: ¥ #{billable_total}"
  end

  def fetch_ordered_projects(page) # 受注確定/受注済, 確定売上
    params = {
      'order_status_in[]' => '4,5',
      'per_page' => PER_PAGE.to_s,
      'page' => page
    }
    response = get_request(BOARD_API_BASE + '/v1/projects', BOARD_API_HEADER, params)

    if success?(response.code)
      [
        JSON.parse(response.body).map do |project|
          {
            project_no: project['project_no'],
            total: project['total']
          }
        end,
        next_page?(page, response)
      ]
    else
      puts '受注確定/受注済みの案件が取得できませんでした'
      [[], false]
    end
  end

  def fetch_issued_invoices(page) # 請求済/入金済/回収不能, 請求済み。確定売上から案件別に引く
    params = {
      'invoice_status_in[]' => '2,3,9',
      'per_page' => PER_PAGE.to_s,
      'page' => page
    }
    response = get_request(BOARD_API_BASE + '/v1/invoices', BOARD_API_HEADER, params)

    if success?(response.code)
      [
        JSON.parse(response.body).map do |invoice|
          {
            project_no: invoice['project_no'],
            total: invoice['total']
          }
        end,
        next_page?(page, response)
      ]
    else
      puts '請求済みの請求書が取得できませんでした'
      [[], false]
    end
  end

売掛金

売掛金は簡単です。
請求リストから「請求済」ステータスの請求を取得するだけです。
なお、これは「入金済」を含みません。boardの「請求済」は入金前のみに付くステータスです。
「回収不能」というステータスもあります。面白いですね。

  def run()
    receivable_sales = []
    page = 1
    has_next_page = true
    while has_next_page
      result, has_next_page = fetch_receivable_invoices(page)
      page += 1
      receivable_sales.push(*result)
    end

    receivable_total = receivable_sales.inject(0) { |total, invoice| total + invoice[:total].to_i }.to_s(:delimited)

    puts "売掛金: ¥ #{receivable_total}"
  end

  def fetch_receivable_invoices(page) # 請求済（入金前）。いわゆる売掛金
    params = {
      'invoice_status_in[]' => '2',
      'per_page' =>PER_PAGE.to_s,
      'page' => page
    }
    response = get_request(BOARD_API_BASE + '/v1/invoices', BOARD_API_HEADER, params)

    if success?(response.code)
      [
        JSON.parse(response.body).map do |invoice|
          {
            project_no: invoice['project_no'],
            total: invoice['total']
          }
        end,
        next_page?(page, response)
      ]
    else
      puts '売掛金情報が取得できませんでした'
      [[], false]
    end
  end

Rubyでboard APIを叩く

boardとは

算出したいデータ

APIキー、APIトークンの取得

APIキー

発行方法

APIトークン

発行方法

コードと解説

httpヘルパ

見込み売上

確定売上

売掛金