{"openapi":"3.0.0","paths":{"/v1/leads":{"get":{"description":"Los leads que tu cuenta ha trabajado: los que has movido a tu tablero, los que has llamado y los que te ha traído una alerta. **Consume cuota por FILA DEVUELTA, no por petición**; una consulta sin resultados no consume nada. No devuelve el censo completo.","operationId":"ConnectV1Controller_listLeads","parameters":[{"name":"limit","required":false,"in":"query","description":"Filas por página (máximo 200)","schema":{"default":50,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Cursor de la página siguiente. Se devuelve en `nextCursor`; no se construye a mano.","schema":{"type":"string"}},{"name":"since","required":false,"in":"query","description":"Solo leads que entraron o cambiaron desde esta fecha. Máximo 90 días atrás.","schema":{"type":"string"}},{"name":"municipality","required":false,"in":"query","description":"Filtra por municipio","schema":{"type":"string"}},{"name":"province","required":false,"in":"query","description":"Filtra por provincia","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"type":"string","enum":["live","delisted","sold_likely"]}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LeadV1Dto"}}}}}},"security":[{"bearer":[]}],"summary":"Listar leads","tags":["Leads, eventos y zonas"]}},"/v1/events":{"get":{"description":"El log de cambios de tu cuenta, para quien prefiera consultar en vez de recibir webhooks. Ventana de 30 días. Consume cuota por fila devuelta.","operationId":"ConnectV1Controller_listEvents","parameters":[{"name":"limit","required":false,"in":"query","description":"Filas por página (máximo 200)","schema":{"default":50,"type":"number"}},{"name":"since","required":false,"in":"query","description":"Desde cuándo. Por defecto, 24 horas atrás. Máximo 90 días.","schema":{"type":"string"}},{"name":"type","required":false,"in":"query","description":"Tipos de evento a devolver","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Listar eventos","tags":["Leads, eventos y zonas"]}},"/v1/webhooks":{"get":{"description":"Los destinos a los que te avisamos. Nunca devuelve los secretos de firma.","operationId":"ConnectV1Controller_listWebhooks","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Listar webhooks","tags":["Leads, eventos y zonas"]},"post":{"description":"Da de alta un destino al que avisaremos. **El secreto de firma se devuelve SOLO en esta respuesta**: guárdalo para poder verificar que las entregas vienen de Kaptalo. El destino debe ser https y no puede apuntar a una red privada.","operationId":"ConnectV1Controller_createWebhook","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookDto"}}}},"responses":{"201":{"description":""}},"security":[{"bearer":[]}],"summary":"Crear un webhook","tags":["Leads, eventos y zonas"]}},"/v1/webhooks/{id}":{"delete":{"description":"Deja de avisar a ese destino. Las entregas pendientes se descartan.","operationId":"ConnectV1Controller_deleteWebhook","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"204":{"description":""}},"security":[{"bearer":[]}],"summary":"Borrar un webhook","tags":["Leads, eventos y zonas"]}},"/v1/zones/{municipality}/market":{"get":{"description":"Stock de anuncios vivos, porcentaje de particulares, medianas de precio y de €/m², y movimiento de los últimos 30 días. **No consume cuota** y no devuelve ningún identificador de anuncio: son datos agregados.","operationId":"ConnectV1Controller_zoneMarket","parameters":[{"name":"municipality","required":true,"in":"path","schema":{"type":"string"}},{"name":"operation","required":true,"in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Mercado de un municipio","tags":["Leads, eventos y zonas"]}},"/v1/usage":{"get":{"description":"Cuántas filas has consumido, cuál es tu cuota y cuántas te quedan. La cuota se renueva el día 1.","operationId":"ConnectV1Controller_usage","parameters":[],"responses":{"200":{"description":""}},"security":[{"bearer":[]}],"summary":"Consumo del mes","tags":["Leads, eventos y zonas"]}}},"info":{"title":"Kaptalo Connect API","description":"Los leads que tu cuenta ya trabaja, sincronizados con tu CRM.\n\n**Autenticación**: `Authorization: Bearer kap_live_...` (o la cabecera `X-Api-Key`).\nLas claves se crean desde el panel de Kaptalo, en Integraciones.\n\n**Consumo**: `/v1/leads` y `/v1/events` gastan cuota por FILA DEVUELTA, no por petición;\nuna consulta sin resultados no consume. `/v1/zones/.../market` es libre.\nConsulta lo que te queda en `/v1/usage`.\n\n**Pruebas**: una clave `kap_test_` devuelve datos sintéticos con la forma exacta del\ncontrato, sin tocar datos reales ni gastar cuota.\n\n**Webhooks**: cada entrega va firmada en `X-Kaptalo-Signature` como\n`v1=HMAC_SHA256(secreto, \"{timestamp}.{cuerpo}\")`, con el momento en `X-Kaptalo-Timestamp`.\nVerifica la firma y descarta lo que llegue con más de unos minutos de retraso.\nDeduplica por `X-Kaptalo-Event-Id`: un reintento repite el mismo id.","version":"1.0","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http"}},"schemas":{"LeadAddressDto":{"type":"object","properties":{"street":{"type":"string","nullable":true},"neighborhood":{"type":"string","nullable":true},"municipality":{"type":"string","nullable":true},"province":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true}}},"LeadPortalDto":{"type":"object","properties":{"portal":{"type":"string","example":"fotocasa"},"externalId":{"type":"string","description":"Id del anuncio en ese portal"},"url":{"type":"string","nullable":true},"price":{"type":"number","nullable":true,"description":"Precio en ESE portal: no siempre coinciden"},"alive":{"type":"boolean","description":"El anuncio sigue publicado en ese portal"}},"required":["portal","externalId","alive"]},"LeadPriceChangeDto":{"type":"object","properties":{"date":{"type":"string"},"price":{"type":"number","description":"Precio al que pasó"},"previousPrice":{"type":"number","nullable":true,"description":"Precio que tenía antes"},"changePct":{"type":"number","nullable":true,"description":"Variación en %, negativa si baja"}},"required":["date","price"]},"LeadPropertyDto":{"type":"object","properties":{"type":{"type":"string","nullable":true,"example":"piso"},"operation":{"type":"string","enum":["sale","rent"]},"title":{"type":"string","nullable":true},"price":{"type":"number","nullable":true},"initialPrice":{"type":"number","nullable":true,"description":"Precio de salida, si se vio publicar"},"surfaceM2":{"type":"number","nullable":true},"rooms":{"type":"number","nullable":true},"bathrooms":{"type":"number","nullable":true},"address":{"$ref":"#/components/schemas/LeadAddressDto"},"daysOnMarket":{"type":"number","nullable":true},"postedDate":{"type":"string","nullable":true,"description":"Fecha de publicación que da el portal"},"portals":{"description":"El mismo inmueble en cada portal donde está","type":"array","items":{"$ref":"#/components/schemas/LeadPortalDto"}},"priceHistory":{"type":"array","items":{"$ref":"#/components/schemas/LeadPriceChangeDto"}},"status":{"type":"string","enum":["live","delisted","sold_likely"]},"delistedAt":{"type":"string","nullable":true,"description":"Cuándo dejó de estar publicado"},"images":{"type":"array","items":{"type":"string"}}},"required":["operation","address","portals","priceHistory","status"]},"LeadSellerDto":{"type":"object","properties":{"isParticular":{"type":"boolean","description":"Lo anuncia un particular y no una agencia"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"phoneAvailable":{"type":"boolean","description":"Tenemos el número guardado y se puede destapar"}},"required":["isParticular","phoneAvailable"]},"LeadPipelineDto":{"type":"object","properties":{"stage":{"type":"string","nullable":true,"description":"Columna del tablero, tal como la nombró el cliente"},"contactMethod":{"type":"string","nullable":true},"lastContactAt":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}}},"LeadContextDto":{"type":"object","properties":{"priceDropTotalPct":{"type":"number","nullable":true,"description":"Bajada acumulada desde el precio de salida, en %"},"priceChangeCount":{"type":"number","description":"Veces que ha cambiado el precio"},"portalCount":{"type":"number","description":"En cuántos portales está anunciado"},"moment":{"type":"string","nullable":true,"enum":["price-drop","burnout","agency-breakup","gone-solo"],"description":"Momento de captación detectado por el Radar"},"momentScore":{"type":"number","nullable":true,"description":"0-100"},"zoneMedianEurM2":{"type":"number","nullable":true,"description":"Mediana de €/m² de su municipio"}},"required":["priceChangeCount","portalCount"]},"LeadV1Dto":{"type":"object","properties":{"schema":{"type":"string","example":"lead.v1"},"id":{"type":"string","description":"Identificador estable del lead dentro de la cuenta"},"kaptaloUrl":{"type":"string"},"createdAt":{"type":"string","description":"Cuándo entró en el perímetro de la cuenta"},"updatedAt":{"type":"string","description":"Última vez que cambió algo del lead"},"source":{"type":"string","enum":["board","alert","reveal","call","web","api"]},"duplicateGroupId":{"type":"string","nullable":true,"description":"Agrupador del inmueble entre portales. Dos leads con el mismo valor son el mismo piso."},"property":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/LeadPropertyDto"}]},"seller":{"$ref":"#/components/schemas/LeadSellerDto"},"pipeline":{"$ref":"#/components/schemas/LeadPipelineDto"},"context":{"$ref":"#/components/schemas/LeadContextDto"}},"required":["schema","id","kaptaloUrl","createdAt","updatedAt","source","seller","pipeline","context"]},"CreateWebhookDto":{"type":"object","properties":{"name":{"type":"string","description":"Nombre para reconocerlo en el panel"},"targetUrl":{"type":"string","description":"URL https a la que se hará POST"},"eventTypes":{"type":"array","description":"Tipos que quieres recibir. Vacío = todos.","items":{"type":"string","enum":["lead.created","lead.stage_changed","lead.price_dropped","lead.delisted","lead.sold_likely","lead.back_on_market","lead.phone_revealed","call.completed","valuation.ready","alert.fired","moment.detected"]}}}}}}}