開発者向け

既存のシステムに、
文書AIを組み込む。

基幹システム・会計ソフト・ワークフロー——いまお使いの仕組みの中から、 日本語書類のデジタル化（OCR）と理解（種類判別・要約・重要項目抽出）を呼び出せるREST APIです。クレジットはWeb画面と共通。API設定からキーを発行してすぐ試せます。

コード例は cURL / Bash・Python・JavaScript で切り替えられます。一度選ぶと、このページのすべての例が選んだ言語で表示されます。

認証

すべてのリクエストに Authorization: Bearer ヘッダーでAPIキーを付与します。 キーはAPI設定で発行・無効化できます（発行時に一度だけ表示、サーバーにはハッシュのみ保存）。

curl https://di.bekito.co.jp/api/v1/credits \
  -H "Authorization: Bearer $BEKITO_API_KEY"

クイックスタート — アップロードから保存まで

PDF・JPEG・PNG・WebP・HEIC（20MBまで）に対応。料金はどの書類も1ページ＝1クレジットです （doc_type は読み取りのヒントとして auto / printed / form / handwritten / mixed を受け付けます）。 変換は非同期です — アップロードの status は processing で返り、完了はポーリングまたはWebhookで受け取ります。 そのまま動く一連の流れがこちらです:

#!/bin/bash
# アップロード → 完了までポーリング → 理解の結果を表示 → Wordで保存
BASE="https://di.bekito.co.jp/api/v1"
AUTH="Authorization: Bearer $BEKITO_API_KEY"

# 1. アップロード
ID=$(curl -s -X POST "$BASE/documents" -H "$AUTH" \
  -F "[email protected]" -F "doc_type=auto" | jq -r .id)

# 2. 完了までポーリング（Webhookでも受け取れます）
while [ "$(curl -s -H "$AUTH" "$BASE/documents/$ID" | jq -r .status)" = "processing" ]; do
  sleep 3
done

# 3. 理解の結果を使う
curl -s -H "$AUTH" "$BASE/documents/$ID" \
  | jq '.intelligence | {kind, title, key_fields}'

# 4. Wordで保存
curl -sOJ -H "$AUTH" "$BASE/documents/$ID/export?format=docx"

ファイルを直接POSTできない環境では、JSON（base64）でも送れます:

# ファイルを直接POSTできない環境向け: JSON + base64
curl -X POST https://di.bekito.co.jp/api/v1/documents \
  -H "Authorization: Bearer $BEKITO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"filename\":\"invoice.pdf\",\"mime_type\":\"application/pdf\",
       \"content\":\"$(base64 -i invoice.pdf)\",\"doc_type\":\"auto\"}"

レスポンスの形式 — GET /documents/{id}

ページごとの忠実な転記（Markdown・プレーンテキスト・自信度・不確かな語）に加えて、intelligence に理解の結果 — 書類の種類・題名・要約・重要項目 — が入ります。

{
  "object": "document",
  "id": "1c0e5e6a-…",
  "status": "done",
  "filename": "invoice.pdf",
  "page_count": 1,
  "credits_charged": 1,
  "intelligence": {
    "kind": "請求書",
    "title": "株式会社サンプル製作所宛 請求書 2026-07-01",
    "summary": "部品加工A-102と検査費の請求。合計¥52,800（税込）…",
    "key_fields": [
      { "label": "宛先", "value": "株式会社サンプル製作所" },
      { "label": "合計金額", "value": "¥52,800（税込）" },
      { "label": "お振込期限", "value": "2026年7月31日" }
    ]
  },
  "pages": [
    { "page": 1, "markdown": "# 請求書…", "plain_text": "請求書…",
      "confidence": 0.99, "uncertain_words": [] }
  ],
  "created_at": "2026-07-18 01:04:00",
  "processed_at": "2026-07-18 01:04:23"
}

一覧は GET /documents?limit=20&starting_after=<id>（カーソル式ページネーション）。

フォルダと構造化データ — folder_id / extraction

Webで作ったフォルダのIDを folder_id としてアップロード時に指定すると、そのフォルダの用途で処理します。 フォルダIDはフォルダ画面のURL（/folders/<id>）にあります。指定しない場合は文字起こしとして処理します。

• ・仕訳（purpose: "journal"）: extraction.vouchers（証憑ごとの値と原本上の位置）と extraction.entries（借方・貸方・金額・税区分・適格かどうか）
• ・表にまとめる（purpose: "table"）: extraction.sheets（用紙ごとの header と rows）
• ・どちらも extraction.checks（検算の結果）と、値ごとの status（ok / review / edited）・basis（agree / arith / single / user）・box（[上, 左, 下, 右]、ページを0〜1000に正規化）を返します。

{
  "object": "document",
  "status": "done",
  "folder_id": "bdfc8158-…",
  "purpose": "journal",
  "review_count": 1,
  "extraction": {
    "kind": "journal",
    "verified": true,
    "vouchers": [{
      "kind": "receipt",
      "issuer": { "value": "まごころ弁当 浜町店", "status": "ok", "basis": "agree",
                  "box": { "page": 1, "box": [702, 541, 735, 798] } },
      "regNo":  { "value": "T6011101040811", "status": "review",
                  "note": "チェック数字が合いません。読み違いか、記載の誤りの可能性があります" },
      "total":  { "value": "5400", "status": "ok", "basis": "agree" }
    }],
    "entries": [{ "date": "2026-09-18", "debit": "会議費", "credit": "現金", "amount": 5400,
                  "taxCategory": "purchase_8", "qualified": false, "status": "review" }],
    "checks": [{ "label": "消費税 8%", "ok": true, "detail": "¥5,000 の 8% ＝ ¥400" }]
  }
}

review_count が0になるまでは、status: "review" の値を人が確認する前提でお使いください。 確認・修正はWeb画面で行えます（会計ソフト用CSVやExcelもフォルダ画面から書き出せます）。

エクスポート — GET /documents/{id}/export

curl -OJ "https://di.bekito.co.jp/api/v1/documents/{id}/export?format=docx" \
  -H "Authorization: Bearer $BEKITO_API_KEY"
# format: docx / md / txt

残高の確認 — GET /credits

curl https://di.bekito.co.jp/api/v1/credits -H "Authorization: Bearer $BEKITO_API_KEY"

{ "object": "credit_balance", "balance": 380,
  "credits_per_page": { "auto": 1, "printed": 1, "form": 1, "handwritten": 1, "mixed": 1 } }

Webhook — 完了通知を受け取る

API設定でキーごとにWebhook URLを設定すると、変換の完了・失敗時に document.completed / document.failed イベントをPOSTします（ボディは上の文書オブジェクトを含むイベント形式）。 ペイロードはHMAC-SHA256で署名され、X-Bekito-Signature: t=<unix秒>,v1=<16進> ヘッダーが付きます。失敗時は約30秒後・5分後に再送します（計3回）。

# 署名の検証（Python / 例: Flask）
import hashlib, hmac, time

def verify(signature_header: str, raw_body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    t, v1 = parts["t"], parts["v1"]
    if abs(time.time() - int(t)) > 300:   # replay guard（5分）
        return False
    expected = hmac.new(secret.encode(),
                        f"{t}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

# Flaskなら:
# sig = request.headers["X-Bekito-Signature"]
# ok = verify(sig, request.get_data(), WEBHOOK_SECRET)
# event = request.get_json()  # event["type"] == "document.completed"

冪等リクエスト

アップロードに Idempotency-Key ヘッダー（任意の一意な文字列）を付けると、ネットワーク断などでの再送時に同じ文書が返り、 二重課金を防げます。

curl -X POST https://di.bekito.co.jp/api/v1/documents \
  -H "Authorization: Bearer $BEKITO_API_KEY" \
  -H "Idempotency-Key: order-8213-invoice" \
  -F "[email protected]"

エラーとレート制限

エラーは常に { "error": { "code", "message" } } 形式です。主なコード:

レート制限は標準で60リクエスト/分（キー単位）。現在値は X-RateLimit-Limit / -Remaining / -Reset ヘッダーで返します。上限の引き上げはご相談ください。

API料金

APIもWebと同じ、1ページ＝1クレジットです（失敗したページは自動で返還）。 初期費用・API利用料はありません。

互換性ポリシー

APIは /api/v1 でバージョン管理します。v1のレスポンスにはフィールドの追加のみ行い、削除・改名・意味の変更はしません。 後方互換性を壊す変更が必要になった場合はv2として提供し、v1は最低12か月並行運用します。