# FinObra — SaaS de Gestão Financeira e Operacional para Construtoras (Documentação Completa para LLMs) > Documento completo de especificação de sistema, arquitetura, contratos de API, dicionário de dados e fluxos operacionais, formatado conforme o padrão llmstxt.org para agentes e modelos de inteligência artificial. > Versão: 2.38.0 > Data: 2026-09-15 > URL Canônica: https://fingo.api.br/llms-full.txt --- ## 1. Visão Geral da Plataforma O FinObra é uma solução B2B desenvolvida para empresas da construção civil no Brasil (construtoras, incorporadoras, empreiteiras, engenheiros civis e arquitetos). O sistema combina gestão financeira especializada, custos de engenharia e controle operacional de prazos em uma única plataforma multitenant. ### Diferenciais Centrais: - **SINAPI Integrado**: Integração analítica e sintética com tabelas oficiais da Caixa Econômica Federal e IBGE (regimes Desonerado e Não Desonerado, encargos sociais e fórmulas de BDI diferenciado). - **Workflow & SLAs em Cascata**: Motor de cronograma inteligente em que a conclusão de etapas predecessoras dispara automaticamente o início de fases sucessoras, recalculando a data final de entrega da obra. - **Notificações Ativas WhatsApp**: Comunicação automatizada via Baileys API para cobrança amigável de etapas atrasadas, avisos de início de fase e envio de resumos executivos. - **Monitoramento Fiscal SEFAZ**: Busca e download em tempo real de XMLs de NF-e emitidas contra o CNPJ da construtora usando Certificado Digital A1 mTLS. - **Boletins de Medição com Retenções Técnicas**: Controle acumulado físico e financeiro com retenções na fonte (ISS, INSS, IRRF, PIS, COFINS, CSLL) e geração de contratos com assinatura ICP-Brasil / Gov.br. --- ## 2. Bounded Contexts & Arquitetura DDD A plataforma segue os princípios de Domain-Driven Design (DDD) dividida em 6 contextos delimitados: 1. **Contexto Financeiro**: - `Lancamento`: Contas a pagar, contas a receber, receitas operacionais e despesas de obra. - `ContaBancaria`: Saldos reais, bancos cadastrados e controle de liquidez. - `ConciliacaoOFX`: Importação de extratos bancários com detecção automática de padrões de transações já cadastradas. - `DRE Gerencial`: Demonstração do Resultado do Exercício consolidada por regime de competência e caixa. 2. **Contexto Engenharia & Orçamentos (SINAPI)**: - `Orcamento`: Cabeçalho do orçamento com modalidade (Obra Própria, Empreitada, MCMV/Financiamento Caixa). - `ItemOrcamento`: Insumos e composições com quantitativo, preço unitário, BDI aplicado e custo total. - `SnapshotSINAPI`: Tabelas oficiais CEF indexadas por UF e competência mensal/anual. 3. **Contexto Medições & Faturamento**: - `Medicao`: Boletim de medição periódica com percentual medido no período e acumulado. - `RetencoesTecnicas`: Dedução automática de alíquotas de retenção municipal e federal sobre o valor bruto. 4. **Contexto Workflow & SLAs**: - `CronogramaProcesso`: Etapas da obra com ordem sequencial, dependências (`predecessor_id`), dias de SLA, checklists obrigatórios e status (`pendente`, `em_andamento`, `concluido`). - `TemplateWorkflow`: Modelos pré-configurados (`obra_particular`, `casa_caixa`, `reforma`, `projeto_arq`). - `ApontamentoHistorico`: Trilha de auditoria de transições de status com comentários, responsáveis e motivos de atraso. 5. **Contexto Comunicação (WhatsApp)**: - `WhatsAppMensagem`: Fila e templates de avisos de vencimento, início de etapa e resumo executivo de obra. 6. **Contexto Fiscal & Segurança**: - `CertificadoA1`: Gestão criptografada de chaves e certificados de empresas para autenticação SEFAZ. - `EventBridge`: Barramento de eventos seguro em conformidade com CSP `script-src-attr 'none'`. --- ## 3. Especificação dos Endpoints RESTful (`/api/*`) Todas as APIs seguem o padrão RESTful sobre HTTPS com JSON, autenticação por Bearer Token / Cookie de Sessão assinado e isolamento obrigatório por `empresa_id`. ### Envelope de Resposta Padrão: ```json { "success": true, "data": { ... }, "timestamp": "2026-09-15T23:50:00.000Z" } ``` ### Envelope de Erro Padrão: ```json { "success": false, "error": "Descrição clara do erro", "code": "SLUG_DO_ERRO", "status": 400, "timestamp": "2026-09-15T23:50:00.000Z" } ``` ### Principais Rotas da API: - `GET /api/db?resource=obras`: Lista obras ativas da empresa autenticada. - `POST /api/db?resource=obras`: Cria ou atualiza dados cadastrais de uma obra. - `GET /api/db?resource=cronograma_processos&obra_id={id}`: Retorna as etapas e SLAs da obra. - `POST /api/db?resource=cronograma_processos`: Salva apontamentos, avanço de etapas ou reconfiguração de prazos. - `GET /api/dashboard`: Retorna indicadores financeiros agregados (receitas, despesas, saldo, inadimplência). - `POST /api/whatsapp`: Dispara notificação ou consulta status de conexão da instância Baileys. - `POST /api/nfe`: Consulta SEFAZ para busca de novas notas fiscais eletrônicas. - `POST /api/auth?action=login`: Autentica usuário com e-mail e senha. - `POST /api/auth?action=2fa_verify`: Valida código TOTP de 6 dígitos. --- ## 4. Esquema de Banco de Dados (Neon PostgreSQL) - **Provedor**: Neon Lakebase Serverless PostgreSQL com Connection Pooling (`sslmode=require`). - **Multitenancy**: Todas as tabelas possuem a chave estrangeira `empresa_id INT NOT NULL REFERENCES empresas(id)`. - **Egress Optimization**: Nenhuma listagem usa `SELECT *`; projeções explícitas reduzem o tráfego de rede e latência. --- ## 5. Diretrizes de Segurança & CSP - **Política CSP Ativa**: ```http Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-...' blob:; script-src-attr 'none'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com data:; connect-src 'self' https://*.neon.tech https://*.vercel-storage.com; img-src 'self' data: blob: https:; frame-ancestors 'none'; ``` - **Proibição de Handlers Inline**: Atributos como `onclick` ou `onchange` são expressamente rejeitados pela CSP do navegador. Toda interação é mediada pelos atributos `data-fb-click`, `data-fb-change` e `data-fb-submit` vinculados à allowlist do arquivo `js/patch26-events.js`.