スキャン文書をCSVに変換する方法

請求書、領収書、納品書——紙の束を、表計算ソフトの行データにしたい。でも手入力は遅いうえにミスも出ますし、汎用OCRツールに通しても、列に整理し直さなければ使えない生テキストの塊が返ってくるだけです。本当にやりたいのは、もっと絞り込まれた、もっと実用的な作業——文書の写真やスキャン画像を、正しい値が正しい列に収まったクリーンなCSVの1行に、毎回確実に変換することです。

このガイドでは、まさにそれを順を追って解説します。列を一度だけ定義し、space-ocr に画像を渡せば、各文書が自動で1行ずつ埋まっていきます。終わったらシート全体をCSVに書き出すだけ——バイトオーダーマーク付きのUTF-8なので、Excel でも日本語・中国語・韓国語のテキストでも文字化けせずに開けます。手入力は不要で、しかもすべての値がページ上のどこにあったかまで辿れます。

ワークフローの全体像

スキャン文書をCSVに変換する流れは、4つのステップに分かれます。

1. 撮影またはスキャン——ラスター画像（JPEG、PNG、TIFFなど）にします。スマホの写真で十分で、傾いた撮影は自動回転で補正されます。
2. 列を一度だけ定義——必要なフィールドに名前を付けます（vendor、date、total、明細行…）。これが、すべての文書を読み取る際のスキーマになります。
3. アップロード——各画像が読み取られ、その値が定義した列の下に新しい行として並びます。文書ごとの設定は不要です。
4. CSVに書き出し——シート全体を <sheetName>.csv としてダウンロードし、どこでも開けます。

メリットは一貫性です。列を最初に固定しておくため、10枚目の領収書も1枚目とまったく同じ形に収まります。

まずは証拠から——すべての値が「出どころ」を知っている

手順に入る前に、なぜこれが信頼できるのかをお見せします。下のフィールドにマウスを重ねてみてください——領収書上のボックスが、その値を読み取った正確な位置を示し、各フィールドにはマッチ比率（match ratio）が付いています。CSVは中身の数字を裏付けられて初めて役に立つもので、ここではどのセルも元のピクセルまで辿れます。

スキャン文書をCSVに変換する手順

1. 文書を画像として取り込む

space-ocr が読み取るのはラスター画像——JPEG、PNG、GIF、BMP、TIFF、WebP です。机の上で領収書を撮る、請求書をPNGにスキャンする、スキャナーアプリからページを書き出す、いずれでも構いません。スキャンPDFもアプリにそのままドロップでき、各ページは自動で画像化されます。斜めから撮ったスマホ写真でも問題ありません。エンジンがEXIFの向き情報を読んで回転を補正するので、横向きの写真も正しい向きで読み取られ、値は正しい位置に紐づきます。

2. 列を一度だけ定義する

OCRをきれいな表に変えるのが、このステップです。CSVヘッダーにしたいフィールドを列スキーマとしてシートを作成します。スカラー列は単一の値（vendor、invoice_date、total）、配列列は繰り返し現れる明細行（line items）を捉えます。これを一度定義しておけば、その後アップロードするすべての文書が同じ列に対して読み取られます。

vendor        (string)
invoice_date  (string)
total         (string)
items         (array) → name, unit_price, qty

スキーマを手で組むのが面倒なら、組み込みテンプレート（invoice、receipt、business_card など）が、よくある文書タイプ向けのフィールドとプロンプトを用意してくれます。請求書に特化した内容は、請求書から明細行を抽出するをご覧ください。

3. アップロード——行は自動で埋まる

列が用意できたら、画像をシートにアップロードします。各文書が1行になり、エンジンがページを読み取って各値を対応する列の下に振り分けます。領収書を20枚入れれば、すべて同じ形の20行が得られます。明細行の配列は、行の構造化された子要素として保持され、書き出し時に展開できる状態になります。

値はそのまま（verbatim）返ってきます——7,855 はカンマを保ったまま、全角文字や敬称もそのまま残ります——ので、CSVは整形し直した推測ではなく、印字されている内容をそのまま映します。

4. CSVに書き出す

書き出しをクリックすると、シートが <sheetName>.csv としてダウンロードされます。ヘッダー行はスキーマからそのまま組み立てられます。

• 先頭の#列（行インデックス）。
• 各スカラー列名をそのまま。
• 各配列の子要素をcolName.childNameとしてフラット化——name と unit_price を持つ items 配列なら、items.name と items.unit_price の列になります。

明細行の配列を含む行はサブ行に展開されます——親のスカラー値は一度だけ表示され、各明細行がその下に自分の行を持つので、8明細の請求書は、1つの取引先と日付の下に8つのCSV行になります。ファイルはバイトオーダーマーク（BOM）付きのUTF-8で書き出され、これによってExcel——そして日本語・韓国語・中国語のテキスト——が文字化けせずに開けます。

セルを手で編集していた場合、書き出しでは手入力した値が元のOCR値より優先されるので、修正がそのままCSVに反映されます。

APIで実行する

同じ流れをヘッドレスでも利用できます。列付きのシートを作成し、そこに画像をアップロードして、GET /view で構造化された行を取得します——サーバー側で処理され、OCRの再実行も課金もありません。あとはCSVを自分で書き出すか、シートのCSVエクスポートを取得します。GET /view では書き出し前にフィルタ（where）、ソート、列の選択もできるので、必要な行だけを送り出せます。

行が入ったら、GET /view がそれらを構造化されたJSONとして返すので、そのままCSVに書き出すことも、会計システムに引き渡すこともできます。抽出エンドポイントとフィールド仕様の詳しい解説は、請求書データ抽出APIガイドとAPIドキュメントをご覧ください。

スキャンPDFと入力形式についての補足

space-ocr のエンジンが扱うのはラスター画像であり、PDFのバイトデータではありません——とはいえアプリではそれを意識する必要はありません。スキャンPDFをドロップすれば、各ページがOCRの前に自動で画像へラスタライズされます。公開APIを直接呼び出す場合にだけ、先に各ページを画像（PNGまたはJPEG）にレンダリングしてアップロードします。目的がCSVではなく特にExcelなら、同じ流れが当てはまります——詳しくはスキャンPDFをExcelに変換するをご覧ください。CSVは最も手間の少ない出力先です。どこでも開けますし、BOM付きUTF-8での書き出しなので、エンコーディングで驚かされることもありません。