CRM Sperant — Conector para Bricks Builder

Plugin de WordPress que conecta los formularios de Bricks Builder con el CRM inmobiliario Sperant (API v3). En cada envío del formulario, crea automáticamente el lead/cliente en Sperant (POST /v3/clients).

• Versión: 1.1.0
• Autor: Lucuma Agency
• Proyecto: Bastión → Domus (project_id 2, producción api.sperant.com)

📚 Documentación

1. Cómo funciona (arquitectura)

El formulario vive en tu web (Bricks), no dentro de Sperant. Sperant solo recibe los datos por su API.

Visitante → Form en la web (Bricks) → [este plugin] → API Sperant /v3/clients → Lead en el CRM

No existe un paso de "crear el formulario dentro de Sperant" para una web propia. Eso del manual de Sperant aplica solo a los formularios de Facebook Lead Ads.

2. Instalación

1. Copia la carpeta crm-sperant/ a wp-content/plugins/.
2. En WordPress → Plugins, activa CRM Sperant — Bricks Connector.
3. Ve a Ajustes → CRM Sperant y completa la configuración (ver más abajo).
4. En tu formulario de Bricks, en Actions after submit, agrega la acción Custom. (Puedes dejar también "Email" y "Save submission" como respaldo.)

El plugin se engancha al hook bricks/form/custom_action, así que basta con que el formulario tenga la acción Custom activada.

3. Datos que debes pedir a Sperant

Antes de configurar necesitas, del panel o soporte de Sperant:

4. Configuración del plugin (Ajustes → CRM Sperant)

Sección 1 — Conexión

• API Base URL: Sperant tiene dos entornos:
  • Prueba: https://api.eterniasoft.com (default del plugin mientras integras).
  • Producción: https://api.sperant.com (cuando Sperant entregue el token de producción).
• Token: el token entregado por Sperant (primero el de prueba, luego el de producción).
• Esquema de Authorization: Token a secas (header Authorization: <token>). Confirmado contra la API.

Sección 2 — IDs del proyecto

Valores reales de Domus (ya prellenados al activar): project_id 2, input_channel_id 3 (contacto web), source_id 1 (página web), interest_type_id 5 (por contactar), document_type_id 1 (DNI). El panel para ver los leads es https://bastion.sperantone.com/ (no es la API; la API es https://api.sperant.com).

Botón "Cargar catálogos desde Sperant": después de escribir el token (sección 1), haz clic en este botón y el plugin consultará Sperant y mostrará en pantalla la tabla ID → nombre de canales, medios, niveles de interés y tipos de documento. Copia el ID que corresponda a cada campo. (Internamente llama a /v3/input_channels, /v3/captation_ways, /v3/interest_types y /v3/document_types.)

Si además tienes el project_id escrito (Domus = 2), el mismo botón trae las Unidades (con su unit_id, código, estado y precio) y las Tipologías (type_id) del proyecto, llamando a /v3/projects/{id}/units y /v3/projects/{id}/types. Así mapeas cada depto "601, 701…" a su unit_id real sin usar terminal.

Sección 3 — Mapeo de campos

Por cada campo de tu formulario escribe el ID del campo en Bricks (formato form-field-xxxxx, visible en el panel del campo).

Mapeo del formulario de Bastión:

Sección 4 — Tipología

El campo de tipología muestra unidades como 601 - 1 Ambiente. Dos modos:

• Campo personalizado (recomendado para empezar): guarda el texto tal cual en extra_fields con la clave que definas (ej. tipologia). Esa clave debe existir como campo personalizado en Sperant.
• unit_id real: el value de cada <option> del select debe ser el ID interno de la unidad en Sperant (no el número "601"). Útil si luego generas la proforma.

Sección 5 — Opciones

• Form ID objetivo: limita el envío a un único formulario (vacío = todos los que tengan acción Custom).
• Modo debug: escribe errores en wp-content/debug.log (requiere WP_DEBUG_LOG activo).

5. El dropdown de Tipología en Bricks

Configura el campo Select con valor : etiqueta.

Modo campo personalizado (texto): el valor y la etiqueta pueden ser iguales.

601 - 1 Ambiente : 601 - 1 Ambiente
701 - 1 Ambiente : 701 - 1 Ambiente
201 - 2 Ambientes : 201 - 2 Ambientes

Modo unit_id real: el valor es el ID interno de Sperant; la etiqueta es lo que ve el cliente.

4521 : 601 - 1 Ambiente
4522 : 701 - 1 Ambiente
4530 : 201 - 2 Ambientes

Las unidades de Domus están listadas en UNIDADES.md con su unit_id real.

6. Mapeo a la API (referencia)

POST https://api.sperant.com/v3/clients

{
  "fname": "Juan",
  "lname": "Pérez",
  "document": "70123456",
  "document_type_id": 1,
  "email": "juan@correo.com",
  "phone": "+51987654321",
  "observation": "Mensaje del formulario",
  "project_id": 2,
  "input_channel_id": 3,
  "source_id": 1,
  "interest_type_id": 5,
  "extra_fields": { "tipologia": "601 - 1 dorm" }
}

Obligatorios: fname, input_channel_id, source_id, interest_type_id. La API deduplica por DNI / email / teléfono: si el lead ya existe, lo actualiza en vez de duplicarlo.

7. Hooks para desarrolladores

Filtra el payload antes de enviarlo:

add_filter( 'crm_sperant_client_payload', function ( $payload, $fields ) {
    // Ej. forzar un source distinto según una página
    // $payload['source_id'] = 7;
    return $payload;
}, 10, 2 );

8. (Opcional) Generar proforma además del lead

Crear el lead basta para captación. Si además quieres cotizar una unidad concreta:

1. Tras create_client(), toma el client_id devuelto.
2. Llama a POST /v3/budgets con client_id + template_id + unit_id (o type_id).

El cliente CRM_Sperant_Client ya incluye el método create_budget() listo para usarse.

Referencia de endpoints de proforma (API v3)

Body de POST /v3/budgets:

{
  "client_id": 15,      // OBLIGATORIO (lo devuelve POST /v3/clients)
  "template_id": 200,   // OBLIGATORIO (configurado en "medios digitales" del proyecto, o lo da Sperant)
  "unit_id": 45,        // unit_id O type_id (al menos uno)
  "type_id": null,
  "input_channel_id": 7,
  "source_id": 28,
  "agent_id": 74
}

De dónde sale cada ID:

9. Pruebas

1. Activa Modo debug.
2. Envía el formulario con datos de prueba.
3. Revisa wp-content/debug.log:
   • Lead creado en Sperant. client_id=XXXX → OK.
   • Error al crear lead. HTTP 401/422 ... → revisa token / IDs / campos obligatorios.
4. Confirma el lead en Sperant (módulo Leads/Clientes del proyecto).

Errores frecuentes

10. Estructura de archivos

crm-sperant/
├── crm-sperant.php                      # Bootstrap, activación, defaults
├── uninstall.php                        # Limpieza de opciones
├── includes/
│   ├── class-sperant-client.php         # Cliente API v3 (clients + budgets)
│   ├── class-sperant-settings.php       # Página de ajustes (admin)
│   └── class-sperant-form-handler.php   # Hook bricks/form/custom_action
├── README.md
└── UNIDADES.md                          # Tabla de unidades de Bastión