API 集合

可直接导入 Bruno（推荐）、Postman、Insomnia 或任何兼容的 HTTP 客户端的集合。

选择哪一个？

• Bruno（backend/bruno/external/）-- 100% 覆盖（18 个外部端点）,每次端点变更都更新,在 git 中版本化。开发/测试首选。
• Postman（下方 JSON）-- 21 个请求覆盖 18 个外部端点（PIX Cash-Out 有 3 个变体：密钥、电子邮件、复制粘贴）,加上一个 GET /health 示例（/api/external 命名空间之外的端点,用于可用性探测）。必要时更新静态快照。

下载 Postman

下载 Postman Collection (JSON)

Bruno 集合（推荐）

项目维护一个 Bruno 集合,对 Owem 端点（admin、merchant、external、simulator）实现 100% 覆盖。Bruno 是一个开源、git 友好的 API 客户端（请求是文本中的 .bru 文件）。

访问

集合位于 Owem Pay 仓库的 backend/bruno/：

• admin/ — 来自 Admin Console 面板的请求
• merchant/ — 来自 Merchant portal 的请求
• external/ — External API 的 18 个请求,100% 覆盖暴露在 /api/external/* 下的端点 ← 本文档
• simulator/ — CloudPix Simulator 的请求

每个 External 端点按 1:1 映射到 backend/bruno/external/{namespace}/{operacao}.bru 中的 .bru 文件（例：balance/get.bru、pix/cash-out.bru、transactions/list.bru）。

使用

# 安装 Bruno
# https://www.usebruno.com/downloads

# 克隆或仅复制 external 文件夹
cp -r backend/bruno/external/ ~/minha-colecao-owem/

# 在 Bruno 中打开（File > Open Collection）

Bruno 每次端点更改都更新 — 对于开发/测试环境,优先选择它而不是 Postman 集合。

包含内容

类别	端点
PIX Cash-Out	按密钥、电子邮件、复制粘贴发送（相同端点 POST /pix/cash-out 的 3 个变体）
PIX Cash-In	生成 QR Code（POST /pix/cash-in）
查询	按 ID、E2E、tag、external_id、凭证
对账单	GET /statement
交易	GET /transactions（带过滤器的列表）
余额	GET /balance
PIX 密钥	GET /pix/keys
退款	POST /pix/refund
Webhooks	POST /webhooks、GET /webhooks、DELETE /webhooks/:id
MED	GET /med、GET /med/:id
验证	POST /cpf/validate
Health	GET /health（在 /api/external 之外,可用性探测）

总计：21 个请求覆盖 External API 的 18 个端点 + 1 个 GET /health 探测。

与 router 的对应

规范 router 是 backend/lib/fluxiq_web/routers/external_router.ex。集合与 router 之间的任何差异都应作为集合 bug 报告。

配置

1. 导入 Postman

1. 打开 Postman
2. 点击 Import（左上角）
3. 拖动 JSON 文件或点击 Upload Files
4. "Owem Pay - API Externa" 集合出现在左面板中

2. 配置变量

点击集合 > Variables 选项卡并填写：

变量	值	描述
base_url	https://api.owem.com.br/api/external	API base URL（生产）
client_id	您的 cli_...	API key 的 Client ID
client_secret	您的 sk_...	API key 的 Client Secret

对于 homologacao,使用 https://api-hml.owem.com.br/api/external。

3. 自动 HMAC

集合包含全局的 pre-request script,为所有 POST 请求自动生成 hmac 头（HMAC-SHA512）。该脚本执行 JSON.parse(body) + JSON.stringify(parsed, Object.keys(parsed).sort()) 以保证 body 在计算 HMAC 之前按字母顺序的键序列化 — 这与后端的 Jason.decode + Jason.encode! 归一化匹配。无需手动计算。

HMAC 仅用于 POST

GET 和 DELETE 请求不接收 hmac 头 — 它们没有 body 需要签名。pre-request 脚本自动忽略这些方法。

4. 自动变量

test 脚本自动捕获：

• last_transaction_id — 来自 cash-out 响应
• last_e2e_id — 来自 cash-out 响应
• last_qr_tx_id — 来自 cash-in 响应

这些变量在后续查询中重用。

货币值

注意

Request：以分为单位的值（R$ 1,00 = 100）

Response：以子分为单位的值（R$ 1,00 = 10000）

要将响应转换为雷亚尔：除以 10.000。

建议工作流

1. 余额 — GET /balance 检查可用余额（无速率限制）
2. Cash-In — POST /pix/cash-in 生成 QR Code
3. Cash-Out — POST /pix/cash-out 发送 PIX
4. 查询 — GET /transactions/:id（按内部 ID）或 GET /transactions/e2e/:e2e_id（按 BACEN E2E）跟踪状态
5. 按 external_id 查询 — GET /transactions/ref/:external_id 按系统引用定位
6. 凭证 — GET /transactions/:id/receipt 仅在 status: "settled"（PIX Cash-Out）或填充 paid_at（Cash-In）时可用
7. Webhooks — POST /webhooks 接收状态的异步通知（轮询的建议替代方案）

导入 Insomnia

1. 打开 Insomnia
2. Application > Preferences > Data > Import Data
3. 选择 From File 并选择 JSON
4. 使用上面相同的值配置环境变量