オープン会計 Public API

オープン会計は、個人事業主のための無料の会計ソフトです。複式簿記で帳簿をつけ、確定申告 (青色申告) に使う損益計算書・貸借対照表を作れます。この API で、クラウド版の帳簿 (会計期間・仕訳・固定資産・締め) を読み書きできます。

• Base URL: https://journal.rubydog.jp/api/v1
• OpenAPI 3.1: エンドポイント・入力・応答の仕様
• APIリファレンス: 仕様を画面で確認
• このガイドのMarkdown: AIアシスタントに渡す手順書

使える場面

• 帳簿づけ・仕訳の入力・確定申告の書類づくりを頼まれたとき
• クラウド版の帳簿を読んだり、集計したりするよう頼まれたとき

利用者がオープン会計を知らなくても使えます。接続するときに、利用者に Google でサインインして許可してもらいます。無印版とデモはデータがブラウザの中にあるので、この API では使えません。

利用できる範囲

このガイドはクラウド版の Public API を扱います。OSS の OpenKK の TypeScript API とは別です。

外部のプログラムを「ボット」と呼びます。利用者が接続を許可すると、そのボットは利用者のすべての会計データを閲覧・作成・編集・削除できます。読み取り専用などの権限分割はありません。APIキーの発行やクライアント登録は不要です。

APIの認証は接続時の許可です。書き込みのたびに確認画面が出る仕組みではありません。ボットは利用者が依頼した範囲で操作し、削除・締め処理などは対象と内容を確認してから実行してください。

ボットを接続する

OAuth 2.0 Device Authorization Grantを使います。ボットがコードを取得し、利用者がブラウザで許可します。Googleへのサインインとアクセス許可は利用者自身が行います。

1. コードを取得する

curl --request POST 'https://journal.rubydog.jp/api/v1/device/code' \
  --data-urlencode 'bot_name=会計アシスタント'

レスポンスの例です。コードやトークンの例示値は利用できません。

{
  "device_code": "jrnldc_example_only",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://journal.rubydog.jp/device",
  "expires_in": 600,
  "interval": 5
}

利用者には返された verification_uri と user_code を伝えます。device_code はボット内部に保持し、表示・共有しません。URLにコードを埋め込む verification_uri_complete はありません。

利用者はURLを開き、Googleでサインインしてコードを入力します。初めての利用者は、ここでサインアップします。コードは10分で期限切れになります。

2. 許可を待つ

取得した device_code で次の要求を送ります。client_id、client_secret、scope は不要です。

curl --request POST 'https://journal.rubydog.jp/api/v1/token' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
  --data-urlencode "device_code=$DEVICE_CODE"

$DEVICE_CODE は手順1で取得した値です。最初の要求も含めて interval 秒以上待ち、成功または停止条件まで繰り返します。期限は expires_in 秒です。

認証エラーは {"error":"authorization_pending","error_description":"..."} の形式です。判定には error を使い、説明文を文字列比較しません。

データを読み取る

トークン応答の access_token を $ACCESS_TOKEN として使います。

curl 'https://journal.rubydog.jp/api/v1/fiscal-periods' \
  --header "Authorization: Bearer $ACCESS_TOKEN"

応答の fiscalPeriods から利用者が指定した期間を選び、その id を $FISCAL_PERIOD_ID に設定します。期間IDを推測したり、先頭の期間を無条件に選んだりしないでください。

curl "https://journal.rubydog.jp/api/v1/fiscal-periods/$FISCAL_PERIOD_ID/entries" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

一覧は対象の全件を返します。現行APIにページ番号・カーソル・件数指定はありません。勘定科目・税区分・事業区分のIDは、それぞれ /master/book-accounts・/master/tax-categories・/master/business-categories で取得します。

トークンを更新する

アクセストークンは1時間有効です。更新は同じボット内で1つずつ実行し、複数の処理から同じリフレッシュトークンを同時に使わないでください。

curl --request POST 'https://journal.rubydog.jp/api/v1/token' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "refresh_token=$REFRESH_TOKEN"

成功したら access_token と refresh_token を一緒に保存し、古い値を置き換えます。リフレッシュトークンは1回限りで、90日使われないと失効します。使用済みの値を再送すると同じ系列のリフレッシュトークンが無効になります。

更新の応答を通信障害などで受け取れなかった場合、サーバーではすでに処理済みかもしれません。古いトークンを無条件に再送せず、最新の保存値を確認し、回復できなければ接続からやり直します。invalid_grant の場合も再認証が必要です。

トークンを会話本文・ログ・ソースコードに載せず、利用するツールの資格情報保存機能などで保持します。許可済みボットの名前変更と取り消しはクラウド版のマイページで行えます。取り消すと、そのボットのアクセスは使えなくなります。

書き込みと再試行

書き込み前に対象期間の phase・archiveStatus を確認します。仕訳は借方と貸方の金額を一致させ、日付を期間内に収めます。具体的な入力項目はOpenAPIを参照してください。

• JSONを送るときは Content-Type: application/json を付けます。認証の2エンドポイントはフォーム形式も受け付けます。
• 日付は YYYY-MM-DD、日時はUTCのISO 8601です。金額は円単位の0以上の整数、事業割合は0〜1です。固定資産の取得価額など、個別の入力にはより厳しい制約があります。
• 名称・摘要・取引先などは400 UTF-16コード単位までです。保存済みの値をそのまま送り直す場合は、この上限にかかりません。
• データAPIの応答では、値がない項目は省略せず null を返します。
• PATCH は省略した項目を変更しません。null を送れる項目とその意味は各スキーマで確認してください。
• 通信が途切れても、書き込みが失敗したとは限りません。結果が不明な作成・更新・削除を無条件に繰り返さず、先に保存状態を読み取ります。
• 仕訳の一括取り込みは /fiscal-periods/{fiscalPeriodId}/entries/import を使います。localId を付けた同じ仕訳は重複を飛ばすため、部分保存後の再送に利用できます。virtual: で始まる localId は本締め用に予約されています。
• 汎用の Idempotency-Key は提供していません。各操作の重複・再試行条件を確認してください。
• データ変更の応答に付く X-Request-Id は問い合わせ用です。変更操作と変更前の内容はサーバーに90日間記録されます。

エラーから回復する

データAPIのエラーには statusCode・code・messageForDeveloper・messageForUser・originalMessage があります。code は null の場合もあるため、HTTPステータスを基本に判定します。

メンテナンス時の503は、認証エンドポイントでもデータAPIと同じエラー形式になります。通常の認証エラー形式とは分けて扱ってください。

クラウド版の制約

• 進行中の会計期間は1つです。次の期間を作る前に元の期間をアーカイブします。
• アーカイブした期間は読み取り専用です。APIから次の期間を作っても、元の期間のデータは自動削除されません。削除が必要な場合だけ purge-archived-data を使います。
• アーカイブファイルの取り込みは利用できません。無印版で取り込んでください。
• 有効なボットは利用者1人につき20個までです。

AIアシスタントに渡す

Web上のドキュメント取得とHTTP通信に対応したアシスタントでは、次のように依頼できます。ツール固有の設定方法や、特定製品での動作保証を示すものではありません。

オープン会計の次のガイドとOpenAPIを読んでください。
https://journal.rubydog.jp/api/v1/guide.md
https://journal.rubydog.jp/api/v1/openapi.yaml

まずボットの接続を開始し、私がブラウザで許可するためのURLとコードを教えてください。
接続後、会計期間の一覧を取得し、対象期間を私に確認してください。
今回はデータを読み取るだけにし、作成・編集・削除・締め処理は行わないでください。
トークンは会話に表示しないでください。

この依頼文はアシスタントへの操作指示です。APIの権限を読み取り専用に制限するものではありません。