Sistema No Cod De Aprovação De Cadastro E Geração De Contrato E E Coleta De Assinatura.

🚀 Guia Técnico de Implementação - Sistema de Fiador Profissional

📌 Visão Geral do Projeto

Este documento contém todas as instruções necessárias para implementar um sistema automatizado de aprovação de cadastro para serviço de fiador profissional de aluguel.

Objetivo do Sistema

Automatizar o processo de análise, aprovação e geração de contratos para candidatos a locação com fiança profissional, reduzindo o tempo de processamento de 2-4 horas para 2-5 minutos.




📦 Estrutura do Projeto

Plain Text


sistema-fiador/
├── backend/                    # api rest em python/fastapi
│  ├── app/
│  │  ├── api/              # rotas da api
│  │  │  ├── candidatos.py  # Gestão de candidatos
│  │  │  ├── contratos.py  # Gestão de contratos (nova funcionalidade)
│  │  │  ├── webhooks.py    # Webhooks de pagamento/assinatura
│  │  │  └── admin.py      # Rotas administrativas
│  │  ├── models/            # Modelos de dados
│  │  │  ├── candidato.py
│  │  │  └── contrato_dados.py  # NOVO
│  │  ├── services/          # Serviços de integração
│  │  │  ├── google_sheets_service.py
│  │  │  ├── serasa_service.py
│  │  │  ├── asaas_service.py
│  │  │  ├── clicksign_service.py
│  │  │  ├── contract_service.py
│  │  │  └── decision_engine.py
│  │  ├── templates/        # Templates de contratos
│  │  │  └── contrato_locacao_completo.html  # NOVO
│  │  └── main.py          # Aplicação principal
│  ├── config/
│  │  └── settings.py      # Configurações
│  ├── requirements.txt      # Dependências Python
│  └── .env.example        # Exemplo de variáveis de ambiente
│
├── frontend/                  # Dashboard em React
│  ├── src/
│  │  ├── components/
│  │  │  ├── ui/          # Componentes shadcn/ui
│  │  │  └── FormularioContrato.jsx  # NOVO
│  │  ├── App.jsx          # Dashboard principal
│  │  └── AppComContratos.jsx  # Dashboard atualizado (NOVO)
│  ├── package.json
│  └── vite.config.js
│
└── docs/                    # Documentação
    ├── Readme.md
    ├── guia-instalacao.Md
    ├── nova-funcionalidade-contratos.Md
    └── resumo-executivo.md





🔧 Tecnologias Utilizadas

Backend

•
Python 3.11+

•
FastAPI - Framework web moderno e rápido

•
Pydantic - Validação de dados

•
Jinja2 - Templates HTML

•
WeasyPrint - Geração de PDF

•
Requests - Chamadas HTTP para APIs externas

•
Loguru - Logging avançado

Frontend

•
React 18+ com Vite

•
shadcn/ui - Componentes UI modernos

•
Tailwind CSS - Estilização

•
Lucide React - Ícones

Integrações Externas

•
Google Sheets API - Captura de cadastros

•
Serasa Experian API - Consulta de crédito

•
Asaas API - Geração de boletos

•
ClickSign API - Assinatura digital




📋 PASSO 1: Configuração do Ambiente

1.1 Pré-requisitos

Certifique-se de ter instalado:

•
Python 3.11 ou superior

•
Node.js 18+ e npm

•
PostgreSQL 14+ (ou SQLite para desenvolvimento)

•
Git

1.2 Clonar/Extrair o Projeto

Bash


# Se recebeu via ZIP
unzip sistema-fiador-atualizado.zip
cd sistema-fiador

# Se usar Git
git clone <repositorio>
cd sistema-fiador


1.3 Configurar Backend

Bash


cd backend

# Criar ambiente virtual Python
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

# Instalar dependências
pip install -r requirements.txt

# Copiar arquivo de configuração
cp .env.example .env


1.4 Configurar Frontend

Bash


cd ../Frontend

# Instalar dependências
npm install

# Copiar configurações (se necessário)
cp .env.example .env





🔑 PASSO 2: Obter Credenciais das APIs

2.1 Google Sheets API

1.
Acesse Google Cloud Console

2.
Crie um novo projeto

3.
Ative a Google Sheets API

4.
Crie credenciais do tipo Service Account

5.
Baixe o arquivo JSON de credenciais

6.
Salve como backend/config/google_credentials.json

7.
Compartilhe a planilha com o email do Service Account

Variáveis no .env:

Bash


GOOGLE_CREDENTIALS_FILE=config/google_credentials.json
GOOGLE_SHEET_ID=<ID_DA_SUA_PLANILHA>


2.2 Serasa Experian API

1.
Entre em contato com Serasa Experian

2.
Solicite acesso à API de Consulta de Crédito

3.
Obtenha as credenciais de produção

Variáveis no .env:

Bash


SERASA_API_KEY=<SUA_CHAVE>
SERASA_API_SECRET=<SEU_SECRET>
SERASA_BASE_URL=https://api.serasaexperian.com.br


⚠️ IMPORTANTE: Durante desenvolvimento, o sistema usa dados mockados. Para produção, você precisa das credenciais reais.

2.3 Asaas API (Boletos)

1.
Crie conta em Asaas.com

2.
Acesse Integrações → API

3.
Copie sua API Key

Variáveis no .env:

Bash


ASAAS_API_KEY=<SUA_API_KEY>
ASAAS_BASE_URL=https://api.asaas.com/v3
ASAAS_ENVIRONMENT=sandbox  # ou 'production'


2.4 ClickSign API (Assinatura Digital)

1.
Crie conta em ClickSign.com

2.
Acesse Configurações → API

3.
Gere um Access Token

Variáveis no .env:

Bash


CLICKSIGN_ACCESS_TOKEN=<SEU_TOKEN>
CLICKSIGN_BASE_URL=https://api.clicksign.com/v1





🗄️ PASSO 3: Configurar Banco de Dados

3.1 Opção A: PostgreSQL (Recomendado para Produção)

Bash


# Instalar PostgreSQL
# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib

# Criar banco de dados
sudo -u postgres psql
create database fiador_db;
create user fiador_user with password 'senha_segura';
grant all privileges on database fiador_db to fiador_user;
\q


variáveis no .env:

Bash


DATABASE_URL=postgresql://fiador_user:senha_segura@localhost:5432/fiador_db


3.2 Opção B: SQLite (Desenvolvimento)

Variáveis no .env:

Bash


DATABASE_URL=sqlite:///./Fiador.db


3.3 Criar Tabelas

Crie o arquivo backend/database/schema.sql:

SQL


-- Tabela de candidatos
create table candidatos (
    id serial primary key,
    uuid varchar(36) unique not null,
    nome_completo varchar(255) not null,
    cpf varchar(14) unique not null,
    rg varchar(20),
    email varchar(255),
    celular varchar(20),
    data_nascimento date,
    renda_declarada decimal(10,2),
   
    -- dados da consulta
    score_credito integer,
    renda_estimada decimal(10,2),
    pendencias_financeiras jsonb,
   
    -- status
    status varchar(50) default 'pendente',
    decisao_automatica varchar(50),
    motivo_reprovacao text,
   
    -- auditoria
    created_at timestamp default current_timestamp,
    updated_at timestamp default current_timestamp,
    processed_at timestamp
);

-- tabela de dados dos contratos
create table contratos_dados (
    id serial primary key,
    candidato_uuid varchar(36) unique not null,
    dados jsonb not null,
    status varchar(50) default 'pendente',
    preenchido_por varchar(255),
    data_preenchimento timestamp,
    clicksign_document_key varchar(255),
    asaas_payment_id varchar(255),
    created_at timestamp default current_timestamp,
    updated_at timestamp default current_timestamp,
   
    foreign key (candidato_uuid) references candidatos(uuid)
);

-- tabela de pagamentos
create table pagamentos (
    id serial primary key,
    candidato_uuid varchar(36) not null,
    tipo varchar(50) not null,  -- 'taxa_cadastro', 'primeiro_aluguel'
    valor decimal(10,2) not null,
    status varchar(50) default 'pendente',
    asaas_payment_id varchar(255),
    boleto_url text,
    vencimento date,
    data_pagamento timestamp,
    created_at timestamp default current_timestamp,
   
    foreign key (candidato_uuid) references candidatos(uuid)
);

-- tabela de contratos
create table contratos (
    id serial primary key,
    candidato_uuid varchar(36) not null,
    arquivo_path text,
    clicksign_document_key varchar(255),
    status varchar(50) default 'pendente',  -- 'pendente', 'enviado', 'assinado'
    data_envio timestamp,
    data_assinatura timestamp,
    created_at timestamp default current_timestamp,
   
    foreign key (candidato_uuid) references candidatos(uuid)
);

-- índices
create index idx_candidatos_cpf on candidatos(cpf);
create index idx_candidatos_status on candidatos(status);
create index idx_contratos_dados_status on contratos_dados(status);
create index idx_pagamentos_status on pagamentos(status);


execute:

bash


psql -u fiador_user -d fiador_db -f backend/database/schema.sql





⚙️ PASSO 4: Configurar Variáveis de Ambiente

Edite o arquivo backend/.env com todas as configurações:

Bash


# Ambiente
environment=development  # ou 'production'
debug=true

# banco de dados
database_url=postgresql://fiador_user:senha_segura@localhost:5432/fiador_db

# google sheets
google_credentials_file=config/google_credentials.json
GOOGLE_SHEET_ID=1abc123def456ghi789jkl
GOOGLE_SHEET_NAME=Cadastros

# Serasa Experian
SERASA_API_KEY=sua_chave_aqui
SERASA_API_SECRET=seu_secret_aqui
SERASA_BASE_URL=https://api.serasaexperian.com.br
SERASA_MOCK_MODE=True  # True para desenvolvimento

# Asaas (Boletos)
ASAAS_API_KEY=sua_api_key_aqui
ASAAS_BASE_URL=https://api.asaas.com/v3
ASAAS_ENVIRONMENT=sandbox

# ClickSign (Assinatura Digital)
CLICKSIGN_ACCESS_TOKEN=seu_token_aqui
CLICKSIGN_BASE_URL=https://api.clicksign.com/v1

# Dados da Imobiliária
Imobiliaria_nome="silva medeiros imóveis ltda - me"
imobiliaria_cnpj="02.689.804/0001-75"
IMOBILIARIA_ENDERECO="Avenida V - 08 Qd. 26 Lt. 05, Papillon Park, Aparecida de Goiânia - GO"
IMOBILIARIA_CEP="74950-190"
IMOBILIARIA_TELEFONE="(62) 3085-6242"
IMOBILIARIA_EMAIL="caixavivaimoveis@gmail.com"

# Regras de Decisão
SCORE_MINIMO_APROVACAO=700
SCORE_MINIMO_ANALISE_MANUAL=600
RENDA_MINIMA_MULTIPLICADOR=3  # Renda deve ser 3x o aluguel

# Segurança
SECRET_KEY=gere_uma_chave_secreta_aleatoria_aqui
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

# Logs
LOG_LEVEL=INFO
LOG_FILE=logs/app.log





🚀 PASSO 5: Executar o Sistema

5.1 Iniciar Backend

Bash


cd backend
source venv/bin/activate

# Executar em modo desenvolvimento
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Ou em produção
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4


Acesse a documentação automática:

•
Swagger UI: http://localhost:8000/docs

•
ReDoc: http://localhost:8000/redoc

5.2 Iniciar Frontend

Bash


cd frontend

# Modo desenvolvimento
npm run dev
# Acesse: http://localhost:5173

# Build para produção
npm run build
npm run preview





🧪 PASSO 6: Testar o Sistema

6.1 Testar Backend (API)

Bash


# Verificar saúde da API
curl http://localhost:8000/health

# Listar contratos pendentes
curl http://localhost:8000/api/v1/contratos/pendentes

# Processar novos cadastros
curl -X POST http://localhost:8000/api/v1/candidatos/processar


6.2 Testar Frontend

1.
Abra http://localhost:5173

2.
Verifique o dashboard

3.
Clique em "Processar Novos Cadastros"

4.
Verifique se aparecem contratos pendentes

5.
Clique em "Preencher Dados"

6.
Preencha o formulário

7.
Salve e verifique se o contrato é gerado

6.3 Testar Fluxo Completo

Cenário de Teste:

1.
Adicionar candidato no Google Sheets

•
Nome: João da Silva

•
CPF: 123.456.789-00

•
Email: joao@example.com

•
Renda: R$ 8.000,00



2.
Processar cadastro

•
Clique em "Processar Novos Cadastros"

•
Sistema consulta Serasa (mock)

•
Decisão automática: Aprovado



3.
Preencher dados do contrato

•
Candidato aparece em "Aguardando Dados"

•
Clique em "Preencher Dados"

•
Preencha todas as abas

•
Salve



4.
Verificar geração

•
Contrato PDF gerado em backend/contratos/

•
Enviado para ClickSign (se configurado)

•
Boleto gerado no Asaas (se configurado)






🔄 PASSO 7: Fluxo de Trabalho Detalhado

7.1 Fluxo do Candidato

Plain Text


1. Candidato preenche formulário Google Forms
  ↓
2. Dados salvos no Google Sheets
  ↓
3. Sistema detecta novo registro (polling ou webhook)
  ↓
4. Consulta Serasa Experian
  ↓
5. Motor de Decisão avalia:
  - Score ≥ 700 → APROVADO
  - Score 600-699 → análise manual
  - score < 600 → reprovado
  ↓
6. Se APROVADO:
  ↓
7. Candidato vai para "Aguardando Dados do Contrato"
  ↓
8. Corretor preenche dados personalizáveis
  ↓
9. Sistema gera contrato PDF
  ↓
10. Envia para ClickSign
    ↓
11. Gera boleto do primeiro aluguel
    ↓
12. Envia emails de notificação
    ↓
13. Aguarda assinatura
    ↓
14. Processo concluído ✅


7.2 Endpoints da API

Candidatos

Plain Text


post  /api/v1/candidatos/processar
get    /api/v1/candidatos
get    /api/v1/candidatos/{uuid}
put    /api/v1/candidatos/{uuid}/status
post  /api/v1/candidatos/{uuid}/aprovar-manual
post  /api/v1/candidatos/{uuid}/reprovar-manual


contratos (nova funcionalidade)

plain text


get    /api/v1/contratos/pendentes
get    /api/v1/contratos/{candidato_uuid}/dados
post  /api/v1/contratos/{candidato_uuid}/preencher
post  /api/v1/contratos/{candidato_uuid}/validar


webhooks

plain text


post  /api/v1/webhooks/asaas
post  /api/v1/webhooks/clicksign


admin

plain text


get    /api/v1/admin/estatisticas
get    /api/v1/admin/logs
post  /api/v1/admin/reprocessar/{uuid}





📊 passo 8: monitoramento e logs

8.1 Logs da Aplicação

Logs são salvos em backend/logs/app.log:

Bash


# Visualizar logs em tempo real
tail -f backend/logs/app.log

# Buscar erros
grep ERROR backend/logs/app.log

# Buscar por candidato específico
grep "123.456.789-00" backend/logs/app.log


8.2 Métricas Importantes

Monitore:

•
Taxa de aprovação automática

•
Tempo médio de processamento

•
Erros de integração com APIs

•
Contratos pendentes de preenchimento

•
Taxa de conversão (assinatura)




🔒 PASSO 9: Segurança

9.1 Checklist de Segurança




Alterar SECRET_KEY no .env




Usar HTTPS em produção




Configurar CORS corretamente




Validar todos os inputs




Não expor credenciais no código




Usar variáveis de ambiente




Implementar rate limiting




Logs de auditoria ativos




Backup automático do banco

9.2 LGPD - Proteção de Dados

•
Dados pessoais criptografados

•
Consentimento registrado

•
Logs de acesso

•
Direito ao esquecimento implementado

•
Política de privacidade clara




🚢 PASSO 10: Deploy em Produção

10.1 Opção A: VPS (DigitalOcean, AWS, etc.)

Bash


# 1. Configurar servidor
sudo apt update
sudo apt install python3-pip postgresql nginx

# 2. Clonar projeto
git clone <repo>
cd sistema-fiador

# 3. Configurar backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 4. Configurar Nginx
sudo nano /etc/nginx/sites-available/fiador

# Conteúdo:
server {
    listen 80;
    server_name seu-dominio.com;

    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location / {
        root /var/www/fiador/frontend/dist;
        try_files $uri /index.html;
    }
}

# 5. Ativar site
sudo ln -s /etc/nginx/sites-available/fiador /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

# 6. Configurar SSL (Let's Encrypt)
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d seu-dominio.com

# 7. Criar serviço systemd
sudo nano /etc/systemd/system/fiador-api.service

# Conteúdo:
[Unit]
Description=Fiador API
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/sistema-fiador/backend
Environment="PATH=/home/ubuntu/sistema-fiador/backend/venv/bin"
ExecStart=/home/ubuntu/sistema-fiador/backend/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000

[Install]
WantedBy=multi-user.target

# 8. Iniciar serviço
sudo systemctl enable fiador-api
sudo systemctl start fiador-api
sudo systemctl status fiador-api


10.2 Opção B: Docker

Plain Text


# backend/Dockerfile
From python:3.11-slim

workdir /app

copy requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]


Plain Text


# frontend/Dockerfile
from node:18-alpine

workdir /app

copy package*.Json ./
run npm install

copy . .
run npm run build

from nginx:alpine
copy --from=0 /app/dist /usr/share/nginx/html


yaml


# docker-compose.yml
version: '3.8'

services:
  db:
    image: postgres:14
    environment:
      POSTGRES_DB: fiador_db
      POSTGRES_USER: fiador_user
      POSTGRES_PASSWORD: senha_segura
    volumes:
      - postgres_data:/var/lib/postgresql/data

  backend:
    build: ./Backend
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://fiador_user:senha_segura@db:5432/fiador_db
    depends_on:
      - db

  frontend:
    build: ./Frontend
    ports:
      - "80:80"
    depends_on:
      - backend

volumes:
  postgres_data:





🐛 PASSO 11: Troubleshooting

Problemas Comuns

1. Erro ao conectar com Google Sheets

Plain Text


Solução:
- Verificar se o arquivo de credenciais existe
- Verificar se a planilha foi compartilhada com o Service Account
- Verificar se a API está ativada no Google Cloud


2. Erro ao gerar PDF

Plain Text


Solução:
- Instalar dependências do WeasyPrint:
  sudo apt install libpango-1.0-0 libpangoft2-1.0-0


3. CORS Error no Frontend

Plain Text


Solução:
- Adicionar origem do frontend em CORS_ORIGINS no .env
- Verificar se backend está rodando


4. Banco de dados não conecta

Plain Text


Solução:
- Verificar se PostgreSQL está rodando: sudo systemctl status postgresql
- Verificar credenciais no DATABASE_URL
- Verificar se o banco foi criado





📚 PASSO 12: Documentação Adicional

Arquivos de Referência

1.
README.md - Visão geral do projeto

2.
guia-instalacao.md - Instalação básica

3.
nova-funcionalidade-contratos.md - Documentação técnica da nova funcionalidade

4.
resumo-visual-nova-funcionalidade.md - Guia visual com diagramas

5.
resumo-executivo.md - Análise de ROI e benefícios

APIs Externas - Documentação

•
Google Sheets API: https://developers.google.com/sheets/api

•
Serasa Experian: https://www.serasaexperian.com.br/portal-integracao/

•
Asaas: https://docs.asaas.com/

•
ClickSign: https://developers.clicksign.com/




✅ Checklist Final de Implementação

Desenvolvimento




Ambiente Python configurado




Ambiente Node.js configurado




Banco de dados criado




Variáveis de ambiente configuradas




Backend rodando localmente




Frontend rodando localmente




Testes básicos passando

Integrações




Google Sheets API configurada




Serasa API configurada (ou mock ativo)




Asaas API configurada




ClickSign API configurada




Webhooks testados

Produção




Servidor configurado




Domínio apontando




ssl/https ativo




banco de dados em produção




backup automático configurado




monitoramento ativo




logs funcionando

segurança




credenciais seguras




cors configurado




rate limiting ativo




lgpd em conformidade




📞 suporte e contato

para dúvidas técnicas durante a implementação:

1.
Consulte a documentação nos arquivos .md

2.
Verifique os logs em backend/logs/

3.
Teste os endpoints via Swagger UI

4.
Entre em contato com o solicitante do projeto




🎯 Resultado Esperado

Após seguir todos os passos, você terá:

✅ Sistema completamente funcional
✅ Dashboard administrativo operacional
✅ Processamento automático de candidatos
✅ Formulário de preenchimento de contratos
✅ Geração automática de PDFs
✅ Integração com assinatura digital
✅ Geração de boletos
✅ Monitoramento e logs