Global Admin · Docs

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.

Administradores podem acrescentar temas novos: ✎ Editar documentação (menu lateral) → + Nova seção. Cada seção tem título, categoria no menu (uma existente ou nova) e conteúdo em Markdown com pré-visualização; fica salva no mesmo banco do Global Admin.

Estado atual

O sistema está em produção numa VPS com HTTPS. As integrações externas (SERPRO, SMTP e WhatsApp) estão implementadas e aguardando apenas as credenciais — veja Variáveis e chaves e o quadro de pendências.

⬇ PDF: API do e-CAC (Integra Contador) e valores

Arquitetura

Front Next.js, API Spring Boot e PostgreSQL em Docker, atrás do nginx com HTTPS.

CamadaTecnologiaObservações
FrontNext.js 15.5.28 (App Router), React 19.3, TypeScript, Tailwind 4, shadcn/ui, React Hook Form, ZodFaz proxy de /api para o backend: cookie de sessão first-party, sem CORS.
BackSpring Boot 3.5.16 (Java 17), Spring Security, JPA, FlywayJWT em cookie httpOnly + CSRF; agendamentos (@Scheduled).
PDF / assinaturaThymeleaf + 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.
BancoPostgreSQL 16Sem porta pública; volume Docker persistente.
ArquivosVolume Docker (/app/uploads)Nomes aleatórios; imagens e PDFs otimizados.
Assinador LocalJava 17 (HttpServer + Swing)Roda no computador do usuário em 127.0.0.1:9090.
InfraDocker Compose, nginx + Let's EncryptImagens 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ãoConteúdo
V1–V2Contabilidades, usuários, relações de faturamento (+ dados de exemplo)
V3Empresas, pendências, valores picados
V4Assinatura digital da relação
V5Perfis ADMIN/CONTABILIDADE/EMPRESA, sócios, cache de CNPJ, sócio-gerente
V6Mensageria (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.

PerfilPodeNão pode
AdministradorTudo: usuários, contabilidades, empresas, relações, pendências, e-CAC, notificações e auditoria.—
ContabilidadeEmpresas, relações, assinatura, pendências, documentos e e-CAC da própria contabilidade.Usuários, auditoria, notificações, dados de outras contabilidades.
EmpresaVer 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.
O login pode ser por e-mail e senha ou por certificado digital (e-CPF vinculado ao CPF do usuário, ou e-CNPJ da empresa para o perfil Empresa).
Login: no campo “E-mail ou usuário” dá para digitar o e-mail completo ou só o usuário (a parte antes do @), à escolha de quem entra — vale para o sistema e para o modo edição desta documentação. Se o mesmo usuário existir em mais de um e-mail (ex.: 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.

Abrir o design system completo →

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/Tab passam 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.
Editar empresa: ao abrir a edição, o sistema consulta o CNPJ de novo nas bases públicas (sem o cache de 30 dias) e preenche só os campos que estão em branco, destacados em verde; o que já foi digitado não é sobrescrito. A situação cadastral é sempre atualizada. Rota: GET /api/empresas/consulta/{cnpj}?atualizar=true.
Pasta “Pendências”: toda empresa tem esta pasta na raiz (criada no cadastro e liberada ao cliente). Cada pendência entra nela automaticamente como PDF (título, empresa, prazo, descrição, quem registrou) e, se houver, com uma cópia do anexo. O PDF é atualizado ao editar, concluir (com o meio de aviso e a observação) ou reabrir; pendências do e-CAC também são arquivadas. Excluir a pendência não apaga os arquivos (histórico).
Pasta “Faturamentos”: toda empresa tem esta pasta (liberada ao cliente). Cada relação de faturamento é salva nela ao criar, editar ou assinar — 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). Quando NOTIFICAR_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 certificadoComo
Instalado no computador (Windows / Keychain do macOS)Assinador Local (Windows-MY / KeychainStore).
Token ou cartão A3Assinador 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 programaEnvio 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

  1. 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.
  2. Assinar: o navegador (A1) ou o Assinador Local (após confirmação do usuário) assina com SHA256withRSA.
  3. Finalizar: o servidor confere a assinatura com a chave pública, monta o CMS com signingCertificateV2 e grava o PDF. Sessão de uso único, 10 minutos.
Certificados já instalados: o navegador não tem acesso direto ao repositório de certificados do sistema; quem faz essa ponte é o Assinador Local. Com ele aberto, a aba “Computador / Token” lista os certificados instalados no Windows (repositório pessoal), no Keychain do macOS e em tokens/cartões A3 (botão “Conectar token A3”). Requer Java 17+. Se a lista vier vazia, o certificado não está instalado nesse computador (no macOS: Acesso às Chaves → Meus Certificados) — use o arquivo .pfx (“Arquivo A1”) ou o token.

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çalho Host (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.

SistemaComo abrir o instalador
WindowsBotã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.
macOSAbrir o ZIP → botão direito em Instalar Assinador.command → Abrir. No macOS 15+: Ajustes do Sistema → Privacidade e Segurança → Abrir Mesmo Assim.
LinuxExtrair 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
SistemaOnde ficaComo 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 --instalar de 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.
Modelo gov.br: a assinatura gov.br (avançada) só é integrável por API mediante credenciamento junto ao governo; está registrada como tarefa futura (GA-209). O fluxo atual é gratuito e usa certificados ICP-Brasil (assinatura qualificada).

Login com certificado digital

  1. O navegador pede um desafio aleatório (uso único, 2 minutos).
  2. O certificado assina o desafio — no Assinador Local (repositório/token, com confirmação) ou com o arquivo A1 no navegador.
  3. 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).
  4. 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.
  5. Abre a sessão (cookie httpOnly) e registra na auditoria.
Sem a validação de cadeia, alguém poderia gerar um certificado falso com o CPF de outra pessoa — por isso só raízes do ITI são aceitas. Âncoras extras (CERTIFICADO_ANCORAS_EXTRAS) existem apenas para homologação.

Impressões digitais (SHA-256) das raízes embutidas

RaizSHA-256
AC Raiz Brasileira v5CA: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 v106E: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 v1114: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 v12D8: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 v132B: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çoCódigoMétodoUso
Caixa Postal — indicadorCAIXAPOSTAL / INNOVAMSG63MonitorarHá mensagens novas?
Caixa Postal — listaCAIXAPOSTAL / MSGCONTRIBUINTE61ConsultarAssuntos das mensagens não lidas (somente se houver).
Situação Fiscal — protocoloSITFIS / SOLICITARPROTOCOLO91ApoiarInicia a geração do relatório.
Situação Fiscal — relatórioSITFIS / RELATORIOSITFIS92EmitirPDF guardado em “Receita Federal / Situação Fiscal”.
Só empresas ativas são consultadas na Receita — na rotina e na pesquisa imediata. Cada empresa tem o campo “Consultar esta empresa”: Não consultar, Mensalmente, Bimestralmente, Semestralmente ou Anualmente (padrão: mensal). A rotina do dia 10 consulta quem nunca foi consultado ou cuja última consulta foi há pelo menos o intervalo escolhido; o botão Pesquisa imediata consulta na hora. A estimativa de custo da aba e-CAC já pondera a frequência. Rota: PUT /api/ecac/empresas/{id}/frequencia.

Rotina mensal

  1. Todo dia 10 às 07:00 (configurável em ECAC_CRON), com trava no banco contra execução dupla.
  2. Para cada empresa com monitoramento ligado: Caixa Postal + Relatório de Situação Fiscal.
  3. O PDF é salvo na pasta da empresa e analisado: só é “regular” se declarar explicitamente ausência de pendências.
  4. 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).
  5. Ao final, e-mail com o resumo da rodada. Também há “Verificar agora” por empresa e “Verificar todas” (admin).

Valores (referência)

CategoriaFaixa 1 (referência mai/2024)
ConsultaR$ 0,24 por requisição
EmissãoR$ 0,32 por requisição
DeclaraçãoR$ 0,40 por requisição
A tabela tem 8 faixas (quanto maior o consumo mensal, menor o preço). Os valores acima foram obtidos de fontes secundárias e conferem com os exemplos publicados (50 empresas × 6 requisições = R$ 96,00). Confirme a tabela vigente na Loja SERPRO antes de contratar. Estimativa do Global Admin: ≈ R$ 1,04 por empresa/mês (cenário conservador).

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 / ENVIOXMLASSINADO81 com 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).

EventoDestino hojeDestino futuro (NOTIFICAR_CLIENTES=true)
Documento adicionado numa pastaE-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-CACE-mail da Global—
Integração e-CAC não configurada no dia 10E-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": "..." }] }] } }
Fora da janela de 24 h de conversa, a Meta só aceita templates aprovados. Sugestão de template “aviso_global” com corpo: “Olá! A Global Contabilidade informa: {{1}} — {{2}}. Acesse o Global Admin para detalhes.”

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

TelaO que faz
EmpresasFiltro Ativas / Inativas / Todas (padrão: ativas) e selo “inativa”.
Empresa → cabeçalhoChave Ativa: inativar pausa todos os honorários daquela empresa.
Empresa → aba HonoráriosCadastro (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-01Honorá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-02Recorrê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-03A primeira emissão não pode ser no passado. Ao atingir o número de meses, o honorário é encerrado sozinho.
RC-04Só 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-05Vé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-06Dia 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-07Uma 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-08Gerar agora antecipa a cobrança da próxima competência e avança o honorário (conta como aquele mês).
RC-09Sicoob 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-10Ciclo atrasado até 7 dias (servidor fora do ar) ainda é emitido; mais antigo é pulado e a equipe é avisada para decidir.
RC-11Cancelar 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-15Regras 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-16Por honorário: “Protestar/negativar se não pagar”. Desligado, o cliente nunca é protestado nem negativado.
RC-17Pedem 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-18Baixa 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-19Certificado 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-13Honorá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-14Toda 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-12O 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)

  1. Busca os honorários ativos de empresas ativas com emissão amanhã → e-mail da véspera por contabilidade + sino.
  2. 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.
  3. Sicoob configurado → POST /boletos (boleto híbrido) → guarda nosso número, linha digitável, Pix copia e cola e PDF.
  4. Mensagem automática na conversa da empresa: valor, vencimento, linha digitável e Pix; aviso no sino do cliente.
  5. Trava de banco (pg_try_advisory_lock) impede duas execuções em paralelo.

Integração Sicoob — Cobrança Bancária v3

ItemValor
Produçãohttps://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)
Sandboxhttps://sandbox.sicoob.com.br/sicoob/sandbox/cobranca-bancaria/v3 com client_id e token fixo do portal developers.sicoob.com.br
EmissãoPOST /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 usadanossoNumero, linhaDigitavel, codigoBarras, qrCode (Pix copia e cola), pdfBoleto (base64), descricaoRejeicaoPix
BaixaPOST /boletos/{nossoNumero}/baixar
O Pix no boleto (híbrido) precisa estar habilitado no contrato de cobrança junto à cooperativa; sem isso o Sicoob emite só o boleto e informa o motivo em 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

RotaQuem
PUT /api/empresas/{id}/ativaAdministrador e Contabilidade
GET/POST /api/empresas/{id}/honorarios · PUT/DELETE …/honorarios/{h} · POST …/honorarios/{h}/gerar · GET /api/empresas/{id}/cobrancasAdministrador 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/regrasAdministrador 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-01Tipos: Compromisso, Parcelamento e Data de emissão. Título obrigatório; empresa e observação opcionais.
RA-02Recorrê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-03As 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-04Clicar 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-05Cada data pode ser marcada como concluída (registra quem e quando) ou reaberta. Situação: concluída, a vencer ou em atraso (vermelho).
RA-06Editar tudo substitui a lista de datas; as que já estavam concluídas continuam concluídas. Excluir remove todas as datas do compromisso.
RA-07As 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-08Escopo: a equipe vê a agenda da própria contabilidade; administradores veem todas. O cliente (perfil Empresa) não acessa a agenda.
RA-10O 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-11Vencimento 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-12No 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-13Aviso 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-09Toda 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-01Entrada: 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-02Saí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-03Excluir 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-04A 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-05Fora da lixeira, cada pessoa guarda os 1000 avisos mais recentes.
RM-06Todo 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-07Enviar 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-08Saí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

RotaQuem
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/compromissosAdministrador e Contabilidade
PUT /api/agenda/parcelas/{id} · POST …/parcelas/{id}/concluir|reabrirAdministrador 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/lixeiraTodos (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-01Etapas: 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-03Reabrir volta para pendente, mas mantém o registro do aviso (o cliente já foi avisado).
RP-04Editar (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-05Histó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-06Vá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-07Visã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-08Só 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-01A equipe cria o parcelamento só com empresa, título e anotações. As anotações são internas (o cliente não recebe).
RPC-02Anexar 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-03O 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-04Check 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-05Mensagem 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-06Situaçã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-07Pessoa 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-08Arrastar 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

  1. 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).
  2. 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.
  3. 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.
  4. 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-01Ao 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-02Arquivo 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-03Equipe (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-04Cliente: 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-05Situaçã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-06Camada 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-07Enviar 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-08Salvar 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-09Certificado 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-01Cadastro: 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-02Chaves 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-03Mudar 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-04Bloquear tira o acesso na hora e libera a vaga; desbloquear exige vaga.
RCO-05Limite 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-06Quem gerencia: administrador (qualquer contabilidade) ou colaborador com a chave “Gerenciar colaboradores” (só a dele). Tudo na auditoria.

Financeiro — regras

#Regra
RFI-01Contas 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-02Repetir 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-03Baixa 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-04Resumo 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-06Cada 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-01Pendê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-02Ficha 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-03Alertas 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-01Urgê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-02Card 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-03Resumo 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-04Açõ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-05Modal: 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-06Qualidade 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-04Tipos 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-05Geraçã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-06Fluxo: 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-07Painel 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-08Relató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-09Situaçã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-10Envio 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-11Ré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-12A 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-13As 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-14Rodapé 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-15Pessoas 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-16Acessos 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

RotaQuem
GET /api/equipeEquipe (lista de responsáveis)
PUT /api/empresas/{id}/fiscal · POST /api/empresas/regimesEquipe (chave Empresas)
GET /api/obrigacoes · PUT /api/obrigacoes/{id} · POST /api/obrigacoes/gerarEquipe (chave Obrigações); cliente só consulta as da própria empresa
GET/POST/PUT /api/obrigacoes/tiposLeitura: equipe · alteração: administrador
GET /api/painel/indicadoresEquipe (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}/certidoesEquipe; cliente só lê
Banco: V26 (pendência e empresa), V27 (obrigações), V28 (certidões e régua de honorários), V29 (chave Obrigações para quem já tem Empresas).

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-01Novo 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-02O 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-03PDF 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-04Situaçõ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-05API 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.
Banco: V31. Variável 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-01Documentos 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-02Documentos do escritório (toda a equipe da contabilidade) e Meus documentos (só o usuário): repositórios internos, nunca visíveis ao cliente.
DOC-03Lixeira: 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-05Editar 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-06Vencimento: 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-07Visualizado 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-04Comunicaçõ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).
Banco: V32 (lixeira, documentos internos e comunicações), V48 e V49 (vencimento, alteração e visualização). Ao substituir um documento numa pasta liberada, o cliente recebe a mensagem “Documento atualizado”. Rotas: /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-01API 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-02Empresas 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-03Cada 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-04Rotina 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-05Leitor 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-06Aba Notas: filtros por empresa, competência e tipo; totais de serviços prestados, ISS e tomados; exportação CSV.
Banco: V33. Ambientes: produção e produção restrita (testes).

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)

TipoRegras aplicadas
CLT prazo indeterminado · TeletrabalhoINSS progressivo, FGTS 8%, férias, 13º, aviso prévio. Teletrabalho exige aditivo (art. 75-C).
Experiência · Prazo determinadoAté 90 dias (art. 445) · até 2 anos; rescisão antecipada pelos arts. 479/480.
Tempo parcial · IntermitenteAté 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árioFGTS 2%, até 2 anos · até 180 + 90 dias (Lei 6.019).
Doméstico · RuralFGTS 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-01Funcionários: cadastro completo (CEP preenche o endereço), validações de prazo e jornada por tipo, CPF.
DP-02Folha 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-03PDFs: contracheque (duas vias por página) e folha de ponto do mês com domingos e feriados nacionais (CLT art. 74 §2º).
DP-04Tabelas 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-05Fé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-0613º: 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-07Rescisã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-08Admissã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-09Afastamentos: 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-10Importar 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-11Só 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-12Vales (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-13Modelos 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).
Banco: V34 (funcionários, tabelas, folha), V35 (férias, 13º, rescisão), V36 (tabelas 2024/2025), V37 (dependentes, checklist, afastamentos), V38 (empresas do DP e vales). Rotas em /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-01Completar 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-02Guia 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-03Processos 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-04Reforma 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-05Comercial (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-06Registro 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-07Verificaçã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-08Aceite 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-09Teste 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-01Plano 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-02Lançamentos em partida dobrada: data, conta a débito, conta a crédito (analíticas e ativas, diferentes), valor e histórico.
CTB-03Extrato 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-04Conciliaçã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-05Fechamento 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-07Lanç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-06Relató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.
Encerramento anual, bens do imobilizado, centros de custo, orçamento, DMPL/DLPA/DVA e plano referencial: veja Novas funcionalidades. Ainda não faz parte: geração do arquivo da ECD/ECF (o prazo continua em Obrigações fiscais).

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-01Registro: capital social, natureza jurídica, NIRE, data de registro na Junta e observações.
SOC-02Quadro 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-03Alvará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-04Aviso 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-05Histó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-06Tela 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-01Campanha 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-02Cada 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-03Marcar como transmitida ou retificada exige o nº do recibo. A data de transmissão é preenchida com o dia, se vazia.
IR-04Painel: 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-05Carnê-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.

Chaves de acesso novas (V46): quem já tinha 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-01Resumo 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-02Notas: 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-03Receitas 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-04Simples 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-05Lucro 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-06Retençõ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-07Configuraçã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-08Reforma 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-09Só 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-10Eventos (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-11Lote 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-12Seguranç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-13XML 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-14Busca 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-15Leitor 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-16Conferê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-17Situaçã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-18Receitas 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.
Banco: V39 (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.

Todo cálculo novo sai marcado “Pendente de validação por contador” até a conferência. Nada é transmitido a órgãos do governo sem a integração ligada no servidor e confirmação na tela.

Fase 1 — Base parametrizável

#Regra
LAC-01Tabelas 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-02Fechamento fiscal por empresa e competência; reabrir exige motivo e fica na auditoria. V62.
LAC-03Impostos 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-04Fator R automático no Simples: folha dos 12 meses do DP ÷ receita bruta; ≥ 28% → Anexo III.

Fase 2 — Folha e eSocial

#Regra
LAC-05Rubricas do escritório com incidências de INSS, FGTS e IRRF e bases separadas no cálculo da folha. V64 e V68.
LAC-06Cargos (CBO) e sindicatos (piso e data-base), com aviso de salário abaixo do piso. V65.
LAC-07eSocial S-1010 (tabela de rubricas) gerado e validado no XSD oficial S-1.3, sem transmissão.
LAC-08Provisão de férias e 13º com FGTS e lançamento contábil (fonte PROVISAO). V66.
LAC-09RPA 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-10Aba 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-11Anual e livros (Escrita fiscal): participantes das notas, base da DEFIS/DASN-SIMEI e livro de ISS.
LAC-12Conclusão automática: gravar a apuração do mês muda a obrigação de PENDENTE para APURADA.
LAC-13Honorá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-14Simples 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-15Acumuladores (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-16Contá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-17Baixa 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-18Auditoria 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-19DP 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-20Pedidos 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-21Integraçõ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-22Acabamento 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-01Conformidade 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-02PEP 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-03Prova 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-04Pessoas (PEP): pessoas físicas do cadastro, consultadas pelo CPF na lista de PEP e no CEIS/CNEP.
TR-05Governo 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-06Consulta 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-07Limite 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.
Banco: V38 (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-01Menu 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-02Seçõ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-03Canais 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-04Formulá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-01Inicial: 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-02Conteú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-03Quem somos (/quem-somos): reservada, mostra “Em breve”.
SITE-04Trabalhe 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-05Currí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-06Central 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-07Atendimento 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-08Custo 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-09Contatos 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

PerfilNo portal
AdministradorTudo o que a contabilidade faz, em todas as contabilidades; responde qualquer conversa.
ContabilidadeLibera 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-01Só a contabilidade da empresa (ou um administrador) libera o acesso. O login criado é sempre do perfil Empresa e fica preso àquela empresa.
RN-02Senha 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-03Bloquear um acesso encerra na hora as sessões abertas daquele usuário. O histórico (mensagens, envios, auditoria) é preservado.
RN-04Login 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-05Pastas 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-06Na 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-07Pasta ou documento que o cliente não pode ver responde “não encontrado” (não revela que existe).
RN-08Cada 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-09Abrir a conversa marca como lidas as mensagens do outro lado; responder também. O remetente vê ✓ (enviada) ou ✓✓ (lida).
RN-10Cada 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-11Mensagens de 1 a 4.000 caracteres, só texto (sem HTML). A tela mostra as 300 mais recentes.
RN-12O sino guarda as 200 notificações mais recentes por usuário; o histórico permanente é a auditoria.
RN-13Arquivo 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-14O 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-15Empresa 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-16O 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-17Excluir 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-18Entrar 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-19Meu 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-20Acessar 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-21Solicitar 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-22Resposta 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-23Tela 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

EventoQuem é avisado
Mensagem do clienteEquipe da contabilidade da empresa + administradores (e e-mail da Global)
Mensagem da contabilidadeUsuários do cliente (e e-mail para cada um)
Documento enviado pelo clienteEquipe da contabilidade
Documento enviado pela equipe numa pasta liberadaUsuários do cliente (numa pasta fechada, ninguém é avisado)
Pasta liberadaUsuários do cliente
Pendência criadaEquipe e usuários do cliente
Pendência na Receita (rotina do e-CAC)Equipe da contabilidade
Acesso liberadoO 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

  1. Contabilidade abre Empresas → empresa → Acesso do cliente e clica em Liberar acesso.
  2. Informa nome, e-mail e (opcional) CPF; usa a senha sugerida ou define outra.
  3. O cliente recebe o e-mail “Seu acesso foi liberado” com o login; a senha vai por canal seguro.
  4. Opcional: liga Certificado digital (e-CNPJ) para entrar sem senha.
  5. Liga as Pastas liberadas que o cliente deve ver (o cliente é avisado no sino).

Cliente no dia a dia

  1. Entra com e-mail e senha ou com o certificado; cai no Painel com atalhos para documentos e mensagens.
  2. Meus documentos: navega nas pastas liberadas, baixa e envia arquivos (a equipe é avisada).
  3. Mensagens: conversa com a contabilidade; respostas aparecem sozinhas (atualização a cada 8 s) e no sino.
  4. Pendências e Relações: só as da própria empresa.

Equipe atendendo

  1. 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.
  2. Pela página da empresa, o botão Mensagens abre a conversa dela.
  3. Na aba Documentos, o ícone de olho mostra e alterna o que está visível ao cliente.

Endpoints

RotaQuem
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/lidosTodos (sempre do próprio usuário)
GET/POST /api/mensagens/conversa (equipe: ?empresa=ID; cliente: sempre a própria empresa)Todos
GET /api/mensagens/caixaAdministrador 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-01Disponível para todos os perfis logados (administrador, contabilidade e cliente). Sugestões rápidas diferentes para a equipe e para o cliente.
RIA-02A chamada à DeepSeek sai só do backend; a chave nunca vai ao navegador. Sem DEEPSEEK_API_KEY o assistente aparece como “não ativado”.
RIA-03Instruçõ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-04Conversa 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-06Vié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-07Dados 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-05Limite 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

ItemUso
GET /api/assistente{configurado} — se a chave existe.
POST /api/assistente{mensagens:[{papel,texto}]} → {resposta}. Qualquer usuário logado.
DEEPSEEK_API_KEYChave da plataforma platform.deepseek.com. Só no .env.
DEEPSEEK_MODELO · ASSISTENTE_MAX_POR_HORAModelo (padrão deepseek-chat) e limite por usuário.
As tabelas do antigo bot (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).

ItemComo foi testadoResultado
SQL injectionVarredura 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 abertasConexã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 loginLeitura 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 IPLimites 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.
ArquivosCaminho 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).
XSSUso 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çalhosVersõ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ênciasnpm 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.
Correções pendentes no quadro com a etiqueta Segurança: GA-501 (HSTS e versão do nginx), GA-502 (OpenAPI do pet-adaca) e GA-503 (porta 8444).

Variáveis e chaves

Tudo fica no .env do servidor (fora do Git). Basta preencher e reiniciar o backend.

VariávelPara quê
NOTIFICACAO_EMAIL_GLOBALE-mail que recebe todos os avisos internos.
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, EMAIL_REMETENTEEnvio de e-mail.
WHATSAPP_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_TEMPLATE, WHATSAPP_API_VERSIONWhatsApp Cloud API.
NOTIFICAR_CLIENTESfalse por enquanto; true passa a avisar os clientes.
INTEGRA_CONTADOR_HABILITADOtrue para ligar o e-CAC.
INTEGRA_CONTADOR_AMBIENTEtrial (demonstração) ou producao.
INTEGRA_CONTADOR_CONSUMER_KEY, INTEGRA_CONTADOR_CONSUMER_SECRETCredenciais da Loja SERPRO.
INTEGRA_CONTADOR_CERTIFICADO, INTEGRA_CONTADOR_CERTIFICADO_SENHAe-CNPJ A1 da Global (ex.: /app/secrets/ecnpj-global.pfx).
INTEGRA_CONTADOR_CONTRATANTE_CNPJCNPJ da Global.
ECAC_CRONAgenda (padrão 0 0 7 10 * * = dia 10, 07:00).
MANIFESTACAO_ENVIO_HABILITADO, MANIFESTACAO_AMBIENTEEnvio da manifestação do destinatário à SEFAZ (padrão false / HOMOLOGACAO). Sem ligar, o evento só é gerado e assinado.
NFSE_EMISSAO_HABILITADA, NFSE_EMISSAO_AMBIENTEEmissã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_SENHACNPJ e e-CNPJ A1 do escritório para assinar a DPS.
NFSE_EMISSAO_OP_SIMPLES, NFSE_EMISSAO_CTRIBNAC, NFSE_EMISSAO_MUNICIPIO, NFSE_EMISSAO_SERIERegime 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_DIRPasta com os XSD oficiais da EFD-Reinf (habilita o XML dos eventos).
CERTIFICADO_VERIFICAR_REVOGACAOChecagem 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.

ÁreaEndpoints
AutenticaçãoPOST /auth/login · POST /auth/certificado/desafio · POST /auth/certificado · GET /auth/me · POST /auth/logout · PUT /auth/senha
EmpresasGET/POST /empresas · GET/PUT/DELETE /empresas/{id} · GET /empresas/consulta/{cnpj} · GET /cep/{cep} · POST /empresas/importar/{xml|pdf|planilha|certificado}
DocumentosGET /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çõesGET/POST /relacoes · GET/PUT/DELETE /relacoes/{id} · GET /relacoes/{id}/pdf
AssinaturaPOST /relacoes/{id}/assinatura/preparar · .../finalizar · .../upload · GET/DELETE /relacoes/{id}/assinatura · GET /assinador/download
PendênciasGET/POST /pendencias · /pendencias/{id} · /anexo · /concluir · /reabrir · GET /pendencias/resumo
e-CACGET /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.

🔒 Somente leitura

Fontes

Entrar para editar

Use o login de administrador do Global Admin. O acesso vale 2 horas e só para editar esta documentação.

Demanda

Nova seção

Pré-visualização

Formatação: ## Título · **negrito** · *itálico* · `código` · - lista · 1. passos · > nota · >! alerta · tabelas com | · blocos com ```.