子账户

子账户是您名下拥有独立余额的账户：一家分店、一个业务单元、您市场平台上的一个商户。带 ex.subconta 的收款会计入该子账户；在查询中使用 ?subconta= 可以筛选出属于它的数据。

有些账户没有子账户。请读取 GET /v2/ex/config 中的 capacidades.subcontas：为 false 时，创建子账户返回 503 capacidade_indisponivel，查询仍会正常返回。

创建 #

PUT /v2/ex/subcontas/{id}

权限范围：ex.subcontas.write。

PUT /v2/ex/subcontas/SUB01J1ZK7M9QW3ERT5TY6UI8O
{
  "nome": "Filial Centro",
  "cnpj": "11222333000181"
}
→ 201
{
  "id": "SUB01J1ZK7M9QW3ERT5TY6UI8O",
  "nome": "Filial Centro",
  "cnpj": "11222333000181",
  "status": "EM_ANALISE",
  "custodiante": "Conta PI",
  "herda": true,
  "aceitaSplit": true,
  "criadoEm": "2026-09-18T12:00:00Z",
  "atualizadoEm": "2026-09-18T12:00:00Z"
}

每次状态变更都会发出 subconta.atualizada。新的收款和提现要求子账户为 ATIVA，否则返回 403 subconta_indisponivel。已在处理中的提现会继续结算。已签发的收款如果在子账户不是 ATIVA 时被支付，则不会入账：该 Pix 会被拒绝或退还付款人，并触发事件 cob.pagamento_rejeitado（原因为 SUBCONTA_INDISPONIVEL）。

列出与查询 #

GET /v2/ex/subcontas

权限范围：ex.subcontas.read。

GET /v2/ex/subcontas
→ 200
{
  "subcontas": [
    {
      "id": "SUB01J1ZK7M9QW3ERT5TY6UI8O",
      "nome": "Filial Centro",
      "cnpj": "11222333000181",
      "status": "EM_ANALISE",
      "custodiante": "Conta PI",
      "herda": true
    }
  ]
}

?status= 按状态筛选列表。GET /v2/ex/subcontas/{id} 返回单个子账户。

按子账户查询 #

GET /v2/ex/config、GET /v2/ex/saldo、GET /v2/ex/cobrancas、GET /v2/ex/pix、GET /v2/ex/extrato/{data}、GET /v2/ex/extrato/{data}/arquivo、GET /v2/ex/transacoes、GET /v2/ex/transacoes/mapear 和 GET /v2/ex/resumo 都接受 ?subconta=。子账户的功能可能与主账户不同：通过子账户收款、提现或退款之前，请带 ?subconta= 读取 GET /v2/ex/config。

GET /v2/ex/saldo?subconta=SUB01J1ZK7M9QW3ERT5TY6UI8O
→ 200
{
  "subconta": "SUB01J1ZK7M9QW3ERT5TY6UI8O",
  "disponivel": "0.00",
  "total": "0.00"
}

租户 #

当 GET /v2/ex/config 中 capacidades.baas 为真时，子账户可以拥有独立凭证，在自己的账户上自行操作，其权限范围是您权限范围的子集。POST /v2/ex/inquilinos 签发凭证，GET /v2/ex/inquilinos 列出凭证，DELETE /v2/ex/inquilinos/{sub} 吊销凭证。权限范围：ex.inquilinos.write 和 ex.inquilinos.read。租户的凭证创建时没有 IP，要等 AmunPay 登记其出口 IP 后才能申请令牌。在此之前，令牌请求和每次调用都返回 403 origem_nao_permitida。

错误 #