Buscar Propiedad por Código

Permite obtener la información completa de una propiedad específica a partir de su código único. La respuesta incluye 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 cuando ya conoces el código del inmueble y necesitas consultar toda su información detallada. Es ideal para mostrar la ficha completa de una propiedad en tu sitio web, sincronizar datos de un inmueble puntual o verificar la información registrada en el sistema.

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, y {{code}} por el código numérico del inmueble que deseas consultar.

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

¿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. Construye la URL con el código de la propiedad como parte de la ruta e incluye los encabezados requeridos:

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ámetro de ruta:

Ejemplos de peticiones:

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

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

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

El sistema te devolverá un objeto JSON con toda la información de la propiedad solicitada. Si el código no corresponde a ningún inmueble registrado, se devolverá un arreglo vacío [].

Respuesta como objeto, no como lista
A diferencia del servicio Listar Propiedades que devuelve un arreglo de objetos [{...}, {...}], este servicio devuelve directamente un único objeto {...} con la información del inmueble consultado.

La respuesta exitosa 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": "250000",
    "avaluo_catastral": "185000000",
    "impuesto_predial": "1250000.00",
    "area": "75.00",
    "observaciones": "Inmueble ubicado en zona residencial tranquila, cerca de centros comerciales y transporte público.",
    "propiedad_destacada": "No",
    "llaves_en": "oficina",
    "llaves_otro": null,
    "paga_cuota_sost": "propietario",
    "folio_matricula": "001-123456",
    "referencia_catastral": "05001010203040",
    "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": "5",
            "descripcion": "Nº De Piso",
            "tipo_campo": "numeric",
            "orden": "3",
            "grupo": "Características del inmueble",
            "valor": "1"
        },
        {
            "id": "4",
            "descripcion": "Antigüedad del Inmueble",
            "tipo_campo": "numeric",
            "orden": "5",
            "grupo": "Características del Inmueble",
            "valor": "3"
        },
        {
            "id": "14",
            "descripcion": "Cocina Integral",
            "tipo_campo": "checkbox",
            "orden": "5",
            "grupo": "Características Internas",
            "valor": "1"
        },
        {
            "id": "34",
            "descripcion": "Sala",
            "tipo_campo": "checkbox",
            "orden": "6",
            "grupo": "Características del Inmueble",
            "valor": "1"
        },
        {
            "id": "31",
            "descripcion": "Red de gas",
            "tipo_campo": "select",
            "orden": "5",
            "grupo": "Características del Inmueble",
            "valor": "si",
            "valor_texto": "Si"
        },
        {
            "id": "63",
            "descripcion": "Garaje",
            "tipo_campo": "checkbox",
            "orden": "10",
            "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"
        },
        {
            "posicion": "3",
            "size": "19201080",
            "img": "img/fotos/1920x1080_b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8.jpeg",
            "imagen": "https://mi-inmobiliaria.nuby.app/img/fotos/1920x1080_b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8.jpeg"
        }
    ],
    "videos": [
        {
            "url": "dQw4w9WgXcQ",
            "tipo": "youtube",
            "descripcion": null,
            "posicion": "1"
        }
    ],
    "codigos_portales": [
        {
            "nombre_portal": "metrocuadrado",
            "id_portal": "MC-98765",
            "tipo_servicio": "arriendo"
        }
    ]
}

Cuando el código no corresponde a ningún inmueble, la respuesta será:

[]

Campos principales de la propiedad

Esta tabla enumera las claves presentes en el JSON de la 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 de ruta:

Cuando el código es numérico pero no corresponde a ningún inmueble registrado, el sistema no devuelve un error. En su lugar, responde con un HTTP 200 y un arreglo vacío:

[]

Importante
Asegúrate de validar en tu integración si la respuesta es un arreglo vacío [] para manejar correctamente el caso en que la propiedad no exista.

5. Ejemplos de integración

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

# Consultar propiedad por código
curl -X GET "https://{{instancia}}/service/v2/public/properties/137" \
-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
$code = 137; // Código de la propiedad a consultar

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

$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) {
        $propiedad = json_decode($response, true);

        if (!empty($propiedad)) {
            echo "Propiedad encontrada:\n";
            echo "  Código: {$propiedad['codigo']}\n";
            echo "  Título: {$propiedad['titulo']}\n";
            echo "  Estado: {$propiedad['estado_texto']}\n";
            echo "  Dirección: {$propiedad['direccion']}\n";
            echo "  Imágenes: {$propiedad['cantidad_images']}\n";
        } else {
            echo "No se encontró ninguna propiedad con el código {$code}.\n";
        }
    } else {
        echo "Error al consultar la propiedad.\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
codigo = 137 # Código de la propiedad a consultar

# 2. Prepara la dirección de la petición
url = f"https://{instancia}/service/v2/public/properties/{codigo}"

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, headers=headers)

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

    if response.status_code == 200:
        propiedad = response.json()

        if propiedad:
            print(f"Propiedad encontrada:")
            print(f"  Código: {propiedad['codigo']}")
            print(f"  Título: {propiedad['titulo']}")
            print(f"  Estado: {propiedad['estado_texto']}")
            print(f"  Dirección: {propiedad['direccion']}")
            print(f"  Características: {len(propiedad['caracteristicas'])}")
        else:
            print(f"No se encontró ninguna propiedad con el código {codigo}.")
    else:
        print("Error al consultar la propiedad.")
        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
const codigo = 137; // Código de la propiedad a consultar

// 2. Prepara la dirección de la petición
const url = `https://${instancia}/service/v2/public/properties/${codigo}`;

// 3. Función para consultar la propiedad
async function consultarPropiedad() {
    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 propiedad = await response.json();

            if (propiedad && !Array.isArray(propiedad)) {
                console.log(`Propiedad encontrada:`);
                console.log(`  Código: ${propiedad.codigo}`);
                console.log(`  Título: ${propiedad.titulo}`);
                console.log(`  Estado: ${propiedad.estado_texto}`);
                console.log(`  Dirección: ${propiedad.direccion}`);
                console.log(`  Imágenes: ${propiedad.cantidad_images}`);
            } else {
                console.log(`No se encontró ninguna propiedad con el código ${codigo}.`);
            }
        } else {
            console.log('Error al consultar la propiedad.');
            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
consultarPropiedad();

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
    codigo = "137", // Código de la propiedad a consultar

    // 2. Prepara la dirección de la petición
    url = "https://" & instancia & "/service/v2/public/properties/" & codigo,

    // 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 registro
    jsonResponse = Json.Document(response),
    resultado = Record.ToTable(jsonResponse),
    expandido = Table.Pivot(resultado, List.Distinct(resultado[Name]), "Name", "Value")
in
    expandido