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

# 收据配置与下载

> 面向客户的收据端到端如何工作：客户下载时选择什么（语言、用于报销的公司名称，以及为什么只能设置一次）、你可以在 Portal 中配置什么、配置变更是否影响过去的交易、收据 URL，以及你的配置无法触及的交易。

本页把收据当作一份文件来讨论：客户下载时看到什么，以及你对其内容能控制什么。
从交易查看和邮件发送收据，以及该邮件的投递状态，由《收据：查看、发送与配置》页面覆盖。

## 客户下载收据时要选择什么？

无论从哪个入口进入，客户都会落到同一个收据页面并看到同一个对话框：

| 选项 | 行为 |
| - | - |
| **语言** | 始终提供英语并预选。如果订单自身的语言不是英语，它会作为第二个选项提供并同样预选。至少必须保留一种语言被选中 |
| **公司名称** | 每种已选语言下的可选自由文本——应出现在收据上的名称，通常用于报销 |

同时选择两种语言会在一次操作中下载**两份收据**。公司名称按语言输入，因为一家公司的
英文法定名称和本地语言名称通常不是同一个字符串。

公司名称字段只在带有该区块的收据上出现。如果客户看不到它，说明该交易的收据不支持它。

## 为什么客户无法更正他们输入的公司名称？

因为公司名称**一经提交即按语言锁定**。这是有意为之：收据是会计文件，让同一笔交易生成
两份带有两个不同抬头名称的收据，正是收据本应消除的歧义。

完整规则：

| 操作 | 结果 |
| - | - |
| 某语言的首次提交 | 接受并存储 |
| 同一语言，再次提交**相同**的值 | 成功，无变化——可以安全重试 |
| 同一语言，**不同**的值 | 拒绝：`008001B115`——"Receipt company name has already been submitted and cannot be changed. Please download the receipt with the submitted name." |
| **另一种**语言，首次 | 接受——各语言相互独立 |

一旦某语言已有存储的名称，就不再为它提供输入框：下载直接使用存储的值。

名称绑定到**那笔订单和那种语言**。新订单从空白开始，不会从同一客户之前的购买继承任何
东西——所以需要更正名称的客户需要一笔新交易，而不是一次新下载。

对值的校验：

| 规则 | 限制 |
| - | - |
| 最大长度 | **200 个字符** |
| 首尾空格 | 存储前去除 |
| 不允许 | `<` 和 `>`，以及控制字符 |

## 我客户手里的收据链接打不开。有效的链接形态是什么？

存在两种形态，且都在线：

| 形态 | 是什么 |
| - | - |
| `/receipts/form?orderKey=…&locale=…` | 中间收据页面——语言和公司名称对话框，然后下载 |
| `/receipts/{orderKey}.pdf?locale=…&tz=…` | 收据文件本身 |

中间页面在三种情况下拒绝打开，消息会说明是哪一种：缺少订单 key、订单不处于成功状态，
或该交易没有收据。`008001B116`——"Receipt link expired"——意味着链接已超过其有效窗口；
请从 Portal 或订单查询响应重新获取一个。

## 关于收据内容我能配置什么？

在商户 Portal 中打开 **Settings → Receipt Configuration**。可配置的区块：

| 区块 | 字段 |
| - | - |
| **Receipt header** | 文件标题、商户展示名称、商户 logo |
| **Billed to (customer info)** | 显示客户姓名（开/关）、显示客户邮箱（开/关）——值本身来自交易，无法编辑 |
| **From (service entity)** | 主体名称、税号、地址 |
| **Footer & support** | 支持文案、支持网站 |

字段规则：

| 字段 | 规则 |
| - | - |
| 文件标题 | 最多 **50 个字符**。`<` 和 `>` 会被拒绝。为空时回退为 `Receipt`。这就是你得到 `Tax Invoice`、`Invoice`、`Order Confirmation` 等的方式 |
| 其他所有文本字段 | 最多 **128 个字符**。空字段在收据上**隐藏**，而不是渲染为空白 |
| 支持网站 | 插入到支持文案中的 `{website}` 占位符处 |
| 商户 logo | 留空则隐藏 logo |
| **Receipt Enabled** | 按模板：使用该模板的交易是否生成收据 |

费用行和订阅信息在适用于该交易时由系统渲染。你既不能添加也不能抑制它们。

编辑支持对单个字段 **Reset** 以及对整个模板 **Restore all defaults**；两者都仍需
**Save** 才能生效。

## 如果我更改配置，会改变过去交易的收据吗？

**会——这是保存前唯一需要内化的事情。** 配置没有按交易的快照。Portal 在两处说明了这一点，
确认对话框也明确写出：更改立即生效，并影响**所有历史和未来交易**的收据显示。

实际上：上个月下载过收据的客户，在你更改后再次下载，会得到一份带有新标题、主体信息和
logo 的文件。如果过去的收据必须保持与出具时完全一致，你需要自己保留一份副本——
Waffo 不会为你做版本管理。

## 我可以有多个收据版式吗？

可以，以**模板**的形式：

| 规则 | 详情 |
| - | - |
| 多个模板 | 每个显示为自己的 Tab，命名为 `Template 1`、`Template 2`、… |
| 恰好一个默认 | 默认模板带有标记，并且**不能删除** |
| 添加模板 | **Add Template** 完整复制当前默认模板，然后你编辑副本 |
| 更改默认 | 需要确认。没有指定模板的交易使用默认模板 |
| 删除模板 | 需要确认。正在使用它的交易回退到**默认**模板 |
| 按订单选择 | 在创建订单时传 `paymentInfo.receiptTemplateId` |

编辑默认模板**不会**传播到其他模板——它们是副本，不是引用。

如果你从未配置过任何东西，页面会打开一个预填的单一模板，收据尚未启用。

## 我需要 Waffo 审核我的收据配置吗？

不需要。它是自助的，保存即生效，没有审批步骤。有两件事会阻碍保存：

| 拒绝 | 含义 |
| - | - |
| 版本冲突（`008001B126`） | 在你编辑期间有其他人保存了同一配置。刷新并重新应用——后来的保存会被拒绝，而不是静默覆盖 |
| 标题错误（`008001B129` / `008001B130`） | 标题太长，或包含不允许的字符 |
| `008001B128` | 试图删除默认模板 |
| `008001B127` | 模板已不存在 |

每次更改都会被记录。页面的 **Change history** 按模板、最新优先显示谁在何时更改了什么，
包括创建 / 更新 / 设为默认 / 删除事件，表单上方的卡片显示最后的操作人和时间戳。

## 有什么是我的配置无法改变的吗？

有，而且这是一条硬边界，不是一个设置。

已经按 Waffo 自身规则生成收据的交易——出于合规原因出具的收据，以及因 Waffo 是该笔支付
的记录方而出具的收据——**始终**遵循那些规则。你的配置不适用于它们，你也无法用
**Receipt Enabled** 开关关闭那些收据。Portal 在配置页面本身说明了这一点。

你的配置管辖的是另一个方向：原本不会生成收据的交易。这就是启用模板所做的事。

## 为什么某笔交易完全没有收据？

收据只在以下条件全部成立时才存在：支付到达了**成功**状态、经过了 Waffo 收银台会话，
并且收据适用于该交易——要么按 Waffo 自身规则，要么因为你启用了模板。这些都不成立时，
交易详情页会完全隐藏收据区块，针对该订单的邮件请求会以 `RECEIPT_NOT_ENABLED` 被拒绝。

## 收据文件是什么语言？

收据页面始终提供**英语**，以及**订单自身的语言**（当它不是英语时）。该语言由系统根据订单
确定，不由你配置，也不能在每次下载时选择——只能从提供的选项中挑选。当前支持的收据语言：
English、Português、Español、繁體中文、简体中文、Tiếng Việt、ไทย、Bahasa Indonesia、日本語、
한국어、Bahasa Melayu、Polski、Türkçe。

## 收据上的数量显示 1，但客户买了三件。为什么？

因为收据只在订单明确携带大于 1 的数量时才显示真实数量。如果订单没有携带数量、携带了
无法解析的值，或携带的值为 1 或更小，收据显示 **1**。

如果数量对你的收据很重要，请在订单上发送它——事后无法设置，也没有对应的配置开关。

## 我能知道某份收据是由哪个模板生成的吗？

可以。订单和订阅的支付信息以 `receiptTemplateId` 报告所应用的配置，配置页面在每个 Tab 上
显示模板 ID。当收据看起来不像你预期的样子时，这一对信息就是要引用的：它告诉你该交易是否
使用了你以为的模板，还是回退到了默认模板。

## 我可以在保存前预览收据吗？

可以。配置页面在表单旁边渲染一个实时 A4 预览，由固定的示例交易数据驱动，带有产品类型
（一次性 / 订阅）、是否有费用行，以及卡与其他支付方式的切换。预览仅为示例数据：
它不意味着配置已生效，也永远不会发送邮件。

***

只是某一笔特定交易的收据内容有误，而不是全部？
请附上订单 ID 和配置 Tab 上显示的模板 ID
[联系客服](mailto:support@waffo.com)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.