API de publicación de ConnectorProperty

Versión del contrato: 2026-09-17 (viene también en la cabecera X-ConnectorProperty-Api-Version y en el campo api_version de cada respuesta).

Esta API es para integradores: softwares de corretaje (CRM) que publican en ConnectorProperty las propiedades de sus corredoras. El integrador envía cada alta, cambio o baja en el momento en que ocurre; ConnectorProperty valida, publica y devuelve las consultas de los interesados.

1. Resumen

Flujo típico:

1. PUT /publishers/{id} — da de alta la corredora (una vez, y cuando cambie).
2. PUT /publishers/{id}/agents/{id} — da de alta a cada agente.
3. PUT /listings/{id} — publica o actualiza una propiedad.
4. DELETE /listings/{id} — la despublica.
5. Recibe las consultas por webhook y avisa con POST /leads/{id}/events cuando el agente respondió.

2. Autenticación y ambientes

PUT /api/v1/listings/NX-00012 HTTP/1.1
Host: connectorproperty.com
Authorization: Bearer cp_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Content-Type: application/json

• Hay dos tipos de llave:
  • cp_live_… — producción. Lo publicado aparece en el portal.
  • cp_test_… — pruebas. Se valida y se guarda igual, pero nunca se muestra públicamente. Cada respuesta trae una preview_url privada.
• Los datos de prueba y producción están separados: un external_id de pruebas no toca el de producción.
• Guarden la llave como secreto del servidor. Si se filtra, avisen y se revoca.
• Sin llave, inválida o revocada: 401 unauthorized.

3. Corredoras (publishers)

Quien publica: una corredora o un corredor independiente.

PUT /publishers/{external_id}

{
  "kind": "agency",
  "name": "Focolare Propiedades",
  "legal_name": "Focolare Propiedades SpA",
  "rut": "77.123.456-7",
  "email": "contacto@focolare.cl",
  "phone": "+56223456789",
  "website": "https://focolare.cl",
  "logo_url": "https://…/logo.png",
  "active": true
}

Respuesta 200 (o 201 si es nueva):

{
  "data": {
    "external_id": "focolare",
    "name": "Focolare Propiedades",
    "rut": "77123456-7",
    "active": true,
    "verification": { "rut_valid": true, "sii_status": "pending", "verified_at": null }
  },
  "api_version": "2026-09-17"
}

Verificación. ConnectorProperty verifica el RUT y la razón social contra el SII y muestra un sello "Corredora verificada" cuando coincide. sii_status: pending · verified · mismatch (el nombre no coincide) · not_found. La verificación no bloquea la publicación.

4. Agentes

PUT /publishers/{publisher_external_id}/agents/{external_id}

{
  "name": "Javiera Soto",
  "title": "Corredora de Propiedades",
  "email": "javiera@focolare.cl",
  "phone": "+56988823456",
  "whatsapp": "+56988823456",
  "photo_url": "https://…/javiera.webp",
  "profile_url": "https://llaveprop.com/javiera-soto",
  "active": true
}

Respuesta 200/201 con el agente guardado.

5. Propiedades (listings)

5.1 PUT /listings/{external_id} — publicar o actualizar

Crea la propiedad si no existe y la reemplaza entera si existe (no es un parche: envíen siempre todos los campos). Es idempotente: repetir la misma petición no cambia nada. Si la propiedad estaba despublicada, la vuelve a publicar.

{
  "publisher_external_id": "focolare",
  "agent_external_id": "cmu3msc0g01d5y0sg8k4q1x2z",
  "code": "NX-00012",
  "source_url": "https://llaveprop.com/p/NX-00012",

  "operation": "rent",
  "property_type": "apartment",
  "availability": "available",
  "title": "Departamento 2D/2B con vista despejada",
  "description": "Luminoso, a pasos del metro…",

  "price": { "amount": 850000, "currency": "CLP" },
  "common_expenses_clp": 120000,

  "bedrooms": 2,
  "bathrooms": 2,
  "parking_spaces": 1,
  "storage_units": 1,
  "built_area_m2": 72.5,
  "land_area_m2": null,
  "floor": 8,
  "total_floors": 20,
  "year_built": 2018,
  "orientation": "Norte",
  "furnished": true,
  "pets_allowed": true,
  "features": ["Piscina", "Gimnasio"],

  "location": {
    "region": "Metropolitana de Santiago",
    "commune": "Providencia",
    "street": "Av. Providencia",
    "number": "1234",
    "unit": "801",
    "lat": -33.42612,
    "lng": -70.61705,
    "show_exact_address": false
  },

  "photos": [
    { "url": "https://llaveprop.com/uploads/fotos/1789-ab12.jpg", "caption": "Living" }
  ],
  "video_url": null,
  "virtual_tour_url": null,

  "sii_role": null,
  "rent_requirements": {
    "income_multiple": 3,
    "guarantee_months": 1,
    "requires_guarantor": false
  },

  "published_at": "2026-09-10T18:22:05.110Z"
}

Campos

Campos desconocidos se ignoran. Nunca envíen datos del propietario ni la comisión: no hay campos para eso y se descartan.

Respuesta

201 si es nueva, 200 si se actualizó (o no cambió nada):

{
  "data": {
    "external_id": "NX-00012",
    "public_code": "CP-10042",
    "status": "published",
    "url": "https://connectorproperty.com/propiedad/CP-10042-departamento-arriendo-providencia",
    "preview_url": null,
    "result": "updated",
    "quality": {
      "score": 82,
      "warnings": [
        { "field": "photos", "code": "few_photos", "message": "Tiene 3 foto(s). Con menos de 12 fotos el aviso aparece más atrás en los resultados." }
      ]
    },
    "updated_at": "2026-09-17T14:03:12.481Z"
  },
  "api_version": "2026-09-17"
}

• result: created · updated · unchanged · republished.
• status: ver 5.3.
• quality.warnings no impiden publicar. Los errores sí (ver sección 8).

5.2 DELETE /listings/{external_id} — despublicar

DELETE /listings/NX-00012?reason=closed

La propiedad no se borra: queda despublicada con su motivo y su historial. Un PUT posterior la vuelve a publicar. Es idempotente: despublicar algo ya despublicado responde 200. Si nunca existió, 404.

Respuesta 200:

{ "data": { "external_id": "NX-00012", "status": "unpublished", "reason": "closed" }, "api_version": "2026-09-17" }

5.3 Estados

5.4 Reglas de calidad

Errores (rechazan la petición con 422):

• common_expenses_clp obligatorio (puede ser 0) para apartment y office.
• built_area_m2 obligatorio para apartment, house, office, commercial y warehouse; land_area_m2 obligatorio para land y farm.
• Precio fuera de rango razonable para su moneda y operación (p. ej. un arriendo de $500 o una venta de UF 5.000.000).
• built_area_m2 > 0 y < 100.000; bedrooms ≤ 50; bathrooms ≤ 50.

Advertencias (publican igual, bajan el puntaje de calidad):

• Menos de 12 fotos (baja el puntaje de forma importante), sin coordenadas, descripción de menos de 200 caracteres.
• Teléfonos o correos dentro de la descripción (se ocultan al mostrarla).
• Arriendo sin rent_requirements.

El puntaje de calidad (0–100) influye en el orden por relevancia.

5.5 GET /listings/{external_id}

Devuelve el estado de la propiedad en ConnectorProperty: status, url, quality, motivo de baja o moderación y estadísticas de los últimos 30 días:

{
  "data": {
    "external_id": "NX-00012",
    "public_code": "CP-10042",
    "status": "published",
    "url": "https://connectorproperty.com/propiedad/CP-10042-…",
    "unpublished_reason": null,
    "moderation_reason": null,
    "quality": { "score": 82, "warnings": [] },
    "stats_30d": { "views": 312, "whatsapp_clicks": 14, "phone_clicks": 3, "leads": 5 },
    "updated_at": "2026-09-17T14:03:12.481Z"
  },
  "api_version": "2026-09-17"
}

5.6 GET /listings — reconciliación

Lista todas las propiedades del integrador en ConnectorProperty, para comparar con el CRM y corregir diferencias.

{
  "data": [ { "external_id": "NX-00012", "status": "published", "updated_at": "…" } ],
  "has_more": false,
  "next_cursor": null,
  "api_version": "2026-09-17"
}

Recomendado una vez al día: todo lo que esté published aquí y no deba estar publicado en el CRM, se despublica con DELETE.

6. Consultas (leads)

Cuando un interesado escribe desde la ficha, ConnectorProperty crea una consulta y la entrega al integrador.

6.1 Webhook

El integrador registra una URL https (se configura con soporte). Cada evento llega como POST:

POST /webhooks/connectorproperty HTTP/1.1
Content-Type: application/json
X-ConnectorProperty-Event: lead.created
X-ConnectorProperty-Delivery: 5b1f7e0c-…
X-ConnectorProperty-Signature: t=1789653792,v1=5f2c…

{
  "event": "lead.created",
  "created_at": "2026-09-17T14:05:00.000Z",
  "environment": "live",
  "data": {
    "id": "a6f0c3e2-…",
    "type": "question",
    "listing_external_id": "NX-00012",
    "listing_public_code": "CP-10042",
    "publisher_external_id": "focolare",
    "agent_external_id": "cmu3msc0g01d5y0sg8k4q1x2z",
    "name": "Pedro Pérez",
    "email": "pedro@example.com",
    "phone": "+56911112222",
    "message": "Hola, ¿sigue disponible? ¿Se puede visitar el sábado?",
    "created_at": "2026-09-17T14:05:00.000Z"
  }
}

• type: question · visit_request.
• Firma: v1 es HMAC-SHA256(secreto_webhook, "<t>.<cuerpo crudo>") en hexadecimal. Verifiquen la firma y rechacen t con más de 5 minutos de diferencia.
• Respondan 2xx en menos de 10 segundos. Si no, se reintenta con espera creciente durante 24 horas. Pueden llegar repetidos: usen data.id.
• Otros eventos: listing.moderated (con external_id y reason).

6.2 Consulta periódica (respaldo)

GET /leads?since=2026-09-17T00:00:00.000Z&limit=100&cursor=…

Devuelve las consultas creadas desde since, en orden ascendente, con la misma forma que data del webhook, más has_more y next_cursor.

6.3 Tiempo de respuesta

Cuando el agente responde al interesado (correo, llamada, WhatsApp), el integrador lo informa una vez:

POST /leads/{id}/events

{ "type": "first_response", "occurred_at": "2026-09-17T14:31:00.000Z", "channel": "whatsapp" }

• channel: email · phone · whatsapp · other.
• Si ya estaba informado, responde 200 sin cambiar la fecha original.

ConnectorProperty muestra en la ficha el tiempo de respuesta típico del agente: la mediana de los últimos 90 días, con al menos 3 consultas. Las consultas sin respuesta después de 72 horas cuentan como 72 horas. Con menos de 3 consultas se muestra "Nuevo en ConnectorProperty".

Sugerencia para CRMs: informen first_response cuando la consulta pasa de "nueva" a "contactada".

7. Límites

• 600 peticiones por minuto por llave. Al superarlo: 429 con cabecera Retry-After (segundos).
• Tamaño máximo del cuerpo: 1 MB.
• Ante 429 o 5xx, reintenten con espera creciente (1 s, 2 s, 4 s…).

8. Errores

Todos los errores tienen la misma forma:

{
  "error": {
    "code": "validation_failed",
    "message": "La propiedad tiene 2 errores.",
    "details": [
      { "field": "common_expenses_clp", "code": "required", "message": "Obligatorio para departamentos (usa 0 si no tiene)." },
      { "field": "location.commune", "code": "unknown_commune", "message": "Comuna desconocida: \"Provdencia\". ¿Quisiste decir \"Providencia\"?" }
    ]
  }
}

9. Ejemplo con curl

export CP_API_KEY="cp_test_…"
BASE=https://connectorproperty.com/api/v1

curl -s -X PUT "$BASE/publishers/focolare" \
  -H "Authorization: Bearer $CP_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"agency","name":"Focolare Propiedades","legal_name":"Focolare Propiedades SpA","rut":"77.123.456-7"}'

curl -s -X PUT "$BASE/listings/NX-00012" \
  -H "Authorization: Bearer $CP_API_KEY" -H "Content-Type: application/json" \
  -d @propiedad.json

curl -s -X DELETE "$BASE/listings/NX-00012?reason=closed" \
  -H "Authorization: Bearer $CP_API_KEY"

10. Próximamente

• Feed XML en formato LIFULL/Trovit, para CRMs que ya lo generan y no quieren integrar la API: ConnectorProperty lo leerá periódicamente.