凭证金额与换算金额分开保存
报销预览按指定参考日的欧洲央行参考汇率显示等值金额。保留原始凭证金额和币种不变，另外记录换算金额、参考日期与使用汇率，避免用舍入后的显示值覆盖会计证据。
一次业务意图对应一个请求身份
为每笔换算意图生成并保存一个 Idempotency-Key，同时保存输入指纹。参数变化后复用旧键应被拒绝。超时后先查询原请求状态；随手换新键重试可能导致操作重复执行。
周末回退需要明确呈现
星期六的凭证可能使用星期五的参考汇率。界面应同时显示请求日和返回日，再由实际会计规则决定是否接受该回退。不要把星期五的数据重新标成星期六的数据。
舍入留在明确的边界
预览模型保留输入金额、汇率和未舍入的结果。生成会计分录之前，先确定币种适用的十进制舍入规则。示例中的 JavaScript 二进制浮点计算不是账本，也不能用来计算钱包积分。
由一个响应生成预览
下方代码由一个 convert 响应生成预览记录，把原始金额与币种、参考日期和请求日期并列保存。rates 中缺少的币种或出现 stop_reason 时，要展示明确状态，不能填零掩盖问题。
// Example convert response: 100 USD requested for Saturday 2024-01-06 uses the Friday 2024-01-05 reference rate.
const response = { ok: true, data: { from: 'USD', to: 'EUR', amount: 100,
rate: 0.9, result: 90, date: '2024-01-05', requested_date: '2024-01-06' } };
if (!response.ok || !Number.isFinite(response.data.result)) throw new Error('Invalid preview');
const preview = { originalAmount: response.data.amount, originalCurrency: response.data.from,
referenceDate: response.data.date, requestedDate: response.data.requested_date,
indicativeAmount: response.data.result, targetCurrency: response.data.to };
console.log(preview); // Original amount and currency, both dates and the converted amount, kept side by side.
服务端请求模板
以下服务端模板以此 API 的第一个操作为例，演示认证与请求标识。请根据场景选择操作，并在 API 页面查看其当前可用状态与价格。超时后，使用同一个 Idempotency-Key 重发未改变的请求。
网关请求始终使用 POST。
使用文档中的平铺 JSON 对象。字段保留在顶层，不要再包裹一层 body。
# Server-side only. Set ATLAS_API_KEY in your secret manager.
# Set ATLAS_API_ORIGIN to your configured deployment origin.
# Every gateway operation is called with POST.
# Only operations shown as enabled on the API page can be called.
# Generate once per intent; retain the same value on status checks.
REQUEST_ID="$(uuidgen)"
curl --request POST 'https://apigate.vercel.app/api/v1/currency/latest' \
--header "Content-Type: application/json" \
--header "x-api-key: $ATLAS_API_KEY" \
--header "Idempotency-Key: $REQUEST_ID" \
--data '{"base":"EUR","symbols":"USD,GBP,JPY"}'接入检查清单
- API 密钥保存在服务端密钥管理器中，从不发送到浏览器。
- 每个请求携带自己的 Idempotency-Key，并保留到请求得到最终结果为止。
- 集成读取 ok 与 error.code，并按错误码表处理每个错误码。
- 使用原标识检查结果不确定的 POST，绝不盲目更换标识重试。
- 已在 API 页面查看该操作的当前可用状态与价格。