Global Admin
Sistema administrativo da Global Contabilidade: relações de faturamento com assinatura digital, cadastro de empresas, documentos, pendências e monitoramento da Receita Federal (e-CAC).
Relação de faturamento
PDF padronizado, valor por extenso, valores picados e assinatura PAdES ICP-Brasil.
Empresas e documentos
Consulta de CNPJ com fallback, CEP, importação por XML/PDF/planilha/e-CNPJ e pastas de documentos.
Receita Federal (e-CAC)
Integra Contador (SERPRO): verificação automática todo dia 10 e alerta de pendências.
Departamento pessoal
13 tipos de vínculo, folha, férias, 13º, rescisão com TRCT, admissão, afastamentos e importação do eSocial.
NFS-e e documentos
XMLs do Ambiente Nacional com o certificado A1, documentos em abas, lixeira e comunicações com prazo.
Segurança
Login por senha ou certificado ICP-Brasil, três perfis, auditoria, CSRF, cookies httpOnly e mTLS no SERPRO.
Estado atual
Arquitetura
Front Next.js, API Spring Boot e PostgreSQL em Docker, atrás do nginx com HTTPS.
| Camada | Tecnologia | Observações |
|---|---|---|
| Front | Next.js 15.5.28 (App Router), React 19.3, TypeScript, Tailwind 4, shadcn/ui, React Hook Form, Zod | Faz proxy de /api para o backend: cookie de sessão first-party, sem CORS. |
| Back | Spring Boot 3.5.16 (Java 17), Spring Security, JPA, Flyway | JWT em cookie httpOnly + CSRF; agendamentos (@Scheduled). |
| PDF / assinatura | Thymeleaf + OpenHTMLtoPDF, PDFBox 2.0.37, BouncyCastle 1.84 (1.85+ quebra a leitura do CMS na assinatura; fixado até ajustar) | PAdES (ETSI.CAdES.detached) com selo visual. |
| Banco | PostgreSQL 16 | Sem porta pública; volume Docker persistente. |
| Arquivos | Volume Docker (/app/uploads) | Nomes aleatórios; imagens e PDFs otimizados. |
| Assinador Local | Java 17 (HttpServer + Swing) | Roda no computador do usuário em 127.0.0.1:9090. |
| Infra | Docker Compose, nginx + Let's Encrypt | Imagens compiladas localmente e enviadas à VPS (sem build no servidor). |
Fluxo de uma requisição
Navegador ──HTTPS──▶ nginx (VPS) ──▶ Next.js :3020 (127.0.0.1)
│ /api/* (rewrite)
▼
Spring Boot :8080 (rede Docker)
├─▶ PostgreSQL (rede Docker)
├─▶ Volume de arquivos
├─▶ SERPRO Integra Contador (mTLS e-CNPJ)
├─▶ SMTP / WhatsApp Cloud API
└─▶ BrasilAPI · CNPJ.ws · ReceitaWS · MinhaReceita · ViaCEP
Migrações do banco (Flyway)
| Versão | Conteúdo |
|---|---|
| V1–V2 | Contabilidades, usuários, relações de faturamento (+ dados de exemplo) |
| V3 | Empresas, pendências, valores picados |
| V4 | Assinatura digital da relação |
| V5 | Perfis ADMIN/CONTABILIDADE/EMPRESA, sócios, cache de CNPJ, sócio-gerente |
| V6 | Mensageria (outbox), pastas e documentos, auditoria, e-CAC, CPF do usuário |
Perfis de acesso
As regras valem no backend (Spring Security + escopo nos serviços). Recurso de outra empresa/contabilidade responde 404.
| Perfil | Pode | Não pode |
|---|---|---|
| Administrador | Tudo: usuários, contabilidades, empresas, relações, pendências, e-CAC, notificações e auditoria. | — |
| Contabilidade | Empresas, relações, assinatura, pendências, documentos e e-CAC da própria contabilidade. | Usuários, auditoria, notificações, dados de outras contabilidades. |
| Empresa | Ver as próprias relações (PDF e PDF assinado), pendências e documentos; enviar documentos e anexos. | Criar/alterar/excluir dados, consultas externas, outras empresas. |
joao@a.com e joao@b.com), o login só pelo usuário é recusado e é preciso usar o e-mail completo. Sem diferença entre maiúsculas e minúsculas; a mensagem de erro é a mesma em todos os casos e o limite de tentativas continua valendo.Design system
Identidade visual da Global aplicada ao sistema e ao site: cores, tipografia, componentes, padrões de tela e protótipo navegável.
Cores
Azul institucional #0070ac, azul-marinho #08263f no menu, fundo #f4f8fc; estados verde, âmbar e vermelho.
Tipografia
Inter em tudo, números tabulares; títulos 600–700, corpo 14–15 px.
Componentes
shadcn/ui + Tailwind 4: botões, selos, campos, abas, filtros, indicadores, avisos, carrossel (Embla).
Protótipo
Site (início com carrossel), login e sistema (documentos com vencimento e visualização) — dados fictícios.
Relação de faturamento
Reproduz o documento padrão da Global com todos os campos editáveis.
- Meses gerados automaticamente (até 24) e editáveis; total e valor por extenso calculados.
- Valores picados por mês: só valores;
Enter/Tabpassam ao próximo campo; o servidor recalcula a soma. - Sócio-gerente opcional (nome + CPF validado), com sugestões dos sócios da empresa.
- PDF com selo de assinatura acima dos dados da contabilidade; modo compacto mantém tudo em uma página.
- Alterar a relação remove a assinatura (o conteúdo assinado deixaria de corresponder).
Valores zerados
Mês sem faturamento pode ficar em branco ou com 0: ao sair do campo vira 0,00 e a linha mostra o aviso “Valor zerado neste mês”, que permanece enquanto o valor for zero. O aviso não bloqueia: a relação é salva e o PDF é gerado normalmente (o toast de “salvo” informa quantos meses estão zerados). Só texto inválido impede salvar.
PDF, assinatura e impressão
- Baixar PDF entrega sempre a versão oficial: se a relação estiver assinada, é o PDF assinado (com o selo e a assinatura digital PAdES); senão, o PDF gerado na hora.
- Imprimir abre a janela de impressão do navegador com esse mesmo PDF (assinado, quando houver).
- Salvar sem alterar nada mantém a assinatura. Ela só é removida quando algo que aparece no documento muda (empresa, CNPJ, atividade, cidade, data, sócio-gerente, meses ou valores) — a tela avisa antes.
- Sem alterações pendentes, o botão vira Gerar PDF (não salva de novo).
Empresas e documentos
Cadastro
- CNPJ: busca automática ao completar 14 dígitos. Ordem de fallback: BrasilAPI → CNPJ.ws → ReceitaWS → MinhaReceita; cache de 30 dias no banco; limite de 30 consultas/min por usuário. Traz situação cadastral, CNAE e sócios (QSA).
- CEP é o primeiro campo do endereço: ViaCEP → BrasilAPI v2.
- Importação: XML (NF-e, NFC-e, CT-e, NFS-e — parser sem DOCTYPE, protegido contra XXE), PDF (ex.: Cartão CNPJ), planilha XLS/XLSX/CSV (coluna “CNPJ”) e certificado e-CNPJ.
GET /api/empresas/consulta/{cnpj}?atualizar=true.Faturamento 08-2025 a 07-2026 (relação 12).pdf; quando assinada, a versão assinada (… - assinada.pdf) substitui a anterior. A relação entra na pasta da empresa com o mesmo CNPJ na mesma contabilidade.Pastas e documentos
- Ao clicar numa empresa abre-se a página dela, com pastas (subpastas ilimitadas), envio de vários arquivos por vez (arrastar e soltar) e histórico e-CAC.
- Formatos: PDF, JPG, PNG, WebP, XML, XLSX, XLS, DOCX, DOC, PPTX, ODT, ODS, ZIP, CSV, TXT, OFX — até 10 MB cada. O tipo é validado pelos bytes do arquivo; imagens e PDFs são comprimidos e têm metadados (GPS) removidos.
- Cada documento enviado gera um aviso por e-mail para a Global (
NOTIFICACAO_EMAIL_GLOBAL). QuandoNOTIFICAR_CLIENTES=true, documentos postados pela equipe avisam também o cliente por e-mail/WhatsApp. - O cliente (perfil Empresa) vê “Meus documentos” e pode enviar arquivos; criar/renomear/excluir pastas é da equipe.
Assinatura digital
PAdES (ETSI.CAdES.detached) ICP-Brasil. A chave privada nunca chega ao servidor.
| Origem do certificado | Como |
|---|---|
| Instalado no computador (Windows / Keychain do macOS) | Assinador Local (Windows-MY / KeychainStore). |
| Token ou cartão A3 | Assinador Local via PKCS#11 (SafeNet, GD/Valid, Watchdata, Athena, OpenSC), PIN pedido na janela local. |
| Arquivo A1 (.pfx/.p12) | Duas opções: aberto no próprio navegador (node-forge) ou carregado no Assinador Local (botão “Arquivo .pfx”, aceita qualquer formato PKCS#12). |
| Assinado em outro programa | Envio do PDF assinado (Assinador SERPRO, Adobe…): o servidor verifica o CMS, a cadeia ICP-Brasil e se nada foi alterado depois. |
Fluxo em duas etapas
- Preparar: o servidor recebe o certificado público, valida (validade, uso de chave, RSA ≥ 2048, política ICP-Brasil e cadeia até a raiz do ITI), gera o PDF com o selo e devolve os atributos a assinar.
- Assinar: o navegador (A1) ou o Assinador Local (após confirmação do usuário) assina com
SHA256withRSA. - Finalizar: o servidor confere a assinatura com a chave pública, monta o CMS com
signingCertificateV2e grava o PDF. Sessão de uso único, 10 minutos.
Assinar documentos das pastas
Qualquer PDF guardado nas pastas de uma empresa pode ser assinado (ícone de caneta, equipe da contabilidade), pelos mesmos três caminhos: certificado instalado / token (Assinador Local), arquivo A1 + senha (no navegador) ou enviar um PDF já assinado. O sistema acrescenta ao fim do documento uma página “Assinatura digital” (quem assinou, CPF/CNPJ mascarado, emissor e data), aplica a assinatura PAdES e substitui o arquivo na pasta; a lista mostra “Assinado por … em …”. Um PDF que já tem assinatura pode receber outra: ela é acrescentada sem invalidar as anteriores (sem nova página). Rotas: POST /api/documentos/{id}/assinatura/preparar|finalizar|upload.
Assinador Local
- Escuta apenas em
127.0.0.1:9090; confere o cabeçalhoHost(anti DNS-rebinding) e só aceita as origens do Global Admin (CORS +Access-Control-Allow-Private-Network). - Toda assinatura exige confirmação numa janela local, com site, documento e certificado.
- Requer Java 17+. Configuração opcional em
~/.global-admin-assinador.properties(porta,origens,pkcs11). - Navegadores: Chrome, Edge e Firefox. O Safari bloqueia chamadas de páginas HTTPS para
localhost.
Instalador de dois cliques (versão 1.3)
Na tela de assinatura, quando o assinador não é encontrado, aparecem os botões Windows, macOS e Linux (o do computador atual vem destacado). Cada um baixa um ZIP com o assinador, um LEIA-ME e o instalador do sistema (Instalar Assinador.cmd, Instalar Assinador.command ou instalar-assinador.sh). O instalador confere o Java 17+ (se faltar, abre a página de download gratuito do Adoptium Temurin), copia o assinador para a pasta do usuário, registra para abrir junto com o sistema e já deixa aberto. Não precisa de administrador.
| Sistema | Como abrir o instalador |
|---|---|
| Windows | Botão direito no ZIP → Extrair tudo → dois cliques em Instalar Assinador.cmd. Se aparecer “O Windows protegeu o computador”: Mais informações → Executar assim mesmo. |
| macOS | Abrir o ZIP → botão direito em Instalar Assinador.command → Abrir. No macOS 15+: Ajustes do Sistema → Privacidade e Segurança → Abrir Mesmo Assim. |
| Linux | Extrair e rodar ./instalar-assinador.sh. |
Quem abrir só o .jar (dois cliques) encontra na janela a caixa “Abrir ao ligar o computador”, que liga/desliga a abertura automática. Se o assinador já estiver aberto, uma segunda cópia avisa e fecha sozinha (sem reabrir em loop pelo LaunchAgent do macOS). Os avisos de segurança do Windows/macOS só somem com assinatura de código (GA-203).
Abrir junto com o sistema (Windows, macOS e Linux)
Desde a versão 1.2, um único comando — o mesmo nos três sistemas — faz o assinador abrir sozinho, minimizado, sempre que o usuário entrar no computador. Rode uma vez, no Terminal (macOS/Linux) ou no Prompt/PowerShell (Windows), na pasta onde o arquivo foi baixado:
java -jar assinador-global-admin.jar --instalar # abre sozinho a cada login (minimizado)
java -jar assinador-global-admin.jar --remover # deixa de abrir sozinho
java -jar assinador-global-admin.jar --ajuda
| Sistema | Onde fica | Como inicia |
|---|---|---|
| Windows | %LOCALAPPDATA%\GlobalAdmin\ | Registro do usuário (HKCU\…\Run) com javaw, sem janela preta |
| macOS | ~/Library/Application Support/GlobalAdmin/ | LaunchAgent br.com.globaladmin.assinador; reabre se travar; log em ~/Library/Logs/global-admin-assinador.log |
| Linux | ~/.local/share/global-admin/ | Atalho em ~/.config/autostart (GNOME, KDE, XFCE…) |
- Não precisa de administrador; o arquivo é copiado para uma pasta fixa, então o download pode ser apagado depois.
- A janela fica minimizada e volta para a frente sozinha quando um site pede assinatura — a confirmação continua obrigatória.
- Nova versão: baixe o arquivo novo e rode
--instalarde novo. No Windows e no Linux, feche antes o assinador aberto. - Windows: o aviso “editor desconhecido” do SmartScreen/antivírus só some com assinatura de código num instalador (
jpackage), tarefa GA-203.
Login com certificado digital
- O navegador pede um desafio aleatório (uso único, 2 minutos).
- O certificado assina o desafio — no Assinador Local (repositório/token, com confirmação) ou com o arquivo A1 no navegador.
- O servidor valida assinatura, validade, uso de chave e cadeia PKIX até as raízes oficiais da ICP-Brasil (v5, v10, v11, v12, v13 embutidas, + 180 ACs intermediárias), com verificação de revogação (LCR/OCSP, modo tolerante a indisponibilidade).
- Localiza o usuário: e-CPF → CPF cadastrado no usuário; e-CNPJ → CPF do responsável ou o usuário do perfil Empresa daquele CNPJ.
- Abre a sessão (cookie httpOnly) e registra na auditoria.
CERTIFICADO_ANCORAS_EXTRAS) existem apenas para homologação.Impressões digitais (SHA-256) das raízes embutidas
| Raiz | SHA-256 |
|---|---|
| AC Raiz Brasileira v5 | CA:A5:3F:C6:09:1C:69:51:88:7C:97:6E:37:8F:6E:F8:9A:A6:37:7C:55:D9:7B:64:75:42:2B:71:ED:7E:9B:17 |
| AC Raiz Brasileira v10 | 6E:0B:FF:06:9A:26:99:4C:15:DE:2C:48:88:CC:54:AF:84:88:2E:54:95:B7:FB:F6:6B:E9:CC:FF:EC:74:89:F6 |
| AC Raiz Brasileira v11 | 14:06:71:00:58:18:0F:A4:08:1A:AB:3F:24:6F:17:02:42:9C:55:2A:11:FA:31:43:B8:4C:88:CB:3A:B8:E5:E7 |
| AC Raiz Brasileira v12 | D8:47:8E:37:CE:19:C6:90:CF:65:73:81:E6:8F:E6:00:E4:E1:A0:42:53:68:30:F0:68:47:E0:3E:55:4C:4B:01 |
| AC Raiz Brasileira v13 | 2B:07:D0:BC:02:C4:A6:E0:47:8E:D2:2D:0D:99:E8:F9:7E:18:27:B2:69:09:76:96:A7:FE:B6:AA:D3:0C:3A:C8 |
Baixadas de acraiz.icpbrasil.gov.br em 09/10/2026. Confira periodicamente com as publicadas pelo ITI.
Receita Federal (e-CAC)
O e-CAC não possui API pública. A via oficial é a API Integra Contador (SERPRO + Receita Federal), contratada na Loja SERPRO com o e-CNPJ da Global.
⬇ Baixar PDF com detalhes e valores
Autenticação
POST https://autenticacao.sapi.serpro.gov.br/authenticate
Authorization: Basic base64(consumerKey:consumerSecret)
role-type: TERCEIROS
Content-Type: application/x-www-form-urlencoded
(mTLS com o e-CNPJ ICP-Brasil do contratante)
grant_type=client_credentials
→ { access_token, jwt_token, expires_in, token_type: "Bearer" }
Chamada de serviço
POST https://gateway.apiserpro.serpro.gov.br/integra-contador/v1/{Apoiar|Consultar|Declarar|Emitir|Monitorar}
Authorization: Bearer {access_token}
jwt_token: {jwt_token}
Content-Type: application/json
{
"contratante": { "numero": "CNPJ da Global", "tipo": 2 },
"autorPedidoDados": { "numero": "CNPJ da Global", "tipo": 2 },
"contribuinte": { "numero": "CNPJ do cliente", "tipo": 2 },
"pedidoDados": { "idSistema": "SITFIS", "idServico": "SOLICITARPROTOCOLO91",
"versaoSistema": "1.0", "dados": "" }
}
O que o Global Admin consulta
| Serviço | Código | Método | Uso |
|---|---|---|---|
| Caixa Postal — indicador | CAIXAPOSTAL / INNOVAMSG63 | Monitorar | Há mensagens novas? |
| Caixa Postal — lista | CAIXAPOSTAL / MSGCONTRIBUINTE61 | Consultar | Assuntos das mensagens não lidas (somente se houver). |
| Situação Fiscal — protocolo | SITFIS / SOLICITARPROTOCOLO91 | Apoiar | Inicia a geração do relatório. |
| Situação Fiscal — relatório | SITFIS / RELATORIOSITFIS92 | Emitir | PDF guardado em “Receita Federal / Situação Fiscal”. |
PUT /api/ecac/empresas/{id}/frequencia.Rotina mensal
- Todo dia 10 às 07:00 (configurável em
ECAC_CRON), com trava no banco contra execução dupla. - Para cada empresa com monitoramento ligado: Caixa Postal + Relatório de Situação Fiscal.
- O PDF é salvo na pasta da empresa e analisado: só é “regular” se declarar explicitamente ausência de pendências.
- Com pendência: cria uma Pendência (prazo 15 dias), marca o alerta vermelho na lista de CNPJs e envia e-mail para a Global; futuramente também ao cliente (e-mail/WhatsApp).
- Ao final, e-mail com o resumo da rodada. Também há “Verificar agora” por empresa e “Verificar todas” (admin).
Valores (referência)
| Categoria | Faixa 1 (referência mai/2024) |
|---|---|
| Consulta | R$ 0,24 por requisição |
| Emissão | R$ 0,32 por requisição |
| Declaração | R$ 0,40 por requisição |
Pré-requisitos
- Contrato do Integra Contador na Loja SERPRO (e-CNPJ da Global) → Consumer Key e Consumer Secret.
- e-CNPJ A1 da Global no servidor, em
secrets/(montado somente leitura). - Procuração eletrônica de cada cliente para a Global no e-CAC, abrangendo os serviços consultados — sem ela a API responde “acesso negado”.
- Quando o contratante (quem tem o contrato) for diferente do procurador, é preciso o serviço
AUTENTICAPROCURADOR / ENVIOXMLASSINADO81com termo de autorização assinado. No caso da Global (contratante = procurador) não é necessário.
Mensageria (e-mail e WhatsApp)
Padrão outbox: quem gera o aviso só grava na fila; um despachante envia a cada 30 s, com novas tentativas (1, 2, 4, 8, 16 min).
| Evento | Destino hoje | Destino futuro (NOTIFICAR_CLIENTES=true) |
|---|---|---|
| Documento adicionado numa pasta | E-mail da Global | + e-mail/WhatsApp do cliente (quando postado pela equipe) |
| Pendência na Receita Federal (e-CAC) | E-mail da Global | + e-mail/WhatsApp do cliente |
| Resumo da rodada mensal do e-CAC | E-mail da Global | — |
| Integração e-CAC não configurada no dia 10 | E-mail da Global | — |
E-mail (SMTP)
Qualquer provedor SMTP: Gmail/Google Workspace (senha de app), Microsoft 365, Amazon SES, Resend, Brevo. Configure SPF, DKIM e DMARC no domínio do remetente para não cair em spam. Corpo HTML com a identidade da Global; conteúdo sempre escapado.
WhatsApp (Cloud API da Meta)
POST https://graph.facebook.com/{WHATSAPP_API_VERSION}/{WHATSAPP_PHONE_NUMBER_ID}/messages
Authorization: Bearer {WHATSAPP_TOKEN}
{ "messaging_product": "whatsapp", "to": "5561999998888",
"type": "template",
"template": { "name": "{WHATSAPP_TEMPLATE}", "language": { "code": "pt_BR" },
"components": [{ "type": "body", "parameters": [{ "type": "text", "text": "..." }] }] } }
Sem credenciais, as mensagens ficam como “sem configuração” e são reenviadas automaticamente quando o canal for configurado. A aba Notificações (admin) mostra a fila e permite enviar um teste.
Honorários e cobranças (Sicoob)
Cada empresa tem seus honorários (valor, data de emissão e recorrência). Na véspera, a contabilidade recebe por e-mail o que será cobrado; no dia, o sistema gera o boleto com Pix no Sicoob e envia ao cliente pela caixa de mensagens. Empresas inativas nunca são cobradas.
Onde fica
| Tela | O que faz |
|---|---|
| Empresas | Filtro Ativas / Inativas / Todas (padrão: ativas) e selo “inativa”. |
| Empresa → cabeçalho | Chave Ativa: inativar pausa todos os honorários daquela empresa. |
| Empresa → aba Honorários | Cadastro (criar, editar, pausar, excluir), Gerar agora e histórico de cobranças com linha digitável, Pix, PDF e ações. |
| Cobranças (menu) | Situação da integração, emissões dos próximos 30 dias agrupadas por data (com total) e todas as cobranças com filtro por status. Administrador: Rodar rotina do dia. |
Regras de negócio
| # | Regra |
|---|---|
| RC-01 | Honorário = descrição, valor, data da emissão, vencimento (1 a 60 dias após a emissão, padrão 10) e recorrência. |
| RC-02 | Recorrência: “Enviar recorrente” por N meses (1 a 120) ou sem prazo; desligada = cobrança única. Os meses seguintes usam o mesmo dia da primeira emissão (31/01 → 28/02 → 31/03). |
| RC-03 | A primeira emissão não pode ser no passado. Ao atingir o número de meses, o honorário é encerrado sozinho. |
| RC-04 | Só empresas ativas e honorários ativos geram cobrança e entram no aviso da véspera. Empresa inativa: o mês passa sem cobrança e não acumula para depois. |
| RC-05 | Véspera (rotina das 07:00): e-mail para a contabilidade (e para o e-mail da Global, se diferente) com empresa, CNPJ, valor, vencimento e total; aviso no sino da equipe. Uma vez por contabilidade e por data. |
| RC-06 | Dia da emissão: gera a cobrança; com o Sicoob configurado, emite boleto híbrido (com QR Code Pix), salva o PDF em Financeiro → Boletos (pasta liberada ao cliente) e envia ao cliente pela caixa de mensagens (com sino, e-mail e WhatsApp conforme a configuração). |
| RC-07 | Uma cobrança por honorário e competência (garantido no banco): rodar a rotina de novo ou clicar duas vezes nunca cobra em dobro. |
| RC-08 | Gerar agora antecipa a cobrança da próxima competência e avança o honorário (conta como aquele mês). |
| RC-09 | Sicoob não configurado: a cobrança fica Aguardando Sicoob e a equipe é avisada; depois de configurar, Emitir de novo. Erro do banco (ex.: endereço incompleto) fica registrado na cobrança. |
| RC-10 | Ciclo atrasado até 7 dias (servidor fora do ar) ainda é emitido; mais antigo é pulado e a equipe é avisada para decidir. |
| RC-11 | Cancelar uma cobrança emitida dá baixa no Sicoob. Pagamentos são conferidos no Sicoob a cada 3 horas (8h–20h, só leitura): boleto liquidado vira Paga (banco) com data e valor pagos, e cliente e equipe são avisados. Boleto baixado direto no banco vira Cancelada e a equipe é avisada. Não há webhook aberto para a internet. |
| RC-15 | Regras dos boletos (tela Cobranças, só administrador): multa %, juros % ao mês, protesto (2–90 dias corridos ou úteis) ou negativação (2–90 dias úteis), nunca os dois, e uma instrução no boleto. Enquanto não forem revisadas, nenhum boleto é registrado no banco (cobrança fica aguardando). Cada boleto guarda as regras usadas na emissão, e o cliente as recebe escritas na mensagem. |
| RC-16 | Por honorário: “Protestar/negativar se não pagar”. Desligado, o cliente nunca é protestado nem negativado. |
| RC-17 | Pedem a senha de acesso (e o código do app com 2FA): lançar honorário, mudar o valor, cancelar cobrança, dar baixa manual e salvar as regras. 5 erros seguidos bloqueiam por 15 minutos (gravado no banco: vale após reiniciar). |
| RC-18 | Baixa manual (pago fora do boleto): o sistema consulta o banco; se pago lá, registra como banco; se em aberto, baixa o boleto no Sicoob para não ir a protesto. Se a baixa falhar, a cobrança não é marcada como paga. |
| RC-19 | Certificado do Sicoob: trocar o arquivo no servidor basta (a conexão é refeita sozinha). Faltando 30 dias para vencer, e-mail para a Global às segundas (todo dia nos últimos 3 dias); a validade aparece na tela Cobranças. |
| RC-13 | Honorário lançado (empresa ativa): mensagem automática ao cliente com valor, primeira cobrança, vencimento e recorrência. Cobrança gerada: mensagem com valor e vencimento mesmo antes de o boleto sair; quando o Sicoob emitir, chega a mensagem com linha digitável, Pix e o link do PDF. |
| RC-14 | Toda mudança avisa os usuários: lançar, alterar (valor, próxima emissão, vencimento, recorrência, pausar/retomar) ou excluir honorário, cancelar cobrança e confirmar pagamento → aviso na Entrada da equipe (menos quem fez) e, com a empresa ativa, mensagem automática ao cliente listando o que mudou (“Valor: R$ 890,00 → R$ 950,00”), registrada na Saída. |
| RC-12 | O banco exige o endereço completo do pagador (logradouro, bairro, município, UF e CEP): complete o cadastro da empresa (ou use “Editar” → busca pelo CNPJ). |
Fluxo diário (07:00, America/Sao_Paulo)
- Busca os honorários ativos de empresas ativas com emissão amanhã → e-mail da véspera por contabilidade + sino.
- Busca os honorários com emissão hoje (ou atrasados até 7 dias) → cria a cobrança e avança o honorário 1 mês.
- Sicoob configurado →
POST /boletos(boleto híbrido) → guarda nosso número, linha digitável, Pix copia e cola e PDF. - Mensagem automática na conversa da empresa: valor, vencimento, linha digitável e Pix; aviso no sino do cliente.
- Trava de banco (
pg_try_advisory_lock) impede duas execuções em paralelo.
Integração Sicoob — Cobrança Bancária v3
| Item | Valor |
|---|---|
| Produção | https://api.sicoob.com.br/cobranca-bancaria/v3 · token https://auth.sicoob.com.br/auth/realms/cooperado/protocol/openid-connect/token (client_credentials, mTLS com certificado ICP-Brasil da Global, escopos boletos_inclusao boletos_consulta boletos_alteracao) |
| Sandbox | https://sandbox.sicoob.com.br/sicoob/sandbox/cobranca-bancaria/v3 com client_id e token fixo do portal developers.sicoob.com.br |
| Emissão | POST /boletos: numeroCliente, codigoModalidade (1 = simples com registro), numeroContaCorrente, codigoEspecieDocumento (DS), dataEmissao, dataVencimento, valor, seuNumero (GA + id), pagador (CNPJ, nome, endereço), gerarPdf, codigoCadastrarPIX (boleto híbrido) |
| Resposta usada | nossoNumero, linhaDigitavel, codigoBarras, qrCode (Pix copia e cola), pdfBoleto (base64), descricaoRejeicaoPix |
| Baixa | POST /boletos/{nossoNumero}/baixar |
descricaoRejeicaoPix (o sistema mostra na cobrança). O nome do campo do Pix híbrido deve ser confirmado na homologação (sandbox).Variáveis (.env do servidor)
SICOOB_HABILITADO=true
SICOOB_AMBIENTE=sandbox # ou producao
SICOOB_CLIENT_ID=... # portal Sicoob Developers
SICOOB_SANDBOX_TOKEN=... # só sandbox
SICOOB_CERTIFICADO=/app/secrets/sicoob.pfx # só produção (e-CNPJ A1 da Global)
SICOOB_CERTIFICADO_SENHA=...
SICOOB_NUMERO_CLIENTE=... # contrato do beneficiário no Sisbr
SICOOB_NUMERO_CONTA_CORRENTE=...
SICOOB_CODIGO_MODALIDADE=1
SICOOB_ESPECIE_DOCUMENTO=DS
SICOOB_PIX_HIBRIDO=true
COBRANCA_CRON=0 0 7 * * *
COBRANCA_CONFERENCIA_CRON=0 15 8-20/3 * * * # conferência dos pagamentos no Sicoob
# Multa, juros, protesto e negativação NÃO ficam aqui: a Global define na tela Cobranças.
Endpoints
| Rota | Quem |
|---|---|
PUT /api/empresas/{id}/ativa | Administrador e Contabilidade |
GET/POST /api/empresas/{id}/honorarios · PUT/DELETE …/honorarios/{h} · POST …/honorarios/{h}/gerar · GET /api/empresas/{id}/cobrancas | Administrador e Contabilidade |
GET /api/cobrancas · GET /api/cobrancas/proximas?dias=30 · GET /api/cobrancas/integracao · POST /api/cobrancas/{id}/emitir|enviar|conferir · POST /api/cobrancas/{id}/cancelar|paga (com senha) · GET /api/cobrancas/regras | Administrador e Contabilidade |
POST /api/cobrancas/processar · POST /api/cobrancas/conferir · PUT /api/cobrancas/regras (com senha) | Administrador |
Banco (migração V13): empresa.ativa, honorario, cobranca (única por honorário + competência) e cobranca_previa. V52: cobranca_config (regras), honorario.protestar e, na cobrança, regras usadas + pago_em, valor_pago, baixa (MANUAL/BANCO), conferida_em. V53: confirmacao_falha.
Agenda e caixa de mensagens
Calendário de controle da equipe (menu Agenda) com compromissos, parcelamentos e datas de emissão, ligados ou não a uma empresa. Toda segunda-feira chega o resumo da semana. Em Mensagens, além das conversas, ficam a caixa de Entrada (avisos do sistema), a de Saída (o que a contabilidade enviou automaticamente) e a Lixeira.
Agenda — regras de negócio
| # | Regra |
|---|---|
| RA-01 | Tipos: Compromisso, Parcelamento e Data de emissão. Título obrigatório; empresa e observação opcionais. |
| RA-02 | Recorrência: não repete, semanal, quinzenal, mensal, bimestral, trimestral, semestral ou anual, de 1 a 120 datas. Mensal mantém o dia; em meses mais curtos usa o último dia (31/01 → 28/02 → 31/03). |
| RA-03 | As datas são geradas a partir da primeira data e ficam editáveis uma a uma (data e valor), antes e depois de salvar. Valor opcional: “por data” (mesmo valor em todas) ou “total” (dividido; os centavos que sobram vão para a última). |
| RA-04 | Clicar num item abre a modal com a parcela/ocorrência (nº de total, data, valor, situação), os dados da empresa (CNPJ, e-mail, telefone, cidade) e todas as datas do compromisso com o total concluído. |
| RA-05 | Cada data pode ser marcada como concluída (registra quem e quando) ou reaberta. Situação: concluída, a vencer ou em atraso (vermelho). |
| RA-06 | Editar tudo substitui a lista de datas; as que já estavam concluídas continuam concluídas. Excluir remove todas as datas do compromisso. |
| RA-07 | As emissões de honorários aparecem automaticamente (verde), calculadas a partir do cadastro de honorários das empresas ativas, respeitando o número de meses. Para mudar, edite o honorário na empresa. |
| RA-08 | Escopo: a equipe vê a agenda da própria contabilidade; administradores veem todas. O cliente (perfil Empresa) não acessa a agenda. |
| RA-10 | O calendário mostra só os dias úteis da semana (segunda a sexta), nas visões Mês, Semana e Lista. Feriados nacionais aparecem destacados com o nome. |
| RA-11 | Vencimento em sábado, domingo ou feriado nacional (Confraternização, Paixão de Cristo, Tiradentes, Trabalho, Independência, Aparecida, Finados, República, Consciência Negra, Natal) ou ponto facultativo nacional (Carnaval, Corpus Christi): o item aparece no dia útil anterior com ⚠ e a data real, e mostra a mensagem padrão: “Vencimento no sábado (17/10/2026): dia não útil no calendário nacional. Dia útil anterior: 16/10/2026 · seguinte: 19/10/2026.” Feriados estaduais e municipais não entram. |
| RA-12 | No cadastro, cada data não útil é sinalizada e os botões Antecipar p/ dia útil e Adiar p/ dia útil ajustam todas de uma vez. |
| RA-13 | Aviso antecipado: todo dia útil às 07:05, se os dias seguintes forem não úteis (ex.: sexta antes do fim de semana, véspera de feriado), a equipe recebe na Entrada e por e-mail o que vence neles, com a mensagem padrão. O resumo de segunda também marca esses itens com ⚠. |
| RA-09 | Toda segunda-feira às 07:00: resumo da semana (segunda a domingo) para a equipe de cada contabilidade, na caixa de Entrada (+ sino) e por e-mail, com os itens em aberto da semana, as emissões de honorários e os atrasados dos últimos 60 dias. Uma vez por semana; semana vazia não gera aviso. |
Caixa de mensagens — regras de negócio
| # | Regra |
|---|---|
| RM-01 | Entrada: toda notificação do sistema para a pessoa (a mesma do sino): mensagens, documentos, pendências, e-CAC, resumo da agenda… O sino mostra só a Entrada. |
| RM-02 | Saída (só a equipe): todo envio automático da contabilidade ao cliente — arquivos novos em pastas liberadas, honorário lançado e cobranças — registrado para toda a equipe que atende a empresa, já como lido. |
| RM-03 | Excluir move para a Lixeira (por pessoa; não apaga a conversa com o cliente). Na lixeira dá para restaurar, excluir de vez ou esvaziar. |
| RM-04 | A lixeira é limpa automaticamente: o que está lá há mais de 30 dias é apagado todo dia às 04:30. Cada item mostra em quantos dias será apagado. |
| RM-05 | Fora da lixeira, cada pessoa guarda os 1000 avisos mais recentes. |
| RM-06 | Todo documento novo (enviado à mão ou gerado: e-CAC, relação de faturamento, boleto, pendência, assinatura) gera aviso na Entrada da equipe da empresa (menos quem enviou), com o link do arquivo. O cliente é avisado quando o arquivo está numa pasta liberada. |
| RM-07 | Enviar nova (caixa postal interna): assunto, mensagem e até 10 anexos (10 MB no total). A equipe escolhe a empresa e uma pasta liberada (padrão “Correspondências”); o cliente envia à contabilidade (pasta “Enviados pelo cliente”). Os anexos ficam nos documentos da empresa, a mensagem entra na conversa com o link de cada arquivo e o outro lado é avisado na Entrada. |
| RM-08 | Saída para todos os perfis: tudo o que foi enviado — mensagens da conversa, correspondências com anexos e envios automáticos (arquivos, honorários, cobranças). Da equipe: compartilhada por quem atende a empresa; do cliente: dos usuários da empresa. |
Endpoints
| Rota | Quem |
|---|---|
GET /api/agenda?de=aaaa-mm-dd&ate=aaaa-mm-dd (até 400 dias) | Administrador e Contabilidade |
GET/PUT/DELETE /api/agenda/compromissos/{id} · POST /api/agenda/compromissos | Administrador e Contabilidade |
PUT /api/agenda/parcelas/{id} · POST …/parcelas/{id}/concluir|reabrir | Administrador e Contabilidade |
POST /api/agenda/resumo-semanal (envia agora, sem repetir) | Administrador |
GET /api/caixa?pasta=ENTRADA|SAIDA|LIXEIRA · GET /api/caixa/contagem · POST /api/caixa/{id}/lixeira|restaurar · DELETE /api/caixa/{id} · DELETE /api/caixa/lixeira | Todos (cada um a sua caixa) |
AGENDA_RESUMO_CRON=0 0 7 * * MON # resumo semanal
AGENDA_AVISO_NAO_UTIL_CRON=0 5 7 * * * # aviso antecipado de vencimento em dia não útil
CAIXA_LIMPEZA_CRON=0 30 4 * * * # limpeza da lixeira (30 dias)
Banco (migração V16): compromisso, compromisso_parcela, agenda_resumo_semanal e, em aviso, as colunas pasta (ENTRADA/SAIDA) e excluido_em (lixeira). V17: agenda_aviso_nao_util (um aviso antecipado por contabilidade e dia).
Pendências e parcelamentos
Pendências agora têm três etapas visíveis e histórico de acessos e alterações. A aba Parcelamentos reúne todas as empresas com parcelamentos de débitos, cadastrados e atualizados à mão até a integração com o SERPRO.
Pendências — regras
| # | Regra |
|---|---|
| RP-01 | Etapas: Registrada → Cliente avisado → Concluída, com data e responsável em cada uma (no cartão e no detalhe). |
| RP-02 | “Registrar aviso” guarda como o cliente foi avisado (telefonema, WhatsApp, e-mail), observação, quem e quando, sem concluir. Pode haver novo aviso depois. Concluir sem aviso registrado pede os meios e registra os dois de uma vez. |
| RP-03 | Reabrir volta para pendente, mas mantém o registro do aviso (o cliente já foi avisado). |
| RP-04 | Editar (título, prazo, descrição) em qualquer situação, só a equipe. Cada alteração vai para o histórico com o antes → depois e para a auditoria. |
| RP-05 | Histórico: registrou, visualizou (uma vez a cada 30 min por pessoa, inclusive o cliente), editou, anexou/removeu anexo, avisou, concluiu, reabriu. Só a equipe vê. No “Entrar como”, fica em nome do administrador. Excluir a pendência registra na auditoria. |
| RP-06 | Vários arquivos: a contabilidade anexa quantos precisar (ao criar ou depois, “Adicionar arquivos”) e o cliente responde com vários documentos (“Anexar documentos”, até 10 por vez, 10 MB cada). Cada arquivo vira documento da empresa na pasta Pendências; o outro lado é avisado na Entrada e a ação entra no histórico. |
| RP-07 | Visão do cliente: só o que importa para ele — título, prazo, descrição, arquivos enviados pela contabilidade e a área Sua resposta. Não vê etapas internas, “cliente avisado”, meios de aviso, observações, histórico nem o contato; não exclui pendência nem arquivo (bloqueado também no servidor) e nunca substitui o anexo da contabilidade — o que ele envia entra sempre como resposta. |
| RP-08 | Só a equipe remove arquivos da pendência. Excluir a pendência mantém os arquivos na pasta Pendências da empresa. |
Parcelamentos — regras (refeito em 16/10/2026)
| # | Regra |
|---|---|
| RPC-01 | A equipe cria o parcelamento só com empresa, título e anotações. As anotações são internas (o cliente não recebe). |
| RPC-02 | Anexar boleto: arquivo (PDF/imagem), vencimento, valor, descrição e linha digitável (opcionais). O arquivo vai para a pasta Parcelamentos da empresa e o cliente recebe mensagem com o link “Abrir boleto”. |
| RPC-03 | O cliente vê os parcelamentos ativos da empresa dele (menu Parcelamentos): abre, baixa, copia a linha digitável e toca em “Já paguei” (a equipe é avisada; só a equipe desfaz). |
| RPC-04 | Check de leitura: quando o cliente abre o parcelamento ou o boleto, a equipe e o administrador veem ✓✓ azul “Visto pelo cliente em …” (com o número de acessos por boleto); antes disso, ✓ cinza “Não aberto”. A primeira abertura também avisa a equipe na Entrada. No “Entrar como” a abertura não conta como leitura do cliente. |
| RPC-05 | Mensagem no dia do vencimento (07:20): cada boleto não pago de parcelamento ativo gera, uma única vez, a mensagem “Vence HOJE” ao cliente (valor, linha digitável e botão para abrir) e aviso à equipe. O administrador pode disparar na hora pela API (POST /api/parcelamentos/avisar-vencimentos). |
| RPC-06 | Situação do boleto: a vencer, vence hoje, vencido ou pago; vencimento em fim de semana/feriado mostra o aviso padrão. Encerrar o parcelamento tira da tela do cliente; excluir apaga também os boletos. |
| RPC-07 | Pessoa física (CPF): o parcelamento pode ser de uma empresa (CNPJ) ou de uma pessoa física (Clientes → Pessoas físicas). Ao criar, escolha “Pessoa física (CPF)” e busque por nome ou CPF; se não existir, “Cadastrar novo CPF” cria o cadastro ali mesmo (nome e CPF; o resto completa depois). Pessoa física não tem portal: os boletos ficam guardados no próprio parcelamento (não viram documento de empresa), não há mensagem ao cliente nem check de leitura, e os avisos de vencimento, atraso e risco de exclusão vão para a equipe da contabilidade. Banco: migração V57. |
| RPC-08 | Arrastar os boletos: solte um ou vários PDFs/imagens no cartão do parcelamento (ou em “Anexar boletos”). Para cada arquivo o sistema lê a linha digitável e, quando dá, vencimento e valor: pelo texto do PDF (DAS, DARF, GPS, boletos de banco) ou, se o PDF for escaneado/foto, pelo código de barras desenhado na página. Só aceita números com os dígitos verificadores FEBRABAN corretos (boleto bancário de 47 dígitos: vencimento pelo fator — inclusive o ciclo reiniciado em 22/02/2025 — e valor; guia de arrecadação de 48 dígitos: valor pelo código e vencimento pelo texto “Pagar até”/“Vencimento”). Nada é gravado na leitura: a equipe confere, completa o que faltar e anexa todos de uma vez. Sem serviço externo nem IA (PDFBox + ZXing). Rota: POST /api/parcelamentos/ler-boleto. Testes: LeitorBoletoTest. |
Os 42 parcelamentos anteriores foram excluídos a pedido na migração V24 (cópia em CSV guardada fora do sistema, além do backup diário).
Próximos passos: Receita Federal e SERPRO
- GA-401 — Consultar os parcelamentos do Simples Nacional/MEI pelo Integra Contador (serviços de parcelamento do SN/MEI: pedidos, parcelas e pagamentos) e preencher a aba com fonte
SERPRO. Depende do contrato, do e-CNPJ no servidor e das procurações (GA-101 a GA-103). - GA-402 — Emitir o DAS da parcela do mês pela mesma API, salvar na pasta da empresa e enviar ao cliente pela caixa de mensagens.
- GA-403 — PGFN (Regularize/transações) e parcelamentos ordinários da RFB não aparecem nesses serviços: seguem manuais; avaliar a Situação Fiscal (SITFIS) para conferência.
- GA-404 — Rotina diária: atualizar parcelas pagas, vencimento e situação dos parcelamentos SERPRO e avisar atraso ou rescisão.
Confirmar no momento da contratação a lista exata de serviços e o custo por consulta no catálogo do Integra Contador. As tarefas já estão no quadro Pendências.
Banco (migração V19): pendencia.avisado_em/avisado_por/observacao_aviso, pendencia_historico, parcelamento (refeito na V24, com parcelamento_boleto) e tarefas GA-401 a GA-404 (GA-204 e GA-207 marcadas como concluídas). V21: pendencia_arquivo (pendência ↔ documento, origem EQUIPE/CLIENTE).
Certificados digitais
Aba Certificados digitais (menu lateral): guarda os certificados das empresas — A1 (.pfx/.p12, com a chave) ou só o certificado público (.cer/.crt/.pem, para controlar o vencimento de tokens A3) — com aviso antes de vencer.
| # | Regra |
|---|---|
| RCD-01 | Ao enviar, o sistema abre o arquivo (o .pfx exige a senha), lê titular, CNPJ/CPF, tipo (A1/A3), emissor, número de série e validade, e vincula à empresa escolhida ou, em branco, à empresa do mesmo CNPJ. Senha errada ou arquivo inválido é recusado; o mesmo certificado (nº de série + emissor) não entra duas vezes. Até 100 KB. |
| RCD-02 | Arquivo e senha ficam cifrados no banco (AES-256-GCM). A senha só é guardada se marcado “Guardar a senha”. Chave do cofre: CERTIFICADOS_CHAVE (32 bytes em Base64) ou, se vazia, derivada do JWT_SECRET — defina a chave própria antes de trocar o JWT_SECRET, senão os certificados guardados ficam ilegíveis. |
| RCD-03 | Equipe (administrador/contabilidade, da própria contabilidade): envia, lista, baixa, vê a senha guardada, envia por mensagem, salva em pasta e exclui. Cada download, exibição de senha, envio e exclusão vai para a auditoria. |
| RCD-04 | Cliente: envia o certificado da própria empresa, vê/baixa os dela, manda por mensagem à contabilidade e salva nas pastas liberadas; não exclui nem vê senha. A equipe é avisada na Entrada quando o cliente envia. |
| RCD-05 | Situação: válido, vence em até 30 dias (amarelo) ou vencido (vermelho). Todo dia às 07:10 a equipe recebe aviso na Entrada quando faltam 30, 15, 7, 1 e 0 dias (um aviso por marco). |
| RCD-06 | Camada extra de segurança: ver a senha, baixar, enviar por mensagem, salvar numa pasta e excluir pedem de novo a senha de acesso do usuário (e o código do app autenticador, para quem usa verificação em duas etapas) — a cada ação, sem “lembrar”. No “Acessar como”, confirma o administrador com a senha dele. 5 erros seguidos bloqueiam por 15 minutos. Acertos e erros vão para a auditoria (CONFIRMACAO_IDENTIDADE). |
| RCD-07 | Enviar por mensagem (equipe e cliente): o arquivo vai como anexo pela caixa de mensagens (correspondência). Equipe → empresa, com o anexo numa pasta que o cliente enxerga (padrão “Correspondências”); cliente → contabilidade (pasta “Enviados pelo cliente”). A senha do certificado nunca vai junto. |
| RCD-08 | Salvar em pasta (equipe e cliente): cópia nos documentos da empresa. Padrão da equipe: pasta “Certificados digitais” (só a equipe vê); do cliente: “Enviados pelo cliente”. Só vale para certificado vinculado a uma empresa. |
| RCD-09 | Certificado A1 (.pfx/.p12) guardado em qualquer pasta (documentos da empresa ou arquivos internos) também pede a senha de acesso para baixar: o GET responde 428, o navegador abre a janela “Confirme sua identidade” e repete por POST com a senha. As pastas passam a aceitar .pfx, .p12, .cer, .crt, .der e .pem. |
Rotas: POST /api/certificados/{id}/arquivo · /senha · /mensagem · /pasta · /excluir (corpo com senha e codigo); POST /api/documentos/{id}/arquivo e /api/arquivos-internos/item/{id}/arquivo para certificados nas pastas; GET /api/auth/confirmacao diz se a janela pede o código do app.
CERTIFICADOS_CHAVE= # opcional: openssl rand -base64 32
CERTIFICADOS_AVISO_CRON=0 10 7 * * *
Banco (migração V22): certificado_digital.
Colaboradores e financeiro do escritório
Na página da contabilidade (menu Contabilidades → “Colaboradores e financeiro”; para a equipe, também pelo menu lateral) há as abas Dados, Colaboradores e Financeiro.
Colaboradores — regras
| # | Regra |
|---|---|
| RCO-01 | Cadastro: nome, e-mail (login), CPF e telefone; senha provisória exibida uma vez (troca no primeiro acesso). Senha provisória nova a qualquer momento. |
| RCO-02 | Chaves de acesso por área: Empresas e documentos, Pendências, Mensagens com clientes, Agenda, Parcelamentos, Honorários e cobranças, Relações de faturamento, Receita Federal (e-CAC), Certificados digitais, Financeiro do escritório e Gerenciar colaboradores. Valem no menu e no servidor (área sem chave responde “Seu acesso não inclui a área…”). Painel, caixa do sistema (Entrada/Saída), Meu perfil e a lista básica de empresas ficam livres. Usuários anteriores mantêm acesso total. |
| RCO-03 | Mudar as chaves encerra as sessões do colaborador (valem no próximo login). Ninguém tira de si a chave “Gerenciar colaboradores” nem bloqueia o próprio acesso. |
| RCO-04 | Bloquear tira o acesso na hora e libera a vaga; desbloquear exige vaga. |
| RCO-05 | Limite de vagas (colaboradores ativos) por contabilidade, padrão 5; só o administrador altera (“Alterar limite”). Vale também para usuários criados em Usuários. |
| RCO-06 | Quem gerencia: administrador (qualquer contabilidade) ou colaborador com a chave “Gerenciar colaboradores” (só a dele). Tudo na auditoria. |
Financeiro — regras
| # | Regra |
|---|---|
| RFI-01 | Contas a receber e a pagar com categoria (plano de contas de escritório contábil: honorários, serviços avulsos, IRPF, consultoria… / salários, pró-labore, aluguel, sistemas, impostos, CRC…), cliente (empresa cadastrada) ou fornecedor, documento, competência, vencimento e valor. |
| RFI-02 | Repetir o valor por N meses (ex.: honorário fixo, aluguel) ou dividir em N parcelas (centavos na última). Marcar como já pago no cadastro. |
| RFI-03 | Baixa com data, valor (juros/desconto) e forma (Pix, boleto, transferência, cartão…); estorno volta para em aberto; cancelar mantém no histórico; excluir apaga. |
| RFI-04 | Resumo do mês: faturamento (receitas pela competência), despesas, caixa (recebido − pago no mês), a receber e a pagar em aberto (com atrasado) e os últimos 12 meses. |
| RFI-05 | “Importar cobranças de honorários” traz as cobranças da competência para contas a receber (uma vez cada; paga entra recebida). |
| RFI-06 | Cada contabilidade vê só o dela; exige a chave “Financeiro do escritório”. Tudo na auditoria. |
Banco (migração V23): contabilidade.limite_colaboradores, usuario.permissoes e financeiro_lancamento.
Obrigações, painel e relatórios
Camada contábil-fiscal do roadmap (out/2026): o que vence, quem está em risco e quem cuida de cada coisa.
Fase 1 — base de dados
| # | Regra |
|---|---|
| RF-01 | Pendência sempre com prazo e responsável. Prazo padrão: +5 dias úteis. Responsável: alguém da equipe da contabilidade (padrão: responsável da empresa ou quem registra). Também prioridade (baixa/média/alta) e competência (AAAA-MM). Lista ordenada por prazo, selo vermelho “Atrasada” e filtros por responsável, prioridade e atrasadas. Pendências antigas sem prazo receberam criação + 7 dias (migração V26). |
| RF-02 | Ficha fiscal da empresa (aba Ficha fiscal): regime tributário (MEI, Simples, Presumido, Real, Imune/Isenta), CNAE principal, responsável e “tem funcionários”. Importação em lote em Empresas → Importar regimes (CSV): CNPJ;regime;CNAE, aceita nomes por extenso. |
| RF-03 | Alertas diários: certificados vencendo em 30/15/7/1/0 dias (equipe e, agora, também o cliente); parcela de parcelamento vencida e não paga (uma vez por boleto); com 3+ parcelas em atraso, aviso de risco de exclusão. |
Tela de Pendências (revisão de 25/10/2026)
| # | Regra |
|---|---|
| PEN-01 | Urgência em níveis (data de São Paulo): vencida há mais de 7 dias (vermelho forte), vencida de 1 a 7 dias (vermelho suave), vence hoje/amanhã (âmbar), no prazo (neutro). O card mostra “Vencida há N dias” / “Vence hoje” / “Vence em N dias”, fundo neutro e cor só na borda e no selo, sempre com ícone e texto. |
| PEN-02 | Card enxuto: um selo da etapa atual (Aguardando aviso, Aguardando cliente, Concluída) no lugar das 3 etapas; responsável oculto quando só há um usuário ou o filtro já é de um responsável; selo “Sem contato” quando a empresa não tem telefone nem e-mail, com link para o cadastro. |
| PEN-03 | Resumo clicável (Vencidas, Vencem hoje, Próximos 7 dias, Aguardando cliente, Sem contato); filtros, ordenação (prazo, empresa, recentes, prioridade) e agrupamento (empresa ou tipo/órgão) na URL; grade ou lista (preferência guardada no navegador); 60 por vez com “Mostrar mais”; contador nas duas abas. |
| PEN-04 | Ações em lote (POST /api/pendencias/lote): registrar aviso, alterar prazo, reatribuir, prioridade e concluir manualmente. Tudo numa transação (se uma falhar, nenhuma muda), uma linha no histórico de cada; prazo, responsável e prioridade podem ser desfeitos pelo aviso na tela. |
| PEN-05 | Modal: ação principal “Registrar aviso”; “Concluir manualmente” é secundária e exige motivo (o backend recusa sem motivo); botões WhatsApp/e-mail abrem a mensagem-modelo (empresa, pendência, prazo, link do portal) e registram o aviso ao confirmar; alerta “Completar cadastro” quando falta contato. |
| PEN-06 | Qualidade dos dados (V40): tipo/órgão (Receita Federal, PGFN, Simples Nacional, DCTFWeb, Previdenciário, DP, Documento solicitado, Outros) e vencimento legal separado do prazo interno; título sugerido (“Receita Federal · 08/2026”) e capitalização padronizada; aviso de possível duplicidade (mesma empresa + tipo + competência em aberto); prioridade sugerida (Alta para PGFN/dívida ativa ou atraso > 7 dias). Botão Revisar títulos lista genéricos e possíveis duplicadas, só para leitura. |
Fase 2 — controle fiscal
| # | Regra |
|---|---|
| RF-04 | Tipos de obrigação (administrador, em Obrigações → Tipos e prazos): esfera, periodicidade (mensal, trimestral, anual), vencimento (dia fixo, N-ésimo dia útil ou último dia útil), meses após a competência, regimes, “só com funcionários”, se gera guia e o que fazer em dia não útil (antecipar, prorrogar, manter). Já vêm DAS, DAS-MEI, eSocial, DCTFWeb, FGTS Digital, EFD-Reinf, PIS/COFINS, EFD-Contribuições, IRPJ/CSLL trimestral, DEFIS, DASN-SIMEI, ECD e ECF com os prazos usuais — confira com a legislação vigente. ICMS e ISS variam por local: cadastre os que o escritório entrega. |
| RF-05 | Geração: todo dia às 06:30 (e ao iniciar o sistema) garante as obrigações da competência anterior e da atual para empresas ativas com regime; no dia 1º gera a competência que fechou. Idempotente (empresa + tipo + competência). Botão Gerar na tela para a equipe. |
| RF-06 | Fluxo: pendente → apurada → guia gerada → enviada → paga (declarações terminam em “enviada”; “dispensada” quando não há movimento). Quadro por situação, calendário por vencimento e lista, com filtros de competência, responsável, regime e obrigação. Toda mudança vai para a auditoria. A Agenda mostra um item por dia com as obrigações em aberto. |
| RF-07 | Painel v2 (equipe): competência e responsável no topo; indicadores (vencem em 7 dias, obrigações e pendências atrasadas, certificados vencendo, parcelamentos em atraso, inadimplentes); “Vencem esta semana”; situação fiscal dos clientes; financeiro do escritório; produtividade por responsável; botão Gerar relatório. O bloco institucional ficou só no portal do cliente. |
| RF-08 | Relatórios (menu Relatórios): gerencial por período/responsável/regime/contabilidade com os mesmos números do painel (mesma consulta), em PDF ou Excel; relatório mensal por cliente (faturamento 12 meses, obrigações, pendências, honorários, parcelamentos, situação fiscal). Toda emissão fica na auditoria com o tempo de geração. |
Fase 3 — cliente e caixa
| # | Regra |
|---|---|
| RF-09 | Situação fiscal (aba da empresa): certidões federal, estadual, municipal, FGTS e trabalhista, com situação (negativa, positiva, positiva com efeito de negativa) e validade. Registro manual pela equipe; o cliente consulta. Integração automática com e-CAC/SERPRO continua pendente (GA-401..404). |
| RF-10 | Envio do cliente baixa a pendência: ao anexar a resposta pelo portal, a pendência vai para Concluída (aviso “portal”), a equipe recebe aviso para conferir e pode reabrir. |
| RF-11 | Régua de lembrete dos honorários (08:10): mensagem ao cliente 3 dias antes, no dia e 3 dias depois do vencimento de cada cobrança emitida e não paga — uma vez cada, com linha digitável e link do boleto. |
Página inicial pública
| # | Regra |
|---|---|
| RF-12 | A raiz do site (/) é pública: notícias do dia em três temas — Leis trabalhistas (ConJur — trabalhista, TST quando acessível, Jornal Contábil filtrado), Contabilidade e fisco (Receita Federal, CFC) e Mercado financeiro (Agência Brasil, InfoMoney filtrados por assuntos de mercado) — e indicadores do Banco Central (Selic, CDI, IPCA 12 meses, dólar PTAX). Botão Entrar no topo leva ao login; logado, vira “Acessar o sistema”. |
| RF-13 | As fontes (RSS) são lidas pelo servidor a cada 2 horas e ficam só em memória; mostramos título, resumo curto, data e link para a matéria original (o texto não é copiado). Até 4 notícias por fonte e 8 por tema; fonte fora do ar mantém as anteriores. XML lido sem DTD (anti-XXE). Rota pública: GET /api/publico/noticias. |
| RF-14 | Rodapé com links úteis (sites oficiais, nova aba): e-CAC, Simples Nacional, optantes, CNPJ, CND federal, Regularize; eSocial, FGTS Digital, CNDT, Ministério do Trabalho, MEI; NF-e, NFS-e Nacional, Sintegra, Receita, CFC; Banco Central, Calculadora do Cidadão, CVM, B3, IBGE. |
Pessoas físicas e acessos gov.br
| # | Regra |
|---|---|
| RF-15 | Pessoas físicas (menu Pessoas físicas, chave Empresas): nome, CPF (único por contabilidade), nascimento, contato, endereço, empresa vinculada (sócio/titular), observação e ativo. Rotas GET/POST/PUT/DELETE /api/pessoas. |
| RF-16 | Acessos gov.br (chave própria “Acessos gov.br”): para clientes sem certificado digital — titular, CPF ou CNPJ, usuário (padrão: o próprio CPF), senha, verificação em duas etapas (sim/não), nível da conta (bronze/prata/ouro), vínculo com pessoa física ou empresa e observação. A senha é cifrada com AES-256-GCM (chave do cofre de certificados), nunca volta nas listagens e só aparece em POST /api/acessos-gov/{id}/revelar: janela de 30 s com copiar, registro de quem viu e quando no cadastro e na auditoria (ACESSO_GOV_SENHA_VISUALIZADA). Editar sem senha mantém a atual. Sempre que possível, prefira a procuração eletrônica no e-CAC. |
Rotas
| Rota | Quem |
|---|---|
GET /api/equipe | Equipe (lista de responsáveis) |
PUT /api/empresas/{id}/fiscal · POST /api/empresas/regimes | Equipe (chave Empresas) |
GET /api/obrigacoes · PUT /api/obrigacoes/{id} · POST /api/obrigacoes/gerar | Equipe (chave Obrigações); cliente só consulta as da própria empresa |
GET/POST/PUT /api/obrigacoes/tipos | Leitura: equipe · alteração: administrador |
GET /api/painel/indicadores | Equipe (valores de honorários só com a chave Cobranças) |
GET /api/relatorios/gerencial · GET /api/relatorios/cliente/{empresaId} | Equipe (chave Relatórios); formato=pdf|xlsx |
GET/POST/DELETE /api/empresas/{id}/certidoes | Equipe; cliente só lê |
Protocolos de entrega
Entrega física com prova de recebimento, como nos marketplaces: o escritório emite o protocolo com QR code, o entregador lê no app e colhe nome e assinatura de quem recebeu. Menu Protocolos de entrega (chave “Protocolos de entrega”).
| # | Regra |
|---|---|
| PE-01 | Novo protocolo: escolhe a empresa e o sistema puxa razão social, CNPJ, telefone e endereço do cadastro (editáveis). Descrição do conteúdo com atalhos (guias, certidões, holerites…) e observação para o entregador. Número PE-000123. |
| PE-02 | O QR guarda um link {site}/entrega/{codigo} com código aleatório de 24 caracteres. Pela câmera comum abre uma página pública só com número e situação, sem dados do cliente. |
| PE-03 | PDF para imprimir e anexar à entrega, com campos de assinatura em papel; depois da confirmação vira o comprovante, com recebedor, data/hora, localização e a assinatura coletada. |
| PE-04 | Situações: aguardando entrega → entregue (pelo app) ou cancelado (pela equipe). Com o protocolo aberto na tela, a confirmação aparece em até 5 s. |
| PE-05 | API do app em /api/app/**: login com e-mail e senha da equipe devolve token Bearer de escopo “entregas” (7 dias, cai com logout/troca de senha). Rotas: POST /api/app/login, GET /api/app/me, GET /api/app/entregas, GET /api/app/entregas/{codigo}, POST /api/app/entregas/{codigo}/confirmar (nome, documento, assinatura PNG em base64, foto, latitude/longitude). Contrato completo em docs/app-entregas.md. |
ENTREGAS_URL_PUBLICA (padrão: globalcontabilidade.cnt.br). O app deve falar direto com a VPS (a Vercel limita o corpo a 4,5 MB).Documentos em abas
Menu Documentos, no modelo do Onvio: documentos do cliente, do escritório, meus documentos, lixeira e comunicações.
| # | Regra |
|---|---|
| DOC-01 | Documentos do cliente: seletor de empresa e árvore de pastas (URL com ?empresa= para compartilhar). Botão Pastas padrão cria Administrativo, Certidão Negativa de Débito, Contabilidade, Financeiro, Fiscal, Patrimônio, Pessoal e Registro de Empresas (só as que faltam). |
| DOC-02 | Documentos do escritório (toda a equipe da contabilidade) e Meus documentos (só o usuário): repositórios internos, nunca visíveis ao cliente. |
| DOC-03 | Lixeira: excluir documento só marca; restaurar devolve à pasta (ou à raiz, se a pasta foi apagada); “apagar de vez” remove o arquivo. Job diário às 03:40 apaga o que está há mais de 30 dias. |
| DOC-05 | Editar qualquer arquivo (cliente, escritório e meus documentos): renomear (a extensão é mantida), data de vencimento, mover de pasta e substituir por nova versão (mesmo nome, pasta e vencimento; nos documentos do cliente zera assinatura e visualização). Cada linha mostra “inserido em” e “alterado em … por …”. Só a equipe edita. |
| DOC-06 | Vencimento: selo amarelo (≤ 30 dias) ou vermelho (vencido). Todo dia às 07:20 vai aviso na Entrada aos 30, 15, 7 e 0 dias — documentos do cliente e do escritório para a equipe; meus documentos só para o dono. |
| DOC-07 | Visualizado pelo cliente: ao abrir ou baixar, fica registrado quem (usuário da empresa), a 1ª visualização, o último acesso, o total de acessos e o 1º download (o “Acessar como” do administrador não conta). Em pasta liberada sem acesso aparece “Ainda não visualizado pelo cliente”. |
| DOC-04 | Comunicações: envio de guia, certidão, contrato ou documento ao cliente com competência, vencimento, “disponível até” e mensagem. O arquivo vai para a pasta “Comunicações” (liberada) e o cliente recebe a mensagem com o link. Andamento automático: enviado → visualizado (abriu) → baixado; a equipe marca concluída ou cancela. Cancelada ou expirada, o cliente não baixa mais (HTTP 410). |
/api/arquivos-internos/{area}/…, /api/lixeira, /api/comunicacoes, POST /api/empresas/{id}/pastas/padrao, PUT /api/documentos/{id}, POST /api/documentos/{id}/substituir, PUT /api/arquivos-internos/item/{id}, POST /api/arquivos-internos/item/{id}/substituir.NFS-e (XML)
Busca das notas de serviço no Ambiente de Dados Nacional (ADN) com o certificado A1 de cada empresa, leitor de XML e rotina agendada. Menu NFS-e (XML) (chave “NFS-e”).
| # | Regra |
|---|---|
| NF-01 | API de distribuição do ADN (GET /contribuintes/DFe/{NSU}): devolve as NFS-e em que o CNPJ é prestador, tomador ou intermediário. Exige o e-CNPJ da própria empresa ou do mesmo CNPJ raiz (procuração não serve). O certificado é apresentado com a cadeia ICP-Brasil completa (raízes v5/v10/v11/v12 pedidas pelo ADN). |
| NF-02 | Empresas elegíveis: certificado A1 (.pfx) válido e com senha guardada em Certificados digitais. O sistema guarda o último NSU de cada empresa e busca só o que é novo (até 40 lotes por execução). |
| NF-03 | Cada XML vai para Documentos › Fiscal › NFS-e › Prestadas|Tomadas › AAAA-MM, sem duplicar (chave de acesso). Eventos de cancelamento/substituição marcam a nota. “Guardar notas a partir de” evita importar o histórico antigo. |
| NF-04 | Rotina diária no horário configurado (desligada por padrão), só para empresas marcadas como automáticas; busca manual por empresa ou em lote, sempre com confirmação. Histórico de execuções com notas novas e erros. |
| NF-05 | Leitor de XML: arquivo ou texto colado (Nacional, ABRASF e eventos) → resumo legível + todos os campos com filtro, espelho em PDF e “salvar na empresa”. Ler não grava nada. XML sem DTD (anti-XXE). |
| NF-06 | Aba Notas: filtros por empresa, competência e tipo; totais de serviços prestados, ISS e tomados; exportação CSV. |
Departamento pessoal
Menu Departamento pessoal (chave “Departamento pessoal”): escolhe uma das empresas adicionadas ao DP e trabalha em 10 sub-abas. Calcula e gera os documentos; não transmite ao eSocial. Os cálculos devem ser conferidos pela equipe de DP antes de valer para clientes.
Tipos de vínculo (um nível para cada)
| Tipo | Regras aplicadas |
|---|---|
| CLT prazo indeterminado · Teletrabalho | INSS progressivo, FGTS 8%, férias, 13º, aviso prévio. Teletrabalho exige aditivo (art. 75-C). |
| Experiência · Prazo determinado | Até 90 dias (art. 445) · até 2 anos; rescisão antecipada pelos arts. 479/480. |
| Tempo parcial · Intermitente | Até 30 h semanais (art. 58-A) · horas por convocação com DSR, férias + 1/3 e 13º proporcionais a cada período (art. 452-A). |
| Aprendiz · Temporário | FGTS 2%, até 2 anos · até 180 + 90 dias (Lei 6.019). |
| Doméstico · Rural | FGTS 8% + 3,2% de indenização, sem multa na rescisão (LC 150) · adicional noturno de 25% (Lei 5.889). |
| Estágio · Sócio (pró-labore) · Autônomo (RPA) | Bolsa sem INSS/FGTS, até 30 h e 2 anos (Lei 11.788) · INSS 11% até o teto, sem FGTS · INSS 11% retido + 20% patronal. |
Fase 1 — funcionários, folha e ponto
| # | Regra |
|---|---|
| DP-01 | Funcionários: cadastro completo (CEP preenche o endereço), validações de prazo e jornada por tipo, CPF. |
| DP-02 | Folha mensal: horas extras 50/100%, DSR sobre variáveis (dias úteis e domingos/feriados nacionais do mês), adicional noturno, insalubridade (sobre o mínimo) e periculosidade (30%), faltas, atrasos, VT (até 6%), pensão, adiantamento. INSS progressivo; IRRF pelo menor entre deduções legais e desconto simplificado, depois a redução da Lei 15.270/2025; FGTS e encargos. Folha fechada não muda. |
| DP-03 | PDFs: contracheque (duas vias por página) e folha de ponto do mês com domingos e feriados nacionais (CLT art. 74 §2º). |
| DP-04 | Tabelas legais por ano (2024, 2025 e 2026 carregadas), editáveis pelo administrador; ano sem tabela usa a mais recente anterior. |
Fase 2 — férias, 13º e rescisão
| # | Regra |
|---|---|
| DP-05 | Férias: períodos aquisitivos com saldo; dias pelas faltas (art. 130); até 3 períodos, um com 14+ dias (art. 134 §1º); início vedado nos 2 dias antes de DSR/feriado (§3º); abono de até 1/3 (art. 143) sem INSS/IRRF/FGTS; dobra fora do concessivo (art. 137); pagamento até 2 dias antes (art. 145). PDF: aviso + recibo. |
| DP-06 | 13º: avos de 15 dias ou mais; 1ª parcela até 30/11 sem INSS/IRRF; 2ª até 20/12 com INSS e IRRF exclusivo (redução da Lei 15.270 não aplicada — conferir orientação da Receita). Cálculo em lote. PDF: recibo. |
| DP-07 | Rescisão: 10 modalidades (sem justa causa, pedido, justa causa, acordo 484-A, término, antecipada pelo empregador/empregado, indireta, culpa recíproca, falecimento). Aviso proporcional (Lei 12.506) e projeção (OJ 82); férias vencidas (em dobro se venceu o concessivo) e proporcionais + 1/3; 13º proporcional e indenizado; arts. 479/480; incidências por verba; multa do FGTS 40%/20%; saque e seguro-desemprego; prazo de 10 dias (art. 477 §6º). PDFs: TRCT e aviso prévio / pedido de demissão. “Efetivar” marca o desligamento. |
Fase 3 — admissão, afastamentos e eSocial
| # | Regra |
|---|---|
| DP-08 | Admissão: dependentes (IRRF exige CPF; a contagem do cadastro é atualizada sozinha); checklist de documentos por tipo de vínculo com anexo em Documentos › Pessoal; PDFs da ficha de registro (art. 41), contrato conforme o tipo, termo do vale-transporte e declaração de dependentes (modelos-base, revisar antes de assinar). |
| DP-09 | Afastamentos: atestado e acidente (empresa paga 15 dias, depois INSS; acidente com estabilidade de 12 meses — art. 118), maternidade/paternidade (Empresa Cidadã 180/20 dias), faltas legais do art. 473, serviço militar, suspensão e licença não remunerada. Mostra retorno e estabilidade e gera aviso na folha do mês. |
| DP-10 | Importar do eSocial: XMLs do S-2200 e S-2300, soltos ou no ZIP do “Download de eventos”. Converte a categoria em tipo de vínculo, traz dependentes, mostra prévia e pula quem já existe ou é de outro CNPJ raiz. O download direto pelo webservice do eSocial ficou para depois (exige CPF por trabalhador e assinatura XML com o certificado). |
Empresas do DP, vales e modelos do escritório
| # | Regra |
|---|---|
| DP-11 | Só empresas adicionadas: o seletor do DP mostra apenas as empresas incluídas em “Adicionar empresa ao DP” (as que já tinham funcionários entraram sozinhas). “Tirar do DP” só esconde: funcionários e cálculos ficam guardados. |
| DP-12 | Vales (VT, VR, VA): VT só para optantes, sugestão de 2 vales por dia trabalhado na escala do mês (sem domingos, feriados nacionais, folgas — sábado é folga em jornada de até 40 h sem sábado no horário —, férias e afastamentos); tarifa e descrição repetem o último mês. VR/VA repetem quantidade e valor. Recibo de entrega no modelo analítico, 2 por página, com valor por extenso. |
| DP-13 | Modelos do escritório: lista de frequência (horários do contrato no cabeçalho das colunas, dia marcado como Folga, Feriado, Férias ou Atestado/Afastado, quadro da empresa à direita); aviso de férias em 2 vias; recibo de férias com base de cálculo e eventos em colunas por mês do gozo (férias, 1/3, INSS e IRRF rateados pelos dias de cada mês). |
/api/dp/**.Gestão do escritório
Itens da análise de lacunas de 25/10/2026 que não dependem de API externa. Ficaram de fora, aguardando contrato/credenciais: robôs do Integra Contador (PGDAS-D, DCTFWeb), caixas postais da SEFAZ/prefeituras e WhatsApp oficial.
| # | Regra |
|---|---|
| GE-01 | Completar cadastro (Empresas › Completar cadastro, aviso no Painel): empresas ativas sem regime, sem responsável ou sem telefone/e-mail; seleção em lote para definir regime e responsável; “Sugerir regime pela Receita” lê a opção pelo Simples/MEI nos dados abertos (BrasilAPI → MinhaReceita), até 30 por vez, sempre com confirmação. Rotas /api/empresas/saneamento/**. |
| GE-02 | Guia pela obrigação: no detalhe da obrigação, “Enviar a guia ao cliente” cria uma comunicação tipo GUIA (pasta Comunicações, aviso no portal, rastreio de abertura e download) e marca a obrigação como enviada; o detalhe mostra se o cliente abriu. Lembrete às 08:20 na conversa do cliente para guia não aberta que vence nos próximos N dias (comunicacao.lembrete_dias, padrão 3), uma vez. Painel e Documentos › Comunicações › “Guias não abertas”, por vencimento. V41. |
| GE-03 | Processos e tarefas (menu Processos e tarefas, chave Pendências): modelos com checklist e prazo relativo (padrões: onboarding de cliente, abertura, baixa, alteração contratual; o escritório copia e personaliza). Iniciar para uma empresa cria os itens com prazo; item “pede ao cliente” vira pendência no portal e conta como feito quando o cliente responde. Progresso em %. Tarefas recorrentes (mensal, trimestral, anual) geradas às 06:40. V42. |
| GE-04 | Reforma tributária (Escrita fiscal › Reforma): leitura dos grupos IBSCBSTot e cClassTrib da NF-e; simulação por cliente — tributos sobre consumo de hoje (PIS, COFINS, ICMS, IPI, ISS ou DAS) × CBS/IBS estimados (débito sobre vendas e serviços prestados menos crédito sobre compras e serviços tomados, base sem ICMS/PIS/COFINS). Alíquotas na tabela fiscal_aliquota_reforma (2026 teste 0,9/0,1; 2033 estimativa 8,8/17,7), editáveis pelo administrador. V43. |
| GE-05 | Comercial (menu Comercial, chave Cobranças): proposta de honorários em PDF; contrato a partir de modelo com campos automáticos ({{RAZAO_SOCIAL}}, {{VALOR_MENSAL}}, {{INDICE}}…), PDF, “marcar enviado”, anexo do assinado (Documentos › Contratos), distrato com motivo e “Gerar honorário”. Assinatura eletrônica por provedor: a definir. Reajuste anual em lote com histórico (honorario_reajuste); as próximas cobranças saem com o valor novo. V44. |
| GE-06 | Registro de tempo e rentabilidade: menu Registro de tempo (toda a equipe; aceita 1:30, 1h30, 90 ou 1,5); Comercial › Rentabilidade: horas × honorário ativo × meses, custo da hora (comercial.custo_hora ou informado), margem, menor margem primeiro. |
| GE-07 | Verificação em duas etapas (Meu perfil): TOTP (RFC 6238) com QR para Google/Microsoft Authenticator ou Authy; segredo cifrado (AES-GCM, chave do cofre), 8 códigos de recuperação de uso único (BCrypt); no login por senha, desafio de 5 minutos e até 5 tentativas; desativar com a senha; administrador zera em Usuários. Login por certificado não pede código. V45. |
| GE-08 | Aceite do termo de privacidade registrado no servidor (usuário, empresa, versão, data e IP — tabela termo_aceite); o administrador em “Acessar como” não aceita pelo cliente. |
| GE-09 | Teste de restauração: scripts/testar-restauracao.sh [dump] sobe um Postgres temporário, restaura o dump (padrão: o mais recente de /opt/global-admin/copias) e confere migração e contagens, sem tocar no banco de produção. |
Contábil
Aba Contábil (grupo “Contábil, fiscal e DP”, chave de acesso CONTABIL): a contabilidade de cada empresa — plano de contas, lançamentos, extrato bancário com conciliação, fechamento do mês e relatórios.
| # | Regra |
|---|---|
| CTB-01 | Plano de contas por empresa. Botão “Criar plano de contas padrão” (~100 contas para micro e pequenas empresas: 1 Ativo, 2 Passivo com 2.3 Patrimônio líquido, 3 Receitas, 4 Custos, 5 Despesas). Contas de 4 níveis são analíticas (recebem lançamentos); as demais somam as filhas. A conta superior precisa existir e ser sintética; conta com lançamentos só muda de nome ou é desativada. |
| CTB-02 | Lançamentos em partida dobrada: data, conta a débito, conta a crédito (analíticas e ativas, diferentes), valor e histórico. |
| CTB-03 | Extrato OFX: escolha a conta do banco (Ativo, 1.1.1.x) e envie o .ofx do internet banking (SGML ou XML, até 5 MB). Movimentos já importados não se repetem (FITID). Cada item recebe a contrapartida; entrada gera D banco / C contrapartida e saída D contrapartida / C banco. |
| CTB-04 | Conciliação que aprende: a contrapartida escolhida fica guardada pela descrição (sem números e acentos); no próximo extrato o item já vem sugerido e marcado. Itens que não geram lançamento podem ser ignorados. |
| CTB-05 | Fechamento do mês: bloqueia incluir ou excluir lançamentos daquele mês. Só fecha com todo o extrato até o mês conciliado ou ignorado. Reabrir é possível (auditoria). |
| CTB-07 | Lançamentos automáticos do mês (Resumo do mês), no último dia da competência e com as contas do plano padrão: Folha (DP) — salários ou pró-labore contra INSS e IRRF retidos e salários/pró-labore a pagar, FGTS e encargo patronal; Fiscal — receitas do mês (vendas ou serviços) contra clientes, DAS do Simples, PIS/COFINS e, no fim do trimestre, IRPJ/CSLL; Depreciação — saldo de cada bem do imobilizado × taxa anual ÷ 12 (taxa por conta no Plano de contas; padrão 10% máquinas e móveis, 20% veículos e computadores). Gerar de novo substitui o que foi gerado para a mesma fonte e mês; mês fechado não aceita. Cada lançamento mostra a origem (folha, fiscal, depreciação). |
| CTB-06 | Relatórios (com impressão/PDF pelo navegador): balancete (saldo anterior, débitos, créditos e saldo, na natureza de cada grupo, com conferência débitos = créditos), DRE do período, balanço patrimonial na data (Ativo = Passivo + PL + resultado ainda não encerrado, com conferência) e razão da conta com saldo linha a linha. |
Banco (migrações V46, V50 e V51): contabil_conta, contabil_lancamento, contabil_extrato, contabil_regra, contabil_fechamento.
Societário e legalização
Aba Societário e legalização (grupo “Clientes”, chave SOCIETARIO). Abertura, alteração e baixa em andamento continuam nos modelos de “Processos e tarefas”; aqui fica o cadastro e o histórico.
| # | Regra |
|---|---|
| SOC-01 | Registro: capital social, natureza jurídica, NIRE, data de registro na Junta e observações. |
| SOC-02 | Quadro de sócios: nome, CPF/CNPJ, qualificação, participação (%), administrador, entrada e saída. “Importar da Receita” traz o QSA da consulta pública do CNPJ (documento mascarado), sem duplicar nomes. Aviso se a soma das participações dos sócios atuais não der 100%. |
| SOC-03 | Alvarás e licenças: alvará de funcionamento, Corpo de Bombeiros, Vigilância Sanitária, ambiental, conselho de classe, inscrições municipal/estadual e outras — número, órgão, emissão e validade. Situação: válida, vence em até 60 dias, vencida ou sem vencimento. |
| SOC-04 | Aviso de vencimento: todo dia às 07:15 equipe (Entrada) e cliente são avisados quando faltam 60, 30, 15, 7 e 0 dias (um aviso por marco; mudar a validade reinicia os avisos). Cron: app.societario.aviso-cron. |
| SOC-05 | Histórico de alterações concluídas (constituição, alteração contratual, consolidação, endereço, capital, sócios, atividade, baixa…), com nº de registro na Junta. Data futura é recusada. |
| SOC-06 | Tela inicial: licenças vencidas e vencendo de todas as empresas e a lista de empresas com nº de sócios, licenças e próximo vencimento. |
Banco (V46): societario_empresa, societario_socio, societario_licenca, societario_alteracao.
IRPF
Aba IRPF (grupo “Clientes”, chave IRPF) para os clientes cadastrados em Pessoas físicas.
| # | Regra |
|---|---|
| IR-01 | Campanha por exercício (até junho mostra o ano corrente; depois, o seguinte). “Abrir para todas” cria a declaração de cada pessoa ativa que ainda não tem; também dá para abrir uma por vez. |
| IR-02 | Cada declaração tem situação (aguardando documentos, documentos recebidos, em preparo, em conferência, transmitida, em malha, retificada, cancelada), responsável, lista de documentos (10 itens padrão, editável), honorário e se foi pago, resultado (restituir/pagar/sem imposto) com valor, nº do recibo e data de transmissão. |
| IR-03 | Marcar como transmitida ou retificada exige o nº do recibo. A data de transmissão é preenchida com o dia, se vazia. |
| IR-04 | Painel: prazo de entrega (último dia útil de maio — confira o edital do ano), transmitidas × total, honorários da campanha e a receber, filtros por situação e busca. |
| IR-05 | Carnê-leão: por pessoa e ano, rendimentos e deduções de cada mês → imposto pela tabela mensal da competência (até 04/2025: isenção R$ 2.259,20; de 05/2025: R$ 2.428,80; de 01/2026: redução da Lei 15.270/2025, que zera até R$ 5.000 e reduz até R$ 7.350). Usa o maior entre as deduções informadas e o desconto simplificado mensal. DARF 0190 vence no último dia útil do mês seguinte. Conferir no Carnê-Leão Web antes de emitir. |
Banco (V46): irpf_declaracao, irpf_carne_leao. Testes: TabelaIrpfMensalTest.
EMPRESAS recebeu SOCIETARIO e IRPF; quem tinha FISCAL recebeu CONTABIL. Ajuste por colaborador em Colaboradores.Escrita fiscal
Menu Escrita fiscal (chave “Escrita fiscal”, liberada para quem já tinha “Obrigações”): empresa + competência no topo e 7 sub-abas. Calcula para conferência; o valor oficial continua sendo o do PGDAS-D, SicalcWeb e DCTFWeb.
| # | Regra |
|---|---|
| FIS-01 | Resumo do mês: regime, CNAE, IE e município; saídas e entradas (NF-e/NFC-e/CT-e) com ICMS; NFS-e prestadas e tomadas; receita do mês, dos 12 meses anteriores e do ano; ICMS próprio (débito − crédito) para regime normal; obrigações da competência com situação; apurações salvas; certidões e validade. Alertas de sublimite (R$ 3,6 mi), limite do MEI (R$ 81 mil) e regime não informado. |
| FIS-02 | Notas: importação de XML (ou ZIP) de NF-e, NFC-e, CT-e e eventos de cancelamento. Entrada/saída pelo CNPJ (NF-e de entrada própria, tpNF=0, conta como entrada); repetidas são puladas; notas de outro CNPJ, recusadas. XML em Documentos › Fiscal › modelo › Entradas|Saídas › AAAA-MM. Resumo por CFOP e registro de entradas/saídas em PDF. |
| FIS-03 | Receitas do mês por atividade (anexo do Simples ou atividade do Presumido), com segregação de ICMS-ST, PIS/COFINS monofásico, ISS retido e exportação. “Puxar das notas” sugere: vendas (CFOP x.1xx) menos devoluções (1/2.201-202, 1/2.410-411), vendas com ST (x.4xx), exportação (7.xxx), transporte (x.35x) e NFS-e prestadas. |
| FIS-04 | Simples Nacional (LC 123/2006, anexos da LC 155/2016): faixa pelo RBT12, alíquota efetiva, repartição por tributo, exclusão do tributo segregado, ISS limitado a 5% (excedente para os federais), Fator R (folha ≥ 28% → Anexo III; folha do DP ou da configuração), RBT12 proporcional no 1º ano (art. 18 §2º), avisos de sublimite e limite. Memória de cálculo em PDF; vencimento dia 20. |
| FIS-05 | Lucro Presumido: PIS 0,65% e COFINS 3% cumulativos (exclusões automáticas: ICMS destacado — Tema 69 do STF —, ICMS-ST, IPI e monofásico; DARF 8109/2172, dia 25); IRPJ 15% + adicional de 10% acima de R$ 20 mil/mês e CSLL 9% no trimestre, presunção por atividade (8/12, 32/32, 16/32, 1,6/12…), outras receitas a 100%, retenções compensadas, quotas (mín. R$ 1.000; abaixo de R$ 2.000 quota única). LC 224/2025: +10% na presunção sobre a receita acima de R$ 1,25 mi no trimestre (IRPJ desde jan/2026, CSLL desde abr/2026; IN RFB 2.306/2026), com opção de desligar para cliente com liminar (ADI 7936). |
| FIS-06 | Retenções: IRRF 1,5% (profissionais) ou 1% (limpeza/segurança/mão de obra), CSRF 4,65%, dispensa até R$ 10; órgão federal 9,45% (serviços) e 5,85% (mercadorias, IN 1.234/2012); optante do Simples sem IRRF/CSRF; INSS 11% na cessão de mão de obra (Simples só no Anexo IV); ISS retido. |
| FIS-07 | Configuração por empresa: início de atividade, anexo padrão, atividade no Presumido, folha mensal média, alíquota do ISS e observações. Regime/CNAE/IE seguem na ficha fiscal da empresa. |
| FIS-08 | Reforma tributária: em 2026 CBS (0,9%) e IBS (0,1%) são só informativos na NF-e do regime normal; Simples e MEI ficam fora até 2027. |
| FIS-09 | Só documento autorizado: aceita nfeProc (NF-e 55 e NFC-e 65) e cteProc (CT-e 57) com protocolo de autorização cStat 100 ou 150; recusa XML sem protocolo, denegado/rejeitado, de modelo não suportado, malformado ou que não tenha a empresa como emitente ou destinatária (CT-e: também remetente, expedidor, recebedor ou tomador). A empresa é comparada pelo CNPJ com letras (alfanumérico). |
| FIS-10 | Eventos (procEventoNFe/procEventoCTe) só com retorno registrado (cStat 135, 136 ou 155). Cancelamento (110111) e cancelamento por substituição da NFC-e (110112) marcam a nota como cancelada; se o evento chegar antes da nota, fica guardado e é aplicado quando ela for importada. Evento repetido (mesma chave, tipo e sequência) não duplica. |
| FIS-11 | Lote e itens: cada envio vira um lote com o resultado de cada arquivo (importado, já existia, evento, resumo ou erro com o motivo). Cada nota e cada evento são gravados na própria transação: um arquivo ruim não desfaz os outros. Reenvio é “já existia”, sem erro (e completa o protocolo e o hash das notas antigas). |
| FIS-12 | Segurança: sem DTD nem entidades externas (XXE); XML até 5 MB; ZIP até 50 MB, 5.000 XMLs e 200 MB descompactado (para no primeiro XML acima do limite, contra zip bomb); o caminho das entradas do ZIP é descartado (só o nome); o conteúdo é conferido (não só a extensão); nenhum XML vai para o log. |
| FIS-13 | XML original guardado sem alteração em Documentos › Fiscal (nota) ou Fiscal › Eventos, com SHA-256 no banco. Aba Documentos fiscais: arrastar e soltar, filtros (modelo, período, status, emitente, destinatário, chave), detalhe com protocolo e eventos, download do XML da nota e de cada evento, e o histórico de importações. |
| FIS-14 | Busca na SEFAZ (aba própria): web service NFeDistribuicaoDFe do ambiente nacional com o certificado A1 da empresa (ou de outra do mesmo CNPJ raiz) com a senha guardada — o mesmo da busca de NFS-e. Rotina diária no horário configurado (administrador), busca manual de uma, várias ou todas as automáticas, histórico das execuções. Controle do NSU por empresa; respeita a regra de 1 hora sem nova consulta quando não há novidade (137 ou ultNSU = maxNSU) ou após consumo indevido (656). Notas completas e eventos entram como origem DISTRIBUICAO_DFE pelo mesmo importador; resumos (resNFe) ficam “aguardando manifestação” — o sistema não manifesta. NFC-e não é distribuída por esse serviço. Precisa da UF da empresa no cadastro. |
| FIS-15 | Leitor de XML (aba própria, sem escolher empresa): abre NF-e, NFC-e, CT-e e eventos — inclusive sem protocolo, com aviso — mostrando emitente, destinatário, itens, impostos, totais e protocolo; converte para PDF de espelho (não substitui o DANFE) e planilha CSV (itens de uma ou de todas as notas lidas). Nada é gravado. Rotas: POST /api/fiscal/leitor e /api/fiscal/leitor/pdf. |
| FIS-16 | Conferência do mês (aba Documentos fiscais), só com regras objetivas, sem IA: nas notas emitidas pela empresa, CFOP no sentido errado (saída com 1/2/3, entrada própria com 5/6/7) e CFOP estadual (1/5) com participante de outra UF ou interestadual (2/6) da mesma UF; em todas, nota sem protocolo gravado e mesmo número/série/emitente com chaves diferentes; aviso das notas que só chegaram como resumo da SEFAZ. Na nota recebida o CFOP é o do fornecedor, por isso fica fora. Baixar XML (ZIP) por empresa e período (de/até, até 24 meses, com atalhos: este mês, mês passado, últimos 3 meses, este ano, ano passado), separado por mês (AAAA-MM/NF-e/Saídas, Entradas, Canceladas e Eventos), com a opção de levar só as notas baixadas da SEFAZ — nas abas Notas, Documentos fiscais e em cada empresa da Busca na SEFAZ. O ZIP é enviado em streaming (o servidor não o guarda na memória). |
| FIS-17 | Situação cadastral (CNPJ) (Clientes › Situação cadastral, chave Empresas): consulta pública dos dados da Receita (BrasilAPI, CNPJ.ws, ReceitaWS, Minha Receita) de cada empresa ativa, comparada com a verificação anterior — situação cadastral, razão social, CNAE, endereço, sócios e Simples/MEI (acento e maiúscula não contam; campo que a fonte não trouxe não é mudança). Mudança ou situação diferente de ATIVA avisa a equipe da contabilidade e atualiza a situação no cadastro. PDF de cada consulta em Documentos › Receita Federal › Situação Cadastral (relatório do sistema com a fonte; o comprovante oficial exige captcha e não é baixado). Manual (uma, várias ou todas, em segundo plano com pausa entre consultas) ou semanal às segundas no horário configurado pelo administrador. Download do PDF, histórico e ZIP com o PDF mais recente de cada empresa. Banco: V60 (cnpj_verificacao). |
| FIS-18 | Receitas separadas por item (“Puxar das notas”): cada item das NF-e/NFC-e de saída é classificado pelos códigos da própria nota — ICMS-ST já recolhido quando CSOSN 500 (Simples) ou CST 60 (regime normal), em que a empresa é a substituída; PIS/COFINS monofásico quando o CST de PIS ou COFINS é 04 (revenda a alíquota zero). As vendas viram até quatro linhas: normais, só ICMS-ST, só monofásico e ICMS-ST + monofásico, que o Simples (segregação) e o Presumido (exclusão do monofásico no PIS/COFINS) já usam. Devoluções são descontadas nessa ordem. Notas importadas antes foram reclassificadas a partir do XML guardado; sem XML, vale a regra antiga do CFOP (x.4xx = ICMS-ST). Substituto (CSOSN 201/202/203, CST 10/30/70) não entra como ICMS já recolhido. |
fiscal_config, fiscal_nota, fiscal_receita, fiscal_apuracao) e V59 (protocolo, emitente/destinatário, hash e origem em fiscal_nota; fiscal_evento, fiscal_importacao_lote, fiscal_importacao_item, fiscal_dfe_sincronizacao, fiscal_dfe_execucao, fiscal_dfe_resumo). As migrações rodam sozinhas (Flyway) ao subir o backend. Testes com XML fictícios: DocumentoFiscalXmlTest. Rotas em /api/fiscal/**. Lucro Real ainda não tem apuração.Novas funcionalidades (fases 1 a 6)
Entregas feitas a partir da análise comparativa com o mapa de funcionalidades do Domínio Contábil (só a lista de funcionalidades foi usada como referência; nenhuma tela, texto ou código de terceiros). Cobertura atual: 77% — 71 itens existem, 26 parciais, 12 ainda não existem, 7 não se aplicam. Banco: migrações V61 a V75, em produção desde 07/11/2026.
Fase 1 — Base parametrizável
| # | Regra |
|---|---|
| LAC-01 | Tabelas legais do DP por vigência (data inicial, não mais por ano): corrige os anos em que o IRRF mudou no meio do ano (jan/2024 e jan–abr/2025). V61. |
| LAC-02 | Fechamento fiscal por empresa e competência; reabrir exige motivo e fica na auditoria. V62. |
| LAC-03 | Impostos federais em atraso (Escrita fiscal › Impostos em atraso): multa de 0,33% ao dia limitada a 20% e juros SELIC (série 4390 do Banco Central, meses fechados) + 1% no mês do pagamento (Lei 9.430/1996, arts. 5º e 61), com PDF da memória de cálculo. V63. |
| LAC-04 | Fator R automático no Simples: folha dos 12 meses do DP ÷ receita bruta; ≥ 28% → Anexo III. |
Fase 2 — Folha e eSocial
| # | Regra |
|---|---|
| LAC-05 | Rubricas do escritório com incidências de INSS, FGTS e IRRF e bases separadas no cálculo da folha. V64 e V68. |
| LAC-06 | Cargos (CBO) e sindicatos (piso e data-base), com aviso de salário abaixo do piso. V65. |
| LAC-07 | eSocial S-1010 (tabela de rubricas) gerado e validado no XSD oficial S-1.3, sem transmissão. |
| LAC-08 | Provisão de férias e 13º com FGTS e lançamento contábil (fonte PROVISAO). V66. |
| LAC-09 | RPA de autônomo (INSS, IRRF, ISS) com recibo; informe de rendimentos anual em PDF; conferência da guia FGTS/DCTFWeb × folha. V67. |
Fase 3 — Contabilidade anual
| # | Regra |
|---|---|
| LAC-10 | Aba Encerramento anual: responsáveis (contador/CRC, responsável legal, NIRE), históricos e lançamentos padrões, código do plano referencial por conta, zeramento do resultado, Livro Diário com termos de abertura e encerramento, análises vertical/horizontal e índices, DFC (método indireto) e importação de lançamentos por CSV. V69. |
Fases 4 e 5 — Fiscal e escritório
| # | Regra |
|---|---|
| LAC-11 | Anual e livros (Escrita fiscal): participantes das notas, base da DEFIS/DASN-SIMEI e livro de ISS. |
| LAC-12 | Conclusão automática: gravar a apuração do mês muda a obrigação de PENDENTE para APURADA. |
| LAC-13 | Honorários variáveis por nº de notas, funcionários e lançamentos (Comercial) e modelos societários com campos da empresa e dos sócios, em PDF. V70. |
Fase 6 — Bases, gestão e integrações (V71–V75)
| # | Regra |
|---|---|
| LAC-14 | Simples Nacional por vigência: anexos, faixas e repartição no banco (fiscal_simples_tabela); o DAS usa a tabela da competência. Carga inicial = LC 155/2016, com teste que prova o mesmo DAS de antes. A tabela vigente aparece na aba Simples Nacional. |
| LAC-15 | Acumuladores (Escrita fiscal › Acumuladores): CFOP + operação → venda, exportação, transporte, devolução ou “não é receita”. Regras da empresa valem antes das padrão; “x” é curinga (59xx). As regras padrão reproduzem as antigas em todos os CFOPs. |
| LAC-16 | Contábil › Gestão e demonstrações: bens do imobilizado com depreciação bem a bem (residual, depreciação anterior, baixa) — os lançamentos automáticos passam a usar os bens; centros de custo (escolhidos no lançamento) com resultado por centro; orçamento orçado × realizado (cópia do ano anterior com reajuste); DMPL, DLPA e DVA (CPC 09), com conferência contra o PL do balanço; contas de integração por empresa; plano referencial carregado do arquivo oficial, com validação do vínculo. |
| LAC-17 | Baixa de guias (janela da obrigação): data, principal, multa e juros; opcionalmente lança o pagamento (passivo do tributo e juros/multa contra o banco). O estorno volta à situação anterior. |
| LAC-18 | Auditoria antes/depois (Auditoria › Alterações de dados, administrador): gatilho no banco grava os campos alterados em receitas, apurações, configuração fiscal, acumuladores, funcionários, rubricas, folhas, lançamentos, contas e bens. |
| LAC-19 | DP em grupo: variáveis da folha por planilha CSV (cpf; horasExtras50; faltasDias…) e reajuste coletivo por sindicato ou cargo, com simulação e retroativo estimado. |
| LAC-20 | Pedidos ao DP pelo portal: o cliente pede admissão, férias, rescisão, variáveis e afastamento; a equipe aprova, conclui ou recusa (DP › Solicitações do portal). Aprovar não altera o DP sozinho. |
| LAC-21 | Integrações e chaves (menu Administração): mostra o que falta configurar em cada serviço externo — SERPRO (DAS pelo PGDASD e DARF pelo SICALC), manifestação do destinatário da NF-e (evento gerado e assinado com o A1 da empresa), emissão da NFS-e do escritório na Sefin Nacional (DPS assinada) e base da EFD-Reinf por prestador. Tudo desligado até configurar. |
| LAC-22 | Acabamento visual com a mesma paleta: sombras suaves, abas e tabelas com realce, cabeçalho de página com destaque, atalhos com relevo. |
Ainda não feito
- Dependem de arquivos oficiais (download a autorizar): geradores ECD, ECF e EFD-Contribuições, XML dos eventos da Reinf, validação da DPS no XSD e a tabela oficial do plano referencial.
- Dependem de contrato ou chave: SERPRO (Integra Contador), certificado do escritório para a NFS-e, ligar o envio da manifestação.
- Sob demanda: Lalur/e-Lacs, apuração de ICMS e EFD ICMS/IPI, estoque e Bloco K, SST, notas explicativas, demais eventos do eSocial.
Transparência (CGU)
Integração com a API de dados do Portal da Transparência (CGU). Menu Transparência (CGU), chave “Empresas e documentos”. A chave de acesso fica só no servidor (PORTAL_TRANSPARENCIA_CHAVE) e vai no header chave-api-dados.
| # | Regra |
|---|---|
| TR-01 | Conformidade das empresas: resumo do CNPJ (pessoa-juridica) e, quando constar, o detalhe no CEIS (inidôneas e suspensas), CNEP (Lei Anticorrupção) e CEPIM (entidades impedidas); acordos de leniência. Situação: nada consta, atenção (sanção encerrada, leniência ou sócio PEP) ou alerta (sanção vigente). |
| TR-02 | PEP dos sócios: cada sócio pessoa física do QSA é buscado pelo nome na lista de PEP; só vale o nome idêntico e, como QSA e portal mostram os mesmos 6 dígitos centrais do CPF, a coincidência confirma a pessoa (homônimos são descartados). Sem documento, aparece como “possível PEP”. Pessoas físicas vinculadas à empresa são consultadas pelo CPF completo, inclusive no CEIS/CNEP. |
| TR-03 | Prova de diligência: toda verificação fica gravada com data, autor e resultado (histórico na tela) e na auditoria (Lei 9.613/1998). Rotina automática toda segunda às 05:00 (madrugada: limite maior da API); alerta novo vira aviso no sino da equipe. “Verificar todas” roda em segundo plano. |
| TR-04 | Pessoas (PEP): pessoas físicas do cadastro, consultadas pelo CPF na lista de PEP e no CEIS/CNEP. |
| TR-05 | Governo federal: contratos (contratos/cpf-cnpj), pagamentos recebidos no ano (fase pagamento, por órgão), notas fiscais emitidas para órgãos federais e convênios (filtro pelo nome do convenente, conferido pelo CNPJ). Serve para conferir as retenções de IR, CSLL, PIS e COFINS (IN RFB 1.234/2012). Cache de 12 h. |
| TR-06 | Consulta avulsa de qualquer CNPJ ou CPF (fornecedor, futuro cliente), sem gravar além da auditoria. Benefícios sociais de funcionários não são consultados (LGPD). |
| TR-07 | Limite da API: 90 consultas/min (6h–24h) e 300/min de madrugada; as chamadas são espaçadas em 700 ms e o HTTP 429 é repetido com espera. |
transparencia_verificacao, transparencia_cache). Rotas em /api/transparencia/**.Site público
A página inicial (/) segue um modelo institucional com faixas claras e escuras.
| # | Regra |
|---|---|
| SITE-01 | Menu transparente sobre o topo (sólido ao rolar). Topo com carrossel das fotos da equipe (troca a cada 7 s, fade e zoom lento, pausa com a aba oculta, sem zoom para quem pede menos movimento), título, chamadas e destaques. |
| SITE-02 | Seções: Sobre, diferenciais, áreas de atuação, notícias e indicadores do dia (RF-12/13), contato e rodapé com navegação e links úteis. |
| SITE-03 | Canais oficiais fixos no site (dados-global.ts): globalcontabilidade.cnt.br, bezerracontabilidadedp@gmail.com, @global_cont, LinkedIn e WhatsApp (61) 3487-3081; o que faltar vem de Canais de contato (GET /api/publico/contato). |
| SITE-04 | Formulário de contato sem servidor: monta a mensagem e abre o WhatsApp (ou e-mail). Botão flutuante do WhatsApp. |
Trabalhe conosco, ajuda, currículos e atendimento online
Páginas abertas (sem login): inicial, Quem somos, Trabalhe conosco, Central de ajuda e Privacidade. O menu do topo fica fixo e acompanha a rolagem (mais baixo depois de rolar), com o ícone ? para a ajuda.
| # | Regra |
|---|---|
| SITE-01 | Inicial: além de serviços, notícias e contato, tem “Conheça nosso time” e “Histórias de quem confia na Global” (carrosséis componentizados com Embla — components/carrossel: loop infinito, 3/2/1 cartões, deslizar no celular com os vizinhos aparecendo, cartão do meio maior e com sombra, transição suave, setas ao lado dos cartões, pontos em pílula, ← → no teclado e troca a cada 7 s que pausa com mouse/foco e respeita “menos movimento”; dados em publico/conteudo-site.ts) e “Segurança e confiança” (CRC, LGPD, acesso seguro, certificados cifrados). |
| SITE-02 | Conteúdo ilustrativo: equipe e depoimentos são fictícios até a Global ter fotos e relatos reais autorizados; enquanto CONTEUDO_ILUSTRATIVO = true (components/publico/conteudo-site.ts) as seções mostram a etiqueta “ilustrativo” — depoimento inventado apresentado como real é propaganda enganosa (CDC art. 37, CONAR). |
| SITE-03 | Quem somos (/quem-somos): reservada, mostra “Em breve”. |
| SITE-04 | Trabalhe conosco (/trabalhe-conosco): nome, e-mail, telefone, cidade/UF, área de interesse, formação, LinkedIn, mensagem e currículo (PDF, DOC ou DOCX até 5 MB, tipo conferido pelo conteúdo do arquivo) + concordância com o uso dos dados. Proteções: campo-isca contra robôs e no máximo 3 envios por IP por hora. Rota: POST /api/publico/candidaturas. |
| SITE-05 | Currículos recebidos (Administração, só administradores): cada envio avisa os administradores na Entrada. Na tela: filtro por situação (nova, em análise, entrevista, arquivada), contatos, Ver (abre o PDF no navegador e passa a “em análise”), baixar e excluir de vez (apaga também o arquivo — use quando o candidato pedir ou ao fim do processo, LGPD). Download e exclusão vão para a auditoria. |
| SITE-06 | Central de ajuda (/suporte): perguntas frequentes com busca (acesso ao portal, documentos e guias, certificado digital, empresa e serviços), canais de atendimento e “Abrir um chamado” (abre o WhatsApp com a mensagem pronta). |
| SITE-07 | Atendimento online (/atendimento, botão na seção Contato): antes da conversa a pessoa informa nome e telefone e concorda com o uso dos dados (LGPD); o contato é gravado na hora, então a equipe consegue ligar mesmo se o assistente falhar. A assistente virtual (DeepSeek) faz o primeiro atendimento: identifica se é cliente, quer abrir empresa ou outro assunto, indica o link certo do site (portal, serviços, ajuda, trabalhe conosco, WhatsApp) e encaminha para a equipe em reclamação, cobrança, notificação da Receita, prazo vencendo hoje, pedido para falar com uma pessoa ou dúvida repetida. Recusa em uma frase assuntos fora do escritório. Não dá parecer, não calcula impostos e não pede senha, certificado ou dados bancários. Respostas curtas (até 350 tokens). |
| SITE-08 | Custo e abuso: até 5 atendimentos por IP por hora, 12 mensagens por atendimento (400 caracteres cada, histórico das últimas 10), conversa válida por 6 h e teto diário (ATENDIMENTO_MAX_POR_DIA, padrão 400 mensagens). No limite, sem chave ou com erro da DeepSeek, a tela diz que a equipe vai ligar e o contato fica marcado para retorno. Chave própria em ATENDIMENTO_DEEPSEEK_API_KEY (vazia = usa a do assistente interno). O texto da conversa não é guardado no servidor, só o contato e o resumo. |
| SITE-09 | Contatos do site (Administração, só administradores): cada atendimento iniciado e cada encaminhamento avisam os administradores na Entrada. Na tela: nome, telefone (ligar ou WhatsApp), setor, resumo feito pela assistente, motivo (passou para a equipe, sem resposta, limite), situação (novo, em contato, resolvido, descartado) e excluir de vez (LGPD). Rotas: POST /api/publico/atendimento, POST /api/publico/atendimento/mensagem, GET/PUT/DELETE /api/contatos-site. |
Banco (migrações V47 e V54): candidatura e atendimento_site. Testes: CandidaturaServiceTest e AtendimentoSiteServiceTest.
Portal da empresa
A empresa cliente entra no Global Admin e vê só os próprios dados: documentos liberados, pendências, relações de faturamento e uma conversa direta com a contabilidade. Quem libera tudo é a contabilidade, na página da empresa → aba Acesso do cliente. Regras de mensagens e notificações herdadas do pet-adaca.
Perfis e o que cada um faz
| Perfil | No portal |
|---|---|
| Administrador | Tudo o que a contabilidade faz, em todas as contabilidades; responde qualquer conversa. |
| Contabilidade | Libera e bloqueia o acesso das empresas dela, define senha, liga o login por certificado, escolhe as pastas visíveis e responde as conversas dessas empresas. |
| Empresa (cliente) | Consulta e baixa documentos das pastas liberadas, envia arquivos, vê pendências e relações da própria empresa e conversa com a contabilidade. Não cria, renomeia, move nem exclui nada. |
Regras de negócio
| # | Regra |
|---|---|
| RN-01 | Só a contabilidade da empresa (ou um administrador) libera o acesso. O login criado é sempre do perfil Empresa e fica preso àquela empresa. |
| RN-02 | Senha forte obrigatória (10+ caracteres com maiúscula, minúscula, número e símbolo). O sistema sugere uma senha aleatória; o cliente recebe por e-mail só o login — a senha é passada por canal seguro e trocada em Minha conta. |
| RN-03 | Bloquear um acesso encerra na hora as sessões abertas daquele usuário. O histórico (mensagens, envios, auditoria) é preservado. |
| RN-04 | Login com certificado digital por empresa: começa desligado. Só pode ser ligado se houver ao menos um login ativo; o e-CNPJ entra como o usuário titular (o login ativo mais antigo). Usuários com CPF cadastrado também entram com o e-CPF, desde que a empresa tenha o certificado liberado. |
| RN-05 | Pastas começam fechadas para o cliente. Liberar uma pasta libera também as subpastas (herança). Uma pasta liberada por herança só é fechada fechando a pasta de cima. |
| RN-06 | Na pasta principal (raiz), o cliente vê apenas os arquivos que a própria empresa enviou. Ele pode enviar arquivos para a raiz ou para uma pasta liberada. |
| RN-07 | Pasta ou documento que o cliente não pode ver responde “não encontrado” (não revela que existe). |
| RN-08 | Cada empresa tem uma conversa com “a contabilidade”. Todos os usuários do cliente veem a mesma conversa; qualquer pessoa da equipe da contabilidade (e os administradores) responde. |
| RN-09 | Abrir a conversa marca como lidas as mensagens do outro lado; responder também. O remetente vê ✓ (enviada) ou ✓✓ (lida). |
| RN-10 | Cada mensagem gera aviso no sino do outro lado. E-mail só na primeira de uma sequência: no máximo um a cada 15 minutos por lado da conversa, para não lotar a caixa. |
| RN-11 | Mensagens de 1 a 4.000 caracteres, só texto (sem HTML). A tela mostra as 300 mais recentes. |
| RN-12 | O sino guarda as 200 notificações mais recentes por usuário; o histórico permanente é a auditoria. |
| RN-13 | Arquivo novo visível ao cliente = mensagem automática na conversa da empresa, com o botão “Abrir arquivo” (link /arquivos/{id}): documento enviado pela equipe numa pasta liberada, PDF de pendência nova, relação de faturamento criada ou assinada, documento assinado e boleto emitido. Arquivo em pasta fechada não gera mensagem. |
| RN-14 | O link abre a página do arquivo (PDF e imagem com pré-visualização, Baixar, Imprimir). O servidor confere o acesso: o cliente só abre o que está nas pastas liberadas da própria empresa. |
| RN-15 | Empresa nova já nasce com login do cliente: e-mail da empresa (se válido e livre) ou um endereço interno {cnpj}@cliente.invalid, que nunca recebe e-mail. A senha é provisória e aleatória (ex.: aB3d-9kQx-7Pm2), uma por empresa, mostrada uma única vez a quem cadastrou (copiar/anotar). Não existe senha padrão igual para todos. |
| RN-16 | O cliente titular entra digitando o CNPJ (com ou sem pontuação) no lugar do e-mail. No primeiro acesso com senha provisória, o sistema só libera depois que ele cria a própria senha. Toda senha definida por outra pessoa (cadastro ou “Redefinir senha”) é provisória. |
| RN-17 | Excluir empresa remove junto o login criado automaticamente, desde que o cliente nunca tenha entrado; se já entrou, bloqueie o acesso ou inative a empresa. |
| RN-18 | Entrar como (só administradores, em Usuários ou na aba Acesso do cliente): o administrador vê o sistema exatamente como o usuário, sem saber a senha dele. Faixa amarela fixa com “Voltar para a minha conta”; vale por até 2 horas; não funciona com outro administrador; não permite trocar a senha do usuário; sair encerra só a sessão do administrador. Tudo vai para a auditoria em nome do administrador (“Fulano (como cliente@…)”). Não existe senha mestra: uma senha única que abrisse qualquer conta seria uma porta dos fundos. |
| RN-19 | Meu perfil (clicar no nome → Meu perfil): nome, e-mail, CPF e telefone/WhatsApp. Administrador altera na hora; os demais enviam para análise — os administradores recebem aviso na Entrada e aprovam ou recusam (com motivo) em Usuários → Alterações de cadastro; o usuário é avisado. Trocar e-mail ou CPF encerra as sessões (entra de novo). Tudo na auditoria. |
| RN-20 | Acessar como (botão na barra superior, só administradores): busca qualquer usuário (não administrador) e entra como ele; usuário inativo pode ser reativado e acessado na hora; empresa sem login ganha o acesso ali mesmo, ativo ou bloqueado (senha provisória exibida uma vez). Mesmas regras e auditoria de RN-18. |
| RN-21 | Solicitar documento (tela inicial, Mensagens e página da empresa): escolhe o documento (sugestões rápidas), prazo e detalhes; a mensagem sai pronta com os dados da empresa (razão social, CNPJ, contabilidade). Enviar pelo WhatsApp (abre o wa.me com o texto; equipe → telefone da empresa, cliente → WhatsApp da Global) ou Abrir no chat (texto já na caixa de mensagem para revisar). A equipe pode registrar a solicitação como pendência. |
| RN-22 | Resposta automática no chat: quando o cliente escreve, recebe “Recebemos sua mensagem e enviamos sua solicitação para o departamento responsável. Assim que tivermos uma resposta, avisamos você por aqui.” — no máximo uma vez a cada 4 horas por conversa (não repete a cada mensagem seguida); só no chat, sem e-mail. |
| RN-23 | Tela inicial: boas-vindas com saudação e resumo do dia, atalhos por perfil e o cartão da Global com os canais de contato (WhatsApp, Instagram, LinkedIn, telefone fixo, e-mail, site), editados pelo administrador ou pela equipe da contabilidade na modal “Canais de contato” do menu lateral (o cartão atualiza na hora; o cliente não edita). |
Quando o sino toca
| Evento | Quem é avisado |
|---|---|
| Mensagem do cliente | Equipe da contabilidade da empresa + administradores (e e-mail da Global) |
| Mensagem da contabilidade | Usuários do cliente (e e-mail para cada um) |
| Documento enviado pelo cliente | Equipe da contabilidade |
| Documento enviado pela equipe numa pasta liberada | Usuários do cliente (numa pasta fechada, ninguém é avisado) |
| Pasta liberada | Usuários do cliente |
| Pendência criada | Equipe e usuários do cliente |
| Pendência na Receita (rotina do e-CAC) | Equipe da contabilidade |
| Acesso liberado | O novo usuário (boas-vindas + e-mail com o login) |
O sino soma notificações não lidas e mensagens não lidas, atualiza a cada 30 segundos (só com a aba visível) e ao trocar de página. Clicar numa notificação marca como lida e abre a tela certa.
Fluxos
Liberar o portal para uma empresa
- Contabilidade abre Empresas → empresa → Acesso do cliente e clica em Liberar acesso.
- Informa nome, e-mail e (opcional) CPF; usa a senha sugerida ou define outra.
- O cliente recebe o e-mail “Seu acesso foi liberado” com o login; a senha vai por canal seguro.
- Opcional: liga Certificado digital (e-CNPJ) para entrar sem senha.
- Liga as Pastas liberadas que o cliente deve ver (o cliente é avisado no sino).
Cliente no dia a dia
- Entra com e-mail e senha ou com o certificado; cai no Painel com atalhos para documentos e mensagens.
- Meus documentos: navega nas pastas liberadas, baixa e envia arquivos (a equipe é avisada).
- Mensagens: conversa com a contabilidade; respostas aparecem sozinhas (atualização a cada 8 s) e no sino.
- Pendências e Relações: só as da própria empresa.
Equipe atendendo
- Mensagens mostra a caixa de entrada com as conversas mais recentes e o número de não lidas; a busca encontra qualquer empresa para iniciar uma conversa.
- Pela página da empresa, o botão Mensagens abre a conversa dela.
- Na aba Documentos, o ícone de olho mostra e alterna o que está visível ao cliente.
Endpoints
| Rota | Quem |
|---|---|
GET /api/empresas/{id}/acesso · POST …/acesso/usuarios · PUT …/acesso/usuarios/{u} · PUT …/acesso/usuarios/{u}/senha · PUT …/acesso/certificado · PUT …/acesso/pastas/{p} | Administrador e Contabilidade (empresas do seu escopo) |
GET /api/avisos · POST /api/avisos/{id}/lido · POST /api/avisos/lidos | Todos (sempre do próprio usuário) |
GET/POST /api/mensagens/conversa (equipe: ?empresa=ID; cliente: sempre a própria empresa) | Todos |
GET /api/mensagens/caixa | Administrador e Contabilidade |
Banco (migração V12)
pasta.liberada_cliente, empresa.acesso_certificado, aviso (sino), conversa (uma por empresa) e mensagem (com do_cliente e lida_em).
Assistente de dúvidas (IA)
Chat flutuante no canto inferior direito de todas as telas, especialista em documentos de contabilidade e dúvidas simples (guias, prazos, obrigações e uso do sistema). Usa a API da DeepSeek (deepseek-chat, compatível com OpenAI). Substituiu o antigo bot do Telegram, removido em 17/10/2026.
| # | Regra |
|---|---|
| RIA-01 | Disponível para todos os perfis logados (administrador, contabilidade e cliente). Sugestões rápidas diferentes para a equipe e para o cliente. |
| RIA-02 | A chamada à DeepSeek sai só do backend; a chave nunca vai ao navegador. Sem DEEPSEEK_API_KEY o assistente aparece como “não ativado”. |
| RIA-03 | Instruções fixas: responde em português, de forma curta; não inventa valores, alíquotas ou datas que dependam do caso; orienta confirmar com a contabilidade em Mensagens; recusa assuntos fora de contabilidade/sistema; nunca pede senha nem senha de certificado; não tem acesso aos dados da empresa. |
| RIA-04 | Conversa guardada só na aba do navegador (sessionStorage); o servidor não grava perguntas nem respostas. Envia no máximo as 16 últimas mensagens, até 2.000 caracteres cada. |
| RIA-06 | Viés contábil: toda pergunta é respondida pela ótica contábil, fiscal, trabalhista ou documental; perguntas gerais ligadas a dinheiro ou empresa (comprar carro, contratar, viajar a trabalho, investir) viram orientação contábil e terminam com convite para falar com a Global. Assunto sem ligação nenhuma é recusado em uma linha, oferecendo ajuda contábil. |
| RIA-07 | Dados da Global: a cada pergunta o assistente recebe os canais de contato cadastrados (Canais de contato), os dados cadastrais da empresa do cliente (razão social, CNPJ, atividade, cidade) e a base de conhecimento — texto de até 8.000 caracteres editado pelo administrador no botão Ensinar o assistente (ícone de livro no topo do chat): serviços, horários, prazos internos, regras do escritório. Alteração auditada (ASSISTENTE_CONHECIMENTO). Rotas: GET/PUT /api/assistente/conhecimento (administrador). |
| RIA-05 | Limite de custo: ASSISTENTE_MAX_POR_HORA perguntas por usuário por hora (padrão 30). Erros da DeepSeek (chave recusada, sem saldo, ocupado) viram mensagens amigáveis. |
Rotas e configuração
| Item | Uso |
|---|---|
GET /api/assistente | {configurado} — se a chave existe. |
POST /api/assistente | {mensagens:[{papel,texto}]} → {resposta}. Qualquer usuário logado. |
DEEPSEEK_API_KEY | Chave da plataforma platform.deepseek.com. Só no .env. |
DEEPSEEK_MODELO · ASSISTENTE_MAX_POR_HORA | Modelo (padrão deepseek-chat) e limite por usuário. |
bot_*, migrações V8–V10) continuam no banco como histórico, sem uso. TELEGRAM_TOKEN ficou só na VPS para os alertas de backup e monitoramento da infraestrutura.Camadas de segurança
Autenticação
BCrypt (custo 12), política de senha forte, login por certificado ICP-Brasil com desafio de uso único.
Sessão
JWT em cookie httpOnly, SameSite=Strict, Secure em HTTPS; revogação por versão de token (logout, troca de senha/perfil).
Força bruta
Bloqueio de conta após 5 erros (15 min) + limite por IP (20 tentativas/15 min).
CSRF e cabeçalhos
Double-submit cookie; CSP, X-Frame-Options DENY, nosniff, HSTS no nginx.
Autorização
Três perfis; escopo por contabilidade/empresa em todos os serviços; recurso alheio responde 404.
Arquivos
Tipo validado pelos bytes, limite 10 MB, nomes aleatórios, servidos com CSP sandbox; XML sem DOCTYPE (anti-XXE).
Certificados
Cadeia PKIX até as raízes do ITI, revogação (LCR/OCSP), chave privada nunca no servidor.
Auditoria
Logins (sucesso/falha), documentos, assinaturas, e-CAC e testes de envio, com IP real (X-Real-IP só de proxy interno).
Infraestrutura
Banco e API sem porta pública; containers não-root com limite de memória; segredos só no .env e em secrets/ (somente leitura).
Integrações
APIs externas só pelo backend (validação, cache, limite); mTLS com e-CNPJ no SERPRO.
Dois fatores
TOTP com segredo cifrado (AES-GCM), 8 códigos de recuperação e troca obrigatória de senha provisória.
Teste de segurança — 29/10/2026
Revisão do código do backend e do frontend e testes externos não destrutivos contra a VPS (sem gravar nem apagar dados).
| Item | Como foi testado | Resultado |
|---|---|---|
| SQL injection | Varredura de todo SQL montado com + ou formatted(); sondas com ' OR '1'='1 e ';-- na rota pública de protocolos e no login da documentação. | ✅ Seguro. Todos os valores vão como parâmetro (?); colunas dinâmicas vêm de listas fixas no código; as sondas voltam 404/400/401 sem erro de SQL. |
| Portas abertas | Conexão TCP em 52 portas comuns (bancos, Redis, Docker, RabbitMQ, Elasticsearch, APIs internas). | ✅ Só 80, 443 e 8443–8447 (HTTPS pelo nginx). PostgreSQL, Redis, Docker e as APIs (8080/8095) fechados. ⚠ 8444 abre, mas responde 502 (GA-503). |
| Rotas sem login | Leitura do SecurityConfig e chamadas a /actuator, /v3/api-docs, /.env, /.git/config, /api/usuarios, /api/empresas. | ✅ Negado por padrão; só login, saúde, notícias, contato, candidatura, atendimento e o quadro da documentação são públicos. ⚠ O pet-adaca (8443) publica /v3/api-docs sem login (GA-502). |
| Força bruta e IP | Limites dos logins (sistema, documentação, app de entregas), candidatura e atendimento; origem do IP. | ✅ Limite por IP e bloqueio de conta; X-Real-IP só é aceito do proxy interno, então não dá para forjar o IP. |
| Arquivos | Caminho dos anexos, tipo dos arquivos e abertura no navegador. | ✅ Nome validado e caminho preso à pasta de anexos; tipo conferido pelos bytes; arquivos abertos com CSP sandbox (SVG/HTML não executam script). |
| XSS | Uso de dangerouslySetInnerHTML no frontend e o Markdown desta documentação. | ✅ Nenhum no frontend; o Markdown escapa o HTML e só aceita links http(s), mailto e #. |
| HTTPS e cabeçalhos | Versões de TLS, redirecionamento HTTP e cabeçalhos de resposta. | ✅ TLS 1.0/1.1 recusados; HTTP → HTTPS; CSP e X-Frame-Options DENY. ⚠ O domínio globalcontabilidade.cnt.br não envia HSTS e o nginx mostra a versão (GA-501). |
| Dependências | npm audit das dependências de produção do frontend. | ✅ node-forge atualizado para 1.4.2 (falha alta na verificação de assinatura RSA). Restam 3 avisos baixos no shadcn, ferramenta de linha de comando que não vai para o site. |
Variáveis e chaves
Tudo fica no .env do servidor (fora do Git). Basta preencher e reiniciar o backend.
| Variável | Para quê |
|---|---|
NOTIFICACAO_EMAIL_GLOBAL | E-mail que recebe todos os avisos internos. |
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, EMAIL_REMETENTE | Envio de e-mail. |
WHATSAPP_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_TEMPLATE, WHATSAPP_API_VERSION | WhatsApp Cloud API. |
NOTIFICAR_CLIENTES | false por enquanto; true passa a avisar os clientes. |
INTEGRA_CONTADOR_HABILITADO | true para ligar o e-CAC. |
INTEGRA_CONTADOR_AMBIENTE | trial (demonstração) ou producao. |
INTEGRA_CONTADOR_CONSUMER_KEY, INTEGRA_CONTADOR_CONSUMER_SECRET | Credenciais da Loja SERPRO. |
INTEGRA_CONTADOR_CERTIFICADO, INTEGRA_CONTADOR_CERTIFICADO_SENHA | e-CNPJ A1 da Global (ex.: /app/secrets/ecnpj-global.pfx). |
INTEGRA_CONTADOR_CONTRATANTE_CNPJ | CNPJ da Global. |
ECAC_CRON | Agenda (padrão 0 0 7 10 * * = dia 10, 07:00). |
MANIFESTACAO_ENVIO_HABILITADO, MANIFESTACAO_AMBIENTE | Envio da manifestação do destinatário à SEFAZ (padrão false / HOMOLOGACAO). Sem ligar, o evento só é gerado e assinado. |
NFSE_EMISSAO_HABILITADA, NFSE_EMISSAO_AMBIENTE | Emissão da NFS-e do escritório na Sefin Nacional (padrão false / RESTRITA = homologação). |
NFSE_EMISSAO_CNPJ, NFSE_EMISSAO_CERTIFICADO, NFSE_EMISSAO_CERTIFICADO_SENHA | CNPJ e e-CNPJ A1 do escritório para assinar a DPS. |
NFSE_EMISSAO_OP_SIMPLES, NFSE_EMISSAO_CTRIBNAC, NFSE_EMISSAO_MUNICIPIO, NFSE_EMISSAO_SERIE | Regime no Simples (3 = ME/EPP), código de tributação nacional (padrão 171901), município IBGE (5300108) e série da DPS. |
REINF_XSD_DIR | Pasta com os XSD oficiais da EFD-Reinf (habilita o XML dos eventos). |
CERTIFICADO_VERIFICAR_REVOGACAO | Checagem de LCR/OCSP no login/assinatura (padrão true). |
Passo a passo no servidor
ssh adaca-vps
cd /opt/global-admin
mkdir -p secrets && chmod 700 secrets
# copie o e-CNPJ: scp ecnpj-global.pfx adaca-vps:/opt/global-admin/secrets/
nano .env # preencha as variáveis acima
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --no-build backend
API (endpoints principais)
Todas sob /api; escrita exige cookie de sessão e cabeçalho X-XSRF-TOKEN.
| Área | Endpoints |
|---|---|
| Autenticação | POST /auth/login · POST /auth/certificado/desafio · POST /auth/certificado · GET /auth/me · POST /auth/logout · PUT /auth/senha |
| Empresas | GET/POST /empresas · GET/PUT/DELETE /empresas/{id} · GET /empresas/consulta/{cnpj} · GET /cep/{cep} · POST /empresas/importar/{xml|pdf|planilha|certificado} |
| Documentos | GET /empresas/{id}/documentos?pastaId= · POST /empresas/{id}/documentos · POST/PUT/DELETE /empresas/{id}/pastas[/{pastaId}] · GET /documentos/{id}/arquivo · PUT /documentos/{id}/pasta · DELETE /documentos/{id} |
| Relações | GET/POST /relacoes · GET/PUT/DELETE /relacoes/{id} · GET /relacoes/{id}/pdf |
| Assinatura | POST /relacoes/{id}/assinatura/preparar · .../finalizar · .../upload · GET/DELETE /relacoes/{id}/assinatura · GET /assinador/download |
| Pendências | GET/POST /pendencias · /pendencias/{id} · /anexo · /concluir · /reabrir · GET /pendencias/resumo |
| e-CAC | GET /ecac/status · GET /ecac/verificacoes · POST /ecac/empresas/{id}/verificar · PUT /ecac/empresas/{id}/monitorar · POST /ecac/executar |
| Notificações (admin) | GET /notificacoes/status · GET /notificacoes · POST /notificacoes/teste · POST /notificacoes/{id}/reenviar |
| Auditoria (admin) | GET /auditoria?acao=&limite= |
| Usuários (admin) | GET/POST /usuarios · PUT /usuarios/{id} · PUT /usuarios/{id}/senha |
Assinador Local (127.0.0.1:9090)
GET /status · GET /certificados · POST /tokens/conectar · POST /arquivos/carregar · POST /assinar
Pendências e impedimentos
Quadro no estilo Jira. “Bloqueado” = depende de ação da Global (contratos, credenciais, certificados) antes de o desenvolvimento continuar.
Fontes
- SERPRO — Integra Contador: Quick Start (autenticação, gateway, estrutura)
- SERPRO — Catálogo de serviços (SITFIS, CAIXAPOSTAL, DCTFWEB, PGDASD…)
- Loja SERPRO — Integra Contador (contratação e tabela de preços vigente)
- SCI — Análise de custos do Integra Contador (mai/2024)
- Domínio — Quais os custos da API Integra Contador
- Biblioteca de referência (comunidade) — formatos de SITFIS, Caixa Postal e Autentica Procurador
- ITI — Repositório da AC Raiz ICP-Brasil
- Meta — WhatsApp Cloud API
- BrasilAPI · ViaCEP