📚 Wiki do Sistema

Visão Geral

O Confia ISP é um Sistema de Proteção ao Crédito especializado para Provedores de Internet. O ecossistema é composto por três plataformas integradas:

Funcionalidades Principais

Módulos do Sistema

O Confia ISP é dividido nas seguintes áreas de acesso:

Central do Cliente

URL: https://confiaisp.com.br/central/ — Acesso dos clientes finais (ISPs).

Módulo	Descrição	Funcionalidades
📊 Dashboard	dashboard.php	Faturas pendentes, registros ativos, consultas do mês, gráficos
🔍 Consultar	consultar.php	Consulta CPF/CNPJ na base colaborativa de inadimplentes
🚫 Negativar	negativar.php	Cadastro de inadimplentes com validação de CPF e score
📄 Contratos	contratos.php	Histórico de faturas e contratos
📜 Histórico	historico.php	Histórico de consultas realizadas
🔌 API	api-config.php	Token de acesso, webhook, IPs permitidos, plano

Site Público (Confia ISP)

URL: https://confiaisp.com.br — Páginas institucionais e de captação.

Página	Descrição
/	Landing page com stats, features, depoimentos, FAQ
/planos.php	Planos e preços (Básico R$97, Profissional R$197, Enterprise R$497)
/contratar.php	Formulário de cadastro para ISPs com seleção de CRM
/contato.php	Formulário de contato
/sgp-docs.php	Documentação completa da API REST
/wiki.php	Wiki do sistema (esta página)

Integrações

O sistema suporta integração com sistemas externos via API REST, Webhooks e Gateways de Pagamento. As integrações são gerenciadas no módulo Financeiro do Painel Admin.

Tipos de Integração

Tipo	Descrição	Finalidade
widepay	Wide Pay	Gateway de pagamento — emissão de boletos e cobrança
saas	SaaS Bank	Integração bancária para gestão financeira
bank	Banco	Integração bancária genérica
crm	CRM	Sincronização com sistemas de gestão de clientes
api	API Key	Token de autenticação para integração via API REST
other	Outro	Integração genérica/configurável

Cadastro de Integração

As integrações são cadastradas no Painel Admin → Financeiro. Cada integração possui:

Campo	Descrição
nome	Nome identificador da integração
tipo	Tipo (widepay, saas, bank, crm, api, other)
chave_api	Chave de API fornecida pelo serviço externo
token	Token de autenticação
webhook_url	URL para receber notificações do serviço
config	JSON com configurações específicas: descricao, usuario, senha, limite_doc, limite_consultas, ambiente (producao/homologacao), debug

CRMs Suportados

O sistema possui integração nativa com os seguintes CRMs. A seleção do CRM é feita no cadastro do cliente (Painel Admin) ou no formulário de contratação.

Integração via Webhook

Para CRMs que suportam webhooks, o sistema pode enviar notificações em tempo real sobre:

• nova_negativacao — Novo registro de inadimplente cadastrado
• baixa — Pagamento/dedução de dívida registrado
• cancelamento — Contrato/devedor cancelado

URL do webhook: https://confiaisp.com.br/api/webhook.php

Autenticação: Header X-Webhook-Token com token configurado na tabela webhook_tokens.

Integração via API REST

Todos os CRMs podem se integrar via API REST padrão. Consulte a documentação completa da API para detalhes dos endpoints.

Gateways de Pagamento

Gateway	Tipo	Status	Funcionalidades
Wide Pay	widepay	Configurável	Emissão de boletos, conciliação automática
SaaS Bank	saas	Configurável	Gestão financeira integrada
Manual	manual	Ativo	Registro manual de pagamentos

As faturas podem ter o campo gateway preenchido com o tipo de integração utilizada. O sistema armazena gateway_id e link_pagamento para rastreamento.

Webhook de CRM

Endpoint: POST https://confiaisp.com.br/api/webhook.php

Autenticação: Header X-Webhook-Token ou query param ?token=

Payload Padrão

{
  "evento": "nova_negativacao",
  "dados": {
    "cpf_cnpj": "000.000.000-00",
    "nome": "João da Silva",
    "contrato": "CT-0001",
    "valor": 1500.00,
    "data_vencimento": "2026-08-15"
  }
}

Eventos Suportados

Evento	Alias	Ação no sistema
nova_negativacao	new_debt	Cria/atualiza cliente, contrato e registro de dívida
baixa	payment	Marca dívidas como pagas por CPF ou número de contrato
cancelamento	cancellation	Cancela contratos por número ou CPF do cliente

Exemplo de Chamada

curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Token: SEU_TOKEN" \
  -d '{
    "evento": "nova_negativacao",
    "dados": {
      "cpf_cnpj": "000.000.000-00",
      "nome": "João da Silva",
      "contrato": "CT-0001",
      "valor": 1500.00,
      "data_vencimento": "2026-08-15"
    }
  }' \
  https://confiaisp.com.br/api/webhook.php

API REST — SGP

A SGP API (Sistema de Gestão de Proteção) permite integração completa com sistemas terceiros. Abaixo um resumo dos endpoints. Consulte a documentação detalhada para exemplos completos.

Base URL: https://confiaisp.com.br/api/v1

Autenticação

Header Authorization: {token}. Dois tipos de token:

Tipo	Onde obter	Acesso
Token de Cliente	Central do Cliente → API	Próprios dados (inadimplentes, consultas)
Token Global	Integração tipo api no Admin	Todos os recursos (clientes, faturas, projetos)

Consultar Inadimplentes

Gerenciar Inadimplentes

Gerenciar Clientes

Requer token global

Gerenciar Faturas

Requer token global

Listar Projetos

Requer token global

Banco de Dados

O banco principal roda em MariaDB no mesmo host da aplicação (localhost).

Tabelas

#	Tabela	Finalidade	Colunas Principais
1	projetos	ISPs/sites gerenciados pelo sistema	nome, slug, url, db_*, espaco_*, status
2	clientes	Clientes finais (subscribers)	nome, email, documento, telefone, senha_hash, crm, cep, status, id_projeto
3	config_cliente_api	Configuração de API por cliente	token_api, webhook_url, ip_permitidos, plano, limite_diario
4	faturas	Faturas de assinatura	numero (unique), valor, taxa, total, gateway, link_pagamento, data_vencimento, status
5	inadimplentes	Registros de inadimplentes	documento, nome, score (0-1000), valor_divida, origem, data_vencimento, status
6	consultas_historico	Auditoria de consultas	tipo, documento_consultado, resultado (JSON), ip, origem
7	integracoes	Integrações externas	tipo (enum), chave_api, token, webhook_url, config (JSON)
8	usuarios	Usuários do painel admin	nome, email, senha_hash, status
9	financeiro	Receitas e despesas	descricao, tipo (receita/despesa), valor, status, data_vencimento
10	configuracoes	Config chave-valor do sistema	chave (unique), valor
11	settings	Config de front-end/branding	chave (unique), valor
12	webhook_logs	Log de chamadas de webhook	origem, evento, payload (JSON), response_status
13	espaco_db_log	Histórico de espaço usado	db_name, used_mb, id_projeto
14	contratos	Contratos de clientes	numero (unique), plano, valor, status
15	dividas	Dívidas vinculadas a contratos	valor, data_vencimento, status
16	webhook_tokens	Tokens de autenticação de webhook	token (unique), nome, ativo
17	crm_stats	Estatísticas de CRM	total_consultas, total_webhooks, total_negativacoes
18	contato_mensagens	Mensagens do formulário de contato	nome, email, mensagem, lida

Views do Sistema

View	Descrição
vw_clientes	Clientes com dados de API config e projeto
vw_faturas_vencidas	Faturas vencidas com dias de atraso
vw_inadimplentes_score	Inadimplentes com faixa de score (baixo/médio/alto)
vw_consultas_status	Consultas com indicador de restrição

Guia de Uso — Painel Administrativo

Acessar o Painel

Login com email e senha de administrador.

Gerenciar Projetos

No módulo Projetos, cadastre cada ISP como um projeto. Configure:

• Nome, slug e descrição do projeto
• URL do site
• Conexão com banco de dados (se o ISP tiver DB próprio)
• Limite de espaço em banco

Gerenciar Clientes

No módulo Clientes, cadastre os clientes finais de cada ISP:

• Selecione o projeto (ISP)
• Preencha dados cadastrais (nome, documento, endereço com CEP automático)
• Selecione o CRM utilizado pelo cliente (SGP, IXC, RD Station, etc.)
• Configure o plano (Promocional, Confia+500) e limite mensal de consultas
• O cliente receberá acesso à Central do Cliente

Gerenciar Financeiro

No módulo Financeiro:

• Crie e gerencie faturas por cliente/projeto
• Acompanhe status de pagamento (pendente, paga, cancelada, estornada)
• Configure integrações com gateways de pagamento (WidePay, SaaS, etc.)
• Ao criar integração do tipo api, o token gerado pode ser usado como token global da API

Alertas de Inadimplência

O módulo Alertas lista automaticamente clientes com faturas em atraso há mais de 90 dias. Ações disponíveis:

• Gerar nova fatura
• Alterar plano do cliente
• Visualizar detalhes do cliente

Configurações

No módulo Configurações:

• Dados da empresa (nome, documento, endereço)
• Upload de logo
• Alterar senha do administrador

Guia de Uso — Central do Cliente

Acessar a Central

URL: https://confiaisp.com.br/central/ — Login com email e senha cadastrados pelo administrador.

Dashboard

Visão geral com:

• Faturas pendentes e valor total a pagar
• Registros de inadimplentes ativos
• Consultas realizadas no mês (com barra de progresso do limite)
• Comparativo de consultas pela Central vs. API
• Últimas faturas e últimos registros

Consultar CPF/CNPJ

No módulo Consultar:

• Digite o CPF ou CNPJ para consultar na base colaborativa
• Resultados exibem nome, documento, valor, vencimento, score e status
• Cada consulta é registrada no histórico e contabilizada no limite mensal

Negativar (Registrar Inadimplente)

No módulo Negativar:

• Preencha CPF/CNPJ, nome, valor da dívida e dados complementares
• O score de risco é calculado automaticamente (0-1000)
• É possível cadastrar múltiplos registros via importação JSON

Contratos e Faturas

Visualize o histórico completo de faturas com status, valores e datas de vencimento.

Histórico de Consultas

Consulte o registro de todas as pesquisas realizadas, com data, documento consultado e se havia restrição.

Configurar API

No módulo API, o cliente pode:

• Visualizar e copiar o token de acesso
• Regenerar o token (invalida integrações atuais)
• Configurar URL de webhook para notificações
• Definir IPs permitidos (IPv4 e IPv6)
• Visualizar documentação básica de uso da API

Guia de Integração — API REST

1. Obter Token de Acesso

Para clientes: Acesse Central do Cliente → API e copie o token exibido.

Para integrações globais: Crie uma integração do tipo api no Painel Admin → Financeiro e utilize o token gerado.

2. Testar a Conexão

curl -s -H "Authorization: SEU_TOKEN" \
  https://confiaisp.com.br/api/v1/projetos

3. Fluxo Completo

# 1. Consultar CPF/CNPJ
curl -s -H "Authorization: SEU_TOKEN" \
  https://confiaisp.com.br/api/v1/consulta/000.000.000-00

# 2. Cadastrar inadimplente
curl -s -X POST \
  -H "Authorization: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documento":"000.000.000-00","nome":"João","valor_divida":1500}' \
  https://confiaisp.com.br/api/v1/inadimplentes

# 3. Listar inadimplentes cadastrados
curl -s -H "Authorization: SEU_TOKEN" \
  https://confiaisp.com.br/api/v1/inadimplentes

4. Tratamento de Erros

A API retorna códigos HTTP padrão:

Código	Significado	Resposta
200	Sucesso	JSON com dados solicitados
201	Criado com sucesso	{"id": 42}
400	Parâmetro obrigatório ausente	{"error": "mensagem"}
401	API key inválida	{"error": "API key inválida"}
403	Acesso negado	{"error": "..."}
404	Recurso não encontrado	{"error": "..."}
405	Método não permitido	{"error": "..."}

Guia de Integração — CRM

Opção 1: Webhook (tempo real)

Ideal para CRMs que suportam envio de webhooks (IXCSoftware, RD Station, HubSpot, etc.).

1. Configure seu CRM para enviar eventos para https://confiaisp.com.br/api/webhook.php
2. Inclua o header X-Webhook-Token com o token configurado no sistema
3. Envie eventos nos formatos suportados (nova_negativacao, baixa, cancelamento)
4. Acompanhe os logs em https://confiaisp.com.br/crm/monitor.php?token=Confia@Admin2026

Opção 2: API REST (pull/sync)

Ideal para integrações programadas ou sistemas que consomem dados periodicamente.

1. Obtenha um token de cliente ou global
2. Utilize os endpoints da API REST para consultar, cadastrar e gerenciar dados
3. Implemente sincronia periódica conforme necessidade do negócio

Opção 3: CRM Nativo (SGP)

O sistema já possui CRM nativo (SGP). Clientes configurados como CRM=SGP têm acesso completo a todas as funcionalidades da Central do Cliente + API.

API do SGP CRM (externa)

O SGP mantém uma API Pública em https://api.sgp.net.br/ (sandbox: https://sandbox.sgp.net.br/) que permite integração programática. Três métodos de autenticação:

Método	Como funciona	Indicado para
Basic Auth	Usuário/Senha no header Authorization: Basic ...	Testes e scripts simples
Token + App	Token e App gerados no SGP (Administração → Tokens), enviados no body	Produção (recomendado)
CPF/CNPJ + Senha	Credenciais do assinante final, enviadas no body	Central do Assinante

Principais Endpoints

Módulo	Endpoint	Método	Descrição
URA	/api/ura/clientes/	GET	Consultar cliente por CPF, contrato, nome ou login
URA	/api/ura/fatura2via/	GET	Gerar 2ª via de fatura
URA	/api/ura/titulos/	GET	Listar títulos do cliente
URA	/api/ura/chamado/	POST	Abrir chamado de suporte
OS	/api/os/list/	GET	Listar ordens de serviço
OS	/api/os/update/id/{os_id}/	PUT	Atualizar OS
Central	/api/central/contratos/	GET	Listar contratos do assinante
CRM	/api/crm/cliente/	GET/POST	Listar/criar clientes
FTTX	/api/fttx/olt/	GET	Listar OLTs
Crédito	/api/ura/documento/consulta/gateway/{id}/	POST	Consultar CPF/CNPJ em gateway (Serasa)

Documentação completa: Integração com SGP CRM na página da API. Classe PHP em includes/class-sgp-api.php.

Monitoramento

Acesse o CRM Monitor para acompanhar as integrações em tempo real:

https://confiaisp.com.br/crm/monitor.php?token=Confia@Admin2026

Indicadores disponíveis:

• Total de clientes e contratos
• Dívidas pendentes e valor total
• Webhooks recebidos
• Tokens ativos
• Últimos webhooks processados
• Últimas consultas realizadas

Deploy e Manutenção

Upload de Arquivos

Utilizamos PSCP (WinSCP CLI) para transferência de arquivos via SSH.

# Site público + Central do Cliente
pscp -r -P 2240 -pw "Pessoni@1204#" "dist/*" root@200.234.212.247:/var/www/confiaisp.com.br/public/

# Verificar nginx e recarregar
plink -ssh -P 2240 -l root -pw "Pessoni@1204#" 200.234.212.247 "nginx -t && systemctl reload nginx"

Banco de Dados

# Upload e execução de script SQL
pscp -P 2240 -pw "Pessoni@1204#" "database/seed.sql" root@200.234.212.247:/tmp/seed.sql
plink -ssh -P 2240 -l root -pw "Pessoni@1204#" 200.234.212.247 "mysql confiaisp < /tmp/seed.sql"

# Backup
plink -ssh -P 2240 -l root -pw "Pessoni@1204#" 200.234.212.247 "mysqldump confiaisp > /tmp/backup.sql"

Manutenção

SSL / Certbot

Os certificados SSL são gerenciados pelo Certbot com renovação automática.

# Testar renovação
certbot renew --dry-run

# Verificar status
certbot certificates

Comandos Úteis

Comando	Descrição
systemctl reload nginx	Recarregar config do nginx sem downtime
systemctl restart php8.3-fpm	Reiniciar PHP-FPM
journalctl -u nginx -n 50	Últimos logs do nginx
journalctl -u php8.3-fpm -n 50	Últimos logs do PHP-FPM
mysql confiaisp -e "SHOW TABLES"	Listar tabelas do banco
df -h	Verificar espaço em disco
free -m	Verificar memória RAM

Problemas Comuns

Problema	Causa	Solução
Erro 500 ao acessar página do cliente	LIMIT ? como bound parameter	Concatenar inteiro: LIMIT " . intval($n)
Sessão não persiste	session.cookie_secure incorreto	True em HTTPS, false em HTTP
MySQL access denied	Usuário sem grant para o banco	GRANT ALL PRIVILEGES ON db.* TO 'user'@'localhost'
Domínio não resolve	DNS preso em nameserver antigo	Alterar no registro.br para IP da VM
Login inválido	Hash da senha corrompido	Regenerar hash com password_hash()

---