> ## Documentation Index
> Fetch the complete documentation index at: https://docs.play2sell.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Integração CVCRM — Pagadoria de Comissões
> Como conectar o seu CVCRM ao Play2sell PAY e pagar comissões automaticamente — credenciais, webhooks, forma de pagamento, comprovante, ciclo de vida, testes, FAQ e solução de problemas. Configuração por telas, sem programação.
A **integração CVCRM × Pagadoria de Comissões** conecta o seu **CVCRM** ao **Play2sell PAY** para emitir o boleto da venda ao comprador e **pagar as comissões automaticamente** — com boleto, baixa, escrituração e comprovante refletidos de volta no seu CVCRM. A configuração é feita **por telas, sem programação**, e leva cerca de **15 minutos**.
## O que você vai configurar
Gerar um **token de API**, criar **3 webhooks** e garantir que a comissão use **forma de pagamento Boleto**.
**Conectar** o CVCRM (credenciais + mapeamento de situações) e **copiar a URL de webhook**.
| Passo | O que você faz | Resultado |
| ----- | ----------------------------------- | ------------------------------------------ |
| **1** | Gera um token no CVCRM | a credencial de API da conexão |
| **2** | Conecta o CVCRM no painel Play2sell | integração configurada |
| **3** | Copia a sua URL de webhook | o endereço para o CVCRM avisar o Play2sell |
| **4** | Cria 3 webhooks no CVCRM | o CVCRM passa a notificar cada evento |
| **5** | Testa com uma venda | confirma o fluxo ponta a ponta |
**Pré-requisitos**
* Acesso **administrativo** ao gestor do seu CVCRM (`suaempresa.cvcrm.com.br/gestor`).
* Um **usuário de API** dedicado (o CVCRM recomenda chamá-lo de **"Integração"**, para o histórico ficar atribuível). Se for usar o **comprovante de repasse** (Passo 2.4), esse usuário precisa ser **gestor com senha de acesso ao painel**.
* As **situações** (status) que você usa para **venda**, **escriturar** e **cancelamento/distrato** já configuradas no CVCRM.
* **Play2sell PAY** habilitado na sua conta (em dúvida, fale com o suporte).
## Como funciona a integração?
O **CVCRM é a fonte da verdade** da venda, das partes, do split de comissão e da escrituração. O **Play2sell PAY** emite o boleto ao comprador, custodia os recursos e distribui as comissões. Os dois sistemas ficam em sincronia por **webhooks** (o CVCRM avisa quando algo muda) e **write-backs** (o Play2sell informa o resultado de volta no CVCRM).
Ao registrar a venda, o CVCRM tem o valor, os beneficiários, o número de parcelas e os vencimentos.
O Play2sell origina a venda e emite um **boleto (com Pix)** ao comprador.
O boleto emitido é gravado de volta na **comissão** da reserva (situação "Programado").
Na confirmação do pagamento, o Play2sell informa o status **pago** de volta ao CVCRM.
Quando a comissão é escriturada, o Play2sell libera e distribui o repasse aos beneficiários.
Repasse via **PIX** a cada beneficiário; o **comprovante** é anexado à comissão no CVCRM. Em distrato, o valor é estornado.
**Sincronização segura.** Os webhooks do CVCRM são **magros** — carregam apenas um identificador (ex.: `{"idreserva": 123}`). O Play2sell usa esse aviso só como gatilho e **busca o registro completo de volta** na API do CVCRM, autenticado, antes de agir. Por isso um webhook forjado não injeta dado.
**Identidade é por CPF/CNPJ, nunca por e‑mail.** Compradores e beneficiários são resolvidos pelo **documento**. Garanta que corretores, imobiliária e demais beneficiários tenham CPF/CNPJ preenchido no CVCRM.
## Passo 1 — Obter as credenciais no CVCRM (e‑mail + token)
A conexão precisa de três valores do seu CVCRM: **domínio**, **e‑mail** e **token**.
No gestor do CVCRM, clique na engrenagem ⚙ (canto superior direito) e vá em **Usuários Administrativos**.
Localize o usuário de integração na lista e, em **Opções**, escolha **Tokens**.
Preencha a **Descrição** (ex.: `Play2sell`), escolha a **Validade do Token** e clique em **Gerar token**. O token aparece na **Listagem de Tokens** — em **Ações → Copiar Token**, copie-o.
* **E‑mail:** o e‑mail do usuário administrativo (precisa pertencer ao mesmo domínio do CVCRM).
* **Domínio:** o subdomínio da sua conta — a parte **antes** de `.cvcrm.com.br` (ex.: em `suaempresa.cvcrm.com.br`, o domínio é `suaempresa`).
Você tem em mãos **domínio**, **e‑mail** e **token** — os três valores do Passo 2.
O **token é sensível** — trate como uma senha. Para trocá-lo depois, gere um novo no CVCRM e atualize a conexão no painel Play2sell.
## Passo 2 — Conectar no painel Play2sell
No painel Play2sell, vá em **Integrações → Conectores**, encontre o **CVCRM** e clique em **Conectar**.
O formulário tem cinco blocos. Preencha cada um conforme abaixo.
### 2.1 — Credenciais
Preencha os três valores do Passo 1:
| Campo | O que informar |
| ------------------------ | ------------------------------------------------------------------------ |
| **Domínio** | O subdomínio antes de `.cvcrm.com.br` (ex.: `suaempresa`). |
| **E‑mail de integração** | O e‑mail do usuário de API. |
| **Token** | O token gerado no CVCRM (gravado de forma segura; não é exibido depois). |
### 2.2 — Mapeamento de situações
Aqui você diz ao Play2sell **qual situação do seu CVCRM** corresponde a cada ação. Informe o **nome** (ou o id) da situação, **exatamente** como aparece no seu CVCRM.
| Campo | Quando usar | Ação que dispara |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| **Vendida** | Situação da **reserva** que indica venda confirmada. | Origina a venda e emite o boleto. |
| **Escriturada** | (Opcional) Situação da **reserva** quando a escrituração é registrada na própria reserva. | Libera o repasse. |
| **Distrato** | (Opcional) Situação da **reserva** de cancelamento/distrato. | Estorno. |
| **Escriturada (via comissão)** | Use quando a escrituração no seu CVCRM é uma situação da **comissão** (ex.: "Escriturar"), e não da reserva. | Libera o repasse. |
| **Cancelada (via comissão)** | (Opcional) Situação da **comissão** que dispara distrato/estorno. | Estorno. |
Use o **label exato** da sua instância. As situações são configuráveis e mudam de empresa para empresa — "Vendida", "Venda Realizada", "Aprovada" etc. Copie o texto como ele aparece no seu CVCRM.
Muitas operações registram a escrituração **na comissão** (situação "Escriturar"), não na reserva. Nesse caso, deixe **Escriturada** em branco e preencha **Escriturada (via comissão)**.
### 2.3 — Situação de saída (write-back)
O **write-back** é quando o Play2sell informa o resultado de volta no CVCRM. Estes campos dizem **qual situação o seu CVCRM deve assumir** em cada evento. São **opcionais**.
| Campo | Significado | Exemplo |
| ----------------------- | ---------------------------------------------------------------- | ------------ |
| **Comissão com boleto** | Situação do pagamento da comissão **quando o boleto é emitido**. | `Programado` |
| **Comissão paga** | Situação do pagamento da comissão **quando há baixa** (pago). | `Pago` |
Para a situação de saída, prefira sempre o **nome** (ex.: `Programado`, `Pago`) em vez do id. Os ids da situação de pagamento variam por instância e podem cair em valores enganosos.
### 2.4 — Comprovante de repasse (opcional)
Faz o Play2sell **anexar o comprovante de pagamento (PDF)** à comissão no CVCRM quando o repasse é pago. É **opcional** e exige login de **gestor** no CVCRM.
| Campo | O que informar |
| ----------------------- | ------------------------------------------------------------------------------------- |
| **Tipo do comprovante** | O **nome do tipo de arquivo** cadastrado no seu CVCRM (ex.: `Comprovante_Play2sell`). |
| **Senha de gestor** | A **senha** do usuário gestor do CVCRM (o mesmo **e‑mail de integração**). |
**Credenciais que o comprovante exige.** O anexo usa a **API v3** do CVCRM, que — diferente do resto da integração (que usa o **token**) — faz **login com e‑mail + senha** no painel do gestor. Portanto:
* O **e‑mail de integração** (Passo 2.1) precisa ser de um **usuário gestor** que entre no painel do CVCRM **com senha**.
* Informe a **senha desse usuário** no campo **Senha de gestor**.
* O acesso é **renovado automaticamente** — você não atualiza nada periodicamente. Se trocar a senha no CVCRM, atualize-a aqui também.
O **tipo de comprovante precisa existir antes** no seu CVCRM, e o **nome** aqui tem que ser **idêntico** ao cadastrado lá. Veja como criá-lo no **Passo 4.2**. Sem essa configuração, todo o resto funciona — só o anexo do comprovante não acontece.
### 2.5 — Mapeamento de papéis (opcional)
Traduza o **tipo de comissão do seu CVCRM** para o papel do beneficiário no Play2sell. À esquerda, o texto como vem do CVCRM (ex.: `Corretor`); à direita, o papel: `VENDEDOR`, `IMOBILIARIA`, `HOUSE`, `GERENTE`, `COORDENADOR` ou `PARCEIRO`. Use **"+ Adicionar papel"** para incluir quantos precisar.
Clique em **Conectar** para salvar.
O CVCRM aparece como **conectado** no painel e abre a tela **"CRM conectado"** com a sua URL de webhook.
## Passo 3 — Copiar a URL de webhook
Ao clicar em **Conectar**, o Play2sell **provisiona automaticamente** o endpoint de recebimento e mostra a tela **"CRM conectado"** com a sua **URL de webhook** e um botão de **copiar**. Copie essa URL — você vai colá-la no CVCRM no próximo passo.
A URL é **única da sua conta**. Para recuperá-la depois, vá em **Integrações → Endpoints** — é onde os endpoints de webhook ficam listados.
Você tem a **URL de webhook** copiada — pronta para colar no CVCRM.
## Passo 4 — Configurar o CVCRM
Aqui você avisa o CVCRM para notificar o Play2sell a cada evento (4.1) e garante duas configurações de apoio (4.2 e 4.3).
### 4.1 — Criar os 3 webhooks
No gestor do CVCRM, vá em **Configurações ⚙ → Integrações** e abra o card **Webhooks** (em "Configurar").
Você vai criar **3 webhooks** — todos apontando para a **mesma URL** (a do Passo 3). O que muda em cada um é a **Funcionalidade** e a **situação do gatilho**:
| # | Funcionalidade | Situação do gatilho (exemplo) | Campo no painel (Passo 2.2) | O que dispara |
| ----- | -------------- | ----------------------------- | ------------------------------ | ------------------------------------------ |
| **1** | **Reserva** | venda / enviar à pagadoria | **Vendida** | originação + emissão do boleto |
| **2** | **Comissão** | escriturar | **Escriturada (via comissão)** | libera o repasse (PIX) |
| **3** | **Comissão** | cancelamento | **Cancelada (via comissão)** | cancela o boleto não pago / estorna o pago |
Para cada um, clique em **"+ Criar novo Webhook"** e preencha o formulário:
| Campo do CVCRM | O que informar |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Nome** | Um rótulo claro, à sua escolha (ex.: `Pagadoria — venda`). |
| **Funcionalidade** | **Reserva** (webhook 1) ou **Comissão** (webhooks 2 e 3). |
| **Workflow** | Aparece quando a Funcionalidade tem mais de um fluxo de situações. Em **Comissão** há mais de um workflow — escolha o que **contém a situação do gatilho** ("Escriturar" / "Cancelada"); na dúvida, abra o seletor e veja em qual workflow a situação aparece. Em **Reserva** normalmente há só um. |
| **Gatilho** | A **situação** que dispara o envio. Use o **label exato** da sua instância (a mesma do Passo 2.2). |
| **Forma de envio** | Deixe o padrão. |
| **Endereço** | **Cole a URL de webhook** copiada no Passo 3. |
| **Ativo no painel** | Deixe **ativo** — sem isso, o webhook não dispara. |
**Funcionalidade Reserva**, na situação que marca a venda / o envio para a pagadoria (a mesma do campo **Vendida**, Passo 2.2). Faz o Play2sell **originar a venda e emitir o boleto**.
**Funcionalidade Comissão**, na situação que indica escriturar/liberar — ex.: "Escriturar" (a mesma do campo **Escriturada (via comissão)**, Passo 2.2). **Libera o repasse** e paga os beneficiários via **PIX**.
**Funcionalidade Comissão**, na situação de cancelamento — ex.: "Cancelada" (a mesma do campo **Cancelada (via comissão)**, Passo 2.2). **Cancela** o boleto não pago ou **estorna** o pago, conforme o estado.
Vincule os webhooks ao usuário de integração ("Integração") — assim as alterações feitas pela automação ficam atribuíveis no histórico do CVCRM.
**Variação por instância.** Se o seu CVCRM registra a escrituração ou o cancelamento na **própria reserva** (e não na comissão), crie os webhooks 2 e 3 com **Funcionalidade Reserva** e, no Passo 2.2, use os campos **Escriturada** e **Distrato** em vez dos "(via comissão)". O comportamento é o mesmo.
**Confirme que os 3 webhooks estão disparando.** Na lista de webhooks, a coluna **Transações** conta cada envio. Se continuar **0** depois de mover um registro para a situação do gatilho, revise: a **Funcionalidade**, a **situação** (deve bater com o Passo 2.2), se o webhook está **Ativo no painel** e se o **Endereço** é a URL exata do Passo 3 (sem espaços).
### 4.2 — Cadastrar o tipo de comprovante (opcional)
Faça isto **apenas se** você habilitou o **Comprovante de repasse** no Passo 2.4. É uma configuração única que cria o **tipo de arquivo** usado para anexar o PDF do comprovante à comissão.
No gestor do CVCRM, vá em **Configurações → Tipos de Arquivos de Pagamento Comissão**, clique em **"+ Criar novo Tipo"** e preencha:
| Campo | O que informar |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Nome** | O nome do tipo (ex.: `Comprovante_Play2sell`). **Use exatamente este nome** no campo "Tipo do comprovante" do Passo 2.4. |
| **Ativo no painel** | `Ativo`. |
| **Tipo Pessoa** | `Física / Jurídica`. |
| **Obrigatório** | `Não` — o Play2sell anexa o comprovante automaticamente. |
### 4.3 — Garantir "Forma de pagamento = Boleto"
Para o boleto emitido pelo Play2sell aparecer como o recebível da comissão (e dar baixa corretamente), os **pagamentos da comissão no CVCRM** precisam usar a **forma de pagamento "Boleto"**.
Para conferir: em **Financeiro → Comissões**, abra uma comissão e clique no ícone **`$`** (Pagamentos). Na seção **Pagamentos**, cada parcela do beneficiário tem a coluna **"Forma de pagamento"** — ela deve estar como **Boleto**.
Se a parcela estiver com outra forma (ex.: "Transferência bancária"), o boleto que emitimos **não casa** com a comissão. Ajuste a forma para **Boleto** na regra/condição de comissão do seu CVCRM.
## Passo 5 — Testar e validar
Antes de operar de verdade, rode um teste de ponta a ponta com valores baixos.
Com comprador (CPF preenchido), valor válido e **comissões somando 100%** para um corretor.
Isso dispara o webhook de originação.
A venda aparece no painel Play2sell e o **boleto é anexado à comissão** no CVCRM (situação "Programado").
Use o Pix copia‑e‑cola (entra na hora).
A comissão muda para **"Pago"** no CVCRM.
Mova a comissão para a situação **Escriturar**.
O repasse PIX é pago ao beneficiário e o **comprovante** é anexado à comissão (se configurado no Passo 2.4).
## Próximos passos
Depois de validar, a integração já opera sozinha. No dia a dia:
* **Cada venda** que entra na situação de pagadoria gera o boleto e o reflete na comissão do CVCRM, sem ação manual.
* **Acompanhe** o status das comissões em **Financeiro → Comissões** (CVCRM) e das vendas no **painel Play2sell**.
* **Para ajustar** o mapeamento de situações ou as credenciais depois, volte em **Integrações → Conectores → CVCRM → Editar configuração**.
## Perguntas frequentes
Não. Toda a configuração é feita por telas, no gestor do CVCRM e no painel do Play2sell. Você só precisa de acesso administrativo aos dois sistemas. Nenhum código é necessário.
Três, todos apontando para a **mesma URL**: (1) **Reserva** na situação de venda → originação; (2) **Comissão** na situação "Escriturar" → libera o repasse; (3) **Comissão** na situação de cancelamento → estorno.
O CVCRM mostra a comissão **bruta**. O Play2sell aplica a **taxa de serviço** (em geral 1–3%) e o beneficiário recebe o **líquido** via PIX. O cálculo usa o **valor da comissão**, não o da venda.
Sim. O boleto e o split são calculados sobre o **valor da comissão**, então qualquer percentual funciona.
Após a comissão ser **escriturada** no CVCRM, o repasse via **PIX** é processado em segundos e cai na conta do beneficiário.
Não, é **opcional**. Sem ele, o repasse é pago normalmente; apenas o anexo do PDF na comissão do CVCRM não acontece.
## Solução de problemas
Verifique no CVCRM: o webhook está **Ativo**? A **Funcionalidade** (Reserva/Comissão) e a **situação** do gatilho batem com o que você mapeou no painel? O **Endereço** é a URL exata copiada no Passo 3 (sem espaços/quebras)?
Confirme que a **forma de pagamento** da comissão é **Boleto** (Passo 4.3) e que a situação de saída **"Comissão com boleto"** está preenchida (ex.: `Programado`). Reprocessar a reserva costuma resolver casos de configuração ajustada depois.
A identidade é por **CPF/CNPJ**, nunca por e‑mail. Garanta que o documento do beneficiário está preenchido e correto no CVCRM.
Confirmações de pagamento e write-backs podem levar alguns instantes. Se persistir, reprocesse a reserva ou fale com o suporte.
## Referência
### Ciclo de vida ponta a ponta
| Etapa | Evento no CVCRM | Ação do Play2sell | O que você vê |
| ------------------------- | ---------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------- |
| **1. Originação** | Reserva → situação de venda | Cria a venda + split e emite o **boleto (com Pix)** | Venda no painel; boleto gerado |
| **2. Boleto na comissão** | — (write-back) | Anexa o boleto à comissão | Comissão fica **Programado**; colunas Boleto/ID Pagadoria preenchidas |
| **3. Pagamento / baixa** | Comprador paga o boleto | Confirma o pagamento e informa o CVCRM | Comissão fica **Pago** |
| **4. Escrituração** | Comissão → situação **Escriturar** | Libera o repasse | Protocolo liberado |
| **5. Repasse** | — | Paga o beneficiário via **PIX** | Repasse concluído (líquido) |
| **6. Comprovante** | — (write-back) | Anexa o comprovante à comissão | PDF em "Documentos do pagamento da Comissão" |
| **Distrato** | Reserva/Comissão → cancelamento | Estorna conforme o estado | Operação estornada |
### Contrato de erro
Respostas de erro seguem o formato `{ code, message, hint? }`:
* **4xx — rejeição:** algo está incorreto (ex.: situação não mapeada). **Corrija e tente de novo.**
* **5xx — erro transitório:** falha temporária. É **reprocessado automaticamente**.
### Apêndice técnico
Esta seção é para times técnicos. A configuração acima não exige nada daqui.
**Famílias de API do CVCRM**
| Família | Uso | Observação |
| ----------------------------- | ----------------------------- | -------------------------------------------------------------------- |
| **v1** (`/api/v1//*`) | Atual — usada pela integração | Auth por headers `email` + `token`; 200 req/min |
| **CVIO** (`/api/cvio/*`) | Legado | **Em depreciação** — o CVCRM está padronizando para v1 |
| **CVDW** (`/api/v1/cvdw/*`) | BI / data warehouse | **Contrato pago à parte**; 20 req/min; retorna 403 se não contratado |
**Sincronização e idempotência**
* **Webhook magro → pull-back:** o webhook carrega só um id; o Play2sell busca o registro completo via `GET` autenticado antes de agir.
* **Idempotência:** cada contrato mapeia para uma chave estável derivada do id da reserva (`cvcrm:{idreserva}`); reentrega nunca duplica a venda.
* **Ordem:** se a escrituração chega antes de a originação concluir, é adiada e reprocessada.
**Atenções (gotchas)**
* O CVCRM pode retornar **HTTP 200 com `codigo:404` no corpo** para rotas inexistentes — sempre confira o campo `codigo`, não só o status HTTP.
* Filtros de data em alguns endpoints são **ignorados** — janele no lado do cliente.
* Datas no GET de parcelas usam **DD/MM/AAAA**.
* Existem **dois workflows de situação distintos** — o da **comissão** e o do **pagamento da comissão** — com ids que podem colidir. Por isso o write-back de situação usa o **nome** ("Programado"/"Pago"), não o id.
## Suporte
Precisa de ajuda para mapear as situações da sua instância? Fale com o suporte em **[suporte@play2sell.com](mailto:suporte@play2sell.com)** com o seu **domínio** e a lista de situações que você usa para vendida / escriturar / distrato.