Navegar por la documentación
Credenciales y acceso
La Partner API v1 usa HTTPS y respuestas JSON. Todas las rutas parten de la misma base.
Base URL: https://www.kuando.cl/api/partner/v1
Envía la API key en uno de estos headers. No la incluyas en código que se ejecute en el navegador.
Authorization: Bearer kdo_live_xxxxxxxxxxxxxxxx
Content-Type: application/jsonTambién se acepta X-API-Key con el mismo valor.
Crear y sincronizar propiedades
Envía un objeto, un array o un objeto con la propiedad properties. La carga es idempotente por corredora y external_id.
POST y PUT sobre la colección hacen un upsert completo. Si vuelves a enviar un external_id existente, se actualiza. Para modificar solo algunos campos usa PATCH.
curl -X POST 'https://www.kuando.cl/api/partner/v1/properties?include=warnings,property' \
-H 'Authorization: Bearer kdo_live_xxxxxxxxxxxxxxxx' \
-H 'Content-Type: application/json' \
-d '{
"properties": [{
"external_id": "A-1001",
"title": "Departamento luminoso en Providencia",
"description": "Cerca del metro y de servicios.",
"purpose": "arriendo",
"property_type": "departamento",
"region": "Metropolitana",
"commune": "Providencia",
"address": "Av. Providencia 1234",
"lat": -33.4372,
"lng": -70.6506,
"location_precision": "exact",
"price_arriendo": 650000,
"price_currency_arriendo": "CLP",
"bedrooms": 2,
"bathrooms": 2,
"m2_total": 75,
"m2_useful": 68,
"images": [
"https://cdn.ejemplo.cl/propiedades/A-1001-1.jpg",
"https://cdn.ejemplo.cl/propiedades/A-1001-2.jpg"
]
}]
}'POST y PUT reemplazan los datos de la propiedad.
Puedes agregar ?include=warnings,property para recibir advertencias de normalización y, por fila, el ID interno y la URL pública cuando el aviso está activo.
Campos y valores
Envía los nombres canónicos en inglés para evitar ambigüedades.
Campos obligatorios
external_id, title, purpose,commune y el precio correspondiente a la operación. Para ambos se requieren precio de arriendo y de venta.| Campo | Requisito | Formato y descripción |
|---|---|---|
external_id | Obligatorio | ID estable en tu sistema. Único dentro de la corredora; con una cuenta publicadora compartida, debe ser único en toda la integración. |
title | Obligatorio | Título visible del aviso. |
description | Opcional | Descripción del aviso. |
purpose | Obligatorio | arriendo, venta o ambos. |
property_type | Recomendado | departamento, casa, terreno, pieza, local, oficina, bodega, estacionamiento u otro. Si se omite o no se reconoce, Kuando guarda otro; no infiere el tipo desde el título ni la descripción. |
region | Opcional | Nombre de región. Si no se reconoce, se guarda el texto recibido. Si se omite, el valor interno predeterminado es Metropolitana. |
commune | Obligatorio | Nombre de comuna. Los valores reconocidos se guardan con el nombre del catálogo de Kuando. |
address | Opcional | Dirección de la propiedad. |
lat y lng | Opcional | Coordenadas numéricas de latitud y longitud. Envía ambas o ninguna. Para borrar una ubicación existente, envía ambas como null. |
location_precision | Opcional | exact por defecto o approximate. Debe enviarse junto con lat y lng. approximate redondea las coordenadas a dos decimales antes de guardarlas. |
price_arriendo y price_currency_arriendo | Según operación | Precio numérico y moneda CLP o UF para arriendo. Obligatorio para arriendo y ambos. |
price_venta y price_currency_venta | Según operación | Precio numérico y moneda CLP o UF para venta. Obligatorio para venta y ambos. |
price y price_currency | Compatibilidad | Formato genérico aceptado. Se recomienda enviar los campos específicos de cada operación. |
bedrooms | Opcional | Número de dormitorios. Si se omite, se guarda 0. |
bathrooms | Opcional | Número de baños. Si se omite, se guarda 0. |
m2_total | Opcional | Envía la superficie total según la definición de tu sistema. Kuando la guarda tal como llega y no suma la superficie útil con la terraza. |
m2_useful | Opcional | Superficie útil en m². |
parking | Opcional | Número de estacionamientos. |
storage | Opcional | Indica si incluye bodega. |
common_expenses y common_expenses_currency | Opcional | Gastos comunes y moneda CLP o UF. |
building_age | Opcional | nuevo, 0-5, 5-15 o 15+. |
pet_friendly y furnished | Opcional | Valores booleanos. Se aceptan true/false, sí/no y 1/0. |
amenities | Opcional | Lista de textos. Para que Kuando los reconozca en filtros, usa los nombres canónicos de la lista siguiente. |
images | Opcional | Lista ordenada de URLs de imágenes. |
external_sources | Opcional | Fuentes externas con URL de origen para la sincronización de precio. Revisa el formato en la sección Sincronización de precios. |
agency_external_id | Solo agregadoras | Código estable de la corredora. Obligatorio en cada fila agregadora; con una cuenta publicadora compartida identifica la cartera de origen, no crea una cuenta Kuando. |
seller_contact | Requerido en modo agregador de cuenta única | Contacto propio del aviso. Admite contact, email, phone, area_code, phone2, area_code2 y other_info. Debe incluir un teléfono móvil válido para dirigir el match al corredor. |
status | Opcional | active, paused, rented, sold o draft. |
El campo amenities conserva los textos que envías. Para que coincidan con los filtros de Kuando, usa exactamente estos nombres, respetando mayúsculas, tildes y espacios:
| Amenity reconocida por los filtros |
|---|
Piscina |
Gimnasio |
Terraza |
Quincho |
Conserjería 24h |
Estacionamiento visitas |
Bicicletero |
Sala de eventos |
Juegos infantiles |
Otros textos se pueden guardar y mostrar en el aviso, pero no activan uno de estos filtros. La bodega se informa con storage y la cantidad de estacionamientos con parking. Estacionamiento visitas es una amenity distinta.
{ "amenities": ["Piscina", "Quincho", "Estacionamiento visitas"] }Las monedas canónicas son CLP y UF. En JSON, envía los precios como números, por ejemplo 650000 o 4200 para UF. No existe un campo independiente para superficie de terreno en Partner API v1. Los campos que no aparecen en esta referencia se ignoran y no se guardan.
La ubicación es opcional y se valida en conjunto.
lat y lng como números dentro de los rangos de latitud (-90 a 90) y longitud (-180 a 180). No envíes solo una coordenada. Si omites location_precision, se usa exact. Para aproximar el punto, usa approximate; Kuando redondea ambas coordenadas a dos decimales antes de guardarlas. Si omites las coordenadas, una actualización conserva el punto existente y una propiedad nueva queda sin ubicación. Para borrar el punto, envía ambas coordenadas como null. En un PATCH, si cambias coordenadas sin indicar precisión, se conserva la precisión que ya tenía la propiedad.En nombres reconocidos de región y comuna, Kuando normaliza mayúsculas, tildes y espacios y guarda el nombre del catálogo. Por ejemplo, nunoa se normaliza a Ñuñoa. Una ubicación desconocida se guarda tal como llega y no genera por sí sola un error 400. Para revisar advertencias usa include=warnings.
Regiones y comunas reconocidas por Kuando
Arica y Parinacota
Arica, Camarones, General Lagos, Putre
Tarapacá
Alto Hospicio, Camiña, Colchane, Huara, Iquique, Pica, Pozo Almonte
Antofagasta
Antofagasta, Calama, María Elena, Mejillones, Ollagüe, San Pedro de Atacama, Sierra Gorda, Taltal, Tocopilla
Atacama
Alto del Carmen, Caldera, Chañaral, Copiapó, Diego de Almagro, Freirina, Huasco, Tierra Amarilla, Vallenar
Coquimbo
Andacollo, Canela, Combarbalá, Coquimbo, Illapel, La Higuera, La Serena, Los Vilos, Monte Patria, Ovalle, Paiguano, Punitaqui, Río Hurtado, Salamanca, Vicuña
Valparaíso
Algarrobo, Cabildo, Calle Larga, Cartagena, Casablanca, Catemu, Concón, El Quisco, El Tabo, Hijuelas, Isla de Pascua, Juan Fernández, La Calera, La Cruz, Limache, Llaillay, Los Andes, Nogales, Olmué, Panquehue, Papudo, Petorca, Puchuncaví, Putaendo, Quillota, Quilpué, Quintero, Rinconada, San Antonio, San Felipe, Santa María, Santo Domingo, Valparaíso, Villa Alemana, Viña del Mar, Zapallar
Metropolitana
Alhué, Buin, Calera de Tango, Cerrillos, Cerro Navia, Colina, Conchalí, Curacaví, El Bosque, El Monte, Estación Central, Huechuraba, Independencia, Isla de Maipo, La Cisterna, La Florida, La Granja, La Pintana, La Reina, Lampa, Las Condes, Lo Barnechea, Lo Espejo, Lo Prado, Macul, Maipú, María Pinto, Melipilla, Ñuñoa, Padre Hurtado, Paine, Pedro Aguirre Cerda, Peñaflor, Peñalolén, Pirque, Providencia, Pudahuel, Puente Alto, Quilicura, Quinta Normal, Recoleta, Renca, San Bernardo, San Joaquín, San José de Maipo, San Miguel, San Pedro, San Ramón, Santiago, Talagante, Til Til, Vitacura
O'Higgins
Chépica, Chimbarongo, Codegua, Coinco, Coltauco, Doñihue, Graneros, La Estrella, Las Cabras, Litueche, Lolol, Machalí, Malloa, Marchigüe, Mostazal, Nancagua, Navidad, Olivar, Palmilla, Paredones, Peralillo, Peumo, Pichidegua, Pichilemu, Placilla, Pumanque, Quinta de Tilcoco, Rancagua, Rengo, Requínoa, San Fernando, San Vicente, Santa Cruz
Maule
Cauquenes, Chanco, Colbún, Constitución, Curicó, Empedrado, Hualañé, Licantén, Linares, Longaví, Molina, Parral, Pelarco, Pelluhue, Pencahue, Retiro, Río Claro, Romeral, Sagrada Familia, San Clemente, San Javier, San Rafael, Talca, Teno, Vichuquén, Villa Alegre, Yerbas Buenas
Ñuble
Bulnes, Chillán, Chillán Viejo, Cobquecura, Coelemu, Coihueco, El Carmen, Ninhue, Ñiquén, Pemuco, Pinto, Portezuelo, Quillón, Quirihue, Ranquil, San Carlos, San Fabián, San Ignacio, San Nicolás, Trehuaco, Yungay
Biobío
Alto Biobío, Antuco, Arauco, Cabrero, Cañete, Chiguayante, Concepción, Contulmo, Coronel, Curanilahue, Florida, Hualpén, Hualqui, Laja, Lebu, Los Álamos, Los Ángeles, Lota, Mulchén, Nacimiento, Negrete, Penco, Quilaco, Quilleco, San Pedro de la Paz, San Rosendo, Santa Bárbara, Santa Juana, Talcahuano, Tirúa, Tomé, Tucapel, Yumbel
La Araucanía
Angol, Carahue, Cholchol, Collipulli, Cunco, Curacautín, Curarrehue, Ercilla, Freire, Galvarino, Lautaro, Loncoche, Lonquimay, Los Sauces, Lumaco, Melipeuco, Nueva Imperial, Padre Las Casas, Perquenco, Pitrufquén, Pucón, Purén, Renaico, Saavedra, Temuco, Teodoro Schmidt, Toltén, Traiguén, Victoria, Vilcún, Villarrica
Los Ríos
Corral, Futrono, La Unión, Lago Ranco, Lanco, Los Lagos, Máfil, Mariquina, Paillaco, Panguipulli, Río Bueno, Valdivia
Los Lagos
Ancud, Calbuco, Castro, Chaitén, Chonchi, Cochamó, Curaco de Vélez, Dalcahue, Fresia, Frutillar, Futaleufú, Hualaihué, Llanquihue, Los Muermos, Maullín, Osorno, Palena, Puerto Montt, Puerto Octay, Puerto Varas, Puqueldón, Purranque, Puyehue, Queilén, Quellón, Quemchi, Quinchao, Río Negro, San Juan de la Costa, San Pablo
Aysén
Aysén, Chile Chico, Cisnes, Cochrane, Coyhaique, Guaitecas, Lago Verde, O'Higgins, Río Ibáñez, Tortel
Magallanes
Cabo de Hornos, Laguna Blanca, Porvenir, Primavera, Puerto Natales, Punta Arenas, Río Verde, San Gregorio, Timaukel, Torres del Paine
También puedes obtener el catálogo canónico completo por API. Requiere el permiso properties:read.
GET /api/partner/v1/catalogs/locations
Authorization: Bearer kdo_live_xxxxxxxxxxxxxxxxSe aceptan algunos nombres alternativos de campos, como titulo, operacion, comuna, precio_arriendo e fotos. Los campos no reconocidos se ignoran. Usa los nombres canónicos de la tabla en nuevas integraciones.
Estados e imágenes
En una propiedad nueva, si omites status, con imágenes válidas Kuando intenta dejarla active y sin imágenes queda draft. Si la corredora ya alcanzó el cupo de su plan, la nueva propiedad puede quedar pausada por ese límite. En una propiedad existente, omitir status conserva su estado actual. Así una actualización de contenido no reactiva por sí sola un aviso pausado, vendido o arrendado.
Puedes enviar active, paused, rented, sold o draft. También se reconocen equivalentes habituales en español, como publicada, pausada, arrendada, vendida y borrador.
Se guardan hasta 30 imágenes por propiedad, en el mismo orden enviado. La primera imagen se usa como portada. Envía URLs HTTP o HTTPS que se puedan abrir desde internet. Kuando procesa las imágenes de forma asíncrona, así que mantén las URLs disponibles hasta que termine ese proceso.
Retirar un aviso no borra su registro.
?status=sold o ?status=rented.Consultar propiedades
El listado devuelve hasta 100 propiedades por defecto. Puedes aumentar el valor de limit hasta 500. Esta versión no ofrece cursor, página ni filtros de búsqueda adicionales. Para consultar una propiedad puntual, usa su external_id.
GET /api/partner/v1/properties?limit=500
GET /api/partner/v1/properties/A-1001La respuesta del detalle incluye la propiedad y su ID interno. En una integración agregadora, agrega el código de la corredora:
GET /api/partner/v1/properties?limit=500&agency=C-017
GET /api/partner/v1/properties/A-1001?agency=C-017El detalle tiene esta estructura:
{
"property": {
"id": "uuid-interno",
"external_id": "A-1001",
"title": "Departamento luminoso en Providencia",
"status": "active",
"lat": -33.4372,
"lng": -70.6506,
"location_precision": "exact"
},
"external_sync": null
}El listado y el detalle incluyen lat, lng y location_precision. Si la propiedad no tiene un punto guardado, las coordenadas llegan como null. Las ubicaciones aproximadas ya vienen redondeadas.
Referencia de endpoints
Estas rutas permiten crear, consultar, actualizar y retirar avisos. Todas usan la base URL indicada al inicio de esta guía.
| Método | Ruta | Uso |
|---|---|---|
POST | /properties | Crear o actualizar propiedades en lote. Admite hasta 1.000 por solicitud. |
PUT | /properties | Upsert completo en lote, compatible con integraciones que usan PUT. |
GET | /properties | Listar propiedades. Acepta limit y, para agregadoras, agency. |
GET | /properties/limits | Consultar el cupo del plan y las propiedades activas. En agregadoras, acepta agency o devuelve todas las corredoras vinculadas. |
GET | /properties/{external_id} | Consultar el detalle y el ID interno de un aviso. |
GET | /catalogs/locations | Obtener regiones y comunas canónicas. Requiere properties:read. |
PUT | /properties/{external_id} | Crear o reemplazar completamente un aviso puntual. |
PATCH | /properties/{external_id} | Actualizar solo los campos enviados. El aviso debe existir. |
DELETE | /properties/{external_id} | Retirar el aviso. Por defecto lo pausa. Admite status=sold o status=rented. |
POST | /properties/{external_id}/status | Cambiar el estado a active, paused, sold o rented. |
GET / PATCH | /properties/{external_id}/sync | Consultar o pausar/reanudar la sincronización de precio desde una fuente externa. |
PUT | /agencies/{agency_external_id} | Registrar una corredora en una integración agregadora. |
En solicitudes puntuales de una key agregadora, agrega ?agency=CODE para identificar la cuenta de la corredora. En las cargas de colección, cada propiedad debe incluiragency_external_id. Para un PUT puntual también puedes enviar ese código en el body o como parámetro agency.
Una integración para varias corredoras
La API key agregadora conecta varias cuentas, pero cada corredora mantiene su propia cuenta Kuando.
La misma API agregadora sirve para integradores que administran varias carteras. Cada corredora conserva su cuenta Kuando, sus datos de acceso y su propio cupo. La key no tiene un plan de propiedades propio. Kuando configura para cada integración quién cubre el plan de las cuentas vinculadas y, si corresponde, qué plan se les asigna.
- En el modelo de pago directo, cada corredora contrata su plan con Kuando. Al crear la cuenta, queda en un estado interno inicial identificado como
free. Este estado no es un plan gratuito publicable ni permite tener propiedades activas. Para publicar, la corredora debe contratar Inicia o un plan superior. Si es elegible, puede activar una prueba gratis de 3 días. Mientras tanto, puede enviar propiedades pausadas para preparar o probar la integración. El integrador puede seguir administrando sus propiedades mediante la API. - En el modelo financiado por la integración, Kuando asigna a cada cuenta nueva el plan que se haya configurado para esa integración. El plan se define con Kuando y puede variar según el acuerdo. Cada corredora tiene su propio cupo y los cupos no se comparten.
- Kuando entrega una key al integrador para usar la API. Para propiedades, debe tener los permisos
properties:readyproperties:write. - Antes de enviar la cartera, el integrador registra a la corredora con su ID interno estable como
agency_external_id, el nombre que se mostrará en su cuenta, un correo de acceso y un teléfono móvil con código de país. El código debe mantenerse igual en las siguientes solicitudes. - Kuando crea la cuenta independiente de la corredora y envía una contraseña temporal a su correo. En el primer ingreso debe cambiarla. Si la corredora ya tiene una cuenta Kuando con ese correo, la API no crea otra ni las fusiona automáticamente. En ese caso, hay que coordinar la vinculación con Kuando.
- El plan de la cuenta depende del modelo de facturación configurado para la integración. Para consultar el plan y el cupo de una corredora, usa
GET /properties/limits?agency=CODE. Sinagency, la respuesta incluye todas las corredoras vinculadas a la key. Kuando debe dejar configurados el modelo y el plan antes de vincular la primera corredora. Si una cuenta patrocinada ya tiene un plan contratado directamente, la API responde 409 con el códigoagency_plan_billing_conflictpara revisar el cambio con Kuando.
PUT /api/partner/v1/agencies/C-017
Authorization: Bearer kdo_live_xxxxxxxxxxxxxxxx
Content-Type: application/json
{
"name": "Corredora Pérez",
"email": "contacto@corredoraperez.cl",
"phone": "+56912345678"
}La respuesta confirma el registro y el envío del correo:
{
"ok": true,
"agency_external_id": "C-017",
"result": "created",
"access_email_sent": true
}En cada propiedad incluye el mismo agency_external_id. En las operaciones sobre un aviso puntual de una agregadora usa ?agency=C-017. La respuesta indica si la cuenta se creó y si se envió el correo de acceso. Si el correo o teléfono ya pertenecen a otra cuenta, la API responde 409. Después del primer correo de acceso, el integrador no puede cambiar los datos de contacto por API.
Registra cada corredora antes de enviar su cartera.
Sincronización de precios
Puedes asociar un aviso de Kuando con la publicación de origen para revisar su precio periódicamente.
Incluye external_sources al crear o actualizar una propiedad. Indica la URL pública del aviso de origen. El portal puede detectarse desde la URL, y price_fieldpermite indicar cuál de los precios debe actualizarse. Aunque el formato es una lista, Kuando registra una sola fuente canónica por propiedad, así que envía una fuente.
{
"external_sources": [
{
"portal": "portalinmobiliario",
"source_url": "https://www.portalinmobiliario.com/MLC-123456789",
"price_field": "price_venta",
"sync_price": true
}
]
}Cuando esta función está habilitada, Kuando revisa el precio una vez al día y actualiza el campo indicado conservando la moneda detectada en el aviso de origen. El último resultado y los errores de lectura se pueden consultar en GET /properties/{external_id}/sync. Para detener o reanudar la sincronización, usa PATCH con { "sync_price": false }o { "sync_price": true }.
La lectura depende del portal de origen.
GET /api/partner/v1/properties/A-1001/sync
PATCH /api/partner/v1/properties/A-1001/sync
Content-Type: application/json
{ "sync_price": false }En una integración agregadora, agrega ?agency=CODE a estas rutas. La fuente se debe volver a enviar si cambias su URL.
Respuestas y errores
Revisa el resultado por propiedad. Una solicitud puede procesarse correctamente aunque alguna fila individual falle.
Un upsert exitoso devuelve contadores y un resultado por external_id:
{
"total": 2,
"created": 1,
"updated": 0,
"failed": 1,
"results": [
{
"external_id": "A-1001",
"status": "created",
"propertyStatus": "active",
"pausedByPlanLimit": false,
"property_id": "uuid-interno",
"public_url": "https://www.kuando.cl/p/uuid-interno"
},
{
"external_id": "A-1002",
"status": "error",
"error": "Falta commune / comuna."
}
]
}property_id y public_url aparecen si solicitas include=property. La URL pública es null cuando el aviso no está activo. Las advertencias aparecen con include=warnings. El ejemplo omite el resumen del límite de propiedades que también puede venir en la respuesta.
| HTTP | Cuándo aparece |
|---|---|
| 400 | JSON o body inválido, lote vacío o superior a 1.000, PATCH sin campos válidos o estado no admitido. Los campos requeridos que falten en una fila se informan dentro de results. |
| 401 | La API key falta o no es válida. |
| 403 | La key no tiene el permiso requerido o una activación supera el límite del plan. |
| 404 | No existe el aviso o el código de corredora no está vinculado a la integración. |
| 409 | Conflicto de correo o teléfono al registrar una corredora. |
| 413 | El XML supera 5 MB. |
| 422 | XML mal formado o sin publicaciones reconocibles. También puede ocurrir al intentar activar un aviso sin imágenes. |
| 429 | Se alcanzó el límite de solicitudes por IP. |
Los errores de filas del POST/PUT se informan dentro de results.
status: "error" mientras las demás continúan. Revisa failed y vuelve a enviar las filas corregidas.Límites y forma de sincronizar
| Operación | Límite actual |
|---|---|
| POST / PUT de propiedades | Hasta 1.000 propiedades por solicitud. |
| GET de propiedades | limit por defecto 100, máximo 500. Sin paginación por cursor o página. |
| Solicitudes de Partner API | 120 solicitudes por minuto por IP. El exceso responde HTTP 429. |
| Propiedades activas | Sujetas al cupo del plan de cada corredora. En cargas agregadoras, propertyLimitsByAgency informa el estado por código. |
La integración funciona por envío desde tu sistema hacia Kuando. Envía altas y cambios con POST, PUT o PATCH. La API no retira automáticamente las propiedades que no aparezcan en una carga nueva. Para retirar, cambia el estado explícitamente o usa DELETE.
Consulta el cupo actual antes de cargar propiedades con GET /properties/limits. Una key individual recibe el plan, el límite, cuántas propiedades están activas y cuántos cupos quedan. Una key agregadora obtiene el resumen de todas sus corredoras o puede indicar ?agency=CODE para consultar una en particular. Las respuestas POST/PUT siguen incluyendo propertyLimitsByAgency para informar los límites después de cada carga. En una cuenta nueva de pago directo que todavía no contrató un plan, la respuesta puede mostrar plan: free y limit: 0. Es el estado inicial de la cuenta, no un plan gratuito con publicaciones activas.
GET /api/partner/v1/properties/limits
GET /api/partner/v1/properties/limits?agency=C-017{
"count": 1,
"agencies": [
{
"agency_external_id": "C-017",
"plan": "agencia",
"limit": 10000,
"active": 0,
"available": 10000,
"atLimit": false
}
]
}¿Necesitas coordinar tu integración?
Cuéntanos qué sistema usas y qué método quieres conectar.