11. API連携導入ガイド

このガイドは、なんでも読めるくん（ASR Alpha）のAPIと統合するためのサンプルコードと、
その仕様について解説するものです。

サンプルコードはJavaScriptで記述されており、
Node.js（バージョン22以降を推奨）で動作します。

サンプルコードの参照やAPI連携テストをご希望の方は営業担当者までお問い合わせください。
※API利用にはAPIキーが必要となります。

下記内容についてより詳細にご確認いただきたい場合　こちら　をご確認ください。

1. 接続先情報（URL）

システムを利用するための主要なURLは以下の通りです。

- ユーザーインターフェース (UI): https://alpha.aiscanrobo.netsmile.jp
- API エンドポイント: https://templateless-api-v2.aiscanrobo.netsmile.jp
- Swagger ドキュメント（仕様書）: https://templateless-api-v2.aiscanrobo.netsmile.jp/api-docs
  
  ※UIで確認したい場合は https://petstore.swagger.io/#/ も利用可能です。

2. セットアップ手順

サンプルコードを動かすにはAPIキーが必要です。以下の手順で環境を準備してください。

- Node.jsのインストール システムにNode.jsがインストールされている必要があります（推奨：v22.18.0以降）。公式サイト: https://nodejs.org/en/download/
- APIキーの設定
  - UIからダウンロードした場合: すでにAPIキーが設定された .env ファイルが含まれています。
  - それ以外の場合: 同梱されている .env.sample ファイルを .env という
    名前にコピーし、ファイル内の該当箇所にAPIキーを貼り付けてください。
- 依存関係のインストールと実行 コマンドラインで以下のコマンドを実行します。
  1. インストール: npm install
  2. 実行: npm run dev

3. API利用の基本（認証）

APIを利用するには、APIキーを使って「JWTトークン」を発行する必要があります。

- トークンの発行: POST /sign/apiKey にAPIキーを送信して取得します。
- 有効期限: トークンは1時間有効です。期限切れの場合のみ更新するか、
  API呼び出しのたびに新規取得することも可能です。
- 実装例: apiclient.js 内の getToken 関数を参照してください。

4. ドキュメントのスキャン（読み取り）

このシステムの主な機能は、PDF、JPEG、PNGファイルをアップロードし、
LLM（大規模言語モデル）を使って文字情報を抽出することです。
処理は「非同期」で行われます（リクエスト送信 → 完了待ち → 結果取得）。

スキャンの流れ

1. 1. ファイルを送信し、ドキュメントを作成（IDが発行されます）。
  2. システムがバックグラウンドで処理を行います。
  3. ステータスを確認し、完了するまで待ちます。
  4. 結果を取得します。

3つのスキャン方法

用途に合わせて以下の3つの方法から選択できます。

- - 全ページ一括抽出（推奨）
    ドキュメント全体を1つのデータとして扱います
    （例：複数ページにわたる注文リスト）。
    参照するサンプルコード：src/single-group.js

- - ページごとの個別抽出
    各ページをそれぞれ独立したデータとして扱います
    （例：レシートの束）。
    参照するサンプルコード：src/simple.js
  - カスタムグループ化
    ページを自由にグループ分けして抽出します
    （例：1つのPDF内に複数の契約書が混在している場合）。
    参照するサンプルコード：src/custom-groups.js

5. プロンプト（抽出設定）について

APIでは、UI上の「抽出設定」を「プロンプト」と呼びます。スキャンを行う前に、
UI（https://alpha.aiscanrobo.netsmile.jp/document-type）でプロンプトを作成し、
IDを取得しておく必要があります。

- シンプル設定: 「全ての項目を取得する」のように文章で指示する方法。
- 詳細設定: 項目名や表の列名を具体的に指定する方法。

※初めて処理するフォーマットの場合、最初はUIからアップロードして
　自動識別（プロンプトID: -1）を行ってください。

6. ドキュメント作成APIの詳細

基本的な作成方法（POST /documents）

最も簡単な方法は、POST /documents エンドポイントを使用することです。
これにより、アップロードからスキャン開始までを自動で行います。

主なパラメータ:

- - file: PDFまたは画像ファイル（複数可）
  - origin: asralpha 固定
  - pdfConversionMethod: standard 固定
  - scanMode: llm 固定
  - useOcr: true 推奨（OCR結果をLLMに渡して精度向上）
  - promptId: 使用するプロンプトのID（自動識別の場合は -1）

高度な作成方法（カスタムグループ化など）

複雑な処理を行う場合は、以下の手順でAPIを個別に呼び出します。

- 作成: POST /documents/create
  （枠だけ作成）
- 変換: PATCH /documents/{documentId}/reprocess
  （画像を変換）
- グループ化: PATCH /documents/{documentId}/groups
  （ページとプロンプトの紐付け）
- スキャン開始: POST /documents/{documentId}/scan

7. 結果の確認と取得

ステータスの確認

GET /documents/{documentId} を呼び出し、status が scanned になるまで待ちます（推奨ポーリング間隔：10秒以上）。

データの取得

スキャン完了後、同じく GET /documents/{documentId} で結果を取得できます。レスポンスには以下が含まれます。

- extractedItems: 抽出されたフィールドデータ
- extractedTables: 抽出された表データ

8. データのエクスポート

データをファイルとしてダウンロードする場合、以下の形式が利用可能です。

- 形式: CSV, Excel, JSON
- 出力単位:
  - 結合: 1つのファイルにまとめる
  - グループ別: ZIPファイルで個別にダウンロード

APIエンドポイント:

- 単一ドキュメント: GET /documents/{documentId}/groups/export
- 一括エクスポート: GET /documents/export

9. ドキュメントの検索

GET /documents/search を使用して、過去のドキュメントを検索できます。 ID、名前、ステータス、作成日、タグなど、多様な条件でフィルタリングや並べ替えが可能です。

10. さらに活用する場合（プロンプトAPI）

API経由でプロンプト（抽出設定）の作成・更新・検索も可能です。

- POST /prompts: 新規作成
- GET /prompts/{promptId}: 詳細取得
- GET /prompts/search: 検索

プロンプト作成時には、自由記述の指示（textualCombinedPrompt）や、
具体的な項目指定（fieldsPrompt）を設定できます。

11. API連携 導入ガイド