Implementar este caso com um assistente de IA
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
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
Passo a passo
Cadastre as imobiliárias em massa
POST /v1/submerchants para cada uma, com a chave da conta master da Chave Certa.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.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.Deixe a própria imobiliária enviar os documentos
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:Acompanhe o credenciamento da base
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: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.Guarde as chaves de cada imobiliária ativa
active, o ERP busca as chaves e guarda a chave secreta em um cofre de segredos, associada à imobiliária.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.Calcule a taxa do ERP por cobrança
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.Gere a cobrança com a chave da imobiliária
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.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.Concilie pelo metadata e pelos webhooks
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.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).Repasse o saldo à imobiliária
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
- 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-infocom 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 oid. Listafeesvazia significa subconta sem taxas configuradas: as cobranças dela são recusadas com422Fees not configuredaté a Finvia configurar. Nesse caso, acione o suporte. - Valores em reais em cobranças, splits e saques.
- Sem busca por metadata. Guarde o
idda cobrança no ERP. - Timeout na criação da cobrança. Não reenvie de imediato: se a primeira chamada chegou, um novo
POSTcria uma segunda cobrança. Recupere oidpelo webhookcharge.created, que traz ometadatacomo foi enviado, ou liste as cobranças do dia com a chave da subconta esearchForcom 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
E se o ERP for para clínicas?
E se o ERP for para clínicas?
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.E se o ERP preferir cobrar uma mensalidade fixa da imobiliária?
E se o ERP preferir cobrar uma mensalidade fixa da imobiliária?
split.E se a imobiliária repassar parte do aluguel ao proprietário do imóvel?
E se a imobiliária repassar parte do aluguel ao proprietário do imóvel?
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.E se o inquilino quiser pagar no cartão?
E se o inquilino quiser pagar no cartão?
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
activee 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 -
metadatacom contrato e competência, eidda cobrança salvo no ERP - Baixa automática só com
statuspaidconfirmado na API - Endpoint na conta master com
include_submerchants: truepara 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
Veja também
Sócios e documentos
Taxas da subconta
fees-info.
