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 dostres 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 A2: Búsqueda por documento

Si el propietario ya existe pero no conoces su ID, envía el par tipo_doc_id + documento. El sistema lo buscará, y si existe pero no tiene la clase de propietario, se la agregará automáticamente:

"Propietarios": [{"tipo_doc_id": 2, "documento": "11666898"}]

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:comercial. Campos obligatorios: tipo_doc_id, documento, nombre1, direccion1 y municipio_id:

Coherencia documento ↔ persona
El sistema valida que el tipo de documento sea coherente con la naturaleza del tercero (semántica canónica 0/1):
- Persona Natural (persona = 1) no puede registrarse con un tipo de documento NIT/NOP → responde 422.
- Persona Jurídica (persona = 0) debe registrarse con un tipo de documento NIT/NOP → si se envía con cédula u otro documento, responde 422.

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
    "31": "si", // ID 31 (Red de gas) = si (Obligatoria)
    "63": "1"   // ID 63 (Garaje) = 1 (Checkbox de Garaje activo)
}

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.
Nota: En una configuración estándar, el apartamento (1247) y la casa (1249) exigen de forma obligatoria las características de: N° de Habitaciones (ID 1), N° de Baños (ID 2) y Red de gas (ID 31).

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).

Resoluciones automáticas: por cada foto enviada, el sistema genera automáticamente las resoluciones HD, grande, mediana y pequeña, aplicando optimizaciones (redimensionamiento, corrección de orientación por EXIF y marca de agua corporativa). Todas las resoluciones hijas heredan la posición de su foto padre.

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": []
}

Respuesta Exitosa con Advertencias (201 Created, type: warning)

Se genera cuando la propiedad se creó exitosamente pero algún dato adicional no pudo guardarse o se normalizó (no es bloqueante):

{
  "error": false,
  "type": "warning",
  "msg": "La propiedad ha sido creada exitosamente. Sin embargo, algunos datos adicionales no pudieron guardarse.",
  "propiedad_id": 7787,
  "warnings": [
    "Propietarios: Propietario #0: el tipo de tercero enviado (3) fue ignorado y reemplazado por la clase de propietario 6.",
    "Propietarios: Propietario #0: el tercero no tiene correo electrónico, por lo que no podrá generar facturación electrónica ni acceder al área de clientes.",
    "Fotos: Foto #1: la posición 1 ya está ocupada en la propiedad; se asignó la posición 3.",
    "Fotos: Foto #0: No se pudo obtener el contenido de la imagen"
  ]
}

¿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. El propietario sin correo electrónico también genera una advertencia informativa.

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": 1247,
    "propiedad_tipo": "arriendo",
    "municipio_id": 1,
    "direccion": "Carrera 35 # 10B - 120, Apartamento 1201",
    "estrato": 1260,
    "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.",
    "propiedad_area": 185.4,
    "llaves_en": "oficina",
    "paga_cuota_sost": "propietario",
    "fecha_consignacion": "2026-09-29",
    "agrupamiento": "edificio",
    "estado": 1,
    "destacado": 0
  },
  "Propietarios": [
    12471528
  ],
  "Caracteristicas": {
    "1": "3",
    // Alcobas
    "2": "4",   // Baños
    "31": "si",
    // Red de gas (Obligatoria)
    "63": "1"   // Garaje (Checkbox de Garaje - ID 63 en nuby)
  },
  "Coordenadas": "6.205210,-75.561240"
}

{
  "Propiedad": {
    "txtTitulo": "Casa de Campo en Llanogrande",
    "tipo_id": 1249,
    "propiedad_tipo": "venta",
    "municipio_id": 2,
    "direccion": "Vía Llanogrande Kilómetro 4, Parcelación La Sofía",
    "estrato": 1259,
    "valor_venta": 1250000000,
    "valor_administracion": 300000,
    "observaciones": "Hermosa casa de un solo nivel, amplias zonas verdes, deck con zona BBQ, acabados campestres modernos.",
    "propiedad_area": 320.0,
    "paga_cuota_sost": "propietario",
    "llaves_en": "porteria"
  },
  "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"telefono1": "3104567890",
      "tipo_persona_id": 1,
      "regimen_id": 2,
      "resp_fiscal_id": 11
    }
  ],
  "Caracteristicas": {
    "1": "4",
    "2": "5",
    "31": "si",
    // Red de gas (Obligatoria)
    "63": "1",  // Garaje (Checkbox de Garaje - ID 63 en nuby)
    "8": "Sí"
  },
  "Videos": [
    {
      "video_url": "https://www.youtube.com/watch?v=abc123xyz",
      "video_tipo": "youtube",
      "video_descripcion": "Video aéreo con Dron de la parcelación"
    }
  ],
  "Fotos": [
    {
      "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
      "nombre": "foto_fachada_casa_campo.jpg",
      "descripcion": "Fachada principal",
      "posicion": 1
    },
    {
      "url": "https://cdn.example.com/fotos/sala.jpg",
      "nombre": "sala.jpg",
      "descripcion": "Sala comedor",
      "posicion": 2
    }
  ]
}

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

# Prepara el cuerpo de la petición utilizando estrictamente los nombres de campos físicos
PAYLOAD='{
  "Propiedad": {
    "txtTitulo": "Apartamento para prueba cURL",
    "tipo_id": 1247,
    "propiedad_tipo": "arriendo",
    "municipio_id": 127,
    "direccion": "Calle Falsa 123 via cURL",
    "estrato": 1258,
    "propiedad_area": 97
  },
  "Propietarios": [1],
  "Caracteristicas": {
    "1": "3",
    "2": "3",
    "31": "si",
    "63": "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' => 1247,
        'propiedad_tipo' => 'venta',
        'municipio_id' => 127,
        'direccion' => 'Avenida Siempreviva 742, PHP',
        'estrato' => 1258,
        'propiedad_area' => 97 // Nombre exacto de la columna física
    ],
    'Propietarios' => [1], // ID de un propietario existente
    'Caracteristicas' => [
        '1' => '3',   // Habitaciones
        '2' => '3',   // Baños
        '31' => 'si', // Red de gas (Obligatoria)
        '63' => '1'   // Garaje (Checkbox de Garaje - ID 63 en nuby)
    ]
];

$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}\n";
echo "Respuesta del servidor:\n";
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": 1247,
        "propiedad_tipo": "venta",
        "municipio_id": 127,
        "direccion": "Calle de Python, 101",
        "estrato": 1258,
        "propiedad_area": 97
    },
    "Propietarios": [1], # ID de un propietario existente
    "Caracteristicas": {
        "1": "3",
        "2": "3",
        "31": "si",
        "63": "1"
    }
}

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": 1247,
        "propiedad_tipo": "arriendo",
        "municipio_id": 127,
        "direccion": "Avenida JavaScript, Lote 5",
        "estrato": 1258,
        "propiedad_area": 97
    },
    "Propietarios": [1], // ID de un propietario existente
    "Caracteristicas": {
        "1": "3",
        "2": "3",
        "31": "si",
        "63": "1"
    }
};

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 = 1247,
            propiedad_tipo = "venta",
            municipio_id = 127,
            direccion = "Calle Power BI, 4.0",
            estrato = 1258,
            propiedad_area = 97
        ],
        Propietarios = {1}, // ID de un propietario existente
        Caracteristicas = [
            #"1" = "3",
            #"2" = "3",
            #"31" = "si",
            #"63" = "1"
        ]
    ],

    jsonPayload = Json.FromValue(payload),

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