開発者向け

既存のシステムに、
文書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まで）に対応。doc_type は auto / printed / form / handwritten / mixed（手書き系は3クレジット/ページ）。変換は非同期です — アップロードの 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>（カーソル式ページネーション）。

エクスポート — 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": 3, "mixed": 3 } }

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クレジット、手書き中心=3クレジット、失敗は自動返金）。 初期費用・API利用料はありません。大量処理・月次バッチには法人向けボリュームプランをご用意しています。

互換性ポリシー

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