Consultas a Google Sheets

Para qué sirve

Una planilla con una fila por consulta: cuándo entró, quién escribió, por qué propiedad, por qué canal, en qué estado está y quién la atiende. Es útil para un dueño que quiere mirar todo de un vistazo y para un contador o un administrativo que arma informes en Sheets.

Hay dos caminos. Elegí uno:

Qué necesitás

• Una cuenta de Kaptativa con Consultas activo y API y MCP, dentro de Administración.
• Un token que solo vea. Se crea en Administración > API y MCP, en Crear un token: nombre «Planilla de consultas», Qué puede hacer en Solo ver (o Elegir por módulo con Ver en Inmobiliaria, que da el alcance inmobiliaria:lectura) y, al final, Crear el token. Copialo en ese momento: no se vuelve a mostrar. Empieza con kpt_.
• Una planilla de Google Sheets con una hoja que se llame Consultas.

Camino 1: Apps Script lee la API cada hora

Pasos

1. Abrí la planilla. En la hoja Consultas, escribí en la fila 1 estos títulos, uno por columna, de la A a la H: Número, Cargada, Persona, Propiedad, Canal, Estado, Asesor, Mensaje.
2. En el menú, tocá Extensiones > Apps Script. Se abre el editor en otra pestaña.
3. Borrá lo que haya en el archivo Código.gs y pegá el código de más abajo. Tocá el ícono de guardar.
4. A la izquierda, tocá Configuración del proyecto (la rueda dentada). Abajo, en Propiedades de la secuencia de comandos, tocá Agregar propiedad. En Propiedad escribí KAPTATIVA_TOKEN y en Valor pegá tu token (kpt_...). Tocá Guardar propiedades de la secuencia de comandos.
5. Volvé a Editor. Arriba, elegí la función traerConsultas y tocá Ejecutar. La primera vez Google pide permiso para conectarse a un servicio externo y para editar tus planillas: revisá y aceptá. Si dice que la app no está verificada, es tu propio script: Configuración avanzada y seguir.
6. A la izquierda, tocá Activadores (el reloj). Tocá Agregar activador, elegí la función traerConsultas, el tipo Activado por tiempo, Temporizador por horas y Cada hora. Guardá.

// Kaptativa: trae las consultas abiertas y suma como fila las que todavía no están en la hoja.
const URL_CONSULTAS = "https://panel.kaptativa.app/api/v1/inmobiliaria/consultas";
const HOJA = "Consultas";

function traerConsultas() {
  // El token no va en el código: se guarda en Configuración del proyecto > Propiedades de la secuencia de comandos
  const token = PropertiesService.getScriptProperties().getProperty("KAPTATIVA_TOKEN");
  const hoja = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(HOJA);
  const ultima = hoja.getLastRow();
  // La columna A es el número de la consulta: sirve para no repetir filas
  const vistas = new Set(ultima > 1 ? hoja.getRange(2, 1, ultima - 1, 1).getValues().flat().map(String) : []);
  const nuevas = [];
  let cursor = null;
  do {
    const consulta = "?estado=abiertas&limite=100" + (cursor ? "&cursor=" + encodeURIComponent(cursor) : "");
    const respuesta = UrlFetchApp.fetch(URL_CONSULTAS + consulta, { headers: { Authorization: "Bearer " + token }, muteHttpExceptions: true });
    if (respuesta.getResponseCode() !== 200) throw new Error("Kaptativa respondió " + respuesta.getResponseCode() + ": " + respuesta.getContentText());
    const cuerpo = JSON.parse(respuesta.getContentText());
    cuerpo.datos.forEach(function (c) {
      if (vistas.has(String(c.numero))) return;
      nuevas.push([c.numero, new Date(), seguro(c.persona), seguro(c.propiedad), c.canal, c.estado, seguro(c.asesor), seguro(c.mensaje)]);
    });
    cursor = cuerpo.paginacion.siguiente;
  } while (cursor);
  if (nuevas.length) hoja.getRange(hoja.getLastRow() + 1, 1, nuevas.length, nuevas[0].length).setValues(nuevas.reverse());
}

// Un texto que empieza con = + - o @ se leería como fórmula: se le antepone una comilla para que quede como texto
function seguro(valor) {
  return typeof valor === "string" && /^[=+\-@]/.test(valor) ? "'" + valor : valor;
}

El código pide las consultas abiertas, de a 100 por pedido (limite), sigue con el cursor mientras haya más páginas (paginación) y suma una fila por cada número que todavía no esté en la columna A. Una consulta que se cierra queda en la planilla con el estado con el que se cargó.

Camino 2: Make o n8n con el aviso de consulta recibida

El evento se llama inmobiliaria.consulta.recibida («Consulta recibida»). Sus datos son consulta_id, sobre y canal. En cada guía está el armado completo:

• Make: el escenario con un módulo de webhook personalizado, otro de Google Sheets y, si querés, uno de HTTP.
• n8n: un nodo Webhook, uno de código que verifica la firma y uno de Google Sheets.

En los dos casos, el último módulo es el de Google Sheets: Add a Row en Make, Append Row en n8n, con las columnas que elijas (por ejemplo, consulta_id, sobre y canal, más la fecha en que llegó). sobre es el código de la propiedad por la que consultaron.

Cómo comprobar que anda

• Apps Script: ejecutá traerConsultas a mano. Si hay consultas abiertas en la cuenta, aparecen filas nuevas al instante. Ejecutala otra vez: no tiene que sumar filas repetidas.
• Con aviso: en el panel, en Administración > API y MCP > Webhooks, tocá Probar en el destino. Llega un evento webhook.prueba con un mensaje de prueba, que sirve para ver que el escenario se dispara. Después cargá una consulta real, por ejemplo con el formulario del sitio, y mirá que llegue inmobiliaria.consulta.recibida.
• En el Registro de entregas del destino se ve cada intento con el código que respondió tu escenario.

Problemas comunes

Para usarlo con cuidado

• La planilla tiene datos personales (nombre y mensaje de quien consultó). Compartila solo con quien tiene que verla, igual que el panel.
• Usá un token de Solo ver, solo para esta planilla. Si cambia quien la mantiene, revocá el token y creá uno nuevo.
• El token vive en las propiedades del script, no en una celda ni en el código.