> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloclever.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 精算レポート

> Hello Clever の精算レポートが生成される仕組み、ファイルの各列の内容、レポートを自社の台帳と照合する方法を説明します。

精算は、[Payments Account](/ja/platform-overview/clever-concepts/payments-accounts) の利用可能な資金を、自社の Treasury Account のいずれか、または指定した外部の銀行口座へ移動します。Hello Clever はこれらの精算について定期的にレポートを作成します。アカウントで有効にしたレポートの頻度ごとに、その期間の精算をまとめた**精算レポート**を生成します。

これは、以前メールで送られていたものと同じレポートを API から取得するものです。期間内に生成されたレポートを一覧で取得すると、各項目からファイルへのリンクが得られます。ファイルは一度生成されると変わらないため、先月照合した数値は来年読み直しても同じです。

## レポートの流れ

<Steps>
  <Step title="Hello Clever がレポートを生成する">
    日次の精算処理の後、アカウントで設定したタイムゾーンの 09:00 にレポートが生成されます。有効にした頻度ごと、通貨ごとに1件です。
  </Step>

  <Step title="生成されたレポートを一覧で取得する">
    `from_date` と `to_date` を指定して [Get Settlement Reports](/api/reporting/get-settlement-reports) を呼び出します。返されるのはメタデータのみです。ファイル名、対象期間、期間の合計を含む `summary` オブジェクト、`file_url` が含まれます。ファイルの中身は転送されません。
  </Step>

  <Step title="リンクからファイルを取得する">
    `file_url` がファイルそのものです。これに対して通常の `GET` を送ると、レスポンスが CSV になります。リンクは署名付きなので `app-id` や `secret-key` は含まれず、2回目の API 呼び出しも必要ありません。
  </Step>
</Steps>

```bash レポートのファイルを取得する theme={null}
# 1. 期間内に生成されたレポートを一覧で取得する
curl "https://api.lightningpay.me/api/v2/reports/settlements?from_date=2026-09-01T00:00:00Z&to_date=2026-09-30T00:00:00Z" \
  -H "app-id: your-app-id" \
  -H "secret-key: your-secret-key"

# 2. 任意の項目の file_url に GET を送る。認証ヘッダーは不要
curl "https://cdn-private.helloclever.co/hellocleverweb-prod/clever/sections/report/9f3c1ab2-...?sv=2021-08-06&sr=b&sp=r&sig=..." \
  -o settlement.csv
```

## レポートの頻度

レポートは、アカウントで有効にした頻度ごとに、アカウントで設定したタイムゾーンで生成されます。

| `report_frequency` | 対象期間                 | 生成のタイミング     |
| ------------------ | -------------------- | ------------ |
| `daily`            | 生成日の 09:00 までの 24 時間 | 毎日 09:00     |
| `weekly`           | 生成日の 09:00 までの 7 日間  | 毎週月曜日の 09:00 |
| `monthly`          | 生成日の 09:00 までの1か月    | 毎月1日の 09:00  |

<Note>
  頻度が異なるレポートの間では期間が重なります。日次と月次のレポートを両方有効にしている場合、9 月 14 日の精算は 9 月 14 日の日次レポートに含まれ、10 月 1 日に生成される月次レポートにも再び含まれます。各精算を台帳に一度だけ計上するため、`report_frequency` で絞り込んでください。
</Note>

<Warning>
  日次レポートの対象は、アカウントのタイムゾーンの 09:00 から 09:00 までです。0 時から 0 時までではありません。会計期間が暦日の場合、各日の最後の数時間は翌日のレポートに含まれます。
</Warning>

## ファイルの形式

| 項目       | 値                                                                                      |
| -------- | -------------------------------------------------------------------------------------- |
| 形式       | CSV（カンマ区切り、ヘッダー行あり）                                                                    |
| エンコーディング | UTF-8                                                                                  |
| 金額       | 通貨の主単位。資金が残高から出ていく場合は `-` が付きます                                                        |
| タイムスタンプ  | `Date` は `YYYY-MM-DD hh:mm:ss +hhmm`、`Settlement at` は `YYYY-MM-DD hh:mm:ss GMT+hh:mm` |
| 命名規則     | `<Frequency> Report (<CURRENCY>) (<period start> - <period end>).csv`                  |

ファイル名には空白と括弧が含まれます。たとえば `Daily Report (AUD) (Sep 06, 2026 - Sep 07, 2026).csv` です。パスに使う場合は URL エンコードしてください。

## 列

各行は、期間に含まれる1件の精算を表します。

| 列                        | 説明                                                                                                                               |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `Balance ID`             | この精算によって生じた残高の動きに対する Hello Clever の ID。[Get Balance History V2](/api/balance/get-balance-history-v2) に渡すと、残高のタイムラインでその動きを確認できます。 |
| `Account Nickname`       | 資金の精算元となった Payments Account。Merchant Portal で設定したニックネームで表示されます。                                                                  |
| `Merchant name`          | 登録済みの事業者名。                                                                                                                       |
| `Reference`              | 精算の参照番号。Merchant Portal に表示される参照番号と一致します。銀行の取引明細と照合する際のキーとして使ってください。                                                             |
| `Status`                 | レポートが生成された時点での精算のステータス。                                                                                                          |
| `Currency`               | 精算された資金の通貨。1つのファイルは1つの通貨を対象とします。                                                                                                 |
| `Payment method`         | 受取人への精算の送金方法。                                                                                                                    |
| `Date`                   | 精算が作成された日時。                                                                                                                      |
| `Settlement at`          | 精算が完了した日時。完了するまでは空です。                                                                                                            |
| `Type`                   | 動きの種別。精算レポートでは常に `settlement` です。                                                                                                |
| `Amount`                 | 精算された金額。資金が残高から出ていくため `-` が付きます。                                                                                                 |
| `Fee amount`             | 精算に対して請求された手数料。                                                                                                                  |
| `External ID (Order ID)` | 元のリクエストで渡した自社の参照番号。自社の記録と行を照合する際に結合に使う列です。                                                                                       |

ファイルは次のようになります。

```csv Daily Report (AUD) (Sep 06, 2026 - Sep 07, 2026).csv theme={null}
Balance ID,Account Nickname,Merchant name,Reference,Status,Currency,Payment method,Date,Settlement at,Type,Amount,Fee amount,External ID (Order ID)
BL8KMRVX,HC Payments AUD,Demo Store Pty Ltd,BAL_cqxDHqDOSs8,done,AUD,bsb,2026-09-06 23:41:08 +0000,2026-09-07 01:12:44 GMT+00:00,settlement,-4205.00,2.34,SETTLE-10241
BL2QBYTF,HC Payments AUD,Demo Store Pty Ltd,BAL_bnwCGpCNRr7,done,AUD,payid,2026-09-05 23:14:02 +0000,2026-09-05 23:51:20 GMT+00:00,settlement,-1180.00,0.85,SETTLE-10238
```

<Tip>
  期間の合計を出すためにファイルを開く必要はありません。一覧の項目にある `summary` オブジェクトに、これらの数値がすでに含まれています。その内訳となる精算ごとの詳細が必要なときにファイルを取得してください。
</Tip>

## `summary` オブジェクト

`summary` は、レポートの対象期間を表します。すべての数値はファイルの行から算出され、ファイルと同じ方法で通貨の精度に丸められるため、両者は常に一致します。

| 項目                   | 意味                                                    |
| -------------------- | ----------------------------------------------------- |
| `settlement_count`   | 期間内の精算の件数。ヘッダーを除いたファイルの行数です                           |
| `settled_amount`     | 期間内に精算された合計額。正の値です。ファイルの `Amount` 列には同じ値が `-` 付きで入ります |
| `settled_fee`        | ファイルの `Fee amount` 列の合計                               |
| `closing_balance`    | 期間内の最後の精算の直後の残高                                       |
| `closing_balance_at` | 台帳がその残高を記録した日時。アカウントで設定したタイムゾーンで表されます                 |

`closing_balance` は、期間内の最後の精算に対して台帳自体が記録した残高です。ファイルから計算した数値ではありません。

<Note>
  期間内の精算のいずれにも、台帳が記録した残高がまだない場合、`closing_balance` と `closing_balance_at` は `null` になります。他の3つの数値は常に含まれます。
</Note>

<Tip>
  期間終了時点の数値ではなく現在の残高が必要な場合は、[Get Balance Details V2](/api/balance/get-balance-details-v2) を呼び出してください。Reporting API は、意図的に締めた期間のみを対象としています。
</Tip>

## リンクの有効期限

`file_url` はレポートを一覧で取得したときに発行され、3 分間有効です。

<Warning>
  リンクを自社のデータベースに保存したり、後で実行するバックグラウンドのジョブに渡したりしないでください。レポートの `id` を保持し、レポートを再度一覧で取得して新しいリンクを受け取ってください。返された項目ごとにリンクが発行されるため、その処理で取得する分だけの `size` を指定してください。
</Warning>

<Note>
  リンクには独自の署名が含まれるため、リンクを持っていれば誰でも有効期限までファイルを読めます。ファイルの内容そのものと同様に扱い、ログに記録されたり共有されたりする URL には決して含めないでください。
</Note>

## 期間の照合

<Steps>
  <Step title="期間のレポートを取得する">
    締める期間を指定して [Get Settlement Reports](/api/reporting/get-settlement-reports) を呼び出します。頻度の重なりによる二重計上を防ぐため、`report_frequency` で絞り込んでください。範囲は生成日時に対して適用されるため、期間の始まりを含むレポートを取りこぼさないよう、範囲を1期間分広げてください。
  </Step>

  <Step title="各ファイルを取得する">
    リンクが有効なうちに同じ処理の中で各項目の `file_url` に `GET` を送り、`has_more` が `false` になるまでページを進めます。
  </Step>

  <Step title="銀行の取引明細の入金と照合する">
    `Reference` をキーとして、`Amount` から `Fee amount` を差し引いた金額と照合します。1つの参照番号は1件の入金に対応し、期間の合計は `summary.settled_amount` と `summary.settled_fee` です。
  </Step>

  <Step title="一致しないものを追跡する">
    `Balance ID` を [Get Balance History V2](/api/balance/get-balance-history-v2) に渡すと、残高のタイムラインでその精算を確認できます。精算元の残高を構成した決済、返金、手数料も併せて表示されます。
  </Step>
</Steps>

<Tip>
  夜間のジョブでは、実行をまたいでカーソルを追跡するのではなく、固定の範囲（たとえば UTC で直前の丸2日間を `report_frequency=daily` で絞り込んだもの）を照会してください。範囲が重なっても二重に計上されないよう、レポートの `id` で重複を排除してください。
</Tip>

## Payments Account

1つのレポートは、1つの通貨について、期間内に精算を行った Payments Account 全体の精算を対象とします。ファイルの `Account Nickname` 列で各精算の精算元のアカウントがわかるため、複数のアカウントにまたがるレポートでも、自社の側でアカウントごとに分けられます。

現時点では、1つの Payments Account のみを対象とするレポートを要求する方法はありません。必要な場合はお問い合わせください。各モデルでアカウントが残高を保持する仕組みは、[残高モデル](/ja/platform-overview/clever-concepts/balance-models)を参照してください。


## Related topics

- [Reporting API の概要](/ja/api/reporting/overview.md)
- [Hello Clever API の概要](/ja/api/overview.md)
- [Hello Clever 開発者ドキュメント](/ja/index.md)