Crear Propiedad

Permite registrar una nueva propiedad en el sistema de forma integral. A través de este servicio, es posible guardar la información básica de la propiedad, asociar propietarios (existentes o creados dinámicamente en la misma petición), registrar características personalizadas, coordenadas geográficas, videos de recorridos, fotos del inmueble y relacionar otras propiedades.

¿Para qué sirve este servicio?
Úsalo cuando necesites automatizar el ingreso de propiedades a nuby desde portales externos, aplicaciones móviles o sistemas de captación propios. Este endpoint está diseñado bajo un modelo transaccional robusto, asegurando que si algún paso crítico falla (por ejemplo, validación de un propietario o falta de características obligatorias del tipo de propiedad), toda la operación se cancele de forma automática para evitar datos inconsistentes en tu base de datos.

1. El Endpoint (La dirección web)

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

POST 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 estructura la petición con un cuerpo (Body) en formato JSON que contenga las secciones detalladas a continuación:

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 write para poder consumir este endpoint.

Cuerpo de la petición (JSON Body - Estructura General)

La raíz del JSON enviado debe estructurarse con las siguientes llaves principales:

Estructura Detallada de las Secciones

2.1 Sección "Propiedad" 🏢

Contiene la información comercial y técnica base del inmueble. Los siguientes campos son validados estrictamente bajo validación rápida (Fail-Fast):

2.2 Sección "Propietarios" 👥

Cada propiedad en nuby requiere obligatoriamente tener asociado al menos un propietario. El arreglo acepta dos formatos de datos, los cuales pueden combinarse:

Formato A: Propietario Existente (Por ID)

Si el propietario ya se encuentra registrado en el ERP nuby, simplemente envía su identificador único (ID de tercero) como un entero dentro del arreglo:

"Propietarios": [1528, 4390]

Formato B: Creación Dinámica de Propietario (Objeto de Datos)

Si el propietario no existe, puedes enviar sus datos completos estructurados en un objeto. El sistema validará su información, lo creará automáticamente en la base de datos de nuby, y lo asociará al inmueble bajo una misma transacción comercial:

2.3 Sección "Caracteristicas" ⚙️

Permite registrar valores para las características personalizadas del inmueble. Se envía en formato de objeto clave-valor, donde la clave es el ID numérico de la característica y el valor es el contenido a asignar:

"Caracteristicas": {
    "1": "3",   // ID 1 (Habitaciones) = 3
    "2": "2",   // ID 2 (Baños) = 2
    "12": "Sí"  // ID 12 (Ascensor) = Sí
}

Validación de Características Obligatorias por Tipo
El motor de validación del sistema nuby verificará qué características están configuradas en el ERP como obligatorias para el tipo de propiedad seleccionado (tipo_id). Si omites alguna de estas características obligatorias en la petición, o el formato del valor es erróneo (por ejemplo, enviar texto en un campo netamente numérico), el endpoint devolverá un código de estado 422 Unprocessable Entity y se revertirá todo el proceso de guardado.

2.4 Sección "Fotos" 📸

Permite adjuntar imágenes del inmueble de forma directa. El procesamiento de imágenes está automatizado y realiza optimizaciones de rendimiento y de presentación visual (redimensionamiento, corrección de orientación por metadatos EXIF, e inserción de la marca de agua corporativa configurada en el sistema).

2.5 Sección "Videos" 🎥

Permite registrar recorridos en video de las propiedades (por ejemplo, cargados en plataformas como YouTube o Vimeo):

2.6 Sección "PropiedadesRelacionadas" y "Coordenadas" 📍

• PropiedadesRelacionadas → Permite enlazar propiedades entre sí (ideal para bodegas subdivididas, oficinas del mismo centro de negocios, etc.). Recibe una lista de códigos de inmuebles: [137, 1042]. El sistema nuby creará una asociación recíproca: la propiedad creada apuntará a estas asociadas, y estas asociadas apuntarán automáticamente a la nueva propiedad.
• Coordenadas → Coordenadas de geolocalización. Se recomienda enviar como una cadena de texto separada por comas "latitud,longitud" (Ej: "6.2089,-75.5678"). El motor de nuby se encarga de analizar la cadena, validar su rango físico geográfico y guardarlo bajo el formato propietario del sistema.

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

Esta sección describe la respuesta que recibirás del sistema cuando la creación del inmueble sea completamente exitosa.

Respuesta Exitosa (201 Created)

Se genera cuando la propiedad y todos sus componentes asociados han sido validados e insertados con éxito. Se retorna el identificador único físico asignado al inmueble:

{
  "error": false,
  "type": "success",
  "msg": "La propiedad ha sido creada exitosamente.",
  "propiedad_id": 7786,
  "warnings": []
}

¿Qué contiene la sección "warnings"?
Si se incluyen fotos o videos y el almacenamiento en la nube o procesamiento de marcas de agua tiene algún inconveniente no letal (por ejemplo, formato no soportado o redimensión fallida de una imagen en particular), el inmueble se creará con éxito, pero se devolverán advertencias en esta sección para que puedas corregir los archivos de forma manual. Esto no interrumpe el registro del inmueble.

4. Seguridad y Posibles Errores

El sistema realiza validaciones de autenticación, permisos (scopes) y estructura de datos. Si alguna falla, devolverá un error con su respectivo código HTTP y un mensaje descriptivo:

Operación Atómica y de Transacción Segura
nuby implementa transacciones anidadas en sus modelos de negocio. Si el endpoint responde con un código 422 (o un fallo 500 del servidor), toda la creación física del inmueble es cancelada de forma automática (ROLLBACK). No tendrás propiedades huérfanas sin propietario ni registros incompletos en las tablas del sistema.

5. Ejemplos de integración

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

{
  "Propiedad": {
    "txtTitulo": "Penthouse Duplex El Poblado con Terraza",
    "tipo_id": 15,
    "propiedad_tipo": "arriendo",
    "municipio_id": 1,
    "direccion": "Carrera 35 # 10B - 120, Apartamento 1201",
    "estrato": 6,
    "barrio_id": 5,
    "valor_arriendo": 4800000,
    "valor_administracion": 650000,
    "urbanizacion": "Torres de San Lucas",
    "observaciones": "Espectacular penthouse con vista de 360 grados, tina de hidromasajes en terraza principal, 3 alcobas cada una con baño.",
    "area": 185.4,
    "llaves_en": "oficina",
    "paga_cuota_sost": "propietario"
  },
  "Propietarios": [
    1247
  ],
  "Caracteristicas": {
    "1": "3",
    "2": "4",
    "15": "2"
  },
  "Coordenadas": "6.205210,-75.561240"
}

{
  "Propiedad": {
    "txtTitulo": "Casa de Campo en Llanogrande",
    "tipo_id": 10,
    "propiedad_tipo": "venta",
    "municipio_id": 2,
    "direccion": "Vía Llanogrande Kilómetro 4, Parcelación La Sofía",
    "estrato": 5,
    "valor_venta": 1250000000,
    "valor_administracion": 300000,
    "observaciones": "Hermosa casa de un solo nivel, amplias zonas verdes, deck con zona BBQ, acabados campestres modernos.",
    "area": 320.0,
    "paga_cuota_sost": "propietario"
  },
  "Propietarios": [
    {
      "persona": 1,
      "documento": "1024567890",
      "tipo_doc_id": 1,
      "nombre1": "Alejandro",
      "apellido1": "Restrepo",
      "direccion1": "Transversal 39B # 4G - 85",
      "municipio_id": 1,
      "email": "alejandro.restrepo@email.com",
      "telefono": "3104567890",
      "tipo_persona_id": 1,
      "regimen_id": 2,
      "resp_fiscal_id": 11
    }
  ],
  "Caracteristicas": {
    "1": "4",
    "2": "5",
    "8": "Sí"
  },
  "Videos": [
    {
      "link": "https://www.youtube.com/watch?v=abc123xyz",
      "descripcion": "Video aéreo con Dron de la parcelación"
    }
  ],
  "Fotos": [
    {
      "imagen": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "principal": true,
      "descripcion": "Fachada principal de la casa",
      "posicion": 1
    }
  ]
}

# Define tu token y tu instancia
TOKEN="TU_TOKEN_AQUI"
INSTANCIA="tu-inmobiliaria.nuby.app"

# Prepara el cuerpo de la petición en un archivo (ej: payload.json)
# o directamente en el comando.
PAYLOAD='{
  "Propiedad": {
    "txtTitulo": "Apartamento para prueba cURL",
    "tipo_id": 15,
    "propiedad_tipo": "arriendo",
    "municipio_id": 1,
    "direccion": "Calle Falsa 123 via cURL",
    "estrato": 4
  },
  "Propietarios": [1]
}'

curl -X POST "https://${INSTANCIA}/service/v2/public/properties" 
-H "Content-Type: application/json" 
-H "Authorization: Bearer ${TOKEN}" 
-d "${PAYLOAD}"

<?php

$instancia = 'tu-inmobiliaria.nuby.app';
$token = 'TU_TOKEN_AQUI';

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

$payload = [
    'Propiedad' => [
        'txtTitulo' => 'Propiedad creada desde PHP',
        'tipo_id' => 15,
        'propiedad_tipo' => 'venta',
        'municipio_id' => 1,
        'direccion' => 'Avenida Siempreviva 742, PHP',
        'estrato' => 5,
        'valor_venta' => 320000000
    ],
    'Propietarios' => [1] // ID de un propietario existente
];

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

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

curl_close($ch);

echo "Código de estado HTTP: {$http_code}
";
echo "Respuesta del servidor:
";
print_r($response);

?>

import requests
import json

instancia = 'tu-inmobiliaria.nuby.app'
token = 'TU_TOKEN_AQUI'
url = f"https://{instancia}/service/v2/public/properties"

payload = {
    "Propiedad": {
        "txtTitulo": "Propiedad Creada desde Python",
        "tipo_id": 10,
        "propiedad_tipo": "venta",
        "municipio_id": 1,
        "direccion": "Calle de Python, 101",
        "estrato": 4,
        "valor_venta": 280000000
    },
    "Propietarios": [1] # ID de un propietario existente
}

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

try:
    response = requests.post(url, headers=headers, data=json.dumps(payload))
    
    print(f"Código de estado HTTP: {response.status_code}")
    print("Respuesta del servidor:")
    print(response.json())

except requests.exceptions.RequestException as e:
    print(f"Ocurrió un error en la petición: {e}")

const instancia = 'tu-inmobiliaria.nuby.app';
const token = 'TU_TOKEN_AQUI';
const url = `https://${instancia}/service/v2/public/properties`;

const payload = {
    "Propiedad": {
        "txtTitulo": "Propiedad Creada desde JavaScript",
        "tipo_id": 20,
        "propiedad_tipo": "arriendo",
        "municipio_id": 1,
        "direccion": "Avenida JavaScript, Lote 5",
        "estrato": 5,
        "valor_arriendo": 1800000
    },
    "Propietarios": [1] // ID de un propietario existente
};

async function crearPropiedad() {
    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${token}`
            },
            body: JSON.stringify(payload)
        });

        const data = await response.json();

        console.log(`Código de estado HTTP: ${response.status}`);
        console.log('Respuesta del servidor:');
        console.log(data);

    } catch (error) {
        console.error('Error en la petición:', error);
    }
}

crearPropiedad();

let
    instancia = "tu-inmobiliaria.nuby.app",
    token = "TU_TOKEN_AQUI",
    url = "https://" & instancia & "/service/v2/public/properties",

    payload = [
        Propiedad = [
            txtTitulo = "Propiedad desde Power Query",
            tipo_id = 15,
            propiedad_tipo = "venta",
            municipio_id = 1,
            direccion = "Calle Power BI, 4.0",
            estrato = 3,
            valor_venta = 150000000
        ],
        Propietarios = {1} // ID de un propietario existente
    ],

    jsonPayload = Json.FromValue(payload),

    response = Web.Contents(url, [
        Headers = [
            #"Content-Type" = "application/json",
            #"Authorization" = "Bearer " & token
        ],
        Content = jsonPayload
    ]),
    
    jsonResponse = Json.Document(response)
in
    jsonResponse