Integração Portal do Cliente CVCRM

📘 Visão Geral

As APIs do Portal do Cliente CVCRM foram criadas para que parceiros, integradores e desenvolvedores possam construir portais personalizados ou chatbots conectados ao ecossistema do Construtor de Vendas (CVCRM) e possuam integração com o ERP Sienge.

Essas APIs permitem que os clientes finais — compradores de imóveis — acessem informações do seu contrato, boletos, documentos, mensagens e dados de cadastro diretamente em um ambiente criado pelo parceiro.

🔐 1. Autenticação e Acesso do Cliente

A jornada do cliente começa pela autenticação.
O CVCRM disponibiliza diferentes formas de login e validação de identidade, permitindo integração flexível com o portal ou chatbot.

Endpoints principais

POST /autenticacao – Login com e-mail e senha.
POST /autenticacao/sindico – Login voltado a síndicos.
POST /autenticacao-externa/{origem} – Login via sistema externo.
POST /codigo-verificacao – Envia código de acesso por e-mail/SMS.
POST /validar-autenticacao – Valida o código e confirma o login.
POST /resetar-senha-email e /resetar-senha-sms – Redefinem a senha do usuário.

💡 Fluxo típico:
O cliente informa CPF/e-mail → recebe código → valida → obtém token de acesso.

👤 2. Dados do Cliente (Pessoa)

Após o login, o parceiro pode buscar e exibir informações pessoais do cliente.

GET /pessoa – Retorna dados básicos do cliente.
PUT /pessoa – Atualiza informações cadastrais.

💡 Uso prático:
Chatbots podem confirmar se os dados estão atualizados ou permitir alterações simples como telefone e e-mail.

🏢 3. Empreendimentos, Unidades e Contratos

O cliente pode visualizar o imóvel adquirido, o empreendimento e o status contratual.

GET /empreendimento – Lista empreendimentos vinculados ao cliente.
GET /unidade – Retorna detalhes da unidade.
GET /contrato – Exibe contratos de compra e venda.

💡 Uso prático:
O portal pode ter uma seção “Meu Imóvel”, e o chatbot pode responder perguntas sobre a unidade.

💰 4. Boletos e Financeiro

Essas APIs permitem visualizar boletos e acompanhar o status de pagamentos via extrato financeiros oriundos do ERP Sienge.

GET /boleto – Lista boletos e status.
GET /boleto/{id} – Retorna o boleto específico.

💡 Uso prático:
O chatbot pode enviar o link do boleto diretamente ao cliente.

📄 5. Documentos e Arquivos

Os clientes podem consultar ou baixar documentos oficiais.

GET /documento – Lista documentos disponíveis.
GET /documento/{id} – Faz o download de um arquivo.

💡 Uso prático:
Chatbots podem atender comandos como “Baixar meu contrato” e enviar o arquivo ao cliente.

💬 6. Comunicação e Mensagens

Permite troca de mensagens entre cliente e construtora.

GET /mensagem – Lista mensagens trocadas.
POST /mensagem – Envia nova mensagem ao time da construtora.

💡 Uso prático:
Em chatbots, esse recurso mantém o histórico de atendimentos e dúvidas.

⚙️ 7. Segurança, Tokens e Boas Práticas

Todas as requisições exigem token JWT, enviado no header:
```
Authorization: Bearer {token}
```
Tokens têm validade limitada; o cliente deve se autenticar novamente após expiração.
Evite armazenar dados sensíveis (CPF, token, e-mail) sem criptografia.

🧩 8. Exemplo de Fluxo Completo (Chatbot)

Cliente inicia conversa → informa CPF.
Chatbot chama /codigo-verificacao.
Cliente recebe o código → chatbot chama /validar-autenticacao.
Com o token obtido, o chatbot consulta:
- /pessoa → dados pessoais
- /boleto → boletos em aberto
- /contrato → status do contrato
Cliente solicita “Baixar contrato” → chatbot chama /documento/{id}.

🪄 9. Diagrama do Fluxo de Integração

flowchart TD
    A[Início da interação] --> B[Cliente informa CPF ou e-mail]
    B --> C[POST /codigo-verificacao]
    C --> D[Cliente recebe código por e-mail/SMS]
    D --> E[POST /validar-autenticacao]
    E --> F[Token JWT gerado]
    F --> G[GET /pessoa<br/>Consultar dados pessoais]
    F --> H[GET /contrato<br/>Visualizar contrato]
    F --> I[GET /boleto<br/>Listar boletos]
    F --> J[GET /documento<br/>Baixar documentos]
    F --> K[GET /mensagem<br/>Histórico de mensagens]
    F --> L[POST /mensagem<br/>Enviar nova mensagem]
    J --> M[Fim da jornada do cliente]
    I --> M
    H --> M
    K --> M
    L --> M

🧱 Conclusão

As APIs do Portal do Cliente CVCRM oferecem a base necessária para criar experiências digitais personalizadas, permitindo que os clientes acompanhem seus imóveis, pagamentos e documentos de forma simples e segura — seja em portais, aplicativos ou chatbots.

⚙️ Referências

https://desenvolvedor.cvcrm.com.br/reference/auth-2