Skip to main content

印尼地区 API 文档 — 编写与展示规范（维护说明）

smilepayz teamsAbout 5 min

印尼地区 API 文档 — 编写与展示规范（维护说明）

面向维护者：编辑 docs/**/reference/indonesia/** 下内容时，请按本文与 英文 Pay-In 范本 对齐，以便 VuePress 客户端增强 与 样式 正确生效。

一、目标与原则

  • 易扫：文首短段 + 清晰标题层级；参数表四列、描述短句；支付方式枚举表描述控制在约两行。
  • 易复制：HTTP 接口四列表「字段名」、支付方式三列表「Method 码」均可点击复制（行为见下文）。
  • 多语言一致：en / id / zh / th 目录层级相同，相对路径 ../ 段数一致；表格列名与 EN 对齐时，增强逻辑最稳定。
  • 侧栏可读：title（frontmatter）侧栏展示，宜「有语义、不过分冗长」，各语言可本地化。

二、全局能力（仓库已实现，非单页重复配置）

能力文件说明
四列表增强.vuepress/client.ts识别 4 列表头 Field | Required | Type | Description：子字段树线、Required 列 M/O/C 替换为 required/optional/condition、首列 code 点击复制、路由/DOM 更新后重绑。
支付方式三列表同上识别 3 列「Method / Type / Description」及 中文「方式 | 类型 | 描述」、泰文「วิธี | ประเภท | คำอธิบาย」：表加 class pm-method-table，首列包成 code.pm-method-chip，点击复制 method 字符串（交互与四列表类似：悬停后点击 / 触屏可直接点 / Enter·Space）。
表格与芯片样式.vuepress/styles/index.scss四列表：必填橙、可选/条件灰、首列蓝系 chip。apifox-endpoint-bar：POST 橙色字 + path 等宽继承正文色。pm-method-chip：中性灰字与浅灰底，悬停略加深。暗色主题均有对应覆盖。
Vite 依赖.vuepress/config.tsresolve.dedupe：vue、vue-router、@vuepress/client，减轻文档路由与主题组合时的 provider 问题。
Sass 补丁patches/[email protected]color.whiteness → color.channel，兼容新版 Dart Sass。

三、HTTP 接口页（transaction/、inquiry/）

范本：docs/en/reference/indonesia/transaction/payin.md。已对齐全套的文件：payin、payout、inquiryBalance、inquiryAccount、inquiryStatus（各语言同路径）。

3.1 文首

  • Frontmatter 之后 先写一段简短说明（能力 + 印尼场景/关键条件），不要一上来就是 ### Request 加长表。
  • 文风：去掉「The xxx API returns…」类套话，改为短句或分号式（与现网 inquiryStatus 等页一致）。

3.2 Endpoint 条（apifox-endpoint-bar）

  • 位置：紧跟在 ### Request 标题下面，在 #### Request Path: 之前（已从「文首后」调整到此，避免抢在章节标题前）。
  • HTML 模板（替换 METHOD、apifox-method--post|get、PATH）：
<div class="apifox-endpoint-bar" role="group" aria-label="HTTP endpoint"><span class="apifox-method apifox-method--post">POST</span><code class="apifox-path">/v2.0/your-path</code></div>
  • apifox-method--post / apifox-method--get 为小写 class；apifox-path 内为 相对 path（如 /v2.0/transaction/pay-in）。

3.3 章节顺序

  1. ### Request
  2. Endpoint 条（上）
  3. #### Request Path: — sandbox / production 两行引用块 URL
  4. #### Header Parameters — 四列表
  5. #### Body Parameters — 四列表
  6. 可选 --- 后 #### Example … + ::: tabs（@tab Header 内仅请求头，不要 POST https://… HTTP/1.1 首行）
  7. ### Responses（复数，不用 ### Response）
  8. 若有回调：### Notification/Callback → 表 → #### Return → :::info + tabs

3.4 四列表（触发 client 增强的硬条件）

  • 表头 恰好 4 列，且语义为：
| Field        | Required | Type   | Description |
  • Field：行内 `code`；子字段：&nbsp;&nbsp;&nbsp;&nbsp; + `fieldName`（与 Pay-In 一致）。
  • Required：只写 M / O / C（由 client 换成英文标签并上色）。
  • Description：单行优先；必要时 `字面量`、加粗；避免长 <br> 堆砌。

3.5 链接深度

从 docs/{locale}/reference/indonesia/transaction/ 到产品文档示例：../../../product/overview/signature.md、../../../product/dataModel/merchant.md。inquiry/ 下同样用 ../../../product/...。换 locale 不改变 ../ 层数。

3.6 已知纠错点

  • inquiryAccount：示例与 path 必须为 /v2.0/inquiry-account（sandbox/production），勿与 inquiry-balance 混用。

四、侧栏标题（title）

  • 侧栏文案来自各页 frontmatter 的 title。
  • 建议：有区分度、约一行；例如 Pay-In / Pay-Out 用「收款（Pay-In）」「代付／付款（Pay-Out）」等；Inquiry 子项用「交易状态查询」「账户余额查询」等，避免五个单词一排（Status / Balance 过简）或「API INQUIRY XXX」过长。
  • 各语言可本地化；结算 / 支付方式 菜单已用句子大小写或中文短名，与全大写枚举区分。

五、支付方式页（method/paymentMethod.md）

5.1 与 HTTP 接口页的差异

  • 不要求 apifox-endpoint-bar，不要求四列表。
  • 使用 三列表：英文 Method | Type | Description；中文 方式 | 类型 | 描述；泰文 วิธี | ประเภท | คำอธิบาย。

5.2 文案与结构（已优化基线）

  • Supported 小节：说明 Logo 仅供参考，Method/方式/วิธี 列 = 请求里的 paymentMethod。
  • Pay-In：表前一句话说明「仅收款、Type 为 String」；描述列约两行（<br>）：上行产品/机构要点，下行结算与凭证（VA、账号、手机号/QR、时效等）；Mandiri 保留 FAQ 链接。
  • Pay-Out：描述由脚本批量压为两行（上行机构名截断在第一个 - 前 + 语境后缀；下行统一「收款方银行账号/钱包标识 · 即时」类说明）。若从上游贴回长版，可重新跑脚本（见下）。

5.3 维护脚本（可选）

从长描述恢复为两行 Pay-Out 时，可在仓库根目录执行：

node scripts/shorten-payout-descriptions.mjs docs/en/reference/indonesia/method/paymentMethod.md

对 id（英文表）、zh、th 同理替换路径。脚本会识别 ## Pay-Out、## 付款交易方式 等标题进入 Pay-Out 表区间。

六、适用范围与例外

路径建议
transaction/payin.md、payout.md按第三节全文。
inquiry/*.md同上。
method/paymentMethod.md按第五节；首列 method 自动可复制 + 灰 chip。
method/paymentFlow.md流程说明为主，不强制三列表规范。
settlement/*.md叙述/SLA 为主，不强制 endpoint 条与四列表。

七、合并前自检清单

八、参考文件索引

用途路径
HTTP 范本en/…/transaction/payin.md
代付en/…/transaction/payout.md
查询类en/…/inquiry/
支付方式en/…/method/paymentMethod.md
其他地区（版式说明）泰国、印度、菲律宾、越南、墨西哥、巴西、智利、哥伦比亚、秘鲁

本文随印尼区文档迭代更新；若新增全局行为，请同步改 第二节 与 client / scss 说明。