SaaS 企業が海外のクラウドのマーケットプレイス経由の売上について毎月届く英文の支払の明細を読み取り、顧客ごとの売上の台帳と自社の請求の記録との差の一覧を作る

処理の起点を決める

パートナーごとの受付の場所（S3 の接頭辞）に明細が保存されたことを起点にします。 明細はパートナーごとに届く日が違い、月初の数日に集中しますが、全部がそろう日は決まっていません。全部そろってからまとめて読む形にすると、早く届いた明細の差に気づくのが遅れます。 1通ずつ動かします。

保存の場所はパートナーごとに分け、接頭辞からパートナーを決めます。 明細の中の社名は、表記の揺れやロゴの画像で迷うからです。

読み取りを始めるときは、ClientRequestToken にファイルの識別子を入れます。同じトークンで呼び直すと同じ JobId が返るので、同じ明細を二重に読みません。 JobTag にはパートナーのコードを入れます。

入力データを集める

質を決めるのは、請求の記録の「今月の支払の対象か」の列です。 これが無いと、明細に載っていない契約を拾う④の処理が、そもそも何と比べればよいか分かりません。サービスの期間と、パートナーとの支払の取り決め（翌月払いなど）から、この列を請求の記録の側で出しておきます。

返金の承認の記録は、承認した覚えのない返金の行を拾うために持ちます。

データの取得方法を決める

問い（Queries）は、明細の見出しにある値だけに使います。 "What is the statement period?"、"What is the payout currency?"、"What is the total net payout amount?" のような問いです。問いは、ページを指定しないと既定で1ページ目だけに当たります。 支払額の合計は最後のページにあることが多いので、Pages に ["*"] を指定して全ページに当てます。問いは非同期の処理で1ページあたり30個までです。

結果は NextToken で続きを取ります。 1回で返るブロックは最大1,000個で、200行の明細は1回では返りきりません。取りきる前に照合を始めると、後半のページの契約がすべて「明細に無い」になります。 JobId は7日しか有効でないので、取りきった結果はその場で S3 に保存します。

AIへ渡す前に整形する

1. 形式の確認 … PDF・JPEG・PNG・TIFF であることを確かめます。パスワード付きの PDF は読めないので、パートナーに外したものを送ってもらいます
2. サイズとページ数の確認 … 非同期の処理で、PDF は500MBと3,000ページが上限です
3. パートナーと通貨の確定 … 保存の場所からパートナーを決め、ファイル名の決まり（パートナーのコード・期間・通貨）と照らします
4. 列見出しの正規化 … 大文字と小文字、前後の空白、改行の入った見出しをそろえてから、列の対応表に当てます
5. 金額の正規化 … 桁区切りのカンマ、括弧で書かれたマイナス、通貨の記号を外し、数値にそろえます。桁区切りがピリオドの書式のパートナーは、対応表に印を付けておきます
6. 契約の番号の正規化 … 前後の空白とハイフンの有無をそろえます。それ以上は直しません
7. 重複の確認 … 同じパートナー・同じ期間・同じ通貨の明細が既にあれば、差し替えの版かを人に確かめます

5番目を軽く見ないでください。 欧州のパートナーには、1.234,56 のように桁区切りと小数点が逆の書式で明細を出してくるところがあります。そのまま数値にすると、金額が千倍か千分の一になります。 書式はパートナーごとに対応表に書いておき、推測で切り替えません。

6番目で「それ以上は直さない」のは、1文字違いの番号を寄せると、別の顧客の契約に支払が入ったことになるからです。

AIに処理させる

AIにさせるのは、明細の表と見出しの値を読み取って、セルごとの文字と信頼度を返すことだけです。 照合と検算は、Python の決まった処理で行います。

照合で付ける判定は次のとおりです。

2行目がいちばん起きやすい失敗です。 手数料の列だけ読めなかったとき、総額から支払額を引けば手数料が出ます。しかしその瞬間、「手数料が契約の率と合っているか」の検算ができなくなります。 読めなかったセルは読めなかったものとして人に回します。

指示内容を固定する

この構成の読み取りは AWS Textract で、生成AIへの文章の指示はありません。指示にあたるのは、問いの文と、照合の規則の設定です。 パートナーごとの設定の例を示します。

【パートナーの設定】partner_code: P07
statement_prefix: s3://<受付のバケット>/partners/P07/
number_format: "1.234,56"            # 桁区切りがピリオド、小数点がカンマ
negative_format: "parentheses"       # (120.00) はマイナス
currency_from: "query"               # 通貨は問いの答えから取る

【問い（QueriesConfig）】すべて Pages: ["*"]
- Alias: STATEMENT_NO    Text: "What is the statement number?"
- Alias: PERIOD          Text: "What is the statement period?"
- Alias: CURRENCY        Text: "What is the payout currency?"
- Alias: TOTAL_PAYOUT    Text: "What is the total net payout amount?"

【列の対応表】（明細の列見出し → 共通の項目）
"Agreement ID"          → contract_no
"Plan"                  → plan
"Service Period"        → service_period
"Gross Amount"          → gross
"Marketplace Fee"       → fee
"Refund"                → refund
"Withholding Tax"       → tax_withheld
"Net Payout"            → net
上記に無い見出しの列は使わない。必須の列（contract_no、gross、net）が
1つでも見つからない表は、照合せずに明細ごと needs_review にする。

【照合の規則】
- 鍵は contract_no だけ。顧客の名前では照合しない。
- contract_no は前後の空白とハイフンだけをそろえる。近い番号に寄せない。
- 信頼度が 90 未満のセルを含む行は needs_review。値を使って検算しない。
- 手数料の検算は、契約の条件の表の率 × gross。差が許容の幅を超えたら fee_rate_diff。
- fee・refund・tax_withheld のどれかが読めなかったら、gross と net から逆算しない。
- TABLE_SUMMARY の行は契約の行として扱わず、合計の検算にだけ使う。
- 明細の行の net の合計と、問い TOTAL_PAYOUT の答えが合わなければ、
  明細ごと needs_review にする（ページの読み落としを疑う）。
- 請求の記録で今月の支払の対象の契約のうち、どの明細にも無いものを
  not_in_statement として、パートナーごとに並べる。

信頼度の基準の「90」は例です。 最初の1か月は、どの信頼度のセルで誤りが出たかを数えてから決めます。

「明細の合計と行の合計が合わなければ、明細ごと人へ」の規則が、読み落としを止めます。 ページをまたぐ表で1ページ分の行が別の表として返り、対応表に当たらずに落ちても、合計が合わないことで気づけます。 行ごとの照合だけでは、落ちた行は「無かった」ことになります。

出力形式を固定する

次の形のJSONで、明細1通ごとに保存します。

{
  "statement_id": "",
  "partner_code": "P07",
  "marketplace": "",
  "period": { "from": "2026-09-01", "to": "2026-09-30" },
  "currency": "EUR",
  "total_payout": { "value": 0, "confidence": 0 },
  "sum_of_lines": 0,
  "total_check": "ok | mismatch",
  "lines": [
    { "contract_no": "", "plan": "", "service_period": "",
      "gross": 0, "fee": 0, "refund": 0, "tax_withheld": 0, "net": 0,
      "min_confidence": 0,
      "status": "matched | price_diff | fee_rate_diff | period_diff | refund | not_in_records | needs_review",
      "expected": { "gross": 0, "fee": 0, "service_period": "" },
      "source": { "page": 0, "row": 0 } }
  ],
  "not_in_statement": [
    { "contract_no": "", "customer_code": "", "expected_net": 0, "months_missing": 0 }
  ]
}

1つ目の理由は、読み取った値と、比べた先の値を並べて持てることです。 lines の各行に、明細から読んだ値と expected（請求の記録と契約の条件から出した値）を両方入れます。担当者は、差がいくらで、どちらの値が何に基づいているかを、明細を開く前に読めます。

2つ目は、source で明細の該当箇所に戻れることです。 数百行の明細で該当の行を探す時間が、確認の時間の大半を占めがちです。

3つ目は、not_in_statement を行とは別に持つことです。 明細に無い契約は行のどこにも置けないので、別の配列にして、何か月続けて載っていないか（months_missing）を持たせます。 2か月以上続くなら、パートナーの登録の漏れを疑います。

顧客ごとの売上の台帳には、matched の行と人が確かめた行だけを、明細の番号を添えて入れます。

システムへ連携する

会計システムへは書き込みません。 外貨の換算と売上の計上の時期は経理の決まりで決まり、この構成が出すのは、明細と請求の記録の差までです。 書き込みを足すと、読み取りの誤りがそのまま帳簿に入ります。

請求の記録も読むだけです。 違いがどちらの誤りかは、人が確かめてから決めます。

人が確認する

人が開くのは matched 以外の行と、not_in_statement の一覧だけです。 matched の行は、パートナーごとの件数と合計を流し見ます。

1. total_check が mismatch の明細を先に見る … 行の読み落としがある恐れがあります。この明細の行の判定は、合計が合うまで使いません
2. needs_review の行を明細と見比べる … source のページと行を開き、読めなかったセルの値を確かめて入れ直します
3. price_diff と fee_rate_diff の原因を決める … 卸値の改定の反映漏れか、契約の条件の表の誤りかを確かめます
4. refund の行を、返金の承認の記録と照らす … 承認の記録に無い返金は、パートナーへの問い合わせに回します
5. not_in_statement を、続いている月の数で並べて見る … 2か月以上続くものから確かめます
6. 台帳への反映を承認する … 承認したものだけを台帳に入れます

目標は、30通をならして1通24分です。 差のある行は1通あたり数行という想定です。

例外に対処する

3行目から5行目は、どれも「読めなかった」ことが分かる形で止める規則です。 読めた分だけで照合に進めると、読めなかったページの契約がすべて not_in_statement になります。

記録を残す

• 元の明細の PDF と、保存した日時・保存した人・パートナー
• AWS Textract が返した結果の全文（全ページ分、NextToken で取りきったもの）
• 照合に使った、その月の請求の記録の書き出しと、そのときの列の対応表・契約の条件の表
• 行ごとの判定（status、expected、source）と not_in_statement の一覧
• 人が判定を覆した記録 … どの行を、どちらに変え、理由は何か
• パートナーへの問い合わせの日時と、回答・修正された明細との対応

3つ目で「そのときの表」を残すのは、表が後から変わるためです。 契約の条件の表の率を直すと、過去の月の fee_rate_diff の意味が変わります。当時の表が残っていないと、どの月まで遡って直すかが決まりません。