> ## 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.

# Integración CVCRM — Pagaduría de Comisiones

> Cómo conectar tu CVCRM a Play2sell PAY y pagar comisiones automáticamente — credenciales, webhooks, forma de pago, comprobante, ciclo de vida, pruebas, FAQ y solución de problemas. Configuración por pantallas, sin programación.

La **integración CVCRM × Pagaduría de Comisiones** conecta tu **CVCRM** a **Play2sell PAY** para emitir el boleto de la venta al comprador y **pagar las comisiones automáticamente** — con boleto, conciliación, escrituración y comprobante reflejados de vuelta en tu CVCRM. La configuración se hace **por pantallas, sin programación**, y toma alrededor de **15 minutos**.

## Qué vas a configurar

<Steps>
  <Step title="En el CVCRM">
    Generar un **token de API**, crear **3 webhooks** y asegurar que la comisión use **forma de pago Boleto**.
  </Step>

  <Step title="En el panel Play2sell">
    **Conectar** el CVCRM (credenciales + mapeo de situaciones) y **copiar la URL de webhook**.
  </Step>
</Steps>

| Paso  | Qué haces                               | Resultado                                        |
| ----- | --------------------------------------- | ------------------------------------------------ |
| **1** | Generas un token en el CVCRM            | la credencial de API de la conexión              |
| **2** | Conectas el CVCRM en el panel Play2sell | integración configurada                          |
| **3** | Copias tu URL de webhook                | la dirección para que el CVCRM avise a Play2sell |
| **4** | Creas 3 webhooks en el CVCRM            | el CVCRM empieza a notificar cada evento         |
| **5** | Pruebas con una venta                   | confirma el flujo de extremo a extremo           |

<Note>
  **Requisitos previos**

  * Acceso **administrativo** al gestor de tu CVCRM (`tuempresa.cvcrm.com.br/gestor`).
  * Un **usuario de API** dedicado (el CVCRM recomienda llamarlo **"Integração"**, para que el historial quede atribuible). Si vas a usar el **comprobante de transferencia** (Paso 2.4), ese usuario debe ser **gestor con contraseña de acceso al panel**.
  * Las **situaciones** (estados) que usas para **venta**, **escriturar** y **cancelación/rescisión** ya configuradas en el CVCRM.
  * **Play2sell PAY** habilitado en tu cuenta (en caso de duda, habla con el soporte).
</Note>

## ¿Cómo funciona la integración?

El **CVCRM es la fuente de la verdad** de la venta, de las partes, del split de comisión y de la escrituración. **Play2sell PAY** emite el boleto al comprador, custodia los recursos y distribuye las comisiones. Los dos sistemas se mantienen sincronizados mediante **webhooks** (el CVCRM avisa cuando algo cambia) y **write-backs** (Play2sell informa el resultado de vuelta en el CVCRM).

<Steps>
  <Step title="El CVCRM crea el contrato">
    Al registrar la venta, el CVCRM tiene el monto, los beneficiarios, el número de cuotas y los vencimientos.
  </Step>

  <Step title="Play2sell emite el boleto">
    Play2sell origina la venta y emite un **boleto (con Pix)** al comprador.
  </Step>

  <Step title="El boleto vuelve al CVCRM">
    El boleto emitido se registra de vuelta en la **comisión** de la reserva (situación "Programado").
  </Step>

  <Step title="El comprador paga → el CVCRM recibe la conciliación">
    Al confirmarse el pago, Play2sell informa el estado **pago** de vuelta al CVCRM.
  </Step>

  <Step title="El CVCRM escritura → se libera la transferencia">
    Cuando la comisión es escriturada, Play2sell libera y distribuye la transferencia a los beneficiarios.
  </Step>

  <Step title="Play2sell paga y adjunta el comprobante">
    Transferencia vía **PIX** a cada beneficiario; el **comprobante** se adjunta a la comisión en el CVCRM. En caso de rescisión, el monto se reembolsa.
  </Step>
</Steps>

<Note>
  **Sincronización segura.** Los webhooks del CVCRM son **livianos** — llevan solo un identificador (ej.: `{"idreserva": 123}`). Play2sell usa ese aviso solo como disparador y **busca el registro completo de vuelta** en la API del CVCRM, autenticado, antes de actuar. Por eso un webhook falsificado no inyecta datos.
</Note>

<Warning>
  **La identidad es por CPF/CNPJ, nunca por correo electrónico.** Compradores y beneficiarios se resuelven por el **documento**. Asegúrate de que corredores, inmobiliaria y demás beneficiarios tengan el CPF/CNPJ completado en el CVCRM.
</Warning>

## Paso 1 — Obtener las credenciales en el CVCRM (correo + token)

La conexión necesita tres valores de tu CVCRM: **dominio**, **correo** y **token**.

<Steps>
  <Step title="Abre Usuários Administrativos">
    En el gestor del CVCRM, haz clic en el engranaje ⚙ (esquina superior derecha) y ve a **Usuários Administrativos**.
  </Step>

  <Step title="Abre las opciones del usuario de integración">
    Localiza el usuario de integración en la lista y, en **Opções**, elige **Tokens**.

    <Frame caption="Gestor CVCRM → Usuários Administrativos → lista de usuarios">
      <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/09-cvcrm-usuarios.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=52da52556f8d82a578af4adc3efcff43" alt="Página Usuários Administrativos del CVCRM" width="1650" height="544" data-path="images/integrations/cvcrm/09-cvcrm-usuarios.png" />
    </Frame>
  </Step>

  <Step title="Genera y copia el token">
    Completa la **Descrição** (ej.: `Play2sell`), elige la **Validade do Token** y haz clic en **Gerar token**. El token aparece en la **Listagem de Tokens** — en **Ações → Copiar Token**, cópialo.

    <Frame caption="Pantalla de Tokens — generar y, en Ações → Copiar Token, copiar">
      <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/10-cvcrm-token.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=d722dfbaad33d15838e2bfd866a31fa7" alt="Generación y copia del token en el CVCRM (Ações → Copiar Token)" width="1658" height="1272" data-path="images/integrations/cvcrm/10-cvcrm-token.png" />
    </Frame>
  </Step>

  <Step title="Anota el correo y el dominio">
    * **Correo:** el correo del usuario administrativo (debe pertenecer al mismo dominio del CVCRM).
    * **Dominio:** el subdominio de tu cuenta — la parte **antes** de `.cvcrm.com.br` (ej.: en `tuempresa.cvcrm.com.br`, el dominio es `tuempresa`).
  </Step>
</Steps>

<Check>Tienes a mano **dominio**, **correo** y **token** — los tres valores del Paso 2.</Check>

<Note>
  El **token es sensible** — trátalo como una contraseña. Para cambiarlo después, genera uno nuevo en el CVCRM y actualiza la conexión en el panel Play2sell.
</Note>

## Paso 2 — Conectar en el panel Play2sell

En el panel Play2sell, ve a **Integrações → Conectores**, encuentra el **CVCRM** y haz clic en **Conectar**.

<Frame caption="Integrações → Conectores → CVCRM">
  <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/01-conectores.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=32092647dee9db29cb24f393f7f89606" alt="Tarjeta del conector CVCRM" width="1320" height="854" data-path="images/integrations/cvcrm/01-conectores.png" />
</Frame>

El formulario tiene cinco bloques. Completa cada uno según lo siguiente.

<Frame caption="Modal “Conectar CRM/ERP” — formulario completo">
  <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/02-conectar-modal.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=55be8ae29645a865c7c64eb727d0516f" alt="Formulario Conectar CRM/ERP: credenciales, mapeo de situaciones, situación de salida y comprobante de transferencia" width="670" height="1160" data-path="images/integrations/cvcrm/02-conectar-modal.png" />
</Frame>

### 2.1 — Credenciales

Completa los tres valores del Paso 1:

| Campo                    | Qué informar                                                                     |
| ------------------------ | -------------------------------------------------------------------------------- |
| **Domínio**              | El subdominio antes de `.cvcrm.com.br` (ej.: `tuempresa`).                       |
| **E-mail de integração** | El correo del usuario de API.                                                    |
| **Token**                | El token generado en el CVCRM (guardado de forma segura; no se muestra después). |

### 2.2 — Mapeo de situaciones

Aquí le dices a Play2sell **qué situación de tu CVCRM** corresponde a cada acción. Informa el **nombre** (o el id) de la situación, **exactamente** como aparece en tu CVCRM.

| Campo                          | Cuándo usar                                                                                                            | Acción que dispara                  |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **Vendida**                    | Situación de la **reserva** que indica venta confirmada.                                                               | Origina la venta y emite el boleto. |
| **Escriturada**                | (Opcional) Situación de la **reserva** cuando la escrituración se registra en la propia reserva.                       | Libera la transferencia.            |
| **Distrato**                   | (Opcional) Situación de la **reserva** de cancelación/rescisión.                                                       | Reembolso.                          |
| **Escriturada (vía comisión)** | Úsala cuando la escrituración en tu CVCRM es una situación de la **comissão** (ej.: "Escriturar"), y no de la reserva. | Libera la transferencia.            |
| **Cancelada (vía comisión)**   | (Opcional) Situación de la **comissão** que dispara rescisión/reembolso.                                               | Reembolso.                          |

<Warning>
  Usa el **label exacto** de tu instancia. Las situaciones son configurables y cambian de empresa a empresa — "Vendida", "Venda Realizada", "Aprovada", etc. Copia el texto tal como aparece en tu CVCRM.
</Warning>

<Tip>
  Muchas operaciones registran la escrituración **en la comisión** (situación "Escriturar"), no en la reserva. En ese caso, deja **Escriturada** en blanco y completa **Escriturada (vía comisión)**.
</Tip>

### 2.3 — Situación de salida (write-back)

El **write-back** es cuando Play2sell informa el resultado de vuelta en el CVCRM. Estos campos indican **qué situación debe asumir tu CVCRM** en cada evento. Son **opcionales**.

| Campo                   | Significado                                                           | Ejemplo      |
| ----------------------- | --------------------------------------------------------------------- | ------------ |
| **Comissão com boleto** | Situación del pago de la comisión **cuando el boleto se emite**.      | `Programado` |
| **Comissão paga**       | Situación del pago de la comisión **cuando hay conciliación** (pago). | `Pago`       |

<Warning>
  Para la situación de salida, prefiere siempre el **nombre** (ej.: `Programado`, `Pago`) en lugar del id. Los ids de la situación de pago varían por instancia y pueden caer en valores engañosos.
</Warning>

### 2.4 — Comprobante de transferencia (opcional)

Hace que Play2sell **adjunte el comprobante de pago (PDF)** a la comisión en el CVCRM cuando la transferencia se paga. Es **opcional** y exige inicio de sesión de **gestor** en el CVCRM.

| Campo                   | Qué informar                                                                             |
| ----------------------- | ---------------------------------------------------------------------------------------- |
| **Tipo do comprovante** | El **nombre del tipo de archivo** registrado en tu CVCRM (ej.: `Comprovante_Play2sell`). |
| **Senha de gestor**     | La **contraseña** del usuario gestor del CVCRM (el mismo **e-mail de integração**).      |

<Warning>
  **Credenciales que el comprobante exige.** El adjunto usa la **API v3** del CVCRM, que — a diferencia del resto de la integración (que usa el **token**) — hace **login con correo + contraseña** en el panel del gestor. Por lo tanto:

  * El **e-mail de integração** (Paso 2.1) debe ser de un **usuario gestor** que entre al panel del CVCRM **con contraseña**.
  * Informa la **contraseña de ese usuario** en el campo **Senha de gestor**.
  * El acceso se **renueva automáticamente** — no actualizas nada periódicamente. Si cambias la contraseña en el CVCRM, actualízala aquí también.
</Warning>

<Note>
  El **tipo de comprobante debe existir antes** en tu CVCRM, y el **nombre** aquí tiene que ser **idéntico** al registrado allí. Mira cómo crearlo en el **Paso 4.2**. Sin esta configuración, todo lo demás funciona — solo no ocurre el adjunto del comprobante.
</Note>

### 2.5 — Mapeo de roles (opcional)

Traduce el **tipo de comisión de tu CVCRM** al rol del beneficiario en Play2sell. A la izquierda, el texto tal como viene del CVCRM (ej.: `Corretor`); a la derecha, el rol: `VENDEDOR`, `IMOBILIARIA`, `HOUSE`, `GERENTE`, `COORDENADOR` o `PARCEIRO`. Usa **"+ Adicionar papel"** para incluir cuantos necesites.

Haz clic en **Conectar** para guardar.

<Check>El CVCRM aparece como **conectado** en el panel y abre la pantalla **"CRM conectado"** con tu URL de webhook.</Check>

## Paso 3 — Copiar la URL de webhook

Al hacer clic en **Conectar**, Play2sell **provisiona automáticamente** el endpoint de recepción y muestra la pantalla **"CRM conectado"** con tu **URL de webhook** y un botón de **copiar**. Copia esa URL — la vas a pegar en el CVCRM en el próximo paso.

<Note>
  La URL es **única de tu cuenta**. Para recuperarla después, ve a **Integrações → Endpoints** — es donde los endpoints de webhook quedan listados.

  <Frame caption="Integrações → Endpoints — donde la URL queda disponible después">
    <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/05-endpoints.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=9464f18e7d1cbb6e2b6be3a86582ffa8" alt="Página de Endpoints del panel Play2sell" width="1680" height="1298" data-path="images/integrations/cvcrm/05-endpoints.png" />
  </Frame>
</Note>

<Check>Tienes la **URL de webhook** copiada — lista para pegar en el CVCRM.</Check>

## Paso 4 — Configurar el CVCRM

Aquí avisas al CVCRM para que notifique a Play2sell en cada evento (4.1) y aseguras dos configuraciones de apoyo (4.2 y 4.3).

### 4.1 — Crear los 3 webhooks

En el gestor del CVCRM, ve a **Configurações ⚙ → Integrações** y abre la tarjeta **Webhooks** (en "Configurar").

<Frame caption="Gestor CVCRM → Configurações → Integrações → tarjeta Webhooks">
  <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/06-cvcrm-integracoes.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=5adadd744cd615258faf06cc969227ae" alt="Hub de Integrações del CVCRM con la tarjeta Webhooks" width="2084" height="1350" data-path="images/integrations/cvcrm/06-cvcrm-integracoes.png" />
</Frame>

<Frame caption="Lista de webhooks en el CVCRM">
  <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/07-cvcrm-webhooks-lista.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=870eab633111f90db91847c2fa9a684c" alt="Lista de webhooks en el CVCRM" width="1678" height="1354" data-path="images/integrations/cvcrm/07-cvcrm-webhooks-lista.png" />
</Frame>

Vas a crear **3 webhooks** — todos apuntando a la **misma URL** (la del Paso 3). Lo que cambia en cada uno es la **Funcionalidade** y la **situación del gatillo**:

| #     | Funcionalidade | Situación del gatillo (ejemplo) | Campo en el panel (Paso 2.2)   | Qué dispara                                       |
| ----- | -------------- | ------------------------------- | ------------------------------ | ------------------------------------------------- |
| **1** | **Reserva**    | venta / enviar a la pagaduría   | **Vendida**                    | originación + emisión del boleto                  |
| **2** | **Comissão**   | escriturar                      | **Escriturada (vía comisión)** | libera la transferencia (PIX)                     |
| **3** | **Comissão**   | cancelación                     | **Cancelada (vía comisión)**   | cancela el boleto no pagado / reembolsa el pagado |

Para cada uno, haz clic en **"+ Criar novo Webhook"** y completa el formulario:

| Campo del CVCRM     | Qué informar                                                                                                                                                                                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Nome**            | Una etiqueta clara, a tu elección (ej.: `Pagaduría — venda`).                                                                                                                                                                                                                                                            |
| **Funcionalidade**  | **Reserva** (webhook 1) o **Comissão** (webhooks 2 y 3).                                                                                                                                                                                                                                                                 |
| **Workflow**        | Aparece cuando la Funcionalidade tiene más de un flujo de situaciones. En **Comissão** hay más de un workflow — elige el que **contiene la situación del gatillo** ("Escriturar" / "Cancelada"); en caso de duda, abre el selector y mira en qué workflow aparece la situación. En **Reserva** normalmente hay solo uno. |
| **Gatilho**         | La **situación** que dispara el envío. Usa el **label exacto** de tu instancia (la misma del Paso 2.2).                                                                                                                                                                                                                  |
| **Forma de envío**  | Deja el valor por defecto.                                                                                                                                                                                                                                                                                               |
| **Endereço**        | **Pega la URL de webhook** copiada en el Paso 3.                                                                                                                                                                                                                                                                         |
| **Ativo no painel** | Déjalo **activo** — sin esto, el webhook no dispara.                                                                                                                                                                                                                                                                     |

<Frame caption="Registro de un nuevo webhook en el CVCRM">
  <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/08-cvcrm-webhook-form.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=3c705dd46567c23c85173cd7938a0d93" alt="Formulario de registro de webhook en el CVCRM" width="1680" height="1358" data-path="images/integrations/cvcrm/08-cvcrm-webhook-form.png" />
</Frame>

<Steps>
  <Step title="Webhook 1 — Originación (obligatorio)">
    **Funcionalidade Reserva**, en la situación que marca la venta / el envío a la pagaduría (la misma del campo **Vendida**, Paso 2.2). Hace que Play2sell **origine la venta y emita el boleto**.
  </Step>

  <Step title="Webhook 2 — Escrituración → libera la transferencia (obligatorio)">
    **Funcionalidade Comissão**, en la situación que indica escriturar/liberar — ej.: "Escriturar" (la misma del campo **Escriturada (vía comisión)**, Paso 2.2). **Libera la transferencia** y paga a los beneficiarios vía **PIX**.
  </Step>

  <Step title="Webhook 3 — Cancelación / Rescisión (recomendado)">
    **Funcionalidade Comissão**, en la situación de cancelación — ej.: "Cancelada" (la misma del campo **Cancelada (vía comisión)**, Paso 2.2). **Cancela** el boleto no pagado o **reembolsa** el pagado, según el estado.
  </Step>
</Steps>

<Tip>
  Vincula los webhooks al usuario de integración ("Integração") — así los cambios hechos por la automatización quedan atribuibles en el historial del CVCRM.
</Tip>

<Note>
  **Variación por instancia.** Si tu CVCRM registra la escrituración o la cancelación en la **propia reserva** (y no en la comisión), crea los webhooks 2 y 3 con **Funcionalidade Reserva** y, en el Paso 2.2, usa los campos **Escriturada** y **Distrato** en lugar de los "(vía comisión)". El comportamiento es el mismo.
</Note>

<Check>
  **Confirma que los 3 webhooks están disparando.** En la lista de webhooks, la columna **Transações** cuenta cada envío. Si sigue en **0** después de mover un registro a la situación del gatillo, revisa: la **Funcionalidade**, la **situación** (debe coincidir con el Paso 2.2), si el webhook está **Ativo no painel** y si el **Endereço** es la URL exacta del Paso 3 (sin espacios).
</Check>

### 4.2 — Registrar el tipo de comprobante (opcional)

Haz esto **solo si** habilitaste el **Comprobante de transferencia** en el Paso 2.4. Es una configuración única que crea el **tipo de archivo** usado para adjuntar el PDF del comprobante a la comisión.

En el gestor del CVCRM, ve a **Configurações → Tipos de Arquivos de Pagamento Comissão**, haz clic en **"+ Criar novo Tipo"** y completa:

| Campo               | Qué informar                                                                                                                       |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Nome**            | El nombre del tipo (ej.: `Comprovante_Play2sell`). **Usa exactamente este nombre** en el campo "Tipo do comprovante" del Paso 2.4. |
| **Ativo no painel** | `Ativo`.                                                                                                                           |
| **Tipo Pessoa**     | `Física / Jurídica`.                                                                                                               |
| **Obrigatório**     | `Não` — Play2sell adjunta el comprobante automáticamente.                                                                          |

<Frame caption="CVCRM → Tipos de Arquivos de Pagamento Comissão → Criar novo Tipo">
  <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/11-cvcrm-tipo-comprovante.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=ab2c54a028696a8a1fecd263241d4915" alt="Formulario de registro del tipo de archivo de pago de comisión en el CVCRM" width="1654" height="894" data-path="images/integrations/cvcrm/11-cvcrm-tipo-comprovante.png" />
</Frame>

### 4.3 — Asegurar "Forma de pagamento = Boleto"

Para que el boleto emitido por Play2sell aparezca como el cobrable de la comisión (y se concilie correctamente), los **pagos de la comisión en el CVCRM** deben usar la **forma de pago "Boleto"**.

Para verificar: en **Financeiro → Comissões**, abre una comisión y haz clic en el ícono **`$`** (Pagamentos). En la sección **Pagamentos**, cada cuota del beneficiario tiene la columna **"Forma de pagamento"** — debe estar como **Boleto**.

<Warning>
  Si la cuota está con otra forma (ej.: "Transferência bancária"), el boleto que emitimos **no coincide** con la comisión. Ajusta la forma a **Boleto** en la regla/condición de comisión de tu CVCRM.
</Warning>

<Frame caption="Comissão → Pagamentos: cada cuota con Forma de pagamento = Boleto (situación “Programado” tras la emisión)">
  <img src="https://mintcdn.com/play2sell/UX439KPh_mD83OMk/images/integrations/cvcrm/12-cvcrm-forma-boleto.png?fit=max&auto=format&n=UX439KPh_mD83OMk&q=85&s=b10581fd9b164cfb1287d2709d0dde29" alt="Pagamentos de la comisión en el CVCRM con Forma de pagamento igual a Boleto" width="1650" height="1350" data-path="images/integrations/cvcrm/12-cvcrm-forma-boleto.png" />
</Frame>

## Paso 5 — Probar y validar

Antes de operar de verdad, ejecuta una prueba de extremo a extremo con valores bajos.

<Steps>
  <Step title="Crea una reserva de prueba limpia">
    Con comprador (CPF completado), monto válido y **comisiones sumando 100%** para un corredor.
  </Step>

  <Step title="Mueve a la situación de venta">
    Esto dispara el webhook de originación.
    <Check>La venta aparece en el panel Play2sell y el **boleto se adjunta a la comisión** en el CVCRM (situación "Programado").</Check>
  </Step>

  <Step title="Paga el boleto vía Pix">
    Usa el Pix copia-y-pega (entra al instante).
    <Check>La comisión cambia a **"Pago"** en el CVCRM.</Check>
  </Step>

  <Step title="Escritura la comisión">
    Mueve la comisión a la situación **Escriturar**.
    <Check>La transferencia PIX se paga al beneficiario y el **comprobante** se adjunta a la comisión (si está configurado en el Paso 2.4).</Check>
  </Step>
</Steps>

## Próximos pasos

Después de validar, la integración ya opera sola. En el día a día:

* **Cada venta** que entra en la situación de pagaduría genera el boleto y lo refleja en la comisión del CVCRM, sin acción manual.
* **Acompaña** el estado de las comisiones en **Financeiro → Comissões** (CVCRM) y de las ventas en el **panel Play2sell**.
* **Para ajustar** el mapeo de situaciones o las credenciales después, vuelve a **Integrações → Conectores → CVCRM → Editar configuração**.

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Necesito un programador para configurar?">
    No. Toda la configuración se hace por pantallas, en el gestor del CVCRM y en el panel de Play2sell. Solo necesitas acceso administrativo a los dos sistemas. No se requiere ningún código.
  </Accordion>

  <Accordion title="¿Qué webhooks necesita tener el CVCRM?">
    Tres, todos apuntando a la **misma URL**: (1) **Reserva** en la situación de venta → originación; (2) **Comissão** en la situación "Escriturar" → libera la transferencia; (3) **Comissão** en la situación de cancelación → reembolso.
  </Accordion>

  <Accordion title="¿Cómo se calcula el monto de la comisión?">
    El CVCRM muestra la comisión **bruta**. Play2sell aplica la **tasa de servicio** (en general 1–3%) y el beneficiario recibe el **neto** vía PIX. El cálculo usa el **monto de la comisión**, no el de la venta.
  </Accordion>

  <Accordion title="¿La integración funciona con comisión menor que el 100% de la venta?">
    Sí. El boleto y el split se calculan sobre el **monto de la comisión**, así que cualquier porcentaje funciona.
  </Accordion>

  <Accordion title="¿En cuánto tiempo recibe el corredor?">
    Después de que la comisión sea **escriturada** en el CVCRM, la transferencia vía **PIX** se procesa en segundos y cae en la cuenta del beneficiario.
  </Accordion>

  <Accordion title="¿El comprobante de transferencia es obligatorio?">
    No, es **opcional**. Sin él, la transferencia se paga normalmente; solo no ocurre el adjunto del PDF en la comisión del CVCRM.
  </Accordion>
</AccordionGroup>

## Solución de problemas

<AccordionGroup>
  <Accordion title="Ningún evento llega a Play2sell">
    Verifica en el CVCRM: ¿el webhook está **Ativo**? ¿La **Funcionalidade** (Reserva/Comissão) y la **situación** del gatillo coinciden con lo que mapeaste en el panel? ¿El **Endereço** es la URL exacta copiada en el Paso 3 (sin espacios/saltos)?
  </Accordion>

  <Accordion title="El boleto no apareció en la comisión">
    Confirma que la **forma de pago** de la comisión es **Boleto** (Paso 4.3) y que la situación de salida **"Comissão com boleto"** está completada (ej.: `Programado`). Reprocesar la reserva suele resolver casos de configuración ajustada después.
  </Accordion>

  <Accordion title="Un beneficiario no fue encontrado / la transferencia no salió">
    La identidad es por **CPF/CNPJ**, nunca por correo electrónico. Asegúrate de que el documento del beneficiario esté completado y correcto en el CVCRM.
  </Accordion>

  <Accordion title="El estado pago no se reflejó al instante">
    Las confirmaciones de pago y los write-backs pueden tomar algunos instantes. Si persiste, reprocesa la reserva o habla con el soporte.
  </Accordion>
</AccordionGroup>

## Referencia

### Ciclo de vida de extremo a extremo

| Etapa                        | Evento en el CVCRM                  | Acción de Play2sell                                   | Qué ves                                                                    |
| ---------------------------- | ----------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------- |
| **1. Originación**           | Reserva → situación de venta        | Crea la venta + split y emite el **boleto (con Pix)** | Venta en el panel; boleto generado                                         |
| **2. Boleto en la comisión** | — (write-back)                      | Adjunta el boleto a la comisión                       | La comisión queda **Programado**; columnas Boleto/ID Pagaduría completadas |
| **3. Pago / conciliación**   | El comprador paga el boleto         | Confirma el pago e informa al CVCRM                   | La comisión queda **Pago**                                                 |
| **4. Escrituración**         | Comissão → situación **Escriturar** | Libera la transferencia                               | Protocolo liberado                                                         |
| **5. Transferencia**         | —                                   | Paga al beneficiario vía **PIX**                      | Transferencia concluida (neto)                                             |
| **6. Comprobante**           | — (write-back)                      | Adjunta el comprobante a la comisión                  | PDF en "Documentos do pagamento da Comissão"                               |
| **Rescisión**                | Reserva/Comissão → cancelación      | Reembolsa según el estado                             | Operación reembolsada                                                      |

### Contrato de error

Las respuestas de error siguen el formato `{ code, message, hint? }`:

* **4xx — rechazo:** algo está incorrecto (ej.: situación no mapeada). **Corrige e intenta de nuevo.**
* **5xx — error transitorio:** falla temporal. Se **reprocesa automáticamente**.

### Apéndice técnico

<Note>
  Esta sección es para equipos técnicos. La configuración anterior no exige nada de aquí.
</Note>

**Familias de API del CVCRM**

| Familia                       | Uso                               | Observación                                                           |
| ----------------------------- | --------------------------------- | --------------------------------------------------------------------- |
| **v1** (`/api/v1/<module>/*`) | Actual — usada por la integración | Auth por headers `email` + `token`; 200 req/min                       |
| **CVIO** (`/api/cvio/*`)      | Legado                            | **En depreciación** — el CVCRM está estandarizando hacia v1           |
| **CVDW** (`/api/v1/cvdw/*`)   | BI / data warehouse               | **Contrato pagado aparte**; 20 req/min; retorna 403 si no se contrata |

**Sincronización e idempotencia**

* **Webhook liviano → pull-back:** el webhook lleva solo un id; Play2sell busca el registro completo vía `GET` autenticado antes de actuar.
* **Idempotencia:** cada contrato mapea a una clave estable derivada del id de la reserva (`cvcrm:{idreserva}`); la reentrega nunca duplica la venta.
* **Orden:** si la escrituración llega antes de que la originación concluya, se pospone y se reprocesa.

**Atenciones (gotchas)**

* El CVCRM puede retornar **HTTP 200 con `codigo:404` en el cuerpo** para rutas inexistentes — siempre verifica el campo `codigo`, no solo el estado HTTP.
* Los filtros de fecha en algunos endpoints son **ignorados** — acota del lado del cliente.
* Las fechas en el GET de cuotas usan **DD/MM/YYYY**.
* Existen **dos workflows de situación distintos** — el de la **comisión** y el del **pago de la comisión** — con ids que pueden colisionar. Por eso el write-back de situación usa el **nombre** ("Programado"/"Pago"), no el id.

## Soporte

<Tip>
  ¿Necesitas ayuda para mapear las situaciones de tu instancia? Habla con el soporte en **[suporte@play2sell.com](mailto:suporte@play2sell.com)** con tu **dominio** y la lista de situaciones que usas para vendida / escriturar / rescisión.
</Tip>