サービス紹介ログインアカウント作成

API・WEBHOOK・MCP

開発者ドキュメント

法人番号から、
登記情報（PDF）まで。

取得できるのは登記情報提供サービス由来の履歴事項の PDF（いわゆる謄本の内容）で、法務局の登記事項証明書ではありません。

最初の 1 文書を取得する ↓ API 仕様を読む

商業登記を API で取得する

法人番号を指定して見積を確認し、購入申請を作成します。原則として Web で承認・決済後、取得完了を署名付き Webhook で受信し、PDF を REST、住所を含まない解析データを JSON で取得できます。CSV/JSONL の書き出しや MCP による AI エージェントからの利用にも対応します。

  • REST API の /api/v1 で法人検索・見積・購入申請。購入は原則承認制で、承認なし購入にはオーナーの設定と金額上限が必要です。
  • Webhook の通知先と署名検証を設定し、order_item.available などで取得状況を確認します。PDF 配信は通知先ごとの設定と別途同意が必要です。
  • 文書 ID で PDF・JSON を取得し、Web のマイライブラリで CSV/JSONL を書き出します。MCP（/mcp）は検索・見積・購入申請・解析データに対応し、PDF は返しません。

API 仕様（OpenAPI 3.1）

形式・入手方法・権限・プラン

形式・連携入手方法必要な権限・条件必要なプラン
PDFREST：GET /api/v1/documents/{id}/pdfpdf:read・文書の権利・所属確認・提供可否の確認基本プラン（文書の取得料金は別途）
JSONREST：GET /api/v1/documents/{id}/datadata:read・文書の権利・データ閲覧条件最初の 5 文書はお試し。以降とアップロード分はデータ機能
CSVWeb：マイライブラリの書き出し文書の権利・データ閲覧条件。API キー権限とは別最初の 5 文書はお試し。以降とアップロード分はデータ機能
JSONLWeb：マイライブラリの書き出し文書の権利・データ閲覧条件。API キー権限とは別データ機能（月額 3,300 円・税込）
Webhook設定した通知先へ署名付きで送信通知先ごとの利用同意。PDF 配信は別途同意と提供判定が必要通知自体にデータ機能の契約は不要
REST/api/v1（OpenAPI 3.1）API キー。基本権限＋操作に応じ purchase・pdf:read・data:read・cart:write基本プラン。解析データには上記のデータ閲覧条件
MCP/mcp（AI エージェントから利用）API キー。ツールに応じた権限。PDF は REST で取得基本プラン。解析データには上記のデータ閲覧条件

5 分で最初の登記情報（PDF）まで

キーの発行からダウンロードまで、接続の手順を 5 分で確認します。承認・決済と実際の取得にかかる時間は含みません。Webhook の通知先は、ここではまだ不要です。

  1. キー発行
  2. 法人番号で申請
  3. Web で承認・決済
  4. GET で状態を確認
  5. 文書 ID から PDF 取得

例の ID・社名・金額は説明用です。curl はサーバーやローカルのターミナルから実行します。Origin ヘッダを含むリクエストは拒否されます。

1. キーを発行する

所属確認（利用する法人への所属を運営が確認する手続き）と規約への同意を済ませます。設定の「API キー」で purchase と pdf:read を選んで発行してください。発行者とはキーを発行したメンバーです。キー本体は発行直後だけ表示されます。TOKI_BASE_URL は https://toki.compalyze.co.jp です。Webhook の設定は最初は不要です。

curl・ターミナル
export TOKI_BASE_URL='https://toki.compalyze.co.jp'
# シェルの履歴にキーを残さずに入力（bash / zsh）
read -rs TOKI_API_KEY
export TOKI_API_KEY

正常に設定できた場合、ターミナルには何も表示されません。キーは表示せず次のリクエストで確認します。

2. 法人番号で購入申請する

登記情報の PDF の最新取得は kind=latest です。例の法人番号を取得したい法人の番号に置き換えます。同じ処理の再試行には同じ Idempotency-Key を使い、新しい申請では値を変えます。status が pending_approval なら申請成功です。reason は申請の失敗理由ではなく、承認なし購入を適用しなかった理由です。auto_purchase_disabled は承認なし購入が無効で、Web での承認が必要という意味です。

curl・ターミナル
curl --fail-with-body "$TOKI_BASE_URL/api/v1/purchase-requests" \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: first-history-001' \
  -d '{"items":[{"cn":"2000000000001","kind":"latest"}]}'
応答
{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending_approval",
  "reason": "auto_purchase_disabled"
}

3. Web で承認する

POST で返された request_id を設定し、詳細の approval_url を開きます。同じ法人の購入権限を持つメンバーが金額・内容を確認して承認し、Web で決済してください。申請だけでは購入は確定しません（承認なし購入を設定した場合を除く）。

curl・ターミナル
export REQUEST_ID='返された request_id'
curl --fail-with-body "$TOKI_BASE_URL/api/v1/purchase-requests/$REQUEST_ID" \
  -H "Authorization: Bearer $TOKI_API_KEY"

4. 状態を確認する

同じ GET を 30 秒〜1 分程度の間隔でポーリングします。approved は承認済みで、取得完了とは限りません。order_items の status=available と document_id を確認します。rejected・cancelled・expired なら停止してください。本番運用で通知を受け取る方法は「Webhook」の節を参照してください。

curl・ターミナル
curl --fail-with-body "$TOKI_BASE_URL/api/v1/purchase-requests/$REQUEST_ID" \
  -H "Authorization: Bearer $TOKI_API_KEY"

本番運用向けの Webhook →

5. 登記情報の PDF を取得する

申請を 1 回 GET し、提供できる明細の document_id を PDF の GET に渡します。下の抽出には Python 3 を使います。order_id・item_id は文書 ID ではありません。PDF の取得時にも現在の権利・提供可否を再確認します。

curl・ターミナル
curl --fail-with-body "$TOKI_BASE_URL/api/v1/purchase-requests/$REQUEST_ID" \
  -H "Authorization: Bearer $TOKI_API_KEY" -o toki-request.json
DOCUMENT_ID=$(python3 - <<'PYTHON'
import json
with open("toki-request.json") as f:
    request = json.load(f)
rows = [r for r in request["order_items"]
        if r["status"] == "available" and r.get("document_id")]
assert len(rows) == 1, "提供できる明細を 1 件選んでください"
print(rows[0]["document_id"])
PYTHON
) && curl --fail-with-body -OJ \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  "$TOKI_BASE_URL/api/v1/documents/$DOCUMENT_ID/pdf"

HTTP 200・Content-Type: application/pdf・Content-Disposition: attachment。登記情報の PDF がカレントディレクトリに保存されます。

※ --fail-with-body は curl 7.76.0 以降で使えます。古い版では curl を更新するか、-f を使い、エラー本文が出力されない点に注意してください。

認証とキー

すべての REST・MCP リクエストに Authorization: Bearer $TOKI_API_KEY を付けます。Cookie によるログインは API キーの代わりになりません。発行者（キーを発行したメンバー）の現在の所属・所属確認・同意・権限で判定します。

基本権限と 4 種類の追加権限

基本権限は法人検索・法人情報・見積です。在庫は、提供できるアーカイブの有無を指します。権利付与済みとは、その法人が取得済みで利用する権利を持つ状態です。追加権限を選ばないキーでも利用できます。

権限できること
data:read権利付与済み文書の解析データ
pdf:read権利付与済み PDF
cart:writeAPI カートの取得・追加・削除
purchase購入申請の作成・取得・一覧・取消

最初の PDF は purchase + pdf:read、解析データの連携は purchase + data:read、カート経由ならさらに cart:write を付けます。読み取り専用の連携は data:read または pdf:read に絞ります。

購入権限のないメンバー（viewer：閲覧メンバー）も購入申請を作成・確認・取消できます。承認・決済は同じ法人の owner・admin・member（オーナー・管理者・購入メンバー）が行います。API カートの操作と承認なし購入には発行者の購入権限が必要です。

二段階認証・上限・失効

二段階認証を設定している場合は、発行時にも二段階認証が必要です。設定前に発行したキーは設定後に利用できなくなります。認証を済ませてキーを再発行してください。API 呼び出しごとに認証コードを送る方式ではありません。

有効なキーの上限は既定でユーザーごとに 10 本、法人ごとに 50 本です。有効期限を設定でき、設定画面で失効させられます。失効・期限切れ・所属の削除・権限の変更により利用できなくなります。

キーは環境変数で管理し、ソースコード・ブラウザ・AI への指示文へ埋め込まないでください。Authorization ヘッダやキー本体をログに残さず、漏えいしたら失効させて再発行します。シェルの set -x や curl の詳細ログにも注意してください。

API リファレンス

ベース URL は https://toki.compalyze.co.jp です。OpenAPI 3.1 の JSON を取得できます。入力と応答は原則として JSON で、PDF のみバイナリです。日時は ISO 8601 の JST（+09:00）、日付は YYYY-MM-DD、金額は円の整数です。ID の用途を区別し、法人番号は文字列で送ってください。

用途入力欄受理する値
購入申請items[].kindlatest・archive
カート追加items[].kindlatest または new・archive
見積cart[].choicelatest または new・archive

latest は new の別名として受け付け、カートの応答は new・archive、見積の choice は new・archive・redownload です。

API カートは Web カートとは別で、同じ法人・同じ発行者のキー間で共有します。

引換券は、条件を満たすアーカイブの取得に使える利用枠です。

取得代行は、Compalyze からの通常提供とは別に、取得代行約款への同意が必要な Web 専用の取得経路で、API からは購入できません。

社名から法人番号を調べる

GET /api/v1/companies/search

必要権限：基本

項目型意味
qstring・必須1〜200 文字。社名または法人番号。
limitinteger1〜50、既定 20
cursorstring前回の nextCursor（数字のみ）

応答

companies: Company[]・nextCursor: string | null。続きがなければ null。

エラー

400：検索語が空・長すぎる、limit・cursor が不正。検索機能が利用できない場合は 503。 認証・頻度制限・サービス障害は共通エラーを参照してください。

法人情報・アーカイブの有無を確認する

GET /api/v1/companies/{cn}

必要権限：基本

項目型意味
cnstring・必須13 桁の法人番号（パス）

応答

company: Company | null。該当する法人がなければ null。

エラー

400：法人番号の形式が不正。 認証・頻度制限・サービス障害は共通エラーを参照してください。

見積を確認する

POST /api/v1/quote

必要権限：基本

応答

Quote（下の見積の項目）。購入は実行しません。

エラー

400：cart が配列でない・50 件を超える、settings がオブジェクトでない、applyVouchers が boolean でない。 認証・頻度制限・サービス障害は共通エラーを参照してください。

リクエスト本文
{
  "cart": [
    {
      "cn": "2000000000001",
      "choice": "new",
      "manual": true
    }
  ],
  "settings": {
    "maxAgeDays": 90,
    "unverified": "archive"
  },
  "applyVouchers": true
}

API カートを取得する

GET /api/v1/cart

必要権限：cart:write

リクエスト本文・パラメータはありません。

応答

items: object[]（cn: string・kind: new | archive・added_via_key_id: string・added_at: string・quote: Quote | null・error: string | null）。quote: Quote | null はカート全体の見積。提供できない明細は error=not_available。

エラー

403：現在の発行者にカートを操作する権限がない。 認証・頻度制限・サービス障害は共通エラーを参照してください。

カートに追加する

POST /api/v1/cart/items

必要権限：cart:write

項目型意味
itemsobject[]・必須1〜50 件
items[].cnstring・必須13 桁の法人番号
items[].kindstring・必須latest または new・archive。latest は new の別名、応答は new
items[].trackstringprovision。取得代行は対象外。

応答

results: object[]。各要素は cn: string | null・kind: string | null・ok: boolean・status: added | already_in_cart | rejected・error: string | null（already_in_cart では省略）。error は invalid_item・entrusted_requires_web_terms・not_available・order_limit・monthly_cap。

エラー

400：items が配列でない・件数が範囲外。個別の追加結果は HTTP 200 の results で確認。 認証・頻度制限・サービス障害は共通エラーを参照してください。

リクエスト本文
{
  "items": [
    {
      "cn": "2000000000001",
      "kind": "new"
    }
  ]
}

カートから法人を削除する

DELETE /api/v1/cart/items/{cn}

必要権限：cart:write

項目型意味
cnstring・必須法人番号（パス）
kindstringクエリ。new・archive。省略で両方削除。

応答

removed: number（削除した件数）。

エラー

400：cn・kind の形式が不正。 認証・頻度制限・サービス障害は共通エラーを参照してください。

カートを空にする

DELETE /api/v1/cart

必要権限：cart:write

リクエスト本文・パラメータはありません。

応答

removed: number（削除した件数）。

エラー

共通エラーを参照。 認証・頻度制限・サービス障害は共通エラーを参照してください。

法人番号から購入申請する

POST /api/v1/purchase-requests

必要権限：purchase

項目型意味
Idempotency-Keystring・必須ヘッダ。空白のみ不可、最大 200 文字。
itemsobject[]1〜50 件。from_cart と排他。
items[].cnstring・必須13 桁の法人番号
items[].kindstring・必須latest・archive
items[].trackstringprovision のみ
from_cartbooleantrue で API カートを固定して申請。items は指定しない。

応答

request_id: string・status: pending_approval | ordered | cancelled・order_ids: string[]（ordered のみ）・reason: string（値があるときのみ）。HTTP 200。

エラー

400：冪等キーなし・空入力・未知のトップレベル項目・items と from_cart の併用。409：同じキーで別の内容。422：items_rejected。 認証・頻度制限・サービス障害は共通エラーを参照してください。

リクエスト本文
{
  "items": [
    {
      "cn": "2000000000001",
      "kind": "latest"
    }
  ]
}

申請・決済・取得の状態を確認する

GET /api/v1/purchase-requests/{id}

必要権限：purchase

項目型意味
idstring・必須申請 UUID（パス）

応答

PurchaseRequest（下の申請の項目）。作成時の ordered はここでは approved。

エラー

400：UUID が不正。403：このキーの申請ではない。 認証・頻度制限・サービス障害は共通エラーを参照してください。

このキーの申請を一覧する

GET /api/v1/purchase-requests

必要権限：purchase

リクエスト本文・パラメータはありません。

応答

requests: PurchaseRequest[]。新しい順、最大 100 件。このキーで作成した申請のみ。

エラー

共通エラーを参照。 認証・頻度制限・サービス障害は共通エラーを参照してください。

承認待ち申請を取り消す

DELETE /api/v1/purchase-requests/{id}

必要権限：purchase

項目型意味
idstring・必須申請 UUID（パス）

応答

PurchaseRequest。status=cancelled。期限を過ぎていた場合は expired。決済済み注文の取消 API ではありません。

エラー

400：UUID が不正。409：承認待ち以外など取消できない状態。 認証・頻度制限・サービス障害は共通エラーを参照してください。

文書の解析データを取得する

GET /api/v1/documents/{id}/data

必要権限：data:read

項目型意味
idstring・必須文書 UUID（パス）。注文・明細 ID と異なります。

応答

rows・excluded。文書と解析データの項目は下記。

エラー

400：文書 ID の形式が不正。個別の提供可否は excluded を確認。 認証・頻度制限・サービス障害は共通エラーを参照してください。

登記情報の PDF を取得する

GET /api/v1/documents/{id}/pdf

必要権限：pdf:read

項目型意味
idstring・必須文書 UUID（パス）

応答

application/pdf のバイナリ。Content-Disposition: attachment（filename と filename*）。Cache-Control: private, no-store。

エラー

400：ID が不正。403：権利・提供可否の確認・所属確認などの条件を満たさない。404：認可後にファイルが見つからない（Not found）。429：PDF の頻度上限。 認証・頻度制限・サービス障害は共通エラーを参照してください。

API カートの応答

項目型意味
itemsobject[]API カートの品目
items[].cnstring法人番号
items[].kindstringnew・archive
items[].added_via_key_idstring追加した API キーの UUID
items[].added_atstring追加日時
items[].quoteQuote | nullこの品目の見積
items[].errorstring | null見積できない場合は not_available
quoteQuote | nullカート全体の見積。見積できない場合は null

カート追加の応答

項目型意味
resultsobject[]指定品目ごとの追加結果
results[].cnstring | null法人番号。不正入力では null の場合あり。
results[].kindstring | null受理した種別。latest は new に正規化。
results[].okboolean追加済み・すでに登録済みなら true
results[].statusstringadded・already_in_cart・rejected
results[].errorstring | null（任意）invalid_item・entrusted_requires_web_terms・not_available・order_limit・monthly_cap。already_in_cart では項目なし。

法人情報：Company

見積：Quote

申請：PurchaseRequest

取得・一覧・取消の応答です。申請作成は簡略化した応答を返します。approved は承認済みを示し、PDF の提供可否は order_items[].status で確認します。

文書の解析データ

項目型意味
rowsobject[]提供可能な文書
rows[].document_idstring文書 ID
rows[].corporate_numberstring法人番号
rows[].file_namestring既定の PDF 名
rows[].dataobject解析データ。未取得の値は null
excludedobject[]提供対象から除いた文書
excluded[].document_idstring文書 ID
excluded[].reasonstring除外理由

下の役員・支店・履歴は配列です。例：officers: [{ name, title, appointed_on, status }]。住所は出力せず、本店移転の変更前・変更後・要約は null にします。解析情報の利用には文書の権利に加えデータ閲覧の条件を満たす必要があります。組織で最初に権利付与した 5 文書はデータ表示・CSV/JSON を無料で試せます。6 文書目以降とアップロード分にはデータ機能の契約（月額 3,000 円・税込 3,300 円）が必要です。対象は固定され、削除・権利取消し後も別文書へ移りません。JSONL は契約必須です。

PDF のファイル名

既定のファイル名は {取得日}_{商号}_{種別}.pdf です。文書の商号・取得日を使います。Web で保存した名前の設定は、この API の既定名には適用されません。file_name は同じ既定ルールによる名前です。日本語名は Content-Disposition の filename* も確認してください。curl の対応に応じて -OJ の保存名が異なる場合は、応答ヘッダを参照して保存名を指定します。

ファイルを保存する
curl --fail-with-body -OJ -H "Authorization: Bearer $TOKI_API_KEY" \
  "$TOKI_BASE_URL/api/v1/documents/$DOCUMENT_ID/pdf"

エラーとレート制限

API キーの認証失敗は理由を区別せず 403 {"error":"Request denied"} です。キーの有無・失効・権限不足などを応答から判別できません。Web の未ログイン時の 401 とは異なります。

HTTPerror意味
400Invalid requestJSON 不正、法人番号不正、必須ヘッダ不足など
403Request deniedキーの認証・認可を通らない
403Origin not allowedOrigin ヘッダを含む呼び出し
404Not found未定義のメソッド・パス、認可後の PDF が見つからない
409Request conflict冪等キーの内容不一致・操作できない状態
422items_rejected品目ごとの理由を items に返す
429Rate limit exceededRetry-After: 60 を確認して待つ
503Service unavailableサービスを利用できない。申請の再試行は同じ冪等キーを使う。
400 の例：Idempotency-Key がない
HTTP/1.1 400
Content-Type: application/json

{"error":"Invalid request"}

REST・MCP 共通で、API キー単位で毎分 120 回・送信元 IP 単位で毎分 120 回です。PDF はさらに、キー単位で毎分 10 回・法人単位で毎分 60 回（既定値）に制限します。内部的にもキー照合に毎分 120 回の制限があり、1 リクエストで複数回照合する場合があるため、HTTP で常に毎分 120 回を使える保証はありません。取得済み文書の再配信も PDF の枠に数えます。
通常は毎分数十回以下を目安にし、状態確認は 30 秒〜1 分程度空けます。429 を受けたら Retry-After（現在 60 秒）以上待ち、同時実行を減らして再試行します。購入申請の再試行は同じ冪等キーを再利用してください。

items_rejected のすべての理由コード

1 品目でも拒否されると申請全体を作成しません。HTTP 422 の items は cn: string | null・kind: string | null・reason: string の配列です。

コード意味
invalid_item法人番号・kind・項目の構造が不正
entrusted_requires_web_terms取得代行約款への同意が必要な Web 専用の取得経路
not_available対象法人・アーカイブを提供できない状態
already_ownedすでに権利を保有
duplicate_company法人番号の重複（1 法人につき 1 品目）
order_limit1 回の注文の件数上限に到達
monthly_cap月間の取得上限に到達
daily_limit1 日の取得上限に到達
422 の例
{
  "error": "items_rejected",
  "items": [
    {
      "cn": "2000000000001",
      "kind": "latest",
      "reason": "already_owned"
    }
  ]
}

購入と承認

  1. API で申請
  2. Web で見積差分を確認
  3. 購入権限のあるメンバーが承認
  4. 決済・与信
  5. 取得・提供可否を確認

承認できるのは同じ法人の owner・admin・member です。発行者と承認者の現在の所属・権限を検査します。申請の期限は既定で 72 時間です。必ず応答の expires_at を使ってください。

状態の遷移

pending_approval（承認待ち）

  • 承認 → approved（承認済み）→ 注文の決済・取得状況へ
  • 却下 → rejected
  • 期限・キーなどの失効 → expired
  • 申請キーで取消 → cancelled

承認なし購入：approved → 追加認証が必要 → pending_approval

POST の応答では承認済みは ordered、承認なし購入の全注文が取消済みなら cancelled です。GET では通常の承認済みは approved、承認なし購入の全注文が取消済みなら cancelled になります。

承認時に現在の見積・提供可否・上限を再確認します。申請時より増額していれば承認できません。表示した見積と一致しなければ確認し直します。権限・キー・規約・提供条件が変わった場合も再確認が必要です。

承認なし購入を使う条件

owner が Web でキーごとに明示設定します。REST と MCP は別々に許可し、正の整数の「日次上限額・月次上限額」を両方指定します。admin は停止できますが、有効化は owner のみです。発行者に購入権限があり、現在も有効な owner の設定・保存済みカード・上限内の金額が必要です。取得代行は対象外です。

上限はキー単位・JST の日付・月単位で、予約中と確定済みの金額を合算します。並行要求と再送で重複して枠を消費しないよう検査します。保存済みカードの追加認証が必要なら承認待ちに戻り、Web で対応します。同じ申請の再送で設定変更後の自動承認をやり直すことはありません。

承認なし購入時の作成応答
{
  "request_id": "11111111-1111-4111-8111-111111111111",
  "status": "ordered",
  "order_ids": [
    "33333333-3333-4333-8333-333333333333"
  ]
}

latest は最新の取得を希望する指定です。直近取得済みならアーカイブを優先する場合があります。閉鎖法人の最新の取得は閉鎖事項へ切り替わるため、履歴事項だけを扱う連携では事前に法人情報の closed と見積の docType を確認してください。

Idempotency-Key の使い分け

同じ処理のネットワーク再試行は同じヘッダ値と同じ内容を再送します。同じキーに異なる入力を渡すと 409 です。別の購入は新しい値にします。from_cart の申請内容は初回に固定され、カートを変更して再送しても新しい申請にはなりません。

Webhook：完了を受け取る

設定画面の Webhook で HTTPS の受信 URL とイベントを登録します。法人単位で共有され、管理には owner・admin と二段階認証が必要です。通知先は既定で 5 件までです。公開ホストの HTTPS・443 番のみで、ローカル IP・認証情報付き URL・リダイレクト先は利用できません。

通知先ごとに「Webhook 利用時の注意点」への同意が必要です。既存通知先も、同意を記録するまで疎通確認・テスト・通常イベントは配信されません。設定画面から同意すると配信対象に戻ります。URL 変更時も再同意が必要です。 利用規約 第 14 条の 2

PDF 配信は通知先ごとの設定で、既定は無効です。有効にする際は受信先の管理・第三者に提供しない利用・委託先の監督と安全管理について別途表明保証への同意が必要です。無効化・URL 変更で同意は失効します。現行版の利用同意・PDF 同意がある通知先には、明細を提供可能になったとき document.pdf を送ります。購読イベントの選択とは独立した設定で、order_item.available は選択に従い別に届きます。

いつ届くか

  1. purchase_request.pending_approval → 承認待ち
  2. purchase_request.approved・purchase_request.rejected → メンバーの承認・却下・取消
  3. auto_purchase.executed → 承認なし購入の与信確定
  4. order_item.available → 明細を提供可能
  5. document.pdf → PDF 配信が有効な通知先へ送付
  6. order.completed → 通常処理終了
  7. order.registration_followup → 登記の追跡終了

承認待ちの期限切れなどの失効は purchase_request.expired です。承認なし購入が成立すれば pending_approval・approved を経ず auto_purchase.executed へ進みます。approved はメンバーの承認時で、決済完了ではありません。到着順は保証しないため、通知後は GET で現在の申請を確認します。

イベントいつ本文の主な項目受け取ったらやること
purchase_request.pending_approval承認待ち申請を作成したとき、または自動決済に追加認証が必要で承認待ちへ戻ったときに通知します。purchase_request_id・counts.items・amount_jpyGET の approval_url で承認を依頼
purchase_request.approvedメンバーが Web で承認したときに通知します。決済・取得完了ではありません。承認なし購入で自動承認された場合はこのイベントではなく auto_purchase.executed が届きます。purchase_request_id・counts.items・amount_jpyGET と counts で進捗・取得結果を確認
purchase_request.rejected承認待ち申請が却下または申請キーで取消されたときに通知します。purchase_request_id・counts.items・amount_jpyGET で状態を確認し処理を停止
auto_purchase.executed承認なし購入の全注文で与信が確定したときに通知します。PDF の取得完了通知ではありません。order_id は代表の 1 注文です。purchase_request_id・order_id・counts.items・amount_jpyGET と counts で進捗・取得結果を確認
order_item.available明細が確定し、現在提供可能になったときに通知します。order_id・counts（available は item_id も）GET の document_id で登記情報の PDF を取得
document.pdfPDF 配信が有効で、両方の同意が現行版の通知先に、明細が提供可能になった時点で送ります。検出済みの明細は、あとから有効化しても配信対象に追加しません。document_id・file_name・size_bytes・sha256・pdf_base64署名検証後に Base64 を復号しサイズ・SHA-256 を照合
order.completed通常の処理が終了したときに通知します。登記完了待ちを含む場合があります。全件成功の意味ではありません。order_id・counts（available は item_id も）GET と counts で進捗・取得結果を確認
order.registration_followuporder.completed で登記完了待ちだった対象の追跡がすべて終了したときに通知します。order_id・counts（available は item_id も）GET と counts で進捗・取得結果を確認
purchase_request.expired承認待ちの申請が期限切れなどで失効したときに通知します。purchase_request_id・counts.items・amount_jpyGET で状態を確認し処理を停止
webhook.ping通知先の登録・URL 変更・疎通の再確認時に送信します。購読イベントには含めません。event_id・type・occurred_at署名検証して 2xx を返す

counts の母集団：申請イベント・auto_purchase.executed は申請品目全体、order_item.available は通知対象の 1 明細、order.completed は注文の対象明細全体（closed_expanded は除外）、order.registration_followup は先の completed 時点で登記完了待ちだった明細だけです。acquired は取得済み、registration は登記完了待ち、failed は取得できなかった数で、後続通知の counts を別の母集団と合算しないでください。

届く HTTP リクエスト

受信する HTTP リクエスト
POST /webhooks/toki HTTP/1.1
Host: your-service.example
Content-Type: application/json
Toki-Webhook-Id: 22222222-2222-4222-8222-222222222222
Toki-Webhook-Timestamp: 1793840700
Toki-Webhook-Signature: v1=<HMAC-SHA256 の 64 桁の小文字 16 進数>

{
  "event_id": "22222222-2222-4222-8222-222222222222",
  "type": "order_item.available",
  "occurred_at": "2026-11-05T10:05:00+09:00",
  "order_id": "33333333-3333-4333-8333-333333333333",
  "item_id": "44444444-4444-4444-8444-444444444444",
  "counts": {
    "items": 1,
    "acquired": 1,
    "registration": 0,
    "failed": 0
  }
}

order_item.available

明細が確定し、現在提供可能になったときに通知します。

order.completed

通常の処理が終了したときに通知します。登記完了待ちを含む場合があります。全件成功の意味ではありません。

order.registration_followup

order.completed で登記完了待ちだった対象の追跡がすべて終了したときに通知します。

purchase_request.pending_approval

承認待ち申請を作成したとき、または自動決済に追加認証が必要で承認待ちへ戻ったときに通知します。

purchase_request.approved

メンバーが Web で承認したときに通知します。決済・取得完了ではありません。承認なし購入で自動承認された場合はこのイベントではなく auto_purchase.executed が届きます。

purchase_request.rejected

承認待ち申請が却下または申請キーで取消されたときに通知します。

purchase_request.expired

承認待ちの申請が期限切れなどで失効したときに通知します。

auto_purchase.executed

承認なし購入の全注文で与信が確定したときに通知します。PDF の取得完了通知ではありません。order_id は代表の 1 注文です。

webhook.ping

通知先の登録・URL 変更・疎通の再確認時に送信します。購読イベントには含めません。

document.pdf

PDF 配信が有効で、両方の同意が現行版の通知先に、明細が提供可能になった時点で送ります。検出済みの明細は、あとから有効化しても配信対象に追加しません。

PDF の受信と検証

document.pdf は未加工の JSON 本文（pdf_base64 を含む全体）で署名を検証した後、Base64 を復号し、size_bytes と SHA-256 を照合します。上の PDF 例は形式説明用の小さな合成データです。実 PDF の上限は 10 MiB（10,485,760 bytes）、Base64 を含む受信本文の上限は 15 MiB 以上を確保してください。file_name は表示用です。保存には document_id など自分で管理する識別子を使ってください。

Node.js：署名検証後の PDF 照合
import { createHash } from 'node:crypto';

// 必ず verifyWebhook(rawBody, headers, secret) が成功した後に呼ぶ。
export function decodeWebhookPdf(body) {
  if (body.type !== 'document.pdf' || body.content_type !== 'application/pdf') throw new Error('invalid_pdf');
  const pdf = Buffer.from(body.pdf_base64, 'base64');
  if (!pdf.length || pdf.length > 10485760 || pdf.length !== body.size_bytes ||
      createHash('sha256').update(pdf).digest('hex') !== body.sha256) throw new Error('invalid_pdf');
  return pdf;
}

送信直前にも配信設定・両同意・権利・所属確認・提供停止を確認します。不適格・上限超過で閉じた配信は手動再送できません。提供可能でも外部への到達は保証されません。提供履歴には配信結果を記録します。

署名ヘッダと検証

項目型意味
Toki-Webhook-IdUUID配信するイベントの識別子。重複排除に使う。
Toki-Webhook-Timestampstring送信時の Unix 秒
Toki-Webhook-Signaturestringv1= + HMAC-SHA256 の小文字 16 進数
Content-Typestringapplication/json

入力は timestamp + "." + 未加工の本文 bytes、鍵は表示された署名シークレットの UTF-8 bytes です。シークレットを 16 進数・Base64 として復号しません。JSON を再シリアライズせず、解析前の本文で計算し、定数時間比較を使います。例では受信側の方針として時刻差を前後 5 分までに制限します。

フレームワークで未加工の本文を読む

Express
// express.json() より前に登録する
app.post('/webhooks/toki', express.raw({type:'application/json'}), handler);
// handler 内の req.body が Buffer。検証後に JSON.parse(req.body)。
Next.js App Router
export async function POST(request: Request) {
  const rawBody = Buffer.from(await request.arrayBuffer());
} // rawBody と request.headers で検証・永続化し Response を返す
FastAPI
@app.post("/webhooks/toki")
async def webhook(request: Request):
    raw_body = await request.body()  # bytes。検証後に JSON を解析する。
Node.js（標準ライブラリのみ）
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: JSON 解析前の Buffer。secret: 表示された署名シークレットそのもの。
export function verifyWebhook(rawBody, headers, secret, now = Date.now()) {
  const timestamp = headers.get('Toki-Webhook-Timestamp') ?? '';
  const signature = headers.get('Toki-Webhook-Signature') ?? '';
  if (!/^\d+$/.test(timestamp) || !/^v1=[a-f0-9]{64}$/.test(signature)) return false;
  // 受信側の方針として前後 5 分まで許容。時計は同期してください。
  if (!Number.isSafeInteger(Number(timestamp)) || Math.abs(now / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', Buffer.from(secret, 'utf8'))
    .update(timestamp + '.', 'ascii').update(rawBody).digest();
  const actual = Buffer.from(signature.slice(3), 'hex');
  return actual.length === expected.length && timingSafeEqual(actual, expected);
}

// 使用例（Node.js の IncomingMessage に対して）:
// const rawBody = Buffer.concat(await Array.fromAsync(request));
// const headers = new Headers();
// for (const [name, value] of Object.entries(request.headers)) {
//   if (typeof value === 'string') headers.set(name, value);
// }
// if (!verifyWebhook(rawBody, headers, process.env.TOKI_WEBHOOK_SECRET)) {
//   response.writeHead(400).end(); return;
// }
// const event = JSON.parse(rawBody.toString('utf8'));
// ここで Toki-Webhook-Id を一意キーにして永続化。その後に 204 を返す。

再送・重複排除・順序

2xx を成功とし、それ以外や通信失敗は再送対象です。接続は最大 3 秒、通常イベントの送信全体は最大 10 秒、document.pdf は PDF 取得を含め最大 30 秒です。本文を永続化してから速やかに 2xx を返し、重い処理は受信側のジョブへ渡してください。

再送間隔は 60 秒から倍増して最大 1 時間、再送開始から 24 時間が上限です。実際の送信時刻は処理状況により遅れる場合があります。履歴から手動で再送もできます。重複・順序逆転に備え、Toki-Webhook-Id に一意制約を設け、処理済みなら 2xx を返します。現在の状態は API で確認します。

疎通確認とテスト送信

登録・URL 変更・再確認で webhook.ping が送られます。署名を検証して 2xx を返すと確認済みになり、選択イベントの配信対象になります。ping の失敗は通常イベントのようには自動再送されないため、設定画面から疎通を再確認します。

確認済みで有効な通知先に、購読中のイベントを選んでテスト送信できます。既定は通知先ごとに 1 時間に 10 回までです。注文や課金は発生しません。本文に test: true が付き、本文のすべての ID はゼロ UUID です。ヘッダの Toki-Webhook-Id は送信ごとの実イベント ID なので、テストもヘッダで重複排除します。テスト通知から PDF の取得や購入を実行しないでください。

PDF 配信が有効で、現行版の利用同意・PDF 同意がある通知先では、document.pdf のサンプルも選べます。同梱のダミー PDF（sample.pdf）を送り、本物の文書は送りません。購入は不要で、提供履歴には残りません。

テスト本文の例
{
  "event_id": "00000000-0000-0000-0000-000000000000",
  "type": "order_item.available",
  "occurred_at": "2026-11-05T10:05:00+09:00",
  "order_id": "00000000-0000-0000-0000-000000000000",
  "item_id": "00000000-0000-0000-0000-000000000000",
  "counts": {
    "items": 1,
    "acquired": 1,
    "registration": 0,
    "failed": 0
  },
  "test": true
}

自動停止とシークレットの更新

連続失敗が既定 20 回に達すると自動停止し、管理者に通知します。送信履歴・受信側のログを確認し、通知先を修正して疎通確認後に有効化してください。署名シークレットは登録時と再発行時に表示します。更新時は受信側にも反映してください。

通常イベントの本文を最小限にする理由

通常イベントの JSON 本文は最小限にし、原則として受け取った側が API で現在の権利・提供可否の確認を通して取得するためです。解析データも本文には含みません。通知が届いても、それ自体が権利の付与やダウンロードの許可にはなりません。

MCP：AI エージェントから申請する

接続先は /mcp です。Streamable HTTP の POST、JSON-RPC 2.0 に対応し、protocolVersion は 2025-11-25 です。REST と同じ API キーを使います。

HTTP MCP クライアントの設定例
{
  "mcpServers": {
    "toki": {
      "type": "http",
      "url": "https://toki.compalyze.co.jp/mcp",
      "headers": {
        "Authorization": "Bearer ${TOKI_API_KEY}"
      }
    }
  }
}

上の JSON は Claude Code の .mcp.json 用の設定例です。Cursor 等の、HTTP とカスタム Authorization ヘッダを設定できるクライアントでも利用できます。設定キーや環境変数の展開方法はクライアントによって異なります。${TOKI_API_KEY} は設定時に環境変数から解決し、平文のキーを設定ファイルへコミットしないでください。

Claude Code CLI
claude mcp add --transport http toki https://toki.compalyze.co.jp/mcp --header "Authorization: Bearer $TOKI_API_KEY"
接続の初期化（curl）
curl --fail-with-body "$TOKI_BASE_URL/mcp" \
  -H "Authorization: Bearer $TOKI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'

最初に initialize、初期化済み通知、tools/list、tools/call の順で呼び出します。Accept は application/json, text/event-stream の両方を含めます。通知への応答は 202 です。GET には 405、Content-Type 不正には 415、Accept 不足には 406 を返します。

送信する本文：tools/call(request_purchase)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "request_purchase",
    "arguments": {
      "items": [
        {
          "cn": "2000000000001",
          "kind": "latest"
        }
      ],
      "idempotency_key": "first-history-001"
    }
  }
}
応答：result.content の text は JSON 文字列
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"request_id\":\"11111111-1111-4111-8111-111111111111\",\"status\":\"pending_approval\",\"reason\":\"auto_purchase_disabled\"}"
      }
    ]
  }
}

公開ツールの全一覧

各ツールの入力は以下の JSON Schema のとおりです。応答は result.content[] の type=text、text に JSON が入ります。品目拒否などは isError=true で返します。tools/call 中の認可拒否・頻度上限は JSON-RPC の error ではなく、HTTP 403・429 と通常の {"error":"Request denied"}・{"error":"Rate limit exceeded"} で返ります。429 の Retry-After も確認してください。入力不正は JSON-RPC の -32602、未知のメソッドは -32601 です。

PDF と購入の扱い

MCP に PDF を返すツールはありません。PDF は REST の documents/{id}/pdf を利用します。解析データにも住所・PDF は含みません。

AI エージェントにはまず見積・購入申請までを任せ、Web でメンバーが内容と金額を承認します。owner が MCP の承認なし購入を有効にしたキーは即時に購入へ進むため、金額上限を明示し、用途ごとにキーを分けてください。同じ呼び出しの再試行は同じ idempotency_key を使います。

よくある質問