# 对账 (/zh/docs/pix-processamento/tutoriais/reconciliation)

<QuickLinks>
  <QuickLink href="/docs/pix-processamento/endpoints/reports/get_user_transactions" title="GET /user/transactions" method="GET" path="/user/transactions" />

  <QuickLink href="/docs/pix-processamento/endpoints/reports/post_user_report" title="POST /user/report" method="POST" path="/user/report" />

  <QuickLink href="/docs/pix-processamento/best-practices/pagination" title="分页" />

  <QuickLink href="/docs/pix-processamento/best-practices/multi-tenant" title="多租户" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;小周期&#x22;] --> B[&#x22;GET /user/transactions&#x22;]
  A2[&#x22;大周期&#x22;] --> C[&#x22;POST /user/report&#x22;]
  C --> D[&#x22;GET /user/report/{id}&#x22;]
  D --> E[&#x22;POST /user/report/{id}/download&#x22;]
  B --> F[&#x22;与您的数据库交叉核对&#x22;]
  E --> F
  F --> G[&#x22;告警差异&#x22;]

  click B &#x22;/zh/docs/pix-processamento/endpoints/reports/get_user_transactions&#x22; &#x22;GET /user/transactions&#x22;
  click C &#x22;/zh/docs/pix-processamento/endpoints/reports/post_user_report&#x22; &#x22;POST /user/report&#x22;
  click D &#x22;/zh/docs/pix-processamento/endpoints/reports/get_user_report&#x22; &#x22;GET /user/report/{id}&#x22;
  click E &#x22;/zh/docs/pix-processamento/endpoints/reports/download_user_report&#x22; &#x22;下载&#x22;

  style B fill:#14ce71,stroke:#0eb464,color:#ffffff
  style C fill:#3b82f6,stroke:#1d4ed8,color:#ffffff
  style F fill:#f59e0b,stroke:#d97706,color:#ffffff
`"
/>

## 实时列表 [#实时列表]

用于实时查看交易（仪表盘、前一日对账）：

```bash
curl "https://api.payzu.processamento.com/v1/user/transactions?dateFrom=2025-08-01&dateTo=2025-08-31&page=1&limit=100" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

筛选参数详情见 [`GET /user/transactions`](/docs/pix-processamento/endpoints/reports/get_user_transactions)。

列表筛选参数（`clientReference`、`status`、`type`、`dateFrom`/`dateTo` 时间窗口、`endToEndId`、`document`/`name`、`virtualAccount`）记录于 [分页 · 可用筛选参数](/docs/pix-processamento/best-practices/pagination#可用过滤器)。

### 单笔交易详情 [#单笔交易详情]

```bash
curl "https://api.payzu.processamento.com/v1/user/transactions/PAYZU2025..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

Schema 见 [`GET /user/transactions/{id}`](/docs/pix-processamento/endpoints/reports/get_user_transaction_by_id)。

## 异步报表 [#异步报表]

对于大时间窗口（月度、年度），使用三步流程。

<Steps>
  <Step>
    ### 请求生成 [#请求生成]

    [`POST /user/report`](/docs/pix-processamento/endpoints/reports/post_user_report)。

    ```bash
    curl -X POST https://api.payzu.processamento.com/v1/user/report \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "dateFrom": "2025-01-01",
        "dateTo": "2025-12-31",
        "status": ["COMPLETED"],
        "type": ["DEPOSIT", "WITHDRAW"]
      }'
    ```

    响应中包含任务的 `id`。
  </Step>

  <Step>
    ### 跟踪状态 [#跟踪状态]

    [`GET /user/report/{id}`](/docs/pix-processamento/endpoints/reports/get_user_report)。

    ```bash
    curl "https://api.payzu.processamento.com/v1/user/report/JOB_ID" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Step>

  <Step>
    ### 就绪后下载 [#就绪后下载]

    [`POST /user/report/{id}/download`](/docs/pix-processamento/endpoints/reports/download_user_report) 返回一个短时效的签名 URL，用于下载 CSV。

    ```bash
    curl -X POST "https://api.payzu.processamento.com/v1/user/report/JOB_ID/download" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json"
    ```
  </Step>
</Steps>

## 推荐策略 [#推荐策略]

1. **使用 `clientReference` 标识每笔 Pix 收款/付款**，这是您自己的标识符，不要仅依赖 PayZu 的 `id`。
2. **以 callback 作为主要数据源**，不要轮询。
3. **通过报表进行每日对账**：拉取前一日的 CSV，与您的数据库交叉核对。可检测到丢失的 callback。
4. **保存 `endToEndId`**，在发生争议时便于在 Bacen 追踪。
5. **按 `createdAt` 或 `paidAt` 排序**，绝不要按 `id` 排序。`id` 是不透明的，其中携带的日期片段精度仅到天，因此无法对同一天的两笔交易进行排序。

## 余额 [#余额]

在发起付款前查询可用余额：

```bash
curl https://api.payzu.processamento.com/v1/user/balance \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

参见 [`GET /user/balance`](/docs/pix-processamento/endpoints/account/get_user_balance)。