スキャン文書を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枚目とまったく同じ形に収まり、目を通すべきセルは自分で探さなくても名指しで挙がってきます。

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

手順に入る前に、なぜこれが信頼できるのかをお見せします。下のフィールドにマウスを重ねてみてください——文書上の枠が、その値を読み取った正確な位置を示します。ページの印字と一致しなかった値は、そのまま通らずに要確認の印が付きます。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

スキーマを手で組むのが面倒なら、シートビルダーが見本の写真1枚から列を検出し、提案された一覧をその場で修正できます。APIだけで進める場合は POST /ocr/fields の autoFields が同じ役割で、1枚読ませて返ってきたフィールド名をそのまま列に移せます。請求書に特化した内容は、請求書から明細行を抽出するをご覧ください。

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

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

値は整形し直されず、印字の表記のまま返ってきます——7,855 はカンマを保ったまま、全角文字や敬称もそのまま残り、正規化した形で上書きされることもありません。ただしセルに入るのはモデルがページを読んだ結果であり、1文字ずつ同一な複製ではありません。原本と突き合わせるべきセルは、次のステップで印が付いた形で挙がってきます。

4. 要確認のセルを見てからCSVに書き出す

すべてのセルを読み直す必要はありません。各値はページの印字と突き合わせられ、一致しなかったもの、そして必須列が空のように列の規則に引っかかったものが要確認として挙がります。その値だけを開き、写真上で強調された位置と見比べて修正してください。何も付いていないセルはそのままファイルに入ります。API では同じ作業リストが data.review.flagged で、パスごとに reasons が付いています。

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

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

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

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

ダウンロード自体は無料プランと従量課金プランで1クレジット、Starter と Pro では無料です。同じシートの再ダウンロードは無料で、行が増えたときにだけ改めて課金されます。現在の料金は料金ページをご覧ください。

APIで実行する

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

各行の構造は直接呼び出したときと同じです。業務データは values、座標（box と quad）と検証結果（verified、review）は cells[path]、確認すべきパスの一覧は review.flagged にあります。列に number・integer・date を宣言しても values は印字の表記のままで、解釈された値がセルごとに normalized として隣に足されます（POST /ocr/fields を直接呼ぶ場合は data.normalized としてツリーごと返ります）。人が読む列には印字のままの値を、システムが計算する列には正規化された値を入れる、という使い分けができます。

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

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

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

実例：PCの外に何も保存されない一括CSV化

このワークフローそのものを、デモプログラムに参加した外部の開発者が Windows 用の小さなデスクトップアプリとして実装しました。書類の写真とスキャンPDFが入ったフォルダを選ぶと、全ページを POST /ocr/fields で一括読み取りし、要確認の値は原本画像の該当箇所（返却される quad が読み取り元を囲みます）と見比べて修正し、CSVで書き出します。専用サーバーもデータベースもクラウド保存もありません。

この構成の要点は、データの置き場所です。POST /ocr/* はステートレスで、画像を処理して結果を返すだけ——画像も抽出結果もAPI側には保存されません。残るものはすべて利用者のPCの中にあります。元の写真はフォルダに、確認済みの値はアプリに、CSVは保存先に、APIキーは実行ファイルに埋め込まれず利用者自身のプロファイル領域に。PCの外に出るのはAPI呼び出しの一瞬だけで、外には何も残りません。

書類をこれ以上クラウドに預けたくない経理・総務の現場では、「後から削除を依頼する必要があるか」という確認自体が不要になります——そもそもどこにも保管されていないためです。値の使い分けも実務的です。画面には印字のままの値（原本と見比べるのは人だからです）、CSVには正規化された値（取り込んだ先で計算するのはシステムだからです）を出力します。