Skip to main content
GET
Esta rota devolve todas as subcontas (SubMerchants) ligadas à sua conta master (MerchantMaster) no Connect. É a visão de carteira do marketplace: quem está ativo, quem ainda está em análise, quem foi bloqueado e quanto cada subconta já movimentou.

Quando usar

Antes de chamar

  • O módulo Connect precisa estar habilitado pela Finvia na sua conta master. Sem isso, a resposta é 403.
  • Autentique com a chave secreta (sk_) da conta master. A lista sempre se restringe às subcontas ligadas a ela (Credenciais e ambientes).

Parâmetros de consulta

Todos os parâmetros são opcionais. Sem orderBy, a lista vem da subconta mais recente para a mais antiga.
string[]
Filtra pelo status atual da subconta. Valores aceitos: active, inactive, pending, pre_approved, correcting, rejected e blocked. Qualquer outro valor devolve 400. Para mais de um status, repita o parâmetro: ?status=pending&status=correcting. Não use lista separada por vírgula: ?status=pending,correcting não dá erro, mas devolve a lista vazia.
Busca por trecho, sem diferenciar maiúsculas de minúsculas, na razão social, no nome fantasia, no e-mail de contato e no CNPJ (com ou sem máscara). Ex.: loja exemplo.
string
CNPJ exato da subconta, somente dígitos. Com máscara, não encontra nada. Ex.: 11222333000181.
Trecho da razão social. Diferencia maiúsculas de minúsculas. Ex.: LOJA EXEMPLO.
string
Trecho do nome fantasia. Diferencia maiúsculas de minúsculas. Ex.: Loja Exemplo.
string
Data inicial de criação, no formato AAAA-MM-DD. Inclusiva, considerando o dia no fuso de São Paulo. Ex.: 2026-10-01.
string
Data final de criação, no formato AAAA-MM-DD. Inclusiva, considerando o dia no fuso de São Paulo. Ex.: 2026-10-31.
string
complete traz as subcontas com conta bancária ativa; incomplete, as que não têm.
string
Não filtra subcontas. Limita à moeda informada as somas totalSales e totalSplit de cada item. Ex.: BRL.
integer
default:"1"
Número da página, começando em 1.
integer
default:"10"
Quantidade de subcontas por página. Ex.: 20.
string
Campos de ordenação com o nome da coluna em snake_case, separados por vírgula. Use o prefixo - para ordem decrescente. Ex.: legal_name,-created_at (razão social em ordem crescente e, em caso de empate, as mais recentes primeiro). Nomes em camelCase, como legalName, geram erro 500.
string
deprecated
Legado. Compara igualdade exata com o momento da criação e, na prática, quase nunca encontra nada. Use createdFrom e createdTo.
Os filtros updatedAt, approvedAt, rejectedAt, blockedAt e inactivatedAt também são legados: comparam igualdade exata com o momento do evento e quase nunca encontram resultado. Não use.
Para o desenvolvedor: para varrer toda a carteira, percorra as páginas até page ser igual a pages. Mais detalhes em Paginação, ordenação e idempotência.

Respostas

object[]
Subcontas da página atual.
integer
Total de subcontas em todas as páginas. Ex.: 100.
integer
Página atual. Ex.: 1.
integer
Subcontas por página. Ex.: 10.
integer
Total de páginas. Ex.: 10.
O contrato desta rota não informa quais campos da subconta são sempre presentes. Trate qualquer campo como possivelmente ausente.

Status da subconta

O ciclo completo e quais mudanças geram aviso estão em Webhooks de conta.
Para o negócio: com o filtro de status e o período de criação, o time de operações acompanha o funil de credenciamento dos vendedores: quantos entraram, quantos estão em correção, quantos foram aprovados. completeness=incomplete mostra quem ainda não cadastrou conta bancária. totalSales e totalSplit mostram o movimento de cada subconta.

Erros comuns

Veja também

Consultar subconta

Dados e métricas de uma subconta.

Criar subconta

Cadastro de um novo vendedor.

Subcontas e KYC

Fluxo de cadastro e credenciamento.

Webhooks de conta

Avisos de mudança de status da subconta.