Listar Propiedades

Permite obtener una lista paginada de propiedades registradas en la inmobiliaria, incluyendo información detallada de cada una: datos generales, ubicación, valores económicos, características, propietarios, imágenes, videos y códigos de portales inmobiliarios.

¿Para qué sirve este servicio?
Úsalo para sincronizar el inventario de propiedades con tu sistema externo, alimentar un sitio web, generar reportes o integrar la información de inmuebles con plataformas de terceros. El endpoint soporta paginación y filtros por rangos de fecha para consultas eficientes.

1. El Endpoint (La dirección web)

Apunta tu sistema a la siguiente dirección. Recuerda reemplazar {{instancia}} por la dirección web completa que utilizas para ingresar a tu plataforma.

GET https://{{instancia}}/service/v2/public/properties

¿Qué debes colocar en {{instancia}}?
Es muy sencillo: corresponde a la dirección web principal que utilizas a diario para ingresar a tu plataforma (incluyendo la terminación .nuby.app o .arrendasoft.co).
Por ejemplo, si para entrar a tu sistema escribes inmobiliaria.nuby.app o inmobiliaria.arrendasoft.co en tu navegador, esa será exactamente tu instancia. Solo asegúrate de no incluir el "https://" ni barras diagonales ("/") al final.

2. La Petición (¿Qué debes enviarnos?)

Este servicio requiere autenticación mediante un Token JWT. Envía los encabezados requeridos y opcionalmente los parámetros de filtrado en la URL:

Autenticación requerida
Este servicio requiere un Token de autenticación válido. Debes incluir el encabezado Authorization: Bearer TU_TOKEN en cada petición. El token se obtiene consumiendo el servicio de Login. Adicionalmente, el cliente OAuth debe contar con el scope read para poder consumir este endpoint.

Parámetros de consulta (query string):

Comportamiento de los filtros de fecha
Para los parámetros de tipo fecha que se componen de un rango (por ejemplo listing_start_date y listing_end_date):
— Si envías solo el start_date: se retornarán registros con fecha mayor o igual (>=) a la indicada.
— Si envías solo el end_date: se retornarán registros con fecha menor o igual (<=) a la indicada.
— Si envías ambos: se retornarán registros dentro de ese rango de fechas (BETWEEN).
— La fecha de inicio no puede ser mayor que la fecha de fin; de lo contrario se devolverá un error de validación.

Ejemplos de peticiones:

GET https://{{instancia}}/service/v2/public/properties

GET https://{{instancia}}/service/v2/public/properties?page=1&limit=10

GET https://{{instancia}}/service/v2/public/properties?page=1&limit=10&listing_start_date=2024-03-26

GET https://{{instancia}}/service/v2/public/properties?page=1&limit=10&listing_start_date=2024-03-01&listing_end_date=2024-03-31

GET https://{{instancia}}/service/v2/public/properties?page=2&limit=20&created_start_date=2024-01-01&created_end_date=2024-06-30

3. La Respuesta (¿Qué te entregaremos?)

El sistema te devolverá una lista con las propiedades que coincidan con los filtros aplicados. Cada propiedad incluye datos generales, ubicación, valores económicos, características, propietarios, imágenes, videos y códigos de portales inmobiliarios. La respuesta se verá similar a esta:

[
    {
        "codigo": "137",
        "titulo": "Apartamento amplio con vista al parque central",
        "clase_id": "1247",
        "clase_inmueble": "Apartamento",
        "tipo_servicio_id": "arriendo",
        "tipo_servicio": "Arriendo",
        "estrato": "1258",
        "estrato_texto": "Cuatro",
        "fecha_consignacion": "2024-04-26",
        "asesor_id": "5",
        "asesor": "María López Ramírez",
        "pais_id": "1",
        "pais": "COLOMBIA",
        "departamento_id": "5",
        "departamento": "Antioquia",
        "municipio_id": "1",
        "municipio": "Medellin",
        "barrio_id": "3",
        "barrio": "Los Rosales",
        "direccion": "CALLE 45 # 32 - 18",
        "coordenadas": "6.24830000000000:-75.56120000000000",
        "valor_arriendo1": "1600000",
        "valor_arriendo2": "0",
        "valor_venta1": "0",
        "valor_venta2": "0",
        "valor_administracion": "0",
        "avaluo_catastral": "0",
        "impuesto_predial": "0.00",
        "area": "75.00",
        "observaciones": null,
        "propiedad_destacada": "No",
        "llaves_en": "oficina",
        "llaves_otro": null,
        "paga_cuota_sost": "propietario",
        "folio_matricula": null,
        "referencia_catastral": null,
        "edificio_unidad": "urbanizacion",
        "estado": "1",
        "estado_texto": "Activa",
        "cantidad_images": "3",
        "cantidad_videos": "1",
        "fecha_creacion": "2024-04-26 10:30:00",
        "ultima_fecha_modificacion": "2024-05-15 14:22:00",
        "caracteristicas": [
            {
                "id": "1",
                "descripcion": "Nº De Habitaciones",
                "tipo_campo": "numeric",
                "orden": "1",
                "grupo": "Características del inmueble",
                "valor": "4"
            },
            {
                "id": "2",
                "descripcion": "Nº De Baños",
                "tipo_campo": "numeric",
                "orden": "2",
                "grupo": "Características del inmueble",
                "valor": "3"
            },
            {
                "id": "31",
                "descripcion": "Red de gas",
                "tipo_campo": "select",
                "orden": "5",
                "grupo": "Características del Inmueble",
                "valor": "si",
                "valor_texto": "Si"
            },
            {
                "id": "14",
                "descripcion": "Cocina Integral",
                "tipo_campo": "checkbox",
                "orden": "5",
                "grupo": "Características Internas",
                "valor": "1"
            }
        ],
        "propietarios": [
            {
                "id": "272",
                "documento": "1020304050",
                "nombres": "ANA MARÍA",
                "apellidos": "PÉREZ RODRÍGUEZ"
            }
        ],
        "imagenes": [
            {
                "posicion": "1",
                "size": "19201080",
                "img": "img/fotos/1920x1080_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.jpeg",
                "imagen": "https://mi-inmobiliaria.nuby.app/img/fotos/1920x1080_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6.jpeg"
            },
            {
                "posicion": "2",
                "size": "19201080",
                "img": "img/fotos/1920x1080_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3.jpeg",
                "imagen": "https://mi-inmobiliaria.nuby.app/img/fotos/1920x1080_f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3.jpeg"
            }
        ],
        "videos": [
            {
                "url": "dQw4w9WgXcQ",
                "tipo": "youtube",
                "descripcion": null,
                "posicion": "1"
            }
        ],
        "codigos_portales": [
            {
                "nombre_portal": "metrocuadrado",
                "id_portal": "MC-12345",
                "tipo_servicio": "arriendo"
            }
        ]
    }
]

Campos principales de la propiedad

Esta tabla enumera las claves presentes en el JSON de cada propiedad y proporciona una descripción de cada una:

Características

Cada elemento dentro de la lista caracteristicas contiene la información de una característica del inmueble y su valor asignado:

Propietarios

Cada elemento dentro de la lista propietarios contiene la información de un propietario del inmueble:

Imágenes

Cada elemento dentro de la lista imagenes contiene la información de una fotografía del inmueble:

Videos

Cada elemento dentro de la lista videos contiene la información de un video asociado al inmueble:

Códigos de Portales

Cada elemento dentro de la lista codigos_portales contiene la información de publicación del inmueble en un portal inmobiliario externo:

4. Seguridad y Posibles Errores

El sistema realiza validaciones de autenticación, scopes y parámetros. Si alguna falla, devolverá un error con su respectivo código HTTP:

5. Ejemplos de integración

Aquí tienes ejemplos de código listos para que tus desarrolladores los adapten a tu plataforma:

# Listar propiedades con paginación
curl -X GET "https://{{instancia}}/service/v2/public/properties?page=1&limit=10" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

# Filtrar por rango de fecha de consignación
curl -X GET "https://{{instancia}}/service/v2/public/properties?page=1&limit=10&listing_start_date=2024-03-01&listing_end_date=2024-03-31" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

# Filtrar por fecha de creación
curl -X GET "https://{{instancia}}/service/v2/public/properties?page=1&limit=20&created_start_date=2024-01-01" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

<?php

$instance = 'tu_instancia'; // Reemplaza con tu instancia real
$token = 'TU_TOKEN_AQUI'; // Token obtenido del servicio Login

// Parámetros de consulta
$page = 1;
$limit = 10;
$listingStartDate = '2024-03-01';
$listingEndDate = '2024-03-31';

$queryParams = http_build_query([
    'page' => $page,
    'limit' => $limit,
    'listing_start_date' => $listingStartDate,
    'listing_end_date' => $listingEndDate
]);

$url = "https://{$instance}/service/v2/public/properties?{$queryParams}";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    "Authorization: Bearer {$token}"
]);

$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo "Código de estado HTTP: " . $http_code . "\n";

    if ($http_code === 200) {
        $propiedades = json_decode($response, true);
        echo "Propiedades encontradas: " . count($propiedades) . "\n";
        foreach ($propiedades as $propiedad) {
            echo "  [{$propiedad['codigo']}] {$propiedad['titulo']} - {$propiedad['estado_texto']}\n";
        }
    } else {
        echo "Error al consultar las propiedades.\n";
        echo $response . "\n";
    }
}
curl_close($ch);

?>

import requests

# 1. Configura tus datos de acceso
instancia = 'mi-inmobiliaria.nuby.app' # Reemplaza con tu dirección web completa
token = 'TU_TOKEN_AQUI' # Token obtenido del servicio Login

# 2. Prepara la dirección y los parámetros
url = f"https://{instancia}/service/v2/public/properties"

params = {
    "page": 1,
    "limit": 10,
    "listing_start_date": "2024-03-01",
    "listing_end_date": "2024-03-31"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {token}"
}

# 3. Envía la petición GET y procesa la respuesta
try:
    response = requests.get(url, params=params, headers=headers)

    print(f"Código de estado HTTP: {response.status_code}")

    if response.status_code == 200:
        propiedades = response.json()
        print(f"Propiedades encontradas: {len(propiedades)}")
        for prop in propiedades:
            print(f"  [{prop['codigo']}] {prop['titulo']} - {prop['estado_texto']}")
    else:
        print("Error al consultar las propiedades.")
        print(f"Detalle del error: {response.text}")

except Exception as e:
    print(f"Ocurrió un error de conexión: {e}")

// 1. Configura tus datos de acceso
const instancia = 'mi-inmobiliaria.nuby.app'; // Reemplaza con tu dirección web completa
const token = 'TU_TOKEN_AQUI'; // Token obtenido del servicio Login

// 2. Prepara la dirección con parámetros
const params = new URLSearchParams({
    page: 1,
    limit: 10,
    listing_start_date: '2024-03-01',
    listing_end_date: '2024-03-31'
});

const url = `https://${instancia}/service/v2/public/properties?${params}`;

// 3. Función para consultar las propiedades
async function consultarPropiedades() {
    try {
        const response = await fetch(url, {
            method: 'GET',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${token}`
            }
        });

        console.log(`Código de estado HTTP: ${response.status}`);

        if (response.ok) {
            const propiedades = await response.json();
            console.log(`Propiedades encontradas: ${propiedades.length}`);
            propiedades.forEach(prop => {
                console.log(`  [${prop.codigo}] ${prop.titulo} - ${prop.estado_texto}`);
            });
        } else {
            console.log('Error al consultar las propiedades.');
            const errorData = await response.text();
            console.log(`Detalle del error: ${errorData}`);
        }
    } catch (error) {
        console.error(`Ocurrió un error de conexión: ${error}`);
    }
}

// 4. Ejecutamos la función
consultarPropiedades();

let
    // 1. Configura tus datos de acceso
    instancia = "mi-inmobiliaria.nuby.app", // Reemplaza con tu dirección web completa
    token = "TU_TOKEN_AQUI", // Token obtenido del servicio Login

    // 2. Prepara la dirección de la petición con parámetros
    url = "https://" & instancia & "/service/v2/public/properties?page=1&limit=50",

    // 3. Envía la petición GET
    response = Web.Contents(url, [
        Headers = [
            #"Content-Type" = "application/json",
            #"Authorization" = "Bearer " & token
        ]
    ]),

    // 4. Decodifica la respuesta JSON y conviértela en tabla
    jsonResponse = Json.Document(response),
    tabla = Table.FromList(jsonResponse, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    expandido = Table.ExpandRecordColumn(tabla, "Column1",
        {"codigo", "titulo", "clase_inmueble", "tipo_servicio", "estado_texto", "direccion", "municipio", "departamento", "area", "valor_arriendo1", "valor_venta1", "fecha_consignacion"},
        {"Codigo", "Titulo", "ClaseInmueble", "TipoServicio", "Estado", "Direccion", "Municipio", "Departamento", "Area", "ValorArriendo", "ValorVenta", "FechaConsignacion"})
in
    expandido