幂等性与分页
幂等性 #
没有用于幂等性的请求头：键就是路径中的 id。txid、idEnvio 和子账户的 id 由您生成，长度为 26 至 35 位字母数字字符；退款的 id 也由您生成，长度为 1 至 35 位。请在调用前生成一个 ULID 并保存。
| 情形 | 响应 |
|---|---|
| 新的 id | 201 和创建的资源。 |
| 相同 id，相同正文 | 200、同一资源和响应头 x-replayed: true。 |
| 相同 id，不同正文 | 识别该请求的字段发生变化时返回 409（txid_duplicado、id_envio_duplicado、id_duplicado）：收款为金额、债务人、ex.subconta 和 ex.splitConfig；提现为金额、tipo、收款人证件号、subconta、exigirAprovacao，以及是否带有 validadeSegundos；退款和子账户为任意字段。其他字段不同时返回 200 和已记录的资源，不做修改。 |
超时或出现 5xx 后，请按 id 查询资源。如果资源存在，就以它为准继续。如果返回 404，请用同一个 id 重复调用。在不知道上一次结果之前，绝不要生成新的 id：用另一个 idEnvio 重复的提现会付款两次。
分页 #
分页的列表（收款、退款、提现、交易、当日对账单和 webhook 投递记录）使用不透明的游标。
{
"cobrancas": [],
"cursor": { "proximo": "MTc4OTcyMzIyMzc2NzE1NH5DT0Iw...", "temMais": true }
}
| 字段 | 说明 |
|---|---|
cursor.temMais |
只要还有下一页就为 true。请依据它判断，而不是列表的长度。 |
cursor.proximo |
传入 ?cursor= 获取下一页。最后一页时为空。在事件流中，请传入 ?apos=：那里它从不为空，最后一页的值就是之后继续读取时要保存的位置。使用 ordem=recentes 时，事件流从新到旧返回，游标放在 ?antes= 中。 |
limite |
每页条数，1 至 200。默认为 50。超出范围返回 400 limite_invalido。 |
列表按从新到旧排列；事件流按从旧到新排列。
子账户和分账合作方在一个响应中完整返回，没有游标。争议也是如此，除非您传入 limite 或 cursor：这时按页返回。
巴西中央银行标准的路由（GET /v2/cob、GET /v2/pix）按该标准使用 inicio、fim 和 paginacao.paginaAtual。
关联 ID #
请发送 x-correlation-id，长度为 8 至 64 个不含空格的 ASCII 字符。每个响应都会返回它，令牌请求的响应也不例外；错误会在 correlationId 中重复它，记录的事件也带有相同的值。如果不发送，我们会生成一个。