> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ERP e software de gestão

> Sistema de gestão que cobra em nome dos próprios clientes: cada cliente vira subconta, as cobranças usam a chave da subconta, a taxa do software vem por split e a conciliação usa metadata e webhooks.

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.

> [!TIP]
>
> 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](https://docs.fastpaybrasil.com/integrar-com-ia.md).

Implementar este caso com um assistente de IA

Você vai integrar a API de pagamentos da Finvia neste projeto.

Leia a documentação oficial da Finvia antes de começar. O índice completo está em [https://docs.fastpaybrasil.com/llms.txt](https://docs.fastpaybrasil.com/llms.txt) e estas são as páginas principais para esta tarefa:

* [https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md](https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/saques.md](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md)
* [https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md)
* [https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md)
* [https://docs.fastpaybrasil.com/homologacao/roteiro.md](https://docs.fastpaybrasil.com/homologacao/roteiro.md)
* [https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md)

Regras que valem para toda a integração:

* Autenticação Basic: a chave secreta seguida de dois-pontos, em base64, no cabeçalho `Authorization`. A chave fica numa variável de ambiente do servidor (`FINVIA_API_KEY`) e nunca vai para o front-end, o app ou o repositório.
* Endereço da API: `https://api-global.fastpaybrasil.com`. O ambiente de testes usa o mesmo endereço; o que muda é a chave. Use a chave de teste durante o desenvolvimento.
* Valores em reais, não em centavos: `10` significa dez reais.
* A API não tem cabeçalho de idempotência. Não repita a criação de uma cobrança depois de um timeout sem antes consultar se ela já existe. Guarde o identificador do seu pedido em `metadata`.
* O resultado final de um pagamento chega por webhook. Trate eventos repetidos sem duplicar o efeito (liberar pedido duas vezes, por exemplo).
* Use rotas, campos, status e eventos exatamente como estão na documentação. Se algo não estiver documentado, pergunte antes de supor.

Tarefa: implementar neste projeto o fluxo descrito na página "ERP e software de gestão" ([https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md](https://docs.fastpaybrasil.com/casos-de-uso/erp-software-de-gestao.md)). Resumo do caso: Sistema de gestão que cobra em nome dos próprios clientes: cada cliente vira subconta, as cobranças usam a chave da subconta, a taxa do software vem por split e a conciliação usa metadata e webhooks.

Siga a seção "Passo a passo" da página na ordem em que ela aparece e use o "Checklist de implementação" do fim da página para conferir o resultado.

Antes de escrever código, leia as páginas acima e descubra a linguagem e o framework do projeto pelo código. Se não der para saber, pergunte. Entregue o código, os testes automatizados e uma lista curta do que ainda precisa ser configurado no painel da Finvia.

## 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](https://docs.fastpaybrasil.com/glossario.md)** 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

> [!NOTE]
>
> **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

| Necessidade | Recurso | Rota ou guia |
| - | - | - |
| Habilitar o modelo | Módulo Connect | Contato com o time Finvia |
| Cadastrar a imobiliária | Subconta | `POST /v1/submerchants` · [Subcontas e KYC](https://docs.fastpaybrasil.com/guias/fast-connect/subcontas-e-kyc.md) |
| Documentos enviados pela própria imobiliária | Token de upload | `POST /v1/submerchants/{merchantId}/document/upload-token` e `POST /v1/document-uploads` · [Sócios e documentos](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md) |
| Acompanhar o cadastro | Consulta e listagem de subcontas | `GET /v1/submerchants/{merchantId}` e `GET /v1/submerchants` |
| Cobrar em nome da imobiliária | Chaves da subconta | `GET /v1/submerchants/{merchantId}/api-keys` |
| Taxa do ERP | `split` para a conta master | `POST /v1/charges` · [Cálculo de split](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md) |
| Taxas de cada imobiliária | Consulta de taxas | `GET /v1/fast-connect/sub-accounts/{id}/fees-info` · [Taxas](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md) |
| Baixa automática | `metadata`, webhook na conta master com eventos das subcontas e consulta | [Webhooks de cobrança](https://docs.fastpaybrasil.com/guias/webhooks/cobranca.md) · `GET /v1/charges/{id}` |
| Repasse à imobiliária | Saque da subconta | `POST /v1/submerchants/{merchantId}/payout-requests` · [Saques](https://docs.fastpaybrasil.com/guias/fast-connect/saques.md) |

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.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%

flowchart TB
    IM(["Imobiliária<br/>cliente do ERP"]):::comprador
    ERP["ERP da Chave Certa<br/>conta master, chaves<br/>no cofre de segredos"]:::lojista
    API["Finvia API · Connect"]:::finvia
    PIX["Sistema Pix<br/>inquilino paga no banco"]:::externo
    EV[["charge.paid<br/>com data.merchant_id"]]:::evento
    W["Endpoint da conta master<br/>include_submerchants"]:::lojista
    OK(["Contrato baixado<br/>na competência"]):::ok
    IM -->|"1. dados já estão no ERP"| ERP
    ERP -->|"2. lote de subcontas<br/>POST /v1/submerchants"| API
    IM -.->|"3. documentos com<br/>token de upload"| API
    API -.->|"4. aviso de status<br/>active"| ERP
    ERP -->|"5. GET .../api-keys"| API
    ERP ==>|"6. POST /v1/charges<br/>chave da subconta<br/>split e metadata"| API
    API -->|"7. Pix de 3 dias"| PIX
    API -->|"8. publica o evento"| EV
    EV -.->|"9. entrega"| W
    W ==>|"10. GET /v1/charges/{id}<br/>com a chave da subconta"| OK
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef evento fill:#EAF3FF,stroke:#017AFF,stroke-width:1.5px,color:#003A7A
    classDef externo fill:#F4F0FF,stroke:#6D28D9,stroke-width:1.5px,color:#3B1C80
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
```

O segundo desenho detalha a conciliação de um aluguel pago por Pix e o saque da imobiliária.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%

sequenceDiagram
    autonumber
    box rgb(255,246,229) Comprador
        participant I as Inquilino
    end
    box rgb(243,245,248) Sua aplicação
        participant E as ERP
        participant W as Receptor de webhooks
    end
    box rgb(234,243,255) Finvia
        participant F as Finvia API
    end
    box rgb(244,240,255) Fora da Finvia
        participant B as Banco do inquilino
    end
    E->>F: POST /v1/charges · chave da imobiliária · metadata erpContrato e erpCompetencia
    F-->>E: 201 · pending · copyPaste
    Note over E: Guarda o id da cobrança com o contrato e a competência
    E-->>I: Pix do aluguel, válido por 3 dias
    I->>B: Paga no app do banco
    B->>F: Confirma o Pix
    F-)W: charge.paid · data.merchant_id da imobiliária
    W->>F: GET /v1/charges/{id} com a chave da subconta
    F-->>W: paid · metadata do contrato
    W->>E: Baixa o contrato 4471 na competência 2026-03
    E->>F: POST /v1/submerchants/{merchantId}/payout-requests
    F-)W: payout.approved ou payout.rejected
    Note over E,F: Fechamento diário: GET /v1/charges?status=paid com a chave de cada subconta
```

## 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.

```javascript theme={null}
for (const imob of imobiliariasSemSubconta) {
  const resposta = await finvia.post('/v1/submerchants', {
    legalName: imob.razaoSocial,
    tradeName: imob.nomeFantasia,
    companyTaxId: imob.cnpj, // só dígitos, com dígito verificador válido
    website: imob.site,
    averageMonthlyRevenue: imob.faturamentoMedioMensal,
    averageOrderValue: imob.aluguelMedio,
    productType: 'digital',
    legalRepresentative: {
      fullName: imob.responsavel.nome,
      idNumber: imob.responsavel.cpf,
      idType: 'cpf',
      dateOfBirth: imob.responsavel.nascimento, // formato AAAA-MM-DD
      nationality: 'Brasileira',
      email: imob.responsavel.email,
      motherName: imob.responsavel.nomeDaMae,
      gender: imob.responsavel.genero, // "M" ou "F"
      phones: [{ type: 'mobile', number: imob.responsavel.celular }],
    },
    contactEmail: imob.emailContato,
    productDescription: 'Cobrança de aluguel, condomínio e taxas de locação',
    address: {
      addressLine1: `${imob.endereco.logradouro}, ${imob.endereco.numero}`, // ex.: "Av. Paulista, 1000"
      addressLine2: imob.endereco.complemento || undefined, // opcional, ex.: "Sala 12"
      neighborhood: imob.endereco.bairro, // obrigatório quando country é BRA
      city: imob.endereco.cidade,
      state: imob.endereco.uf, // UF válida, ex.: "MG"
      country: 'BRA', // três letras
      postalCode: imob.endereco.cep, // CEP com 8 dígitos
    },
    phones: [{ type: 'mobile', number: imob.telefone }],
    postbackUrl: 'https://erp.chavecerta.exemplo.com.br/webhooks/finvia/conta',
    canAccessDashboard: false,
    bankAccount: {
      bankCode: imob.banco.codigo,
      agencyCode: imob.banco.agencia,
      accountNumber: imob.banco.conta,
      accountDigit: imob.banco.digito,
      accountType: 'checking',
      bankName: imob.banco.nome,
      recipientName: imob.razaoSocial,
      recipientDocument: imob.cnpj,
    },
  });
  await imob.salvarSubconta(resposta.id, resposta.legalRepresentatives);
}
```

> [!NOTE]
>
> 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:

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/document/upload-token" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json theme={null}
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 300
}
```

O navegador envia os arquivos direto para a Finvia, com o token no lugar da chave:

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/document-uploads" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -F "cnpj_card=@cartao-cnpj.pdf" \
  -F "social_contract=@contrato-social.pdf" \
  -F "responsible_document_front=@cnh-frente.jpg" \
  -F "responsible_document_back=@cnh-verso.jpg" \
  -F "selfie_with_document=@selfie.jpg"
```

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:

| Resposta | Significado |
| - | - |
| `201` | Documentos recebidos |
| `400` `NO_FILE_SENT` | Nenhum arquivo no envio |
| `400` `INVALID_DOCUMENT_NAME` | Nome de campo fora da lista de documentos |
| `401` | Token ausente, inválido ou expirado |
| `403` | Token já usado |
| `413` `FILE_TOO_LARGE` | Arquivo acima de 50 MB |
| `415` `UNSUPPORTED_FILE_TYPE` | Tipo não aceito (aceitos: PDF, JPG, PNG, GIF, BMP e WebP) |
| `422` `DOCUMENT_NOT_EDITABLE` | A subconta já foi aprovada e o documento não pode mais ser alterado |

**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:

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants?status=pending&status=correcting&status=pre_approved&page=1&size=50" \
  -u "$FINVIA_API_KEY:"
```

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.

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/api-keys" \
  -u "$FINVIA_API_KEY:"
```

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](https://docs.fastpaybrasil.com/glossario.md), o percentual precisa ser ajustado com as taxas da subconta, consultadas com a chave da conta master:

```bash theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/fast-connect/sub-accounts/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/fees-info" \
  -u "$FINVIA_API_KEY:"
```

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.

| Passo | Conta | Resultado |
| - | - | - |
| Valor líquido (L) | 2.500 × (1 − 0,015) − 0 | R\$ 2.462,50 |
| Taxa desejada | 1% × R\$ 2.500,00 | R\$ 25,00 |
| Split a informar (s) | 25,00 ÷ 2.462,50, arredondado para cima na quarta casa | 1,0153% |
| Conferência | 1,0153% × 2.462,50 | R\$ 25,00 para a Chave Certa |

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](https://docs.fastpaybrasil.com/guias/fast-connect/calculo-split.md).

**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.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/charges" \
  -u "$CHAVE_SUBCONTA_IMOBILIARIA:" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "BRL",
    "customer": {
      "name": "Joao Silva",
      "email": "joao@email.com",
      "document": { "type": "cpf", "id": "52998224725" },
      "phone": "+5511987654321"
    },
    "paymentMethod": { "type": "pix", "expirationInDays": 3 },
    "items": [
      {
        "title": "Aluguel março",
        "type": "digital",
        "description": "Contrato 4471, Rua das Acácias 120, apto 302",
        "unit_price": 2500,
        "quantity": 1
      }
    ],
    "split": [
      { "merchantId": "36OO3bcGjhPjjF3tzrqOGcmQuKo", "percentage": 1.0153 }
    ],
    "metadata": {
      "erpImobiliaria": "IMB-0093",
      "erpContrato": "4471",
      "erpCompetencia": "2026-03"
    },
    "postbackUrl": "https://erp.chavecerta.exemplo.com.br/webhooks/finvia"
  }'
```

> [!NOTE]
>
> 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.

```javascript theme={null}
app.post('/webhooks/finvia', async (req, res) => {
  const { id, event, data } = req.body;
  if (id && (await eventos.jaProcessado(id))) return res.status(200).send('OK');
  res.status(200).send('OK');

  if (event === 'charge.paid') {
    const chave = await cofre.chaveDaSubconta(data.merchant_id);
    const cobranca = await finvia.get(`/v1/charges/${data.id}`, chave);
    if (cobranca.status === 'paid') {
      const { erpContrato, erpCompetencia } = cobranca.metadata;
      await contratos.darBaixa(erpContrato, erpCompetencia, cobranca.id);
    }
  }
  if (id) await eventos.marcarProcessado(id);
});
```

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`).

> [!TIP]
>
> **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.

```bash theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/2vorkLm4Qp8TzR1sXc7Yb3NdWkE/payout-requests" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 18450.75 }'
```

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

> [!WARNING]
>
> **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.

> [!WARNING]
>
> **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](https://docs.fastpaybrasil.com/primeiros-passos/paginacao-ordenacao-idempotencia.md).

## Variações do caso

> [accordion] E se o ERP for para clínicas?
>
> 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`.

> [accordion] E se o ERP preferir cobrar uma mensalidade fixa da imobiliária?
>
> 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](https://docs.fastpaybrasil.com/casos-de-uso/saas-assinaturas.md). As cobranças de aluguel continuam nas subcontas, sem `split`.

> [accordion] E se a imobiliária repassar parte do aluguel ao proprietário do imóvel?
>
> Se o proprietário também tiver uma subconta no mesmo [grupo Connect](https://docs.fastpaybrasil.com/glossario.md), 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.

> [accordion] E se o inquilino quiser pagar no cartão?
>
> 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

| Funcionalidade | Cenários |
| - | - |
| Subcontas | FC-01 a FC-08 (o FC-07, de saque, não roda com a chave de teste: combine a evidência com o suporte) |
| Split | SPL-01 a SPL-06, com destaque para SPL-05 (valor da taxa conferido) |
| Cobranças | CHG-04 a CHG-09 (Pix, consulta, estorno e webhooks) |

Detalhes no [roteiro de homologação](https://docs.fastpaybrasil.com/homologacao/roteiro.md).

## Veja também

> [card] [Sócios e documentos](https://docs.fastpaybrasil.com/guias/fast-connect/socios-e-documentos.md)
>
> Fluxo com token de upload e documentos por sócio.

> [card] [Taxas da subconta](https://docs.fastpaybrasil.com/guias/fast-connect/taxas.md)
>
> Como ler a resposta de `fees-info`.

> [card] [Listar subcontas](https://docs.fastpaybrasil.com/referencia/fast-connect/listar-subcontas.md)
>
> Filtros e paginação da base de subcontas.

> [card] [Marketplace e PSP](https://docs.fastpaybrasil.com/casos-de-uso/marketplace-psp.md)
>
> O mesmo modelo aplicado a um marketplace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.