Documentação
Start typing to search…

📘 Tutorial de Integração ERP ↔ CVCRM

Resumo dos endpoints no fluxo simplificado para integrar um ERP ao CVCRM

A integração entre o ERP e o CVCRM é organizada em fases, respeitando onde o dado nasce e para onde ele deve ser enviado.

🔹 Fase 1 – Cadastrando a Base de Dados

Aqui são enviados os dados de estrutura de venda: empreendimento → etapas → blocos → unidades.

👉 Se a origem for o ERP, utilize POST para enviar ao CVCRM.

Cadastrar Empreendimento - POST /empreendimentos

{
  "idempreendimento_int": "ERP123",
  "nome": "Residencial Jardim das Flores",
  "matricula": "12345",
  "cidade": "Belo Horizonte",
  "estado": "MG",
  "idempresa_int": "ERP001",
  "nome_empresa": "Incorp ABC",
  "razao_social": "Incorp ABC Ltda",
  "cnpj": "12345678000190",
  "sigla": "ABC",
  "ativo": true
}

Cadastrar Etapa - POST /etapas

#{
  "idetapa_int": "ETP001",
  "idempreendimento_int": "ERP123",
  "nome": "Etapa 1",
  "data_cadastro": "2025-09-15"
}

📌 Se o ERP não tiver etapas, crie uma etapa única com código genérico.


Cadastrar Bloco - POST /blocos

{
  "idbloco_int": "BL001",
  "idetapa_int": "ETP001",
  "idempreendimento_int": "ERP123",
  "nome": "Bloco A",
  "data_cadastro": "2025-09-15"
}

Cadastrar Unidade - POST /unidades

{
  "idunidade_int": "UN001",
  "idbloco_int": "BL001",
  "idetapa_int": "ETP001",
  "idempreendimento_int": "ERP123",
  "nome": "Apto 101",
  "area_privativa": 65.5,
  "situacao": "disponivel"
}

📌 Dica: O CVCRM possui campos extras. Sempre que possível, aproveite-os para enriquecer a base, mesmo que o ERP não os tenha.

🔹 Fase 2 – Montando a Equipe de Vendas

O CVCRM depende da equipe para processar reservas.

Cadastrar Imobiliária

  • POST /imobiliarias
{
  "idimobiliaria_int": "IMO001",
  "nome": "Imobiliária Sol Nascente",
  "cnpj": "22345678000190",
  "ativo": true
}

Cadastrar Corretor POST /corretores

{
  "idcorretor_int": "COR001",
  "nome": "João Silva",
  "creci": "12345/MG",
  "email": "[email protected]",
  "ativo": true
}

Vincular ao Empreendimento - POST /empreendimento/imobiliaria ou POST /empreendimento/corretores

{
  "idempreendimento_int": "ERP123",
  "idimobiliaria_int": "IMO001"
}

🔹 Fase 3 – Propostas, Reservas e Contratos


Webhook - Receber Reserva Criada

Quando uma reserva é feita no CVCRM, o ERP recebe um webhook:

{
    "idreserva": "RES123"
}

Consultar Detalhes da Reserva - GET /reservas/idreserva

{
  "idreserva": "RES123",
  "idempreendimento": "ERP123",
  "idetapa": "ETP001",
  "idbloco": "BL001",
  "idunidade": "UN001",
  "idimobiliaria": "IMO001",
  "idcorretor": "COR001",
  "titular": "CLI001",
  "associados": ["CLI002"]
}

Consultar Cliente da Reserva - GET /clientes/idcliente

{
  "idcliente": "CLI001",
  "nome": "Maria Oliveira",
  "cpf": "12345678901",
  "email": "[email protected]"
}

Assim, o ERP consegue registrar o contrato.

🔹 Fase 4 – Envio de Boletos para o CVCRM

Os boletos sempre têm origem no ERP e precisam ser enviados ao CVCRM para que o cliente final visualize no portal.

Via multipart/form-data (com upload de arquivo PDF)

Esse formato é útil quando você precisa anexar o boleto em PDF diretamente na requisição.

curl -X 'POST' \
  'https://integracao.cvcrm.com.br/api/v1/financeiro/boletos' \
  -H 'accept: application/json' \
  -H 'email: [email protected]' \
  -H 'token: ' \
  -H 'Content-Type: multipart/form-data' \
  -F 'valor=1999.99' \
  -F 'codigointerno=BOL01' \
  -F 'vencimento=2023-05-01' \
  -F '[email protected]' \
  -F 'tipo=Ato' \
  -F 'linha_digitavel=00190500954014481606906809350314337370000000100' \
  -F 'titulo=BOL01' \
  -F 'codigointerno_reserva=5458954' \
  -F 'idreserva=123'

📌 Observações: • arquivo deve ser um PDF válido. • codigointerno_reserva ou idreserva relaciona o boleto a uma reserva/contrato já existente no CVCRM.

Via JSON (mais simples, sem upload de arquivo)

Se não precisar anexar o PDF, basta enviar os dados básicos via JSON:

curl -X 'POST' \
  'https://integracao.cvcrm.com.br/api/v1/financeiro/boletos' \
  -H 'accept: application/json' \
  -H 'email: [email protected]' \
  -H 'token: ' \
  -H 'Content-Type: application/json' \
  -d '{
    "idcliente": "CLI001",
    "idcontrato": "CTR001",
    "nosso_numero": "1234567",
    "valor": 1500.00,
    "vencimento": "2025-10-10",
    "linha_digitavel": "34191.79001 01043.510047 91020.150008 1 94880000015000"
  }

📌 Observações: • idcliente e idcontrato são retornados quando você busca dados de contratos e clientes no CVCRM. • nosso_numero é o identificador do boleto no ERP. • linha_digitavel garante que o boleto seja validado e pago corretamente.

👉 Regra geral:

• Se o ERP gera o PDF, use multipart/form-data. • Se só precisa registrar a cobrança, use JSON.

Envio de Extratos para o CVCRM

O extrato também nasce no ERP (origem do dado). Ele deve ser enviado ao CVCRM para que o cliente final possa visualizar no portal ou no aplicativo.

🔹 Envio com PDF em multipart/form-data

curl --request POST \
     --url https://integracao.cvcrm.com.br/api/v1/financeiro/extratos \
     --header 'accept: application/json' \
     --header 'email: [email protected]' \
     --header 'token: 79d965e5027b7423423f2471824e799949c75f9ce' \
     --header 'content-type: multipart/form-data' \
     --form idreserva=123 \
     --form codigointerno_reserva=123 \
     --form 'descricao=Extrato referente a Maio/2025' \
     --form arquivo='@Fatura.pdf'

📌 Campos principais: • idreserva ou codigointerno_reserva → identifica a reserva/contrato. • descricao → texto explicativo que será exibido ao cliente. • arquivo → PDF do extrato, enviado direto na requisição.

Envio somente em JSON (sem PDF)

Se o ERP não gera o PDF, mas quer apenas registrar o movimento:

curl --request POST \
     --url https://integracao.cvcrm.com.br/api/v1/financeiro/extratos \
     --header 'accept: application/json' \
     --header 'email: [email protected]' \
     --header 'token: ' \
     --header 'Content-Type: application/json' \
     --data '{
       "idreserva": "123",
       "descricao": "Extrato detalhado de Maio/2025",
       "valor_total": 4500.00,
       "periodo_inicio": "2025-05-01",
       "periodo_fim": "2025-05-31"
     }'

📌 Nesse caso: • valor_total, periodo_inicio e periodo_fim podem ser usados para exibir um resumo do extrato sem a necessidade de PDF. • É opcional, mas recomendado preencher para dar mais contexto ao cliente.

Assim como nos boletos:

• Use multipart/form-data se precisar anexar o PDF. • Use JSON se só quiser registrar os dados resumidos.


Enviar Informe de Rendimentos (IR)

Envio de Informe de Rendimentos (IR) para o CVCRM O ERP gera o IR (geralmente em PDF) e envia ao CVCRM. O cliente final acessa esse documento pelo portal/aplicativo.

🔹 Envio com PDF (multipart/form-data)

curl --request POST \
     --url https://integracao.cvcrm.com.br/api/v1/financeiro/informe-rendimentos \
     --header 'accept: application/json' \
     --header 'email: [email protected]' \
     --header 'token: ' \
     --header 'content-type: multipart/form-data' \
     --form idreserva=12 \
     --form codigointerno_reserva=12 \
     --form ano=2024 \
     --form 'descricao=Informe de rendimentos referente ao exercício 2024' \
     --form [email protected]

📌 Campos principais: • idreserva ou codigointerno_reserva → identifica a reserva/contrato associado ao cliente. • ano → ano-base do informe de rendimentos. • descricao → texto explicativo exibido no portal do cliente. • arquivo → PDF oficial do informe de rendimentos.

Envio em JSON (sem PDF)

Caso não precise anexar o documento, é possível registrar os dados básicos via JSON:

curl --request POST \
     --url https://integracao.cvcrm.com.br/api/v1/financeiro/informe-rendimentos \
     --header 'accept: application/json' \
     --header 'email: [email protected]' \
     --header 'token: ' \
     --header 'Content-Type: application/json' \
     --data '{
       "idreserva": "12",
       "ano": 2024,
       "descricao": "Informe de rendimentos exercício 2024",
       "rendimento_total": 48000.50,
       "imposto_retido": 3200.75
     }'

📌 Nesse formato: • rendimento_total e imposto_retido são opcionais, mas úteis para consulta rápida no sistema. • O PDF continua sendo o meio mais comum, mas o JSON pode complementar com valores numéricos.

👉 Resumindo:

• ERP → POST /financeiro/informe-rendimentos → CVCRM → Cliente final consulta no portal/app. • Sempre relacione o IR a uma reserva/contrato (idreserva ou codigointerno_reserva). • Prefira PDF (multipart/form-data), mas JSON é aceito para resumo. Assim o CVCRM passa a exibir ao cliente final, via portal ou app, todas as informações financeiras vindas do ERP.

✅ Resumo do Fluxo

• ERP → CVCRM: Empreendimentos, etapas, blocos, unidades e dados financeiros. • CVCRM → ERP: Reservas e propostas (via webhook + GET). • ERP → Cliente final (via CVCRM): Boletos, extratos, informes de rendimento.


Updated about 4 hours ago