Gerenciamento de Crowdfunding
Pré-requisitos de acesso
- Permissão (módulo):
viewCrowdfundingpara listar/visualizar;manageCrowdfundingpara criar, editar, gerar tokens, cronograma e permissões. - Licença/Feature:
CROWDFUNDINGhabilitada na licença do tenant (Vault). - Contêiner do menu: GERAL → grupo Produtos
O que é / quando usar
O Crowdfunding é a oferta-mãe da plataforma: uma campanha de captação coletiva onde investidores aportam recursos e, ao encerramento, recebem tokens (NFT ou token fungível 1:1) que representam sua participação. O operador usa esta área para cadastrar a oferta, definir como ela será tokenizada, gerar os tokens dos investidores que pagaram, agendar pagamentos previstos (cronograma) e acompanhar a oferta de ponta a ponta (view 360).
A oferta de crowdfunding é o ponto de partida das Cestas (baskets) e da escolha de padrão de contrato (ERC‑721 vs ERC‑3643), decidida por coleção no encerramento da captação.
Pré-condições
- Permissão:
viewCrowdfunding(consulta) oumanageCrowdfunding(escrita) cadastrados para a role do operador. Lembrar: permissão é dupla — enum CPM no backend + módulo dinâmico no DB. Se faltar o módulo dinâmico, o item nem aparece no menu; se faltar o enum CPM, a API recusa a ação. - Licença/Feature:
CROWDFUNDINGhabilitada. Se desabilitada, o item nem aparece no menu. - Dependências: para gerar tokens é preciso ter definido o modelo de tokenização e a rede (aba Tokenização). Para o cronograma materializar, a oferta precisa já ter o
assetId(token/NFT gerado).
Passo a passo (listagem)
- Acesse o menu Produtos → Crowdfunding.
- Use a busca por nome e os filtros Tem captação de carteira (
hasWalletCapturing) e Requer desbloqueio de carteira (walletUnlockRequired) para refinar; a ordenação alterna ASC/DESC. A listagem é paginada no servidor (limite/offset). - Em cada linha, use os ícones de ação: Visualizar, Editar, Clonar, Permissões do captador, Gerar tokens (NFTs), Cronograma de pagamentos e View 360.
- Para criar uma nova oferta, use Criar crowdfunding.
Criar / Editar oferta
O formulário (/crowdfunding/create, /crowdfunding/edit/:id) é organizado em 4 grupos e 16 seções. No modo criar, apenas o grupo Campanha fica disponível; os grupos Empresa, Análise e Operacional só abrem após a oferta existir (modo editar) ou em modo cópia. Isso é intencional: cria-se a campanha primeiro, depois se enriquece com dados regulatórios.
Grupos e seções:
- Campanha: Geral, Tokenização, Foto/Vídeo, Benefícios, Cenários, Documentos.
- Empresa: Dados da empresa, Executivos, Controladores, Advogados, Avaliação.
- Análise: Riscos, Matriz de destinação, Comunicação, Direitos.
- Operacional: Banco.
Campos da seção Geral
| Campo | O que é | Obrigatório? | Efeito no sistema/backend |
|---|---|---|---|
| Nome | Nome público da oferta | Sim | Grava name; usado como base do símbolo default do token. Duplicidade de iniciais gera erro tokens_all_pkey (símbolo já existente). |
| Categoria | Categoria de crowdfunding (judicial, arte, negócios, imóveis…) | Não | Vincula a oferta a uma CrowdfundingCategories (ver Categorias de Crowdfunding). |
| Data de início / Data final | Janela de captação | Sim | Gravadas como startDate/finalDate (dd/MM/yyyy). Validação: data final ≥ data inicial. |
Captação alvo (targetCapture) | Meta de captação | Sim | BigNumber — convertido via ValueConverterService, sem arredondamento. |
Captação mínima (minimumCapture) | Valor mínimo para a oferta ser bem-sucedida | Sim | BigNumber. |
Aporte mínimo (minimumContribution) | Menor aporte por investidor | Sim | BigNumber. |
Valor recebido (moneyReceived) | Quanto já foi captado | Não | BigNumber; normalmente atualizado pelo sistema conforme as compras de cota. |
| Rentabilidade / Período | Rentabilidade esperada e periodicidade (anual, mensal, customizada) | Não | profitability + profitabilityPeriodType. |
| Risco | Nível de risco (mínimo, médio, alto) | Não | typeOfRisk. |
| Contrato (upload) | Documento contratual da oferta | Não | Upload via files API (máx. 10 MB; tipos restritos). Grava a URL em contract. |
Captação de carteira (walletCapturing) | E-mail de um usuário cuja carteira recebe a captação | Não | Valide antes de salvar com o botão de validação: o backend checa se o usuário existe, está APPROVED e tem carteira configurada. Motivos de inelegibilidade são exibidos (usuário não encontrado, bloqueado/rejeitado, não aprovado, sem carteira). |
Validação de captação de carteira
A validação de walletCapturing exige usuário-alvo APPROVED com carteira ativa. Não salve a oferta com um destinatário inelegível — a captação ficaria sem destino válido.
Campos da seção Tokenização
Define como os aportes viram tokens. Escolhe-se o modelo e o comportamento (via presets ou modo Personalizado, que expõe as flags do Token/FMS).
| Campo | O que é | Obrigatório? | Efeito no sistema/backend |
|---|---|---|---|
Modelo (tokenization_type) | NFT (1 token = 1 cota indivisível) ou FUNGIBLE (token fungível de alocação 1:1 com a moeda) | Sim | Default NFT. Decide se a geração cria assets NFT ou um token fungível no FMS. |
Regulada (regulated) | Marca a oferta como ERC‑3643 | Não | Resolve o contract_standard da coleção no encerramento (security token com identidade on-chain). |
| Preset | Modelo de comportamento pronto: Certificado, Negociável ou Personalizado | Não | "Certificado" = NFT regulado, não transferível/negociável, com dividendos. "Negociável" = fungível regulado, transferível e tradeable, com dividendos. "Personalizado" expõe as flags abaixo. |
Transferível (transferable) | Permite transferência P2P entre holders | Não | Flag do token_config. |
Comprável (buyable) | Permite compra direta | Não | Flag do token_config. |
Negociável (tradeable) | Habilita negociação em book/par | Não | Flag do token_config. |
Dividendos (dividends) | Token recebe distribuições | Não | Flag do token_config; pré-requisito para o cronograma de pagamentos fazer sentido. |
Somente inteiro (onlyInteger) | Impede frações de token | Não | Default true. |
| Rede / Instituição / Categoria NFT / Símbolo | Parâmetros de emissão fixados na oferta | Não | network_id, institution_name, nft_category_id, token_symbol. O símbolo default é derivado das iniciais do nome + número final; pode ser sobrescrito. Esses valores são consumidos pela geração de tokens — não se pede rede/instituição de novo no momento de gerar. |
Escrow XRPL (use_xrpl_escrow) | Usa escrow na XRPL | Não | xrpl_network/xrpl_issuer_address/xrpl_currency. O emissor é read-only com link para o explorer público. |
Campos relevantes das demais seções
| Campo | Seção | Efeito no sistema/backend |
|---|---|---|
| Benefícios | Benefícios | Lista {nome, descrição}; obrigatório ter ao menos um para salvar. |
| Cenários (otimista/base/pessimista) | Cenários | Cada cenário exige deadline, maximumExposure (BigNumber), multiple, profitabilityCDI, profitabilityTIR. Os 3 são obrigatórios para salvar. |
| Capital social / Patrimônio / Resultado | Dados da empresa | Campos monetários normalizados via BigNumber antes de persistir. |
| Banco | Operacional | Conta bancária da oferta (ICrowfundingBankingAccount); copiada na clonagem. |
Conta bancária e formas de pagamento
Esta é a seção Banco do formulário e define como o investidor paga a oferta. Ela existe por exigência regulatória: a CVM obriga a disponibilizar pagamento manual por conta bancária nas ofertas de crowdfunding.
A seção tem três blocos:
1. Conta bancária (no topo) — a conta cadastrada para o pagamento manual do investidor (TED/PIX). É obrigatória pela CVM. Cadastre via Adicionar conta (banco, tipo, agência, conta e chave PIX). Os dados de TED e PIX exibidos ao investidor saem desta conta.
2. Métodos de pagamento (toggles) — controlam o que aparece para o investidor no checkout:
| Toggle | Campo | O que faz |
|---|---|---|
| Habilitar TED | ted | Mostra os dados de TED (da conta cadastrada acima) para pagamento manual via TED. |
| Habilitar PIX | pix | Mostra os dados de PIX (da conta cadastrada acima) para pagamento manual via PIX. |
| Habilitar Crypto | crypto | Permite pagamento da oferta via cripto. |
| Captação em USD | isDolar | Capta a oferta em dólar. ⚠️ Não habilitar — comportamento não suportado na operação normal. |
3. Integrações (toggles) — ligam conciliação semi-automatizada do depósito conforme a instituição da conta:
| Toggle | Campo | O que faz |
|---|---|---|
| Habilitar Transfero | transfero_integration | Só vale quando a conta de depósito é da Transfero (Genial). Força o sistema a buscar o extrato deles para conciliar os depósitos de forma semi-automática. Pode remover se a conta não for Transfero. |
| Habilitar PIX QRcode | dillianz_integration | Habilita o QR Code dinâmico de PIX, que permite baixa automática do pagamento. (Aparecia como "Habilitar Dillianz" em versões anteriores — a Dillianz era a provedora do QR Code automático; o rótulo foi renomeado para "Habilitar PIX QRcode" neste redesign.) |
| Habilitar Banco do Brasil | bank_of_brazil_integration | Quando a conta é do Banco do Brasil, o sistema busca o extrato no BB para conciliação semi-automática. |
Recomendações por tipo de oferta
- Ofertas privadas: Habilitar PIX, Crypto e PIX QRcode.
- Ofertas públicas: Habilitar TED, PIX, Crypto e PIX QRcode.
Pagamento manual e conciliação
Se o investidor optar por depósito manual (TED/PIX sem QR Code dinâmico), a conciliação pode ser manual — por isso a plataforma exibe a mensagem de que o pagamento pode levar até 2 dias para ser confirmado. Essa mensagem é norma da CVM e precisa estar disponível na plataforma para fins de auditoria. O PIX QRcode (QR dinâmico) é o que viabiliza a baixa automática, sem essa janela.
Configurações da oferta (toggles da seção Geral)
No fim da seção Geral há um cartão Configurações com seis toggles que governam tanto a vitrine (o que o investidor vê na página pública) quanto o comportamento operacional da oferta (automações de datas, mint, valor de cota e custódia on-ledger). Nenhum desses toggles é meramente cosmético — os de automação disparam jobs reais no backend.
| Rótulo | Campo (ngModel) | O que faz (efeito backend) | Quando usar |
|---|---|---|---|
| Habilitar FAQ | show_faq | Exibição na vitrine. Mostra a aba/seção FAQ na página pública da oferta. Não muda nenhuma regra de captação. | Quando a oferta tem perguntas frequentes cadastradas e você quer expô-las ao investidor. |
| Habilitar Disclaimer | show_disclaimer | Exibição na vitrine. Mostra o aviso de disclaimer/risco na página pública. Não muda nenhuma regra de captação. | Sempre que houver aviso de risco regulatório a exibir; recomendado para ofertas públicas. |
| Valor fixo | fixed_value | Comportamento de checkout. Quando ligado, o investidor não escolhe o valor: o aporte é validado (BigNumber) para ser exatamente igual ao Aporte mínimo (minimumContribution) — qualquer valor diferente é recusado no categories.checkout.core.handler. É uma oferta de cota de valor fixo (ticket único). | Ofertas em que toda cota tem o mesmo preço (ex.: 1 cota = R$ 1.000, sem aporte livre). |
| Controle automático de datas | automatic_dates | Automação por scheduler. Com ligado, o job controlCrowdfunding inicia e encerra a oferta sozinho pelas datas: quando CURRENT_DATE >= startDate e status inactive, vira active (e provisiona o emissor XRPL, se aplicável); quando CURRENT_DATE > finalDate e status active, vira finished. No encerramento automático, se a tokenização estiver pronta (tokenization_type + network_id, e ainda não emitido), ele chama generateNFTs automaticamente (mint idempotente — não redeploya). Sem este toggle, a transição de status e o mint ficam manuais. | Quando você quer que abertura/encerramento e o mint de fechamento ocorram sozinhos nas datas configuradas, sem operador. |
| Gerar NFT automaticamente no encerramento da oferta | automatic_nfts | Sinalização de intenção. O campo é persistido (entidade/DTO/model), mas o auto-deploy de fechamento hoje é gatilhado por automatic_dates + tokenização pronta no controlCrowdfunding, não por automatic_nfts. Ou seja: para mint automático no encerramento, o que efetivamente liga a automação é o Controle automático de datas. Trate este toggle como declaração da intenção "quero NFT automático" e combine-o com automatic_dates; sozinho ele não dispara o mint. | Ligue junto com Controle automático de datas quando a intenção for emitir os NFTs dos investidores assim que a oferta encerrar. Não confie nele isolado. |
| Usar XRPL Escrow (MPT) | use_xrpl_escrow | Custódia on-chain. Ativa o escrow on-ledger na XRPL via MPT (gated também pela feature flag global XRPL_ESCROW — os dois precisam estar ligados). Ao ativar, abre o cartão XRPL Escrow para definir rede (xrpl_network), moeda (xrpl_currency) e exibir o emissor (xrpl_issuer_address, read-only com link para o explorer). Efeitos: ao a oferta ficar ativa, provisiona um emissor XRPL dedicado por oferta; um scheduler (a cada 5 min) cria, para cada aporte pago, uma custódia on-ledger até o encerramento; no fim, libera ao projeto (sucesso) ou faz refund automático ao investidor; um job diário (03:00 UTC) queima os IOUs liberados de volta ao emissor (idempotente). | Ofertas que exigem custódia verificável on-chain dos aportes (liberação ao projeto só no sucesso, refund garantido no insucesso). Requer a feature XRPL_ESCROW habilitada no tenant. |
Automação de datas e mint de fechamento
Quem efetivamente liga as transições automáticas de status e o mint no encerramento é o Controle automático de datas (automatic_dates) + tokenização pronta. O toggle Gerar NFT automaticamente (automatic_nfts) é gravado, mas não é, sozinho, o gatilho do auto-deploy hoje. Para mint automático no fechamento, ligue ambos e garanta modelo/rede definidos na aba Tokenização. O mint segue a regra de mint exclusivo do job de crowdfunding (ver "Regras de negócio").
Escrow XRPL é gated em dois níveis
use_xrpl_escrow só tem efeito se a feature flag global XRPL_ESCROW também estiver habilitada no tenant. Com a flag desligada, os schedulers de escrow são no-op mesmo com o toggle marcado. O emissor é um por oferta, criado quando a oferta fica ativa.
Ações e modais
- Criar / Salvar: abre bottom-sheet de confirmação antes de persistir (mensagem reaproveitada de
manageTokens.crud.snackbar). O botão de salvar fica desabilitado enquanto faltarem os campos obrigatórios (nome, datas, benefícios e os 3 cenários completos) — o tooltip lista o que falta. - Clonar: navega para criação com
?copy=true. Limpa id/datas e copia dados da empresa e banco para a nova oferta. - Gerar tokens (NFTs): abre o modal
CrowdfundingNFTsComponent. Não pede mais rede/instituição — usa o que está na aba Tokenização. O backend resolvecontract_standard, símbolo e categoria a partir da oferta. Gate: modelo + rede definidos. - Cronograma de pagamentos: abre o modal de cronograma (ver Cronograma de Pagamentos).
- Permissões: navega para
/crowdfunding-permissions/:id(ver Permissões do Captador). - View 360: abre a visão consolidada (
/crowdfunding/view-360/:id). - Excluir: remove a oferta e recarrega a página.
View 360
A view 360 (/crowdfunding/view-360/:id) consolida tudo em 5 abas: Ordens concluídas, Ordens pendentes, NFTs/tokens gerados, Holders (resumo por detentor: quantidade + total pago) e Distribuições. Mostra quantidade de investidores, total concluído e total pendente. No modelo fungível, o assetId aponta para um token do FMS (não um asset NFT). Cada NFT individual tem link para sua tela de edição.
Regras de negócio / cuidados
Atenção
- O grupo Campanha é o único disponível na criação; enriqueça Empresa/Análise/Operacional só após criar a oferta (modo editar/cópia).
- Símbolo do token deve ser único — colisão dispara erro de chave (
tokens_all_pkey). - Validação de
walletCapturingé pré-condição de qualidade: destinatário precisa estar APPROVED com carteira.
Irreversível
- Geração de tokens minta supply on-chain a partir das ordens pagas. Não há rollback simples; confira modelo, rede e símbolo antes de gerar.
- Mint exclusivo do job: assets/tokens originados em crowdfunding só são mintados/queimados pelo job de crowdfunding. O TKN_OWNER não emite nem faz "revenda" sobre esses assets, e a alocação manual de admin também respeita a regra. Isso garante por construção a invariante valor captado == soma(NFTs × preço unitário). Transferência secundária P2P entre holders continua permitida (a restrição é sobre criar/extinguir supply, não sobre custódia).
- Valores financeiros: todos os campos monetários (captação, aporte, cenários, capital) são BigNumber — sem arredondamento; confira casas decimais.
Exemplos
Cenário 1 — Oferta com NFT‑certificado regulado (ERC‑3643)
- Em Geral, preencha nome, datas, captação alvo R$ 1.000.000, mínima R$ 300.000, aporte mínimo R$ 1.000, e valide a captação de carteira do destinatário (usuário APPROVED).
- Em Tokenização, escolha o preset Certificado → modelo NFT, regulado, dividendos ligados, somente inteiro. Defina rede e símbolo.
- Complete Benefícios e os 3 Cenários; salve.
- Após captação, abra Gerar tokens — o sistema minta as NFTs‑certificado para quem pagou, com
contract_standardERC‑3643 resolvido pela flagregulated.
Cenário 2 — Oferta com token fungível negociável (1:1 com a moeda)
- Em Tokenização, preset Negociável → modelo FUNGIBLE, regulado, transferível e tradeable, dividendos ligados.
- Cada R$ aportado vira 1 unidade do token (alocação 1:1, transparente à moeda).
- Em Gerar tokens, o
assetIdresultante aponta para um token do FMS. A view 360 lista holders por saldo de token, não por NFT unitária.
Cenário 3 — Importar uma oferta existente (clonar)
- Na listagem, use Clonar numa oferta de referência.
- O formulário abre em criação com
?copy=true: id, datas e janelas são zerados; dados da empresa e conta bancária são copiados. - Ajuste nome (símbolo derivado muda) e datas, e salve como nova oferta.