Sub-contas

Uma sub-conta é uma conta com saldo próprio sob a sua: uma filial, uma unidade de negócio, um lojista do seu marketplace. Uma cobrança com ex.subconta credita nela; ?subconta= nas consultas recorta o que é dela.

Criar #

PUT /v2/ex/subcontas/{id}

Escopo: 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": "SPI",
  "criadoEm": "2026-09-18T12:00:00Z",
  "atualizadoEm": "2026-09-18T12:00:00Z"
}

Cada mudança de status emite subconta.atualizada. Cobrança e saque novos exigem a sub-conta ATIVA e respondem 403 subconta_indisponivel fora dela; o que já estava em curso liquida.

Listar e consultar #

GET /v2/ex/subcontas

Escopo: ex.subcontas.read.

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

GET /v2/ex/subcontas/{id} devolve uma sub-conta.

Consultas por sub-conta #

GET /v2/ex/saldo, GET /v2/ex/cobrancas, GET /v2/ex/pix, GET /v2/ex/extrato/{data}, GET /v2/ex/transacoes e GET /v2/ex/resumo aceitam ?subconta=.

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

Inquilinos #

Quando capacidades.baas é verdadeiro em GET /v2/ex/config, uma sub-conta pode ter credencial própria e operar sozinha, sobre a própria conta, com escopos que são um subconjunto dos seus. POST /v2/ex/inquilinos emite a credencial, GET /v2/ex/inquilinos lista e DELETE /v2/ex/inquilinos/{sub} revoga. Escopo: ex.inquilinos.write e ex.inquilinos.read.

Erros #