Skip to main content
Um software de gestão (ERP) já guarda os contratos, as mensalidades, os vencimentos e os recebimentos dos clientes dele. O passo seguinte é cobrar por dentro do sistema: o inquilino paga o aluguel, o paciente paga a consulta, e o dinheiro cai direto na conta da imobiliária ou da clínica. Esta página mostra como montar isso com o Connect, incluindo a cobrança da taxa do software e o cadastro de muitos clientes de uma vez.
Quer acelerar com um assistente de IA? Copie o prompt abaixo e cole no Claude Code, no Codex, no Gemini ou no Cursor. Veja outros prompts em Integrar com IA.

Implementar este caso com um assistente de IA

Open in Cursor

O cenário

A Chave Certa Sistemas desenvolve um ERP para imobiliárias, com sede em Belo Horizonte. São 180 imobiliárias clientes, que administram juntas cerca de 22 mil contratos de locação. Todo mês, cada imobiliária cobra aluguel, condomínio e taxas dos inquilinos. Hoje, a cobrança acontece fora do ERP e a baixa é manual. A Chave Certa quer:
  • gerar a cobrança de cada aluguel dentro do ERP, por Pix ou cartão;
  • que o dinheiro entre direto na conta da imobiliária;
  • receber 1% do valor bruto de cada cobrança paga como taxa de uso da funcionalidade;
  • dar baixa automática no contrato quando o pagamento for confirmado;
  • cadastrar as 180 imobiliárias sem pedir que cada uma envie documentos por e-mail.

O que a Finvia resolve

Para o negócio: com o Connect, a Chave Certa vira a conta master (MerchantMaster) e cada imobiliária vira uma subconta (SubMerchant), com cadastro, análise de documentos e saldo próprios. O ERP cria as cobranças com a chave da subconta da imobiliária, então o dinheiro entra no saldo dela. O campo split separa a taxa da Chave Certa no momento da venda. O metadata leva o identificador do contrato, e os webhooks avisam o ERP quando dar baixa. A imobiliária saca o saldo por Pix para a chave CNPJ dela.

Arquitetura da solução

O desenho abaixo mostra como o ERP da Chave Certa cadastra as imobiliárias, cobra o aluguel em nome delas e dá baixa no contrato. O segundo desenho detalha a conciliação de um aluguel pago por Pix e o saque da imobiliária.

Passo a passo

1

Cadastre as imobiliárias em massa

O ERP já tem razão social, CNPJ, endereço, responsável e conta bancária de cada imobiliária. Um processo em lote percorre a base e chama POST /v1/submerchants para cada uma, com a chave da conta master da Chave Certa.
O productType aceita digital, physical ou both e descreve o que a subconta vende. A cobrança de aluguel não tem entrega física. Com canAccessDashboard: false, a imobiliária não recebe acesso ao painel e o objeto user não é exigido. Com país BRA, a API confere o dígito verificador do CNPJ e do CPF do responsável, a UF e o CEP: corrija esses dados no ERP antes de rodar o lote, porque um erro de validação volta como 400 com a lista de campos em message.
Processe o lote em ritmo controlado, registre a resposta de cada chamada e reprocesse só as que falharam. A API não tem Idempotency-Key: antes de reenviar uma criação que deu timeout, procure a subconta pelo CNPJ, só com dígitos, com GET /v1/submerchants?companyTaxId=11222333000181. Se o reenvio responder 409 Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco., a subconta já foi criada na primeira chamada.
2

Deixe a própria imobiliária enviar os documentos

Para dispensar o envio de documentos por e-mail, o ERP mostra uma tela de envio para a imobiliária. O backend da Chave Certa emite um token de upload e entrega esse token ao navegador:
O navegador envia os arquivos direto para a Finvia, com o token no lugar da chave:
O token vale 300 segundos (5 minutos) e é de uso único, então emita um novo a cada abertura da tela e envie todos os arquivos na mesma chamada. A subconta e o sócio vêm de dentro do token, nunca do corpo. Sem legalRepresentativeId, os documentos de pessoa ficam ligados ao representante legal. Para um sócio adicional, informe o id dele (retornado em legalRepresentatives na criação) ao emitir o token.Os erros do arquivo vêm no formato { "error": "<CÓDIGO>", "message": "...", "details": { ... } }. Trate pelo código HTTP e pelo campo error, não pelo texto:
3

Acompanhe o credenciamento da base

O ERP recebe os avisos de mudança de status (pre_approved, correcting, active, rejected, blocked) no postbackUrl informado no cadastro e, de tempos em tempos, confere a base pela listagem. Para filtrar por mais de um status, repita o parâmetro:
O filtro status aceita active, inactive, pending, pre_approved, correcting, rejected e blocked. Não separe os valores por vírgula: ?status=pending,correcting devolve a lista vazia. A lista vem da subconta mais recente para a mais antiga. Outros filtros úteis: search (razão social, nome fantasia, e-mail ou CNPJ), createdFrom e createdTo (AAAA-MM-DD) e completeness (complete para subcontas com conta bancária ativa, incomplete para as sem). Se usar orderBy, escreva o nome do campo em snake_case, como -created_at.Quando vier correcting, mostre à imobiliária o texto de rejectionReason. A correção é feita no painel da Finvia, na gestão de subcontas, por isso a Chave Certa precisa ter um operador com acesso ao painel para cuidar desses casos.
4

Guarde as chaves de cada imobiliária ativa

Com a subconta active, o ERP busca as chaves e guarda a chave secreta em um cofre de segredos, associada à imobiliária.
Antes da ativação, a resposta é 404 “API keys not found for this submerchant.”. Nunca guarde as chaves das imobiliárias no mesmo campo de banco das configurações comuns: elas dão acesso às cobranças de cada cliente.
5

Calcule a taxa do ERP por cobrança

A Chave Certa quer 1% do valor bruto. Como o split incide sobre o valor líquido, o percentual precisa ser ajustado com as taxas da subconta, consultadas com a chave da conta master:
O valor líquido é o valor da cobrança menos a taxa transacional da subconta (fixa mais percentual). Exemplo com taxas ilustrativas: aluguel de R$ 2.500,00 por Pix, com taxa de 1,5% e sem taxa fixa.Arredondar para cima evita que a taxa fique um centavo abaixo do alvo: com 1,0152%, o valor seria R$ 24,9993, exibido como R$ 24,99. Faça o cálculo a cada cobrança, com a linha tx_spread certa para o método, a bandeira e a parcela (percentages[parcelas - 1] e fixed). A taxa de antecipação só reduz a base quando a imobiliária antecipa o recebível; nesse caso, a taxa do ERP é recalculada sobre o valor antecipado. Detalhes e código em Cálculo de split.
6

Gere a cobrança com a chave da imobiliária

O ERP cria a cobrança do aluguel autenticando com a chave da subconta da imobiliária, leva o contrato no metadata e manda a taxa por split para a conta master da Chave Certa. O Pix vale 3 dias, para o inquilino pagar até o vencimento.
O percentual 1.0153 do exemplo foi calculado com a taxa ilustrativa de Pix do passo anterior. No cartão, use as linhas de taxa com paymentMethod credit_card, e o percentual muda. Nos exemplos desta página, 2vorkLm4Qp8TzR1sXc7Yb3NdWkE é a subconta da imobiliária e 36OO3bcGjhPjjF3tzrqOGcmQuKo é a conta master da Chave Certa. Guarde o id da cobrança junto do contrato e da competência no banco do ERP.
7

Concilie pelo metadata e pelos webhooks

A baixa no contrato acontece quando o ERP recebe charge.paid e confirma a cobrança na API. O metadata volta na consulta e no webhook, e diz qual contrato e qual competência baixar. Na consulta, as chaves de metadata voltam em camelCase; por isso o exemplo já envia erpContrato e erpCompetencia nesse formato.As cobranças pertencem às subcontas. Para receber os eventos de todas as imobiliárias em um lugar só, cadastre um endpoint na conta master com a opção de incluir subcontas: no painel, em Configurações > Webhooks, ou pela API, em POST /v1/webhook-endpoints com include_submerchants: true. O evento traz em data.merchant_id a subconta dona da cobrança.
Envie também um postbackUrl em todas as cobranças, em uma URL diferente da do endpoint. Ele recebe os mesmos eventos e o charge.updated legado, que é o único aviso de Pix expirado e o único que traz o status: "chargeback" do chargeback formalizado (quando o valor é revertido do saldo, chega também charge.refunded).
Para o desenvolvedor: a listagem GET /v1/charges não busca por metadata. Por isso, guarde o id da cobrança no ERP no momento da criação: é ele que liga a cobrança ao contrato. Para um fechamento diário, liste com a chave de cada subconta as cobranças pagas do dia (GET /v1/charges?status=paid&createdAtStart=2026-03-10&createdAtEnd=2026-03-10&page=1&size=50) e compare com o que o ERP já baixou. As duas datas precisam vir juntas, pegam o dia inteiro em UTC, e a listagem vem sempre da mais recente para a mais antiga.
8

Repasse o saldo à imobiliária

A imobiliária saca o saldo por Pix para a chave CNPJ dela: a chave Pix do tipo CNPJ igual ao CNPJ do cadastro. O valor vai em reais, com mínimo de R$ 1,00. O ERP pede o saque com a chave secreta da conta master e pode oferecer um botão de saque ou agendar saques.
A resposta traz o id do saque. O saque nasce pending, sempre passa por aprovação da Finvia e termina approved (aprovado e enviado para pagamento) ou rejected (o valor volta ao saldo). Só pode haver um saque pending por vez. Peça a cada imobiliária que cadastre o CNPJ como chave Pix em uma conta bancária da empresa antes do primeiro saque: a API não confere se a chave existe, e sem ela o Pix não é concluído.Os avisos payout.approved e payout.rejected vão para os endpoints cadastrados na subconta e para o endpoint da conta master com a opção de incluir subcontas, o mesmo do passo anterior. Os valores (amount, payoutFee, netAmount) chegam como texto decimal, como "18450.75000000": converta antes de usar. Confirme o status pela listagem GET /v1/payout-requests?merchantId=2vorkLm4Qp8TzR1sXc7Yb3NdWkE antes de dar baixa no repasse. Não existe saque no Modo Teste: com a chave de teste, a rota responde 403 WITHDRAWAL_NOT_ALLOWED_IN_TEST_MODE.

Regras e cuidados

Chave errada, conta errada. Uma cobrança criada com a chave da conta master entra no saldo da Chave Certa, e a imobiliária não recebe o valor. Confira, antes de cada chamada, se a chave usada é a da subconta dona do contrato.
O split incide sobre o líquido. Informar "percentage": 1 entrega menos de 1% do bruto. Calcule o percentual a cada cobrança com as taxas reais da subconta.
  • Taxas copiadas na criação. Cada subconta recebe uma cópia das taxas e configurações da conta master vigentes no momento da criação. Depois disso, elas são independentes: mudar as taxas da conta master não muda as das imobiliárias já cadastradas.
  • Subconta só transaciona active. Cobranças e chaves só existem depois da aprovação.
  • Documentos depois da aprovação são bloqueados (422). Faça a imobiliária revisar os arquivos antes de enviar.
  • Taxas por subconta. fees-info com a chave da conta master devolve as taxas da subconta pedida; com a chave da própria subconta, devolve sempre os dados dela e ignora o id. Lista fees vazia significa subconta sem taxas configuradas: as cobranças dela são recusadas com 422 Fees not configured até a Finvia configurar. Nesse caso, acione o suporte.
  • Valores em reais em cobranças, splits e saques.
  • Sem busca por metadata. Guarde o id da cobrança no ERP.
  • Timeout na criação da cobrança. Não reenvie de imediato: se a primeira chamada chegou, um novo POST cria uma segunda cobrança. Recupere o id pelo webhook charge.created, que traz o metadata como foi enviado, ou liste as cobranças do dia com a chave da subconta e searchFor com o documento ou o e-mail do inquilino. Só crie outra se nada for encontrado. O procedimento está em Paginação, ordenação e idempotência.

Variações do caso

O desenho é o mesmo: cada clínica é uma subconta, o paciente paga a consulta ou o procedimento pela cobrança criada com a chave da clínica, e o metadata leva o atendimento e o prontuário administrativo (nunca dados clínicos). Para planos de tratamento parcelados, use o cartão com installments até 12.
Aí a taxa da Chave Certa deixa de passar pelo split. A Chave Certa cobra a imobiliária como cliente dela, com uma assinatura na conta master, como em SaaS por assinatura. As cobranças de aluguel continuam nas subcontas, sem split.
Se o proprietário também tiver uma subconta no mesmo grupo Connect, a cobrança pode levar um segundo item no split, com a parte dele (relação subconta para subconta). O saque de subconta vai sempre para a chave Pix CNPJ do cadastro, então um proprietário pessoa física sem CNPJ não tem como sacar. Avalie com o time Finvia antes de desenhar esse fluxo.
Troque paymentMethod por credit_card com os dados do cartão, coletados em uma página de pagamento do próprio ERP. A cobrança com cartão exige o CVV, então ela acontece com o inquilino presente. Para débito automático no cartão todo mês, use assinaturas na subconta da imobiliária. As cobranças recorrentes das assinaturas não recebem split, então a taxa da Chave Certa não sai automaticamente nesse caso.

Checklist de implementação

  • Connect habilitado na conta do ERP
  • Lote de criação de subcontas com registro de resposta e reprocessamento só das falhas
  • Busca por CNPJ antes de recriar uma subconta após timeout
  • Tela de envio de documentos com token de upload emitido pelo backend
  • Tratamento dos avisos de status e operador com acesso ao painel para correções
  • Chaves das subcontas obtidas após active e guardadas em cofre de segredos
  • Cobranças criadas com a chave da subconta dona do contrato
  • Percentual do split calculado por cobrança com fees-info
  • metadata com contrato e competência, e id da cobrança salvo no ERP
  • Baixa automática só com status paid confirmado na API
  • Endpoint na conta master com include_submerchants: true para cobranças e saques das subcontas
  • Imobiliárias orientadas a cadastrar o CNPJ como chave Pix antes do primeiro saque
  • Fechamento diário comparando cobranças pagas com baixas no ERP

Como homologar

Detalhes no roteiro de homologação.

Veja também

Sócios e documentos

Fluxo com token de upload e documentos por sócio.

Taxas da subconta

Como ler a resposta de fees-info.

Listar subcontas

Filtros e paginação da base de subcontas.

Marketplace e PSP

O mesmo modelo aplicado a um marketplace.