API nuby V2

• Autenticación
• Login
• Maestras
• Propiedades / Listar Estados
• Propiedades / Listar Clases de Inmueble
• Propiedades / Listar Tipos de Servicios
• Propiedades / Listar Características
• Propiedades / Listar Características por Clase de Inmueble
• Propiedades
• Listar Propiedades
• Buscar Propiedad por Código
• Actualizar Estado de la Propiedad
• Crear Propiedad
• Asesores
• Listar Asesores
• Buscar Asesor por Documento
• Facturas
• Listar Facturas
• Registrar Pago de Factura
• Listar Formas de Pago
• Listar Resoluciones
• Contabilidad
• Reporte Auxiliar General
• Contratos
• Listar Contratos

Autenticación

Login

Antes de que tus sistemas puedan comunicarse con nuestra API, necesitan identificarse. Este servicio es como la recepción de nuestro edificio digital: aquí entregas tus credenciales y, a cambio, recibes un "pase de invitado" temporal (llamado Token). Necesitarás presentar este pase para que el sistema te permita acceder a cualquier otra sección (como contratos, facturas o propiedades).

¿Aún no tienes tus credenciales de acceso?
Para usar este servicio, primero necesitas un usuario y contraseña especiales para tu aplicación. Descubre cómo crear un nuevo cliente OAuth2 en nuby para consumo de la API paso a paso aquí.

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.

POST https://{{instancia}}/service/v2/public/auth/login

¿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?)

Tu sistema debe enviarnos un paquete de datos en formato JSON indicando que el contenido es application/json. El cuerpo de tu petición debe verse así:

{
    "username": "TU_CLIENT_ID",
    "password": "TU_SECRET_KEY"
}

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

Si tus credenciales son correctas, el sistema te dará la bienvenida entregándote tu pase de acceso (Token). La respuesta se verá similar a esta:

{
  "message": null,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "expiration": 1690540790
}

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401 Unauthorized. Cuando esto ocurra, tu sistema simplemente debe volver a consumir este servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

5. Ejemplos de integración

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

curl -X POST "https://{{instancia}}/service/v2/public/auth/login" \
-H "Content-Type: application/json" \
-d '{
  "username": "TU_CLIENT_ID", 
  "password": "TU_SECRET_KEY"
}'

<?php

$instance = 'tu_instancia'; // Reemplaza con tu instancia real
$username = 'TU_CLIENT_ID'; // Reemplaza con el ID de cliente proporcionado
$password = 'TU_SECRET_KEY'; // Reemplaza con la clave secreta proporcionada

$url = "https://{$instance}/service/v2/public/auth/login";

$data = json_encode([
    'username' => $username,
    'password' => $password
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Content-Length: ' . strlen($data)
]);

$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";
    $responseData = json_decode($response, true);
    
    if (isset($responseData['token'])) {
        echo "¡Éxito! Tu Token de Autenticación es: " . $responseData['token'] . "\n";
    } else {
        echo "Autenticación fallida.\n";
    }
}
curl_close($ch);

?>

import requests

# 1. Configura tus datos de acceso
instancia = 'mi-inmobiliaria.nuby.app' # Reemplaza con tu dirección web completa
username = 'TU_CLIENT_ID' # Reemplaza con el ID de cliente proporcionado
password = 'TU_SECRET_KEY' # Reemplaza con la clave secreta proporcionada

# 2. Prepara la dirección y los datos a enviar
url = f"https://{instancia}/service/v2/public/auth/login"

headers = {
    "Content-Type": "application/json"
}

payload = {
    "username": username,
    "password": password
}

# 3. Envía la petición a la plataforma y procesa la respuesta
try:
    # Enviamos la petición POST (la librería convierte automáticamente el payload a JSON)
    response = requests.post(url, json=payload, headers=headers)
    
    print(f"Código de estado HTTP: {response.status_code}")
    
    # Si la petición es exitosa (código 200 OK)
    if response.status_code == 200:
        data = response.json()
        token = data.get("token")
        print(f"¡Éxito! Tu Token de Autenticación es: {token}")
    else:
        print("Autenticación fallida.")
        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 username = 'TU_CLIENT_ID'; // Reemplaza con el ID de cliente proporcionado
const password = 'TU_SECRET_KEY'; // Reemplaza con la clave secreta proporcionada

// 2. Prepara la dirección y los datos a enviar
const url = `https://${instancia}/service/v2/public/auth/login`;

const data = {
    username: username,
    password: password
};

// 3. Función para enviar la petición a la plataforma
async function realizarLogin() {
    try {
        // Configuramos y enviamos la petición POST
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify(data) // Convertimos los datos a formato JSON
        });
        
        console.log(`Código de estado HTTP: ${response.status}`);
        
        // Si la petición es exitosa (códigos 200-299)
        if (response.ok) {
            const responseData = await response.json();
            console.log(`¡Éxito! Tu Token de Autenticación es: ${responseData.token}`);
        } else {
            console.log("Autenticación fallida.");
            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
realizarLogin();

let
    // 1. Configura tus datos de acceso
    instancia = "mi-inmobiliaria.nuby.app", // Reemplaza con tu dirección web completa
    username = "TU_CLIENT_ID", // Reemplaza con el ID de cliente proporcionado
    password = "TU_SECRET_KEY", // Reemplaza con la clave secreta proporcionada

    // 2. Prepara la dirección y el cuerpo de la petición (en formato JSON)
    url = "https://" & instancia & "/service/v2/public/auth/login",
    
    body = Json.FromValue([
        username = username,
        password = password
    ]),

    // 3. Envía la petición POST a la plataforma
    response = Web.Contents(url, [
        Headers = [#"Content-Type"="application/json"],
        Content = body
    ]),

    // 4. Decodifica la respuesta JSON y extrae el token
    jsonResponse = Json.Document(response),
    token = jsonResponse[token]
in
    token

Maestras

Propiedades / Listar Estados

Permite obtener la lista completa de estados posibles que puede tener una propiedad en el sistema. Cada elemento de la respuesta contiene el identificador numérico del estado y su descripción en texto. Este servicio es útil para poblar selectores o filtros de estado en tus integraciones.

¿Para qué sirve este servicio?
Úsalo para conocer los valores válidos del campo estado al momento de filtrar, crear o actualizar propiedades a través de la API. Así te aseguras de enviar siempre un valor reconocido por 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.

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

¿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 no requiere cuerpo en la petición. Solo necesitas enviar los encabezados correctos:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

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

Si tu Token es válido, el sistema te devolverá una lista con todos los estados posibles de una propiedad. La respuesta se verá así:

[
    {
        "id": 1,
        "estado": "Activa"
    },
    {
        "id": 0,
        "estado": "Arrendada"
    },
    {
        "id": 2,
        "estado": "Inactiva"
    },
    {
        "id": 3,
        "estado": "Vendida"
    }
]

Tabla con la descripción de cada campo del JSON:

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Otros posibles errores:

5. Ejemplos de integración

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

curl -X GET "https://{{instancia}}/service/v2/public/masters/properties/states" \
-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 de Login

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

$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) {
        $estados = json_decode($response, true);
        echo "Estados de propiedades:\n";
        foreach ($estados as $estado) {
            echo "  ID: {$estado['id']} - {$estado['estado']}\n";
        }
    } else {
        echo "Error al consultar los estados.\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 de Login

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

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:
        estados = response.json()
        print("Estados de propiedades:")
        for estado in estados:
            print(f"  ID: {estado['id']} - {estado['estado']}")
    else:
        print("Error al consultar los estados.")
        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 de Login

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

// 3. Función para consultar los estados de propiedades
async function consultarEstados() {
    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 estados = await response.json();
            console.log('Estados de propiedades:');
            estados.forEach(estado => {
                console.log(`  ID: ${estado.id} - ${estado.estado}`);
            });
        } else {
            console.log('Error al consultar los estados.');
            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
consultarEstados();

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 de Login

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

    // 3. Envía la petición GET con el token de autenticación
    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", {"id", "estado"}, {"ID", "Estado"})
in
    expandido

Propiedades / Listar Clases de Inmueble

Permite obtener la lista completa de clases de inmueble disponibles en el sistema. Cada elemento de la respuesta contiene el identificador único de la clase y su nombre descriptivo. Este servicio es útil para poblar selectores de tipo de inmueble en tus integraciones.

¿Para qué sirve este servicio?
Úsalo para conocer los valores válidos del campo clase de inmueble al momento de filtrar o registrar propiedades a través de la API. Así te aseguras de enviar siempre un valor reconocido por el sistema. Las clases de inmueble disponibles dependen de la configuración de cada instancia.

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/masters/properties/property-classes

¿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 no requiere cuerpo en la petición. Solo necesitas enviar los encabezados correctos:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

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

Si tu Token es válido, el sistema te devolverá una lista con todas las clases de inmueble configuradas en tu instancia. La respuesta se verá similar a esta:

[
    {
        "id": "1367",
        "clase": "Amoblados"
    },
    {
        "id": "1253",
        "clase": "Apartaestudio"
    },
    {
        "id": "1247",
        "clase": "Apartamento"
    },
    {
        "id": "1248",
        "clase": "Bodega"
    },
    {
        "id": "1249",
        "clase": "Casa"
    }
]

Nota: Los valores de id y la cantidad de clases disponibles pueden variar entre instancias, ya que dependen de la configuración particular de cada inmobiliaria. La lista se devuelve ordenada alfabéticamente por el nombre de la clase.

Tabla con la descripción de cada campo del JSON:

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Otros posibles errores:

5. Ejemplos de integración

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

curl -X GET "https://{{instancia}}/service/v2/public/masters/properties/property-classes" \
-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 de Login

$url = "https://{$instance}/service/v2/public/masters/properties/property-classes";

$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) {
        $clases = json_decode($response, true);
        echo "Clases de inmueble:\n";
        foreach ($clases as $clase) {
            echo "  ID: {$clase['id']} - {$clase['clase']}\n";
        }
    } else {
        echo "Error al consultar las clases de inmueble.\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 de Login

# 2. Prepara la dirección y los encabezados
url = f"https://{instancia}/service/v2/public/masters/properties/property-classes"

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:
        clases = response.json()
        print("Clases de inmueble:")
        for clase in clases:
            print(f"  ID: {clase['id']} - {clase['clase']}")
    else:
        print("Error al consultar las clases de inmueble.")
        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 de Login

// 2. Prepara la dirección
const url = `https://${instancia}/service/v2/public/masters/properties/property-classes`;

// 3. Función para consultar las clases de inmueble
async function consultarClasesDeInmueble() {
    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 clases = await response.json();
            console.log('Clases de inmueble:');
            clases.forEach(clase => {
                console.log(`  ID: ${clase.id} - ${clase.clase}`);
            });
        } else {
            console.log('Error al consultar las clases de inmueble.');
            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
consultarClasesDeInmueble();

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 de Login

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

    // 3. Envía la petición GET con el token de autenticación
    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", {"id", "clase"}, {"ID", "Clase"})
in
    expandido

Propiedades / Listar Tipos de Servicios

Permite obtener la lista completa de tipos de servicio que puede tener una propiedad en el sistema. Cada elemento de la respuesta contiene el identificador del tipo de servicio y su nombre descriptivo. Este servicio es útil para poblar selectores o filtros de tipo de servicio en tus integraciones.

¿Para qué sirve este servicio?
Úsalo para conocer los valores válidos del campo de tipo de servicio al momento de filtrar o registrar propiedades a través de la API. Así te aseguras de enviar siempre un valor reconocido por el sistema. Los nombres descriptivos pueden variar ligeramente entre instancias según la configuración de cada inmobiliaria, pero los identificadores (id) son siempre los mismos.

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/masters/properties/service-types

¿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 no requiere cuerpo en la petición. Solo necesitas enviar los encabezados correctos:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

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

Si tu Token es válido, el sistema te devolverá una lista con los tres tipos de servicio disponibles para propiedades. La respuesta se verá similar a esta:

[
    {
        "id": "arriendo",
        "servicio": "Arriendo"
    },
    {
        "id": "venta",
        "servicio": "Venta"
    },
    {
        "id": "venta y arriendo",
        "servicio": "Venta y Arriendo"
    }
]

Nota: El campo id es de tipo texto (string) y sus valores son fijos: "arriendo", "venta" y "venta y arriendo". El campo servicio muestra el nombre descriptivo, que puede variar ligeramente entre instancias según la configuración de cada inmobiliaria.

Tabla con la descripción de cada campo del JSON:

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Otros posibles errores:

5. Ejemplos de integración

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

curl -X GET "https://{{instancia}}/service/v2/public/masters/properties/service-types" \
-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 de Login

$url = "https://{$instance}/service/v2/public/masters/properties/service-types";

$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) {
        $servicios = json_decode($response, true);
        echo "Tipos de servicio:\n";
        foreach ($servicios as $servicio) {
            echo "  ID: {$servicio['id']} - {$servicio['servicio']}\n";
        }
    } else {
        echo "Error al consultar los tipos de servicio.\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 de Login

# 2. Prepara la dirección y los encabezados
url = f"https://{instancia}/service/v2/public/masters/properties/service-types"

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:
        servicios = response.json()
        print("Tipos de servicio:")
        for servicio in servicios:
            print(f"  ID: {servicio['id']} - {servicio['servicio']}")
    else:
        print("Error al consultar los tipos de servicio.")
        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 de Login

// 2. Prepara la dirección
const url = `https://${instancia}/service/v2/public/masters/properties/service-types`;

// 3. Función para consultar los tipos de servicio
async function consultarTiposDeServicio() {
    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 servicios = await response.json();
            console.log('Tipos de servicio:');
            servicios.forEach(servicio => {
                console.log(`  ID: ${servicio.id} - ${servicio.servicio}`);
            });
        } else {
            console.log('Error al consultar los tipos de servicio.');
            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
consultarTiposDeServicio();

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 de Login

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

    // 3. Envía la petición GET con el token de autenticación
    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", {"id", "servicio"}, {"ID", "Servicio"})
in
    expandido

Propiedades / Listar Características

Permite obtener la lista completa de características que pueden tener las propiedades en el sistema. Cada elemento de la respuesta contiene la información detallada de una característica, incluyendo su tipo de campo, opciones disponibles y la clase de inmueble a la que pertenece. Este servicio es útil para construir formularios dinámicos de propiedades o para conocer qué datos se pueden registrar en cada tipo de inmueble.

¿Para qué sirve este servicio?
Úsalo para obtener el catálogo de características configuradas en la plataforma. Cada característica está vinculada a una clase de inmueble específica (Apartamento, Casa, Bodega, etc.) y tiene un tipo de campo que indica cómo debe capturarse la información (numérico, checkbox, lista desplegable, etc.). Si necesitas consultar solo las características de una clase de inmueble en particular, utiliza el endpoint de Listar Características por Clase de Inmueble.

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/masters/properties/features

¿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 no requiere cuerpo en la petición. Solo necesitas enviar los encabezados correctos:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

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

Si tu Token es válido, el sistema te devolverá una lista con todas las características configuradas para las propiedades. La respuesta se verá similar a esta:

[
    {
        "id": "1",
        "descripcion": "Nº De Habitaciones",
        "tipo_campo": "numeric",
        "opciones_valores": null,
        "opciones_descripciones": null,
        "orden": "1",
        "grupo": "Características del inmueble",
        "clase_inmueble_id": "1367",
        "clase_inmueble": "Amoblados"
    },
    {
        "id": "2",
        "descripcion": "Nº De Baños",
        "tipo_campo": "numeric",
        "opciones_valores": null,
        "opciones_descripciones": null,
        "orden": "2",
        "grupo": "Características del inmueble",
        "clase_inmueble_id": "1367",
        "clase_inmueble": "Amoblados"
    },
    {
        "id": "54",
        "descripcion": "Oficina",
        "tipo_campo": "checkbox",
        "opciones_valores": "",
        "opciones_descripciones": "",
        "orden": "3",
        "grupo": "Características del Inmueble",
        "clase_inmueble_id": "1248",
        "clase_inmueble": "Bodega"
    },
    {
        "id": "13",
        "descripcion": "Baño Auxiliar",
        "tipo_campo": "checkbox",
        "opciones_valores": null,
        "opciones_descripciones": null,
        "orden": "4",
        "grupo": "Características del Inmueble",
        "clase_inmueble_id": "1249",
        "clase_inmueble": "Casa"
    },
    {
        "id": "38",
        "descripcion": "Parqueadero",
        "tipo_campo": "select",
        "opciones_valores": "propio,visitantes",
        "opciones_descripciones": "Propio,Visitantes",
        "orden": "12",
        "grupo": "Características del Inmueble",
        "clase_inmueble_id": "1249",
        "clase_inmueble": "Casa"
    }
]

Nota: Las características disponibles, sus grupos y las clases de inmueble asociadas dependen de la configuración de cada instancia. La lista se devuelve ordenada por grupo, luego por orden dentro del grupo, y finalmente por descripción alfabéticamente.

Tabla con la descripción de cada campo del JSON:

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Otros posibles errores:

5. Endpoint relacionado: Filtrar por Clase de Inmueble

Si necesitas obtener únicamente las características de una clase de inmueble específica, puedes usar el siguiente endpoint en lugar de filtrar la respuesta completa:

GET https://{{instancia}}/service/v2/public/masters/properties/features/property-class/{id}

Donde {id} es el identificador numérico de la clase de inmueble (obtenido del servicio Listar Clases de Inmueble). La respuesta tiene exactamente la misma estructura que este endpoint, pero filtrada a la clase indicada.

Si el parámetro {id} está vacío o no es numérico, el sistema devolverá un error 400:

{
    "error": "El ID de la clase del inmueble no puede estar vacío y debe ser de tipo numérico"
}

6. Ejemplos de integración

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

# Listar todas las características
curl -X GET "https://{{instancia}}/service/v2/public/masters/properties/features" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

# Listar características de una clase de inmueble específica (ej. ID 1249 = Casa)
curl -X GET "https://{{instancia}}/service/v2/public/masters/properties/features/property-class/1249" \
-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 de Login

// Para todas las características:
$url = "https://{$instance}/service/v2/public/masters/properties/features";

// Para filtrar por clase de inmueble (descomentar y reemplazar el ID):
// $claseInmuebleId = 1249; // Ejemplo: Casa
// $url = "https://{$instance}/service/v2/public/masters/properties/features/property-class/{$claseInmuebleId}";

$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) {
        $caracteristicas = json_decode($response, true);
        echo "Características de propiedades:\n";
        foreach ($caracteristicas as $car) {
            echo "  [{$car['clase_inmueble']}] {$car['descripcion']} (tipo: {$car['tipo_campo']})\n";
        }
    } else {
        echo "Error al consultar las características.\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 de Login

# 2. Prepara la dirección y los encabezados
# Para todas las características:
url = f"https://{instancia}/service/v2/public/masters/properties/features"

# Para filtrar por clase de inmueble (descomentar y reemplazar el ID):
# clase_inmueble_id = 1249  # Ejemplo: Casa
# url = f"https://{instancia}/service/v2/public/masters/properties/features/property-class/{clase_inmueble_id}"

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:
        caracteristicas = response.json()
        print("Características de propiedades:")
        for car in caracteristicas:
            print(f"  [{car['clase_inmueble']}] {car['descripcion']} (tipo: {car['tipo_campo']})")
    else:
        print("Error al consultar las características.")
        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 de Login

// 2. Prepara la dirección
// Para todas las características:
const url = `https://${instancia}/service/v2/public/masters/properties/features`;

// Para filtrar por clase de inmueble (descomentar y reemplazar el ID):
// const claseInmuebleId = 1249; // Ejemplo: Casa
// const url = `https://${instancia}/service/v2/public/masters/properties/features/property-class/${claseInmuebleId}`;

// 3. Función para consultar las características
async function consultarCaracteristicas() {
    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 caracteristicas = await response.json();
            console.log('Características de propiedades:');
            caracteristicas.forEach(car => {
                console.log(`  [${car.clase_inmueble}] ${car.descripcion} (tipo: ${car.tipo_campo})`);
            });
        } else {
            console.log('Error al consultar las características.');
            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
consultarCaracteristicas();

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 de Login

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

    // 3. Envía la petición GET con el token de autenticación
    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",
        {"id", "descripcion", "tipo_campo", "opciones_valores", "opciones_descripciones", "orden", "grupo", "clase_inmueble_id", "clase_inmueble"},
        {"ID", "Descripcion", "TipoCampo", "OpcionesValores", "OpcionesDescripciones", "Orden", "Grupo", "ClaseInmuebleID", "ClaseInmueble"})
in
    expandido

Propiedades / Listar Características por Clase de Inmueble

Permite obtener la lista de características que puede tener una propiedad, filtrada por una clase de inmueble específica. Cada elemento de la respuesta contiene la información detallada de una característica perteneciente a la clase indicada. Este servicio es ideal cuando ya conoces la clase de inmueble y solo necesitas las características aplicables a ese tipo.

¿Para qué sirve este servicio?
Úsalo cuando necesites construir un formulario dinámico para un tipo de inmueble en particular (por ejemplo, solo las características de "Casa" o de "Apartamento"). Si prefieres obtener todas las características de todas las clases de una sola vez, utiliza el endpoint de Listar Características. Para conocer los identificadores válidos de clases de inmueble, consulta el servicio de Listar Clases de Inmueble.

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 {{id}} por el identificador numérico de la clase de inmueble que deseas consultar.

GET https://{{instancia}}/service/v2/public/masters/properties/features/property-class/{{id}}

¿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 no requiere cuerpo en la petición. Solo necesitas enviar los encabezados correctos y el parámetro de ruta:

Parámetro de ruta:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

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

Si tu Token es válido y el id de la clase de inmueble es correcto, el sistema te devolverá una lista con las características asociadas a esa clase. Por ejemplo, para la clase "Casa" (id = 1249), la respuesta se verá similar a esta:

[
    {
        "id": "1",
        "descripcion": "Nº De Habitaciones",
        "tipo_campo": "numeric",
        "opciones_valores": null,
        "opciones_descripciones": null,
        "orden": "1",
        "grupo": "Características del Inmueble",
        "clase_inmueble_id": "1249",
        "clase_inmueble": "Casa"
    },
    {
        "id": "31",
        "descripcion": "Red de gas",
        "tipo_campo": "select",
        "opciones_valores": "si,no",
        "opciones_descripciones": "Si,No",
        "orden": "5",
        "grupo": "Características del Inmueble",
        "clase_inmueble_id": "1249",
        "clase_inmueble": "Casa"
    },
    {
        "id": "22",
        "descripcion": "Balcón",
        "tipo_campo": "checkbox",
        "opciones_valores": null,
        "opciones_descripciones": null,
        "orden": "10",
        "grupo": "Características del Inmueble",
        "clase_inmueble_id": "1249",
        "clase_inmueble": "Casa"
    },
    {
        "id": "38",
        "descripcion": "Parqueadero",
        "tipo_campo": "select",
        "opciones_valores": "propio,visitantes",
        "opciones_descripciones": "Propio,Visitantes",
        "orden": "12",
        "grupo": "Características del Inmueble",
        "clase_inmueble_id": "1249",
        "clase_inmueble": "Casa"
    }
]

Nota: Las características disponibles y sus grupos dependen de la configuración de cada instancia. La lista se devuelve ordenada por grupo, luego por orden dentro del grupo, y finalmente por descripción alfabéticamente. La estructura de la respuesta es idéntica a la del servicio de Listar Características, pero filtrada a la clase de inmueble indicada.

Tabla con la descripción de cada campo del JSON:

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Si envías un id vacío o no numérico, el sistema te devolverá un error de validación:

{
    "error": "El ID de la clase del inmueble no puede estar vacío y debe ser de tipo numérico"
}

Otros posibles errores:

5. Ejemplos de integración

Aquí tienes ejemplos de código listos para que tus desarrolladores los adapten a tu plataforma. En estos ejemplos se consulta la clase "Casa" con id = 1249:

curl -X GET "https://{{instancia}}/service/v2/public/masters/properties/features/property-class/1249" \
-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 de Login
$claseInmuebleId = 1249; // ID de la clase de inmueble (ej. Casa)

$url = "https://{$instance}/service/v2/public/masters/properties/features/property-class/{$claseInmuebleId}";

$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) {
        $caracteristicas = json_decode($response, true);
        echo "Características de la clase de inmueble (ID {$claseInmuebleId}):\n";
        foreach ($caracteristicas as $car) {
            echo "  {$car['descripcion']} (tipo: {$car['tipo_campo']})\n";
        }
    } else {
        echo "Error al consultar las características.\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 de Login
clase_inmueble_id = 1249 # ID de la clase de inmueble (ej. Casa)

# 2. Prepara la dirección y los encabezados
url = f"https://{instancia}/service/v2/public/masters/properties/features/property-class/{clase_inmueble_id}"

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:
        caracteristicas = response.json()
        print(f"Características de la clase de inmueble (ID {clase_inmueble_id}):")
        for car in caracteristicas:
            print(f"  {car['descripcion']} (tipo: {car['tipo_campo']})")
    else:
        print("Error al consultar las características.")
        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 de Login
const claseInmuebleId = 1249; // ID de la clase de inmueble (ej. Casa)

// 2. Prepara la dirección
const url = `https://${instancia}/service/v2/public/masters/properties/features/property-class/${claseInmuebleId}`;

// 3. Función para consultar las características por clase de inmueble
async function consultarCaracteristicasPorClase() {
    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 caracteristicas = await response.json();
            console.log(`Características de la clase de inmueble (ID ${claseInmuebleId}):`);
            caracteristicas.forEach(car => {
                console.log(`  ${car.descripcion} (tipo: ${car.tipo_campo})`);
            });
        } else {
            console.log('Error al consultar las características.');
            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
consultarCaracteristicasPorClase();

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 de Login
    claseInmuebleId = "1249", // ID de la clase de inmueble (ej. Casa)

    // 2. Prepara la dirección de la petición
    url = "https://" & instancia & "/service/v2/public/masters/properties/features/property-class/" & claseInmuebleId,

    // 3. Envía la petición GET con el token de autenticación
    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",
        {"id", "descripcion", "tipo_campo", "opciones_valores", "opciones_descripciones", "orden", "grupo", "clase_inmueble_id", "clase_inmueble"},
        {"ID", "Descripcion", "TipoCampo", "OpcionesValores", "OpcionesDescripciones", "Orden", "Grupo", "ClaseInmuebleID", "ClaseInmueble"})
in
    expandido

Propiedades

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

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

Actualizar Estado de la Propiedad

Permite actualizar el estado de una propiedad específica a partir de su código único. Este servicio es útil para cambiar el estado de un inmueble entre los estados permitidos por el sistema.

¿Para qué sirve este servicio?
Úsalo cuando necesites cambiar el estado de un inmueble desde tu sistema externo, por ejemplo: marcar una propiedad como inactiva cuando se retira del mercado, reactivarla cuando vuelve a estar disponible, o registrar que fue vendida.

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 cuyo estado deseas actualizar.

PATCH https://{{instancia}}/service/v2/public/properties/{{code}}/status

¿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?)

Debes enviar una petición PATCH con el nuevo estado en el cuerpo de la solicitud en formato JSON:

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

Parámetro de ruta:

Cuerpo de la petición (Body):

Restricción importante sobre el estado "Arrendada" (0)
Aunque el estado 0 (Arrendada) existe en el sistema, no es posible asignar este estado a través de la API. El estado "Arrendada" se gestiona internamente por el sistema cuando se registra un contrato de arrendamiento asociado al inmueble.

Estados válidos del sistema

Reglas de transición de estado

El sistema solo permite cambiar el estado de una propiedad cuando su estado actual es Activa (1) o Inactiva (2). Las transiciones posibles son:

¿Por qué no se puede modificar el estado de una propiedad "Arrendada" o "Vendida"?
Estos son estados terminales que representan transacciones completadas. El cambio de estos estados se gestiona internamente a través de los procesos de negocio del sistema (por ejemplo, al finalizar un contrato de arrendamiento o reversar una venta).

Ejemplo de petición:

PATCH https://{{instancia}}/service/v2/public/properties/137/status

{
    "status": 2
}

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

Si la actualización fue exitosa, el sistema responderá con HTTP 200 y un mensaje de confirmación:

{
    "message": "Se actualizo el estado de la propiedad correctamente"
}

4. Seguridad y Posibles Errores

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

{
    "error": "El estado(status) es requerido"
}

"JWT Token expired."

"Insufficient scope. Required: 'update', granted: '{scope_actual}'."

{
    "error": "No se encontró la propiedad"
}

{
    "error": "El estado no es válido"
}

{
    "error": "El estado actual de la propiedad no permite este tipo de modificación."
}

{
    "error": "No se pudo actualizar el estado de la propiedad"
}

5. Ejemplos de integración

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

# Cambiar estado de propiedad 137 a Inactiva (2)
curl -X PATCH "https://{{instancia}}/service/v2/public/properties/137/status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI" \
-d '{"status": 2}'

# Cambiar estado de propiedad 2045 a Vendida (3)
curl -X PATCH "https://{{instancia}}/service/v2/public/properties/2045/status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI" \
-d '{"status": 3}'

# Reactivar propiedad 890 (de Inactiva a Activa)
curl -X PATCH "https://{{instancia}}/service/v2/public/properties/890/status" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI" \
-d '{"status": 1}'

<?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
$nuevoEstado = 2; // 1 = Activa, 2 = Inactiva, 3 = Vendida

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

$body = json_encode([
    'status' => $nuevoEstado
]);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
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";

    $data = json_decode($response, true);

    if ($http_code === 200) {
        echo "Éxito: " . $data['message'] . "\n";
    } else {
        echo "Error: " . ($data['error'] ?? 'Error desconocido') . "\n";
    }
}
curl_close($ch);

?>

import requests
import json

# 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
nuevo_estado = 2 # 1 = Activa, 2 = Inactiva, 3 = Vendida

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

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

body = {
    "status": nuevo_estado
}

# 3. Envía la petición PATCH y procesa la respuesta
try:
    response = requests.patch(url, headers=headers, json=body)

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

    data = response.json()

    if response.status_code == 200:
        print(f"Éxito: {data['message']}")
    else:
        error_msg = data.get('error', 'Error desconocido')
        print(f"Error: {error_msg}")

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
const nuevoEstado = 2; // 1 = Activa, 2 = Inactiva, 3 = Vendida

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

// 3. Función para actualizar el estado
async function actualizarEstadoPropiedad() {
    try {
        const response = await fetch(url, {
            method: 'PATCH',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${token}`
            },
            body: JSON.stringify({
                status: nuevoEstado
            })
        });

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

        const data = await response.json();

        if (response.ok) {
            console.log(`Éxito: ${data.message}`);
        } else {
            console.log(`Error: ${data.error || 'Error desconocido'}`);
        }
    } catch (error) {
        console.error(`Ocurrió un error de conexión: ${error}`);
    }
}

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

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
    nuevoEstado = 2, // 1 = Activa, 2 = Inactiva, 3 = Vendida

    // 2. Prepara la dirección y el cuerpo de la petición
    url = "https://" & instancia & "/service/v2/public/properties/" & codigo & "/status",
    body = Json.FromValue([status = nuevoEstado]),

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

    // 4. Decodifica la respuesta JSON
    jsonResponse = Json.Document(response)
in
    jsonResponse

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

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

# 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

Asesores

Listar Asesores

Permite obtener la lista completa de asesores registrados en el sistema. Cada elemento de la respuesta contiene los datos básicos de contacto de cada asesor: documento de identidad, nombre completo, teléfono, correo electrónico y fotografía.

¿Para qué sirve este servicio?
Úsalo cuando necesites conocer los asesores disponibles en la inmobiliaria, por ejemplo para mostrar un directorio de agentes en tu sitio web, poblar un selector de asesores en un formulario de contacto, o sincronizar la información de los agentes con tu sistema externo.

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/agents

¿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 no requiere cuerpo en la petición ni parámetros adicionales. Solo necesitas enviar los encabezados correctos:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

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

Si tu Token es válido, el sistema te devolverá una lista con todos los asesores registrados (excluyendo usuarios internos del sistema). Los asesores se devuelven ordenados alfabéticamente por nombre. La respuesta se verá similar a esta:

[
    {
        "id": "3",
        "documento": "52498731",
        "nombre": "ANDREA MILENA CASTRO ROJAS",
        "telefono": "3104567890",
        "email": "andrea.castro@miredinmobiliaria.com",
        "path_photo": "https://mi-inmobiliaria.nuby.app/pic/usuarios/foto_andrea_castro.jpg"
    },
    {
        "id": "7",
        "documento": "80213654",
        "nombre": "CARLOS EDUARDO PINEDA VARGAS",
        "telefono": "3209876543",
        "email": "carlos.pineda@miredinmobiliaria.com",
        "path_photo": "https://mi-inmobiliaria.nuby.app/pic/usuarios/foto_carlos_pineda.jpg"
    },
    {
        "id": "12",
        "documento": "1098745231",
        "nombre": "JULIANA PATRICIA RÍOS MENDOZA",
        "telefono": "3156781234",
        "email": "juliana.rios@miredinmobiliaria.com",
        "path_photo": "https://mi-inmobiliaria.nuby.app/pic/iconos/user_photo.png"
    }
]

Descripción de cada campo:

Nota sobre la respuesta
El listado excluye automáticamente los usuarios internos del sistema (cuentas de administración y soporte). Solo se devuelven los asesores reales de la inmobiliaria. Si no hay asesores registrados, la respuesta será un arreglo vacío [].

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Otros posibles errores:

5. Ejemplos de integración

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

curl -X GET "https://{{instancia}}/service/v2/public/agents" \
-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

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

$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) {
        $asesores = json_decode($response, true);
        echo "Asesores encontrados: " . count($asesores) . "\n";
        foreach ($asesores as $asesor) {
            echo "  [{$asesor['id']}] {$asesor['nombre']} - {$asesor['email']}\n";
        }
    } else {
        echo "Error al consultar los asesores.\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 de la petición
url = f"https://{instancia}/service/v2/public/agents"

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:
        asesores = response.json()
        print(f"Asesores encontrados: {len(asesores)}")
        for asesor in asesores:
            print(f"  [{asesor['id']}] {asesor['nombre']} - {asesor['email']}")
    else:
        print("Error al consultar los asesores.")
        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 de la petición
const url = `https://${instancia}/service/v2/public/agents`;

// 3. Función para consultar los asesores
async function consultarAsesores() {
    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 asesores = await response.json();
            console.log(`Asesores encontrados: ${asesores.length}`);
            asesores.forEach(asesor => {
                console.log(`  [${asesor.id}] ${asesor.nombre} - ${asesor.email}`);
            });
        } else {
            console.log('Error al consultar los asesores.');
            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
consultarAsesores();

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
    url = "https://" & instancia & "/service/v2/public/agents",

    // 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",
        {"id", "documento", "nombre", "telefono", "email", "path_photo"},
        {"ID", "Documento", "Nombre", "Telefono", "Email", "Foto"})
in
    expandido

Buscar Asesor por Documento

Permite obtener la información de un asesor específico a partir de su número de documento de identidad. La respuesta contiene los datos básicos de contacto del asesor: documento, nombre completo, teléfono, correo electrónico y fotografía.

¿Para qué sirve este servicio?
Úsalo cuando ya conoces el número de documento del asesor y necesitas consultar su información detallada. Es ideal para mostrar la ficha de un agente en particular, verificar datos de un asesor asignado a una propiedad o sincronizar la información de un agente puntual con tu sistema externo.

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 {{document}} por el número de documento de identidad del asesor que deseas consultar.

GET https://{{instancia}}/service/v2/public/agents/{{document}}

¿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 no requiere cuerpo en la petición. Solo necesitas construir la URL con el número de documento del asesor como parte de la ruta e incluir los encabezados requeridos:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

Parámetro de ruta:

Ejemplo de petición:

GET https://mi-inmobiliaria.nuby.app/service/v2/public/agents/52498731

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

Si tu Token es válido y el documento corresponde a un asesor registrado, el sistema te devolverá un objeto JSON con la información del asesor. La respuesta se verá similar a esta:

{
    "id": "3",
    "documento": "52498731",
    "nombre": "ANDREA MILENA CASTRO ROJAS",
    "telefono": "3104567890",
    "email": "andrea.castro@miredinmobiliaria.com",
    "path_photo": "https://mi-inmobiliaria.nuby.app/pic/usuarios/foto_andrea_castro.jpg"
}

Descripción de cada campo:

Importante: asesor no encontrado
Cuando el documento no corresponde a ningún asesor registrado, el sistema no devuelve un error. En su lugar, responde con un HTTP 200 y un arreglo vacío:

[]

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

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Otros posibles errores:

5. Ejemplos de integración

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

# Consultar asesor por documento
curl -X GET "https://{{instancia}}/service/v2/public/agents/52498731" \
-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
$documento = '52498731'; // Documento del asesor a consultar

$url = "https://{$instance}/service/v2/public/agents/{$documento}";

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

        if (!empty($asesor)) {
            echo "Asesor encontrado:\n";
            echo "  ID: {$asesor['id']}\n";
            echo "  Nombre: {$asesor['nombre']}\n";
            echo "  Email: {$asesor['email']}\n";
            echo "  Teléfono: {$asesor['telefono']}\n";
        } else {
            echo "No se encontró ningún asesor con el documento {$documento}.\n";
        }
    } else {
        echo "Error al consultar el asesor.\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
documento = '52498731' # Documento del asesor a consultar

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

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:
        asesor = response.json()

        if asesor:
            print(f"Asesor encontrado:")
            print(f"  ID: {asesor['id']}")
            print(f"  Nombre: {asesor['nombre']}")
            print(f"  Email: {asesor['email']}")
            print(f"  Teléfono: {asesor['telefono']}")
        else:
            print(f"No se encontró ningún asesor con el documento {documento}.")
    else:
        print("Error al consultar el asesor.")
        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 documento = '52498731'; // Documento del asesor a consultar

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

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

            if (asesor && !Array.isArray(asesor)) {
                console.log(`Asesor encontrado:`);
                console.log(`  ID: ${asesor.id}`);
                console.log(`  Nombre: ${asesor.nombre}`);
                console.log(`  Email: ${asesor.email}`);
                console.log(`  Teléfono: ${asesor.telefono}`);
            } else {
                console.log(`No se encontró ningún asesor con el documento ${documento}.`);
            }
        } else {
            console.log('Error al consultar el asesor.');
            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
consultarAsesor();

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
    documento = "52498731", // Documento del asesor a consultar

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

    // 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

Facturas

Listar Facturas

Permite obtener la lista paginada de todas las facturas registradas en el sistema. Cada elemento incluye el número de factura, resolución, fechas, valor total, saldo pendiente, tercero facturado, estado, información DIAN y datos de auditoría.

¿Para qué sirve este servicio?
Úsalo para sincronizar la información de facturación con tu sistema externo, generar reportes de cartera, alimentar dashboards con indicadores de facturación, validar el estado de cobro de los contratos o exportar la información a Excel y Power BI.

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/invoices/list

¿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 no requiere cuerpo en la petición. Envía los encabezados requeridos y opcionalmente los parámetros de paginación en la URL:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

Parámetros de consulta (query string):

Ejemplos de petición:

GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/list
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page=2
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page_size=50
GET https://mi-inmobiliaria.nuby.app/service/v2/public/invoices/list?page=3&page_size=100

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

Si tu Token es válido, el sistema te devolverá un objeto JSON con el estado de la respuesta, el listado de facturas y la información de paginación. Los resultados están ordenados por fecha de factura descendente (más recientes primero). La respuesta se verá similar a esta:

{
    "status": 200,
    "message": null,
    "body": [
        {
            "factura_id": 15230,
            "factura_numero": 8745,
            "resolucion": "FECO - 18764000002851",
            "fecha_factura": "2025-04-01",
            "fecha_vencimiento": "2025-04-06",
            "valor_total": "2850000.00",
            "saldo": "2850000.00",
            "documento_tercero": "80213654",
            "nombre_tercero": "CARLOS EDUARDO PINEDA VARGAS",
            "estado": "Facturada",
            "estado_dian": "Aceptada",
            "estado_cliente_dian": "Recibida",
            "notas": 0,
            "creado_por": "Sandra",
            "fecha_envio_dian": "2025-04-01 08:30:15",
            "fecha_creacion": "2025-04-01 07:45:22"
        },
        {
            "factura_id": 15229,
            "factura_numero": 8744,
            "resolucion": "FECO - 18764000002851",
            "fecha_factura": "2025-04-01",
            "fecha_vencimiento": "2025-04-06",
            "valor_total": "4500000.00",
            "saldo": "0.00",
            "documento_tercero": "1098745231",
            "nombre_tercero": "JULIANA PATRICIA RÍOS MENDOZA",
            "estado": "Pagada",
            "estado_dian": "Aceptada",
            "estado_cliente_dian": "Recibida",
            "notas": 0,
            "creado_por": "Sandra",
            "fecha_envio_dian": "2025-04-01 08:31:02",
            "fecha_creacion": "2025-04-01 07:46:10"
        },
        {
            "factura_id": 15210,
            "factura_numero": 8730,
            "resolucion": "0 - 18764000002851",
            "fecha_factura": "2025-03-01",
            "fecha_vencimiento": "2025-03-06",
            "valor_total": "1200000.00",
            "saldo": "1200000.00",
            "documento_tercero": "43876123",
            "nombre_tercero": "DIANA MARCELA OSPINA VELÁSQUEZ",
            "estado": "Facturada",
            "estado_dian": null,
            "estado_cliente_dian": null,
            "notas": 1,
            "creado_por": "Administrador",
            "fecha_envio_dian": null,
            "fecha_creacion": "2025-03-01 09:12:33"
        },
        {
            "factura_id": 14850,
            "factura_numero": 8520,
            "resolucion": "FECO - 18764000002851",
            "fecha_factura": "2025-02-01",
            "fecha_vencimiento": "2025-02-06",
            "valor_total": "3950000.00",
            "saldo": "3950000.00",
            "documento_tercero": "900456789",
            "nombre_tercero": "INVERSIONES HORIZONTE S.A.S.",
            "estado": "Anulada por NC",
            "estado_dian": "Aceptada",
            "estado_cliente_dian": null,
            "notas": 1,
            "creado_por": "Sandra",
            "fecha_envio_dian": "2025-02-01 10:05:44",
            "fecha_creacion": "2025-02-01 08:20:15"
        }
    ],
    "pagination": {
        "total_records": 15230,
        "total_pages": 305,
        "current_page": 1,
        "page_size": 50,
        "current_page_records": 4,
        "has_next_page": true,
        "has_previous_page": false
    }
}

Estructura principal de la respuesta

Campos de cada factura (body)

Cada elemento dentro del arreglo body contiene las siguientes claves:

Campos de paginación (pagination)

El objeto pagination contiene las siguientes claves:

Nota sobre facturas sin resultados
Si no existen facturas registradas en el sistema, la respuesta tendrá HTTP 200 con body vacío ([]), un message informativo: "No se encontraron facturas en el sistema." y los valores de paginación en cero.

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Si alguno de los parámetros de paginación no cumple con las validaciones, el sistema devolverá un error 400. Por ejemplo:

{
    "status": 400,
    "message": "El parámetro \"page_size\" debe ser un número positivo.",
    "body": null,
    "pagination": null
}

Posibles errores:

5. Ejemplos de integración

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

# Listar facturas con paginación por defecto
curl -X GET "https://{{instancia}}/service/v2/public/invoices/list" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

# Listar facturas página 3 con 100 registros por página
curl -X GET "https://{{instancia}}/service/v2/public/invoices/list?page=3&page_size=100" \
-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 paginación
$page = 1;
$page_size = 50;

$queryParams = http_build_query([
    'page' => $page,
    'page_size' => $page_size
]);

$url = "https://{$instance}/service/v2/public/invoices/list?{$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";

    $info = json_decode($response, true);
    $body = $info['body'] ?? [];

    if ($http_code === 200 && !empty($body)) {
        $pagination = $info['pagination'];
        echo "Facturas encontradas: {$pagination['total_records']} (página {$pagination['current_page']} de {$pagination['total_pages']})\n";

        foreach ($body as $factura) {
            echo "  Factura #{$factura['factura_numero']} - {$factura['nombre_tercero']} - {$factura['estado']} - Total: \${$factura['valor_total']} - Saldo: \${$factura['saldo']}\n";
        }
    } else {
        echo "Mensaje: " . ($info['message'] ?? 'Sin resultados') . "\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/invoices/list"

params = {
    "page": 1,
    "page_size": 50
}

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:
        info = response.json()
        body = info.get('body', [])
        pagination = info.get('pagination', {})

        if body:
            print(f"Facturas: {pagination['total_records']} total (página {pagination['current_page']} de {pagination['total_pages']})")
            for factura in body:
                print(f"  #{factura['factura_numero']} - {factura['nombre_tercero']} - {factura['estado']} - Total: ${factura['valor_total']} - Saldo: ${factura['saldo']}")
        else:
            print(f"Mensaje: {info.get('message', 'Sin resultados')}")
    else:
        print("Error al consultar las facturas.")
        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,
    page_size: 50
});

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

// 3. Función para consultar las facturas
async function consultarFacturas() {
    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 info = await response.json();
            const body = info.body || [];
            const pagination = info.pagination || {};

            if (body.length > 0) {
                console.log(`Facturas: ${pagination.total_records} total (página ${pagination.current_page} de ${pagination.total_pages})`);
                body.forEach(factura => {
                    console.log(`  #${factura.factura_numero} - ${factura.nombre_tercero} - ${factura.estado} - Total: $${factura.valor_total} - Saldo: $${factura.saldo}`);
                });
            } else {
                console.log(`Mensaje: ${info.message || 'Sin resultados'}`);
            }
        } else {
            console.log('Error al consultar las facturas.');
            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
consultarFacturas();

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/invoices/list?page=1&page_size=1000",

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

    // 4. Decodifica la respuesta JSON
    jsonResponse = Json.Document(response),
    body = jsonResponse[body],

    // 5. Convierte el listado en tabla
    tabla = Table.FromList(body, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    expandido = Table.ExpandRecordColumn(tabla, "Column1",
        {"factura_id", "factura_numero", "resolucion", "fecha_factura", "fecha_vencimiento", "valor_total", "saldo", "documento_tercero", "nombre_tercero", "estado", "estado_dian", "notas", "creado_por", "fecha_creacion"},
        {"FacturaID", "Numero", "Resolucion", "FechaFactura", "FechaVencimiento", "ValorTotal", "Saldo", "DocTercero", "NombreTercero", "Estado", "EstadoDian", "Notas", "CreadoPor", "FechaCreacion"})
in
    expandido

Registrar Pago de Factura

Permite registrar el pago de una factura existente en el sistema. Si no se especifica la forma de pago, el sistema intentará determinarla automáticamente basándose en el cliente OAuth2 autenticado o utilizará la forma de pago por defecto configurada (Consignación bancaria).

Endpoint: https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/register-payment

{{instancia}}: Hace referencia a la instancia de cada inmobiliaria.

Petición

Ejemplo de petición (Body JSON)

{
    "factura_id": 366,
    "monto": 50000,
    "fecha_pago": "2026-02-05 14:30:00",
    "forma_pago_id": 1,
    "n_comprobante": "REF123456"
}

Ejemplo mínimo (solo campos requeridos):

{
    "factura_id": 366,
    "monto": 50000,
    "fecha_pago": "2026-02-05 10:00:00"
}

Respuestas

Respuesta Exitosa (200)

Cuando el pago se registra correctamente, la respuesta incluye los detalles completos del pago registrado, incluyendo los IDs de los registros generados en el sistema (pago, recibo de ingreso y documento contable) así como el estado actualizado de la factura.

{
    "success": true,
    "status": 200,
    "message": "Pago registrado exitosamente.",
    "body": {
        "factura_id": 366,
        "pago_id": 142,
        "recibo_id": 589,
        "documento_contable_id": 1023,
        "monto_pagado": 50000,
        "fecha_pago": "2026-02-05 14:30:00",
        "forma_pago_id": 1,
        "forma_pago": "Consignación bancaria",
        "n_comprobante": "REF123456",
        "saldo_anterior": 150000,
        "saldo_actual": 100000,
        "estado_factura": "Facturada",
        "gateway": null,
        "client_name": "MiAplicacion"
    }
}

Claves y Descripciones del JSON de Respuesta

Cuerpo de Respuesta Exitosa (body)

Cuando la operación es exitosa, el objeto body contiene las siguientes claves:

Respuestas de Error

Error de Validación (400)

Se retorna cuando los parámetros enviados no cumplen con las validaciones requeridas.

{
    "success": false,
    "status": 400,
    "message": "Errores de validación",
    "body": null,
    "errors": [
        "El parámetro \"factura_id\" es requerido.",
        "El parámetro \"monto\" debe ser un número positivo.",
        "El parámetro \"fecha_pago\" debe tener el formato Y-m-d H:i:s (ej: 2026-02-02 14:30:00).",
        "El parámetro \"n_comprobante\" no puede exceder 100 caracteres.",
        "El parámetro \"n_comprobante\" contiene caracteres no permitidos. Solo se aceptan letras, números, guiones, guiones bajos, puntos y espacios."
    ]
}

Factura No Encontrada (404)

Se retorna cuando no existe una factura con el ID proporcionado.

{
    "success": false,
    "status": 404,
    "message": "No se encontró la factura con el ID proporcionado.",
    "body": null
}

Error de Negocio (422)

Se retorna cuando la factura existe pero no puede recibir el pago por razones de negocio.

Factura no activa:

{
    "success": false,
    "status": 422,
    "message": "La factura no está en estado activo/pendiente de pago. Estado actual: Pagada",
    "body": null
}

Monto excede saldo:

{
    "success": false,
    "status": 422,
    "message": "El monto a pagar (100000) excede el saldo de la factura (50000).",
    "body": null
}

Forma de pago no determinada:

{
    "success": false,
    "status": 422,
    "message": "No se pudo determinar la forma de pago automáticamente. Por favor especifique el parámetro \"forma_pago_id\".",
    "body": null
}

Factura sin detalles:

{
    "success": false,
    "status": 422,
    "message": "La factura no tiene detalles asociados. No es posible registrar el pago.",
    "body": null
}

Forma de pago sin cuenta contable:

{
    "success": false,
    "status": 422,
    "message": "La forma de pago seleccionada no tiene una cuenta contable configurada. No es posible registrar el pago.",
    "body": null
}

Periodo contable no activo:

{
    "success": false,
    "status": 422,
    "message": "No existe un periodo contable activo para la fecha 2026-01-15. Verifique que el periodo esté abierto en el módulo de contabilidad.",
    "body": null
}

Error Interno (500)

Se retorna cuando ocurre un error inesperado en el servidor o cuando el proceso de registro del pago falla.

Error general:

{
    "success": false,
    "status": 500,
    "message": "Error interno del servidor al registrar el pago.",
    "body": null
}

Error al generar recibo de ingreso:

{
    "success": false,
    "status": 500,
    "message": "Error al crear el recibo de ingreso para el pago de la factura.",
    "body": null
}

Pago procesado sin confirmación de ID:

{
    "success": false,
    "status": 500,
    "message": "El pago se procesó pero no se pudo obtener el ID del registro de pago. Verifique manualmente en el sistema.",
    "body": null
}

Códigos de Respuesta HTTP

Notas Importantes

Ejemplos

curl -X POST "https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/register-payment" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN" \
  -d '{
    "factura_id": 366,
    "monto": 50000,
    "fecha_pago": "2026-02-05 10:00:00",
    "n_comprobante": "REF123456"
  }'

<?php

$instance = 'your_instance'; // Reemplace con su instancia actual
$token = 'YOUR_AUTHENTICATION_TOKEN'; // Reemplace con el token obtenido desde el servicio de login

// Datos del pago a registrar
$paymentData = [
    'factura_id' => 366,
    'monto' => 50000,
    'fecha_pago' => '2026-02-05 14:30:00',
    'forma_pago_id' => 1, // Opcional
    'n_comprobante' => 'REF123456' // Opcional
];

$url = "https://{$instance}.arrendasoft.co/service/v2/public/invoices/register-payment";

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($paymentData));
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 "HTTP Status Code: " . $http_code . "\n";
    echo "Response: " . $response . "\n";
    
    // Procesar la respuesta
    $result = json_decode($response, true);
    
    if ($result['success']) {
        echo "Pago registrado exitosamente.\n";
        echo "Factura: " . $result['body']['factura_id'] . "\n";
        echo "Pago ID: " . $result['body']['pago_id'] . "\n";
        echo "Recibo ID: " . $result['body']['recibo_id'] . "\n";
        echo "Documento Contable ID: " . $result['body']['documento_contable_id'] . "\n";
        echo "Monto pagado: " . $result['body']['monto_pagado'] . "\n";
        echo "Forma de pago: " . $result['body']['forma_pago'] . "\n";
        echo "Saldo anterior: " . $result['body']['saldo_anterior'] . "\n";
        echo "Saldo actual: " . $result['body']['saldo_actual'] . "\n";
        echo "Estado factura: " . $result['body']['estado_factura'] . "\n";
    } else {
        echo "Error: " . $result['message'] . "\n";
        if (isset($result['errors'])) {
            foreach ($result['errors'] as $error) {
                echo "- " . $error . "\n";
            }
        }
    }
}
curl_close($ch);

?>

const instance = 'your_instance'; // Reemplace con su instancia actual
const token = 'YOUR_AUTHENTICATION_TOKEN'; // Reemplace con el token obtenido

const paymentData = {
    factura_id: 366,
    monto: 50000,
    fecha_pago: '2026-02-05 14:30:00',
    n_comprobante: 'REF123456'
};

fetch(`https://${instance}.arrendasoft.co/service/v2/public/invoices/register-payment`, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(paymentData)
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('Pago registrado exitosamente');
        console.log('Factura:', data.body.factura_id);
        console.log('Pago ID:', data.body.pago_id);
        console.log('Recibo ID:', data.body.recibo_id);
        console.log('Documento Contable ID:', data.body.documento_contable_id);
        console.log('Monto pagado:', data.body.monto_pagado);
        console.log('Forma de pago:', data.body.forma_pago);
        console.log('Saldo anterior:', data.body.saldo_anterior);
        console.log('Saldo actual:', data.body.saldo_actual);
        console.log('Estado factura:', data.body.estado_factura);
    } else {
        console.error('Error:', data.message);
        if (data.errors) {
            data.errors.forEach(error => console.error('-', error));
        }
    }
})
.catch(error => console.error('Error de conexión:', error));

Listar Formas de Pago

Permite obtener las formas de pago configuradas de la inmobiliaria. Solo devuelve las formas de pago que tengan una cuenta contable (PUC) relacionada.

Endpoint: https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/payment-methods

{{instancia}}: Hace referencia a la instancia de cada inmobiliaria.

Petición

Ejemplos de peticiones

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/payment-methods

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/payment-methods?codigo_dian=42

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/payment-methods?cuenta_puc=1110

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/payment-methods?codigo_dian=42&cuenta_puc=1110

Respuesta

Lista de formas de pago configuradas con información del medio de pago DIAN y cuenta contable asociada.

{
    "success": true,
    "status": 200,
    "message": null,
    "body": [
        {
            "formaPagoId": 1,
            "nombre": "Consignación Bancolombia",
            "cuentaPuc": "11100501",
            "codigoDian": "42",
            "medioPago": "Consignación bancaria"
        },
        {
            "formaPagoId": 2,
            "nombre": "Transferencia Davivienda",
            "cuentaPuc": "11100502",
            "codigoDian": "31",
            "medioPago": "Transferencia débito bancaria"
        },
        {
            "formaPagoId": 3,
            "nombre": "Pago con tarjeta de crédito",
            "cuentaPuc": "11100503",
            "codigoDian": "48",
            "medioPago": "Tarjeta de crédito"
        }
    ],
    "filters_applied": null
}

Claves y Descripciones del JSON de Respuesta

Esta tabla enumera las claves presentes en el JSON principal de la respuesta y proporciona una breve descripción de cada una.

Cuerpo

Cada elemento dentro de la lista body tiene las siguientes claves:

Filtros Aplicados

El objeto filters_applied contiene los filtros que fueron utilizados en la consulta. Solo se incluye en la respuesta cuando se aplican filtros. Las posibles claves son:

Respuesta con Filtros Aplicados

{
    "success": true,
    "status": 200,
    "message": null,
    "body": [
        {
            "formaPagoId": 1,
            "nombre": "Consignación Bancolombia",
            "cuentaPuc": "11100501",
            "codigoDian": "42",
            "medioPago": "Consignación bancaria"
        }
    ],
    "filters_applied": {
        "codigo_dian": "42"
    }
}

Respuesta Sin Resultados

{
    "success": true,
    "status": 200,
    "message": "No se encontraron formas de pago con los criterios especificados.",
    "body": [],
    "filters_applied": {
        "codigo_dian": "99"
    }
}

Respuesta de Error

Error Interno (500)

Se retorna cuando ocurre un error inesperado en el servidor.

{
    "success": false,
    "status": 500,
    "message": "Error interno del servidor al obtener las formas de pago.",
    "body": null,
    "filters_applied": null
}

Códigos de Respuesta HTTP

Códigos DIAN de Medios de Pago

Referencia de códigos DIAN comunes para medios de pago:

Para consultar el listado completo de códigos de medios de pago, visite la Documentación Técnica de Factura Electrónica - DIAN.

Notas Importantes

Ejemplos

curl -X GET "https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/payment-methods" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN"

curl -X GET "https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/payment-methods?codigo_dian=42" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN"

<?php

$instance = 'your_instance'; // Reemplace con su instancia actual
$token = 'YOUR_AUTHENTICATION_TOKEN'; // Reemplace con el token obtenido desde el servicio de login

// Parámetros de filtro opcionales
$codigoDian = '42'; // Opcional: filtrar por código DIAN
$cuentaPuc = null;  // Opcional: filtrar por cuenta PUC

$url = "https://{$instance}.arrendasoft.co/service/v2/public/invoices/payment-methods";

// Agregar parámetros de filtro si existen
$queryParams = [];
if (!empty($codigoDian)) {
    $queryParams['codigo_dian'] = $codigoDian;
}
if (!empty($cuentaPuc)) {
    $queryParams['cuenta_puc'] = $cuentaPuc;
}
if (!empty($queryParams)) {
    $url .= '?' . http_build_query($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 "HTTP Status Code: " . $http_code . "\n";
    echo "Response: " . $response . "\n";
    
    // Procesar la respuesta
    $result = json_decode($response, true);
    
    if ($result['success'] && !empty($result['body'])) {
        echo "Se encontraron " . count($result['body']) . " formas de pago.\n\n";
        
        foreach ($result['body'] as $formaPago) {
            echo "ID: " . $formaPago['formaPagoId'] . "\n";
            echo "Nombre: " . $formaPago['nombre'] . "\n";
            echo "Cuenta PUC: " . $formaPago['cuentaPuc'] . "\n";
            echo "Código DIAN: " . $formaPago['codigoDian'] . "\n";
            echo "Medio de Pago: " . $formaPago['medioPago'] . "\n";
            echo "---\n";
        }
    } else {
        echo $result['message'] ?? "No se encontraron formas de pago.\n";
    }
}
curl_close($ch);

?>

const instance = 'your_instance'; // Reemplace con su instancia actual
const token = 'YOUR_AUTHENTICATION_TOKEN'; // Reemplace con el token obtenido

// Parámetros de filtro opcionales
const params = new URLSearchParams();
// params.append('codigo_dian', '42'); // Opcional: descomentar para filtrar
// params.append('cuenta_puc', '1110'); // Opcional: descomentar para filtrar

const url = `https://${instance}.arrendasoft.co/service/v2/public/invoices/payment-methods${params.toString() ? '?' + params.toString() : ''}`;

fetch(url, {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
    }
})
.then(response => response.json())
.then(data => {
    if (data.success && data.body.length > 0) {
        console.log(`Se encontraron ${data.body.length} formas de pago:`);
        data.body.forEach(formaPago => {
            console.log(`- ${formaPago.nombre} (ID: ${formaPago.formaPagoId})`);
            console.log(`  Cuenta PUC: ${formaPago.cuentaPuc}`);
            console.log(`  Medio DIAN: ${formaPago.medioPago} (${formaPago.codigoDian})`);
        });
    } else {
        console.log(data.message || 'No se encontraron formas de pago.');
    }
})
.catch(error => console.error('Error de conexión:', error));

Listar Resoluciones

Permite obtener el listado de resoluciones de facturación configuradas en la inmobiliaria. Retorna tanto las resoluciones de facturación como las de documento soporte, con soporte para paginación y múltiples filtros.

Endpoint: https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions

{{instancia}}: Hace referencia a la instancia de cada inmobiliaria.

Petición

Ejemplos de peticiones

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions?page=1&page_size=50

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions?activa=SI

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions?resolucion_para=1

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions?resolucion_para=2&activa=SI

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions?fact_electronica=SI&page_size=100

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions?fecha_desde=2024-01-01&fecha_hasta=2026-12-31

https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions?resolucion_para=1&activa=SI&fact_electronica=SI&page_size=50

Respuesta

Lista de resoluciones de facturación con información del tipo de documento asociado, datos de consecutivos, fechas, estado y metadatos de paginación.

{
    "status": 200,
    "message": null,
    "body": [
        {
            "resolucion_id": 4,
            "tipo_doc_id": 7,
            "tipo_doc": "Factura",
            "resolucion_numero": "18700052960",
            "consecutivo_iniciar": 1,
            "consecutivo_inicial": 1,
            "consecutivo_final": 20000,
            "fecha": "2025-07-24",
            "fecha_vigencia": "2026-07-24",
            "prefijo": "FE",
            "dias_vencimiento": 5,
            "activa": "SI",
            "codigo_barra": "NO",
            "codigo_ean": null,
            "tipo_resolucion": null,
            "creadopor": 5,
            "fechacreacion": "2025-07-24 12:00:01",
            "modificadopor": null,
            "fechamodificacion": null,
            "fact_electronica": "SI",
            "resolucion_para": 1
        },
        {
            "resolucion_id": 2,
            "tipo_doc_id": 39,
            "tipo_doc": "Documento Soporte",
            "resolucion_numero": "18760000012",
            "consecutivo_iniciar": 1,
            "consecutivo_inicial": 1,
            "consecutivo_final": 1000000,
            "fecha": "2022-09-01",
            "fecha_vigencia": "2024-05-31",
            "prefijo": "DS",
            "dias_vencimiento": 5,
            "activa": "SI",
            "codigo_barra": "NO",
            "codigo_ean": null,
            "tipo_resolucion": null,
            "creadopor": 5,
            "fechacreacion": "2024-05-02 15:01:48",
            "modificadopor": 5,
            "fechamodificacion": "2024-05-06 15:05:23",
            "fact_electronica": "SI",
            "resolucion_para": 2
        }
    ],
    "pagination": {
        "total_records": 4,
        "total_pages": 2,
        "current_page": 1,
        "page_size": 2,
        "current_page_records": 2,
        "has_next_page": true,
        "has_previous_page": false
    },
    "filters_applied": null
}

Claves y Descripciones del JSON de Respuesta

Esta tabla enumera las claves presentes en el JSON principal de la respuesta y proporciona una breve descripción de cada una.

Cuerpo

Cada elemento dentro de la lista body tiene las siguientes claves:

Paginación

El objeto pagination tiene las siguientes claves:

Filtros Aplicados

El objeto filters_applied contiene los filtros que fueron utilizados en la consulta. Solo se incluye en la respuesta cuando se aplican filtros. Las posibles claves son:

Respuesta con Filtros Aplicados

{
    "status": 200,
    "message": null,
    "body": [
        {
            "resolucion_id": 4,
            "tipo_doc_id": 7,
            "tipo_doc": "Factura",
            "resolucion_numero": "18700052960",
            "consecutivo_iniciar": 1,
            "consecutivo_inicial": 1,
            "consecutivo_final": 20000,
            "fecha": "2025-07-24",
            "fecha_vigencia": "2026-07-24",
            "prefijo": "FE",
            "dias_vencimiento": 5,
            "activa": "SI",
            "codigo_barra": "NO",
            "codigo_ean": null,
            "tipo_resolucion": null,
            "creadopor": 5,
            "fechacreacion": "2025-07-24 12:00:01",
            "modificadopor": null,
            "fechamodificacion": null,
            "fact_electronica": "SI",
            "resolucion_para": 1
        }
    ],
    "pagination": {
        "total_records": 3,
        "total_pages": 1,
        "current_page": 1,
        "page_size": 10,
        "current_page_records": 3,
        "has_next_page": false,
        "has_previous_page": false
    },
    "filters_applied": {
        "resolucion_para": 1,
        "activa": "SI"
    }
}

Respuesta Sin Resultados

{
    "status": 200,
    "message": "No se encontraron resoluciones con los criterios especificados.",
    "body": [],
    "pagination": {
        "total_records": 0,
        "total_pages": 0,
        "current_page": 1,
        "page_size": 10,
        "current_page_records": 0,
        "has_next_page": false,
        "has_previous_page": false
    },
    "filters_applied": {
        "activa": "NO"
    }
}

Respuesta de Error

Error de Validación (400)

Se retorna cuando se envía un parámetro con un valor no válido.

{
    "status": 400,
    "message": "El parámetro \"activa\" debe ser \"SI\" o \"NO\".",
    "body": null,
    "pagination": null,
    "filters_applied": null
}

{
    "status": 400,
    "message": "El parámetro \"resolucion_para\" debe ser 1 (Factura) o 2 (Documento Soporte).",
    "body": null,
    "pagination": null,
    "filters_applied": null
}

{
    "status": 400,
    "message": "El parámetro \"fecha_desde\" debe tener el formato Y-m-d (ej: 2026-01-15).",
    "body": null,
    "pagination": null,
    "filters_applied": null
}

Error Interno (500)

Se retorna cuando ocurre un error inesperado en el servidor.

{
    "status": 500,
    "message": "Error interno del servidor al obtener las resoluciones.",
    "body": null,
    "pagination": null,
    "filters_applied": null
}

Códigos de Respuesta HTTP

Valores de Referencia

Valores de resolucion_para

Valores de activa

Notas Importantes

Ejemplos

curl -X GET "https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN"

curl -X GET "https://{{instancia}}.arrendasoft.co/service/v2/public/invoices/resolutions?resolucion_para=1&activa=SI&page_size=50" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN"

<?php

$instance = 'your_instance'; // Reemplace con su instancia actual
$token = 'YOUR_AUTHENTICATION_TOKEN'; // Reemplace con el token obtenido desde el servicio de login

// Parámetros de ejemplo
$page = 1;
$pageSize = 50;

// Parámetros de filtro opcionales
$resolucionPara = 1;    // Opcional: 1 = Factura, 2 = Documento Soporte
$activa = 'SI';          // Opcional: 'SI' o 'NO'
$factElectronica = null; // Opcional: 'SI' o 'NO'

$url = "https://{$instance}.arrendasoft.co/service/v2/public/invoices/resolutions";

// Construir parámetros de consulta
$queryParams = [
    'page' => $page,
    'page_size' => $pageSize
];
if (!empty($resolucionPara)) {
    $queryParams['resolucion_para'] = $resolucionPara;
}
if (!empty($activa)) {
    $queryParams['activa'] = $activa;
}
if (!empty($factElectronica)) {
    $queryParams['fact_electronica'] = $factElectronica;
}
$url .= '?' . http_build_query($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 "HTTP Status Code: " . $http_code . "\n";
    echo "Response: " . $response . "\n";

    // Procesar la respuesta
    $result = json_decode($response, true);

    if ($http_code == 200 && !empty($result['body'])) {
        echo "Se encontraron " . $result['pagination']['total_records'] . " resoluciones.\n\n";

        foreach ($result['body'] as $resolucion) {
            echo "ID: " . $resolucion['resolucion_id'] . "\n";
            echo "Número: " . $resolucion['resolucion_numero'] . "\n";
            echo "Prefijo: " . $resolucion['prefijo'] . "\n";
            echo "Tipo: " . $resolucion['tipo_doc'] . "\n";
            echo "Activa: " . $resolucion['activa'] . "\n";
            echo "Vigencia: " . $resolucion['fecha_vigencia'] . "\n";
            echo "---\n";
        }
    } else {
        echo $result['message'] ?? "No se encontraron resoluciones.\n";
    }
}
curl_close($ch);

?>

const instance = 'your_instance'; // Reemplace con su instancia actual
const token = 'YOUR_AUTHENTICATION_TOKEN'; // Reemplace con el token obtenido

// Parámetros de filtro opcionales
const params = new URLSearchParams();
params.append('page', '1');
params.append('page_size', '50');
params.append('resolucion_para', '1'); // Opcional: 1 = Factura, 2 = Documento Soporte
params.append('activa', 'SI');          // Opcional: 'SI' o 'NO'
// params.append('fact_electronica', 'SI'); // Opcional: descomentar para filtrar

const url = `https://${instance}.arrendasoft.co/service/v2/public/invoices/resolutions?${params.toString()}`;

fetch(url, {
    method: 'GET',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
    }
})
.then(response => response.json())
.then(data => {
    if (data.status === 200 && data.body.length > 0) {
        console.log(`Se encontraron ${data.pagination.total_records} resoluciones:`);
        data.body.forEach(res => {
            console.log(`- ${res.prefijo} ${res.resolucion_numero} (ID: ${res.resolucion_id})`);
            console.log(`  Tipo: ${res.tipo_doc} | Activa: ${res.activa}`);
            console.log(`  Consecutivos: ${res.consecutivo_inicial} - ${res.consecutivo_final}`);
            console.log(`  Vigencia: ${res.fecha} a ${res.fecha_vigencia}`);
        });

        // Información de paginación
        console.log(`\nPágina ${data.pagination.current_page} de ${data.pagination.total_pages}`);
    } else {
        console.log(data.message || 'No se encontraron resoluciones.');
    }
})
.catch(error => console.error('Error de conexión:', error));

Contabilidad

Reporte Auxiliar General

Permite obtener el reporte contable Auxiliar General, que presenta los movimientos detallados de cada cuenta del Plan Único de Cuentas (PUC) dentro de un período y rango de cuentas. Cada elemento incluye el saldo anterior, débitos, créditos, saldo actual, base de retención, y el desglose por tercero con sus respectivos documentos contables.

¿Para qué sirve este servicio?
Úsalo para alimentar reportes contables en tu ERP, conciliar saldos con sistemas externos, generar informes de auditoría, exportar movimientos detallados a Excel o Power BI, o validar la contabilidad de un período específico.

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/accounting/general-ledger

¿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 no requiere cuerpo en la petición. Envía los encabezados requeridos y opcionalmente los parámetros de filtro en la URL:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

Parámetros de consulta (query string):

Ejemplos de petición:

GET https://mi-inmobiliaria.nuby.app/service/v2/public/accounting/general-ledger
GET https://mi-inmobiliaria.nuby.app/service/v2/public/accounting/general-ledger?fecha_ini=2025-01-01
GET https://mi-inmobiliaria.nuby.app/service/v2/public/accounting/general-ledger?fecha_ini=2025-01-01&fecha_fin=2025-06-30
GET https://mi-inmobiliaria.nuby.app/service/v2/public/accounting/general-ledger?fecha_ini=2025-01-01&fecha_fin=2025-06-30&cuenta_ini=1
GET https://mi-inmobiliaria.nuby.app/service/v2/public/accounting/general-ledger?fecha_ini=2025-01-01&fecha_fin=2025-06-30&cuenta_ini=1&cuenta_fin=4

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

Si tu Token es válido y los parámetros son correctos, el sistema te devolverá un objeto JSON con el listado de cuentas contables, sus terceros y los movimientos detallados de cada uno. La respuesta tiene una estructura jerárquica de tres niveles: Cuenta → Tercero → Detalle.

{
    "error": false,
    "message": "",
    "body": [
        {
            "cuenta": "11050501",
            "nombre_cuenta": "Caja general moneda nacional",
            "saldo_anterior": 8750320.45,
            "debitos": 12480000,
            "creditos": 9230000,
            "saldo_actual": 12000320.45,
            "base_retencion": 0,
            "terceros": {
                "42": {
                    "documento_tercero": "80213654",
                    "nombre_tercero": "CARLOS EDUARDO PINEDA VARGAS",
                    "saldo_anterior": 3250120.45,
                    "debitos": 7500000,
                    "creditos": 4230000,
                    "saldo_actual": 6520120.45,
                    "base_retencion": 0,
                    "detalles": [
                        {
                            "fecha_documento": "2025-02-05",
                            "consecutivo_documento": "RC-10450",
                            "detalle_documento": "Pago canon arrendamiento febrero Apto 501",
                            "debitos": 2850000,
                            "creditos": 0,
                            "base_retencion": 0
                        },
                        {
                            "fecha_documento": "2025-03-03",
                            "consecutivo_documento": "RC-10512",
                            "detalle_documento": "Pago canon arrendamiento marzo Apto 501",
                            "debitos": 2850000,
                            "creditos": 0,
                            "base_retencion": 0
                        },
                        {
                            "fecha_documento": "2025-03-15",
                            "consecutivo_documento": "EG-4021",
                            "detalle_documento": "Consignación propietario marzo",
                            "debitos": 0,
                            "creditos": 4230000,
                            "base_retencion": 0
                        }
                    ]
                },
                "73": {
                    "documento_tercero": "1098745231",
                    "nombre_tercero": "JULIANA PATRICIA RÍOS MENDOZA",
                    "saldo_anterior": 1500200,
                    "debitos": 4980000,
                    "creditos": 5000000,
                    "saldo_actual": 1480200,
                    "base_retencion": 0,
                    "detalles": [
                        {
                            "fecha_documento": "2025-01-10",
                            "consecutivo_documento": "RC-10389",
                            "detalle_documento": "Pago canon arrendamiento enero Local 3",
                            "debitos": 4500000,
                            "creditos": 0,
                            "base_retencion": 0
                        },
                        {
                            "fecha_documento": "2025-01-20",
                            "consecutivo_documento": "EG-3998",
                            "detalle_documento": "Consignación propietario enero",
                            "debitos": 0,
                            "creditos": 5000000,
                            "base_retencion": 0
                        }
                    ]
                }
            }
        },
        {
            "cuenta": "13050501",
            "nombre_cuenta": "Arrendamientos por cobrar",
            "saldo_anterior": 15400000,
            "debitos": 9350000,
            "creditos": 12480000,
            "saldo_actual": 12270000,
            "base_retencion": 0,
            "terceros": {
                "55": {
                    "documento_tercero": "43876123",
                    "nombre_tercero": "DIANA MARCELA OSPINA VELÁSQUEZ",
                    "saldo_anterior": 2400000,
                    "debitos": 3600000,
                    "creditos": 4800000,
                    "saldo_actual": 1200000,
                    "base_retencion": 0,
                    "detalles": [
                        {
                            "fecha_documento": "2025-01-01",
                            "consecutivo_documento": "FV-8901",
                            "detalle_documento": "Factura arrendamiento enero Cll 23 # 56 - 78",
                            "debitos": 1200000,
                            "creditos": 0,
                            "base_retencion": 0
                        },
                        {
                            "fecha_documento": "2025-01-15",
                            "consecutivo_documento": "RC-10401",
                            "detalle_documento": "Recibo de caja pago enero",
                            "debitos": 0,
                            "creditos": 1200000,
                            "base_retencion": 0
                        },
                        {
                            "fecha_documento": "2025-02-01",
                            "consecutivo_documento": "FV-8950",
                            "detalle_documento": "Factura arrendamiento febrero Cll 23 # 56 - 78",
                            "debitos": 1200000,
                            "creditos": 0,
                            "base_retencion": 0
                        },
                        {
                            "fecha_documento": "2025-02-10",
                            "consecutivo_documento": "RC-10465",
                            "detalle_documento": "Recibo de caja pago febrero",
                            "debitos": 0,
                            "creditos": 1200000,
                            "base_retencion": 0
                        }
                    ]
                }
            }
        },
        {
            "cuenta": "24080501",
            "nombre_cuenta": "Retención en la fuente arrendamientos 3.5%",
            "saldo_anterior": -875000,
            "debitos": 0,
            "creditos": 249375,
            "saldo_actual": -1124375,
            "base_retencion": 7125000,
            "terceros": {
                "65": {
                    "documento_tercero": "900456789",
                    "nombre_tercero": "INVERSIONES HORIZONTE S.A.S.",
                    "saldo_anterior": -875000,
                    "debitos": 0,
                    "creditos": 249375,
                    "saldo_actual": -1124375,
                    "base_retencion": 7125000,
                    "detalles": [
                        {
                            "fecha_documento": "2025-01-31",
                            "consecutivo_documento": "EG-3985",
                            "detalle_documento": "Retención arrendamiento enero Local 3",
                            "debitos": 0,
                            "creditos": 157500,
                            "base_retencion": 4500000
                        },
                        {
                            "fecha_documento": "2025-02-28",
                            "consecutivo_documento": "EG-4050",
                            "detalle_documento": "Retención arrendamiento febrero Local 3",
                            "debitos": 0,
                            "creditos": 91875,
                            "base_retencion": 2625000
                        }
                    ]
                }
            }
        }
    ]
}

Estructura principal de la respuesta

Campos de cada cuenta (body)

Cada elemento dentro del arreglo body representa una cuenta contable y contiene las siguientes claves:

Campos de cada tercero (terceros)

Cada entrada dentro del objeto terceros contiene las siguientes claves:

Campos de cada detalle (detalles)

Cada elemento dentro del arreglo detalles representa un documento contable individual:

Nota sobre resultados vacíos
Si no existen movimientos contables para los parámetros indicados, la respuesta tendrá HTTP 200 con error: false, body: null y un message informativo: "No se encontraron registros con los parámetros indicados."

Nota sobre el cálculo de saldos
El cálculo del saldo_actual depende de la clase contable de la cuenta (primer dígito del código PUC):
— Clases 1 (Activos), 5 (Gastos) y 6 (Costos): saldo_anterior + débitos - créditos
— Clases 2 (Pasivos), 3 (Patrimonio), 4 (Ingresos) y demás: saldo_anterior + créditos - débitos
Este comportamiento puede variar según la configuración del sistema (parámetro interno de la plataforma).

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Si alguno de los parámetros no cumple con las validaciones, el sistema devolverá un error 400. Por ejemplo:

{
    "error": true,
    "message": "La fecha inicial no tiene un formato válido (Y-m-d) o no es una fecha válida.",
    "body": null
}

Posibles errores:

5. Ejemplos de integración

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

# Consultar auxiliar general con parámetros por defecto (año actual, todas las cuentas)
curl -X GET "https://{{instancia}}/service/v2/public/accounting/general-ledger" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

# Consultar auxiliar general de enero a junio 2025, cuentas de activos y pasivos (1 a 2)
curl -X GET "https://{{instancia}}/service/v2/public/accounting/general-ledger?fecha_ini=2025-01-01&fecha_fin=2025-06-30&cuenta_ini=1&cuenta_fin=2" \
-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
$fecha_ini = '2025-01-01';
$fecha_fin = '2025-06-30';
$cuenta_ini = '1';
$cuenta_fin = '4';

$queryParams = http_build_query([
    'fecha_ini' => $fecha_ini,
    'fecha_fin' => $fecha_fin,
    'cuenta_ini' => $cuenta_ini,
    'cuenta_fin' => $cuenta_fin
]);

$url = "https://{$instance}/service/v2/public/accounting/general-ledger?{$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";

    $info = json_decode($response, true);
    $body = $info['body'] ?? [];

    if ($http_code === 200 && !empty($body)) {
        echo "Se consultaron " . count($body) . " cuentas contables.\n\n";

        foreach ($body as $cuenta) {
            echo "Cuenta: {$cuenta['cuenta']} - {$cuenta['nombre_cuenta']}\n";
            echo "  Saldo anterior: $" . number_format($cuenta['saldo_anterior'], 2) . "\n";
            echo "  Débitos: $" . number_format($cuenta['debitos'], 2) . "\n";
            echo "  Créditos: $" . number_format($cuenta['creditos'], 2) . "\n";
            echo "  Saldo actual: $" . number_format($cuenta['saldo_actual'], 2) . "\n";

            foreach ($cuenta['terceros'] as $terceroId => $tercero) {
                echo "    Tercero: {$tercero['documento_tercero']} - {$tercero['nombre_tercero']}\n";
                echo "      Movimientos: " . count($tercero['detalles']) . "\n";
            }
            echo "\n";
        }
    } else {
        echo "Mensaje: " . ($info['message'] ?? 'Sin resultados') . "\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/accounting/general-ledger"

params = {
    "fecha_ini": "2025-01-01",
    "fecha_fin": "2025-06-30",
    "cuenta_ini": "1",
    "cuenta_fin": "4"
}

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:
        info = response.json()
        body = info.get('body') or []

        if body:
            print(f"Cuentas encontradas: {len(body)}\n")
            for cuenta in body:
                print(f"Cuenta: {cuenta['cuenta']} - {cuenta['nombre_cuenta']}")
                print(f"  Saldo anterior: ${cuenta['saldo_anterior']:,.2f}")
                print(f"  Débitos: ${cuenta['debitos']:,.2f}")
                print(f"  Créditos: ${cuenta['creditos']:,.2f}")
                print(f"  Saldo actual: ${cuenta['saldo_actual']:,.2f}")

                for tercero_id, tercero in cuenta['terceros'].items():
                    print(f"    Tercero [{tercero_id}]: {tercero['documento_tercero']} - {tercero['nombre_tercero']}")
                    print(f"      Movimientos: {len(tercero['detalles'])}")
                print()
        else:
            print(f"Mensaje: {info.get('message', 'Sin resultados')}")
    else:
        print("Error al consultar el auxiliar general.")
        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({
    fecha_ini: '2025-01-01',
    fecha_fin: '2025-06-30',
    cuenta_ini: '1',
    cuenta_fin: '4'
});

const url = `https://${instancia}/service/v2/public/accounting/general-ledger?${params}`;

// 3. Función para consultar el auxiliar general
async function consultarAuxiliarGeneral() {
    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 info = await response.json();
            const body = info.body || [];

            if (body.length > 0) {
                console.log(`Cuentas encontradas: ${body.length}\n`);
                body.forEach(cuenta => {
                    console.log(`Cuenta: ${cuenta.cuenta} - ${cuenta.nombre_cuenta}`);
                    console.log(`  Saldo anterior: $${cuenta.saldo_anterior.toLocaleString()}`);
                    console.log(`  Débitos: $${cuenta.debitos.toLocaleString()}`);
                    console.log(`  Créditos: $${cuenta.creditos.toLocaleString()}`);
                    console.log(`  Saldo actual: $${cuenta.saldo_actual.toLocaleString()}`);

                    for (const [terceroId, tercero] of Object.entries(cuenta.terceros)) {
                        console.log(`    Tercero [${terceroId}]: ${tercero.documento_tercero} - ${tercero.nombre_tercero}`);
                        console.log(`      Movimientos: ${tercero.detalles.length}`);
                    }
                    console.log('');
                });
            } else {
                console.log(`Mensaje: ${info.message || 'Sin resultados'}`);
            }
        } else {
            console.log('Error al consultar el auxiliar general.');
            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
consultarAuxiliarGeneral();

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 con parámetros
    url = "https://" & instancia & "/service/v2/public/accounting/general-ledger?fecha_ini=2025-01-01&fecha_fin=2025-06-30&cuenta_ini=1&cuenta_fin=4",

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

    // 4. Decodifica la respuesta JSON
    jsonResponse = Json.Document(response),
    body = jsonResponse[body],

    // 5. Convierte el listado de cuentas en tabla
    tablaCuentas = Table.FromList(body, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    expandidoCuentas = Table.ExpandRecordColumn(tablaCuentas, "Column1",
        {"cuenta", "nombre_cuenta", "saldo_anterior", "debitos", "creditos", "saldo_actual", "base_retencion", "terceros"},
        {"Cuenta", "NombreCuenta", "SaldoAnterior", "Debitos", "Creditos", "SaldoActual", "BaseRetencion", "Terceros"}),

    // 6. (Opcional) Expandir terceros para obtener detalle por tercero
    // Nota: La estructura de terceros es un objeto con claves dinámicas.
    // Para un análisis más detallado, es recomendable procesar los terceros
    // con Record.FieldValues y luego expandir los detalles.
    tercerosList = Table.AddColumn(expandidoCuentas, "TercerosLista", each Record.FieldValues([Terceros])),
    expandidoTerceros = Table.ExpandListColumn(tercerosList, "TercerosLista"),
    expandidoTercerosCampos = Table.ExpandRecordColumn(expandidoTerceros, "TercerosLista",
        {"documento_tercero", "nombre_tercero", "saldo_anterior", "debitos", "creditos", "saldo_actual", "base_retencion"},
        {"DocTercero", "NombreTercero", "SaldoAntTercero", "DebitosTercero", "CreditosTercero", "SaldoActTercero", "BaseRetTercero"})
in
    expandidoTercerosCampos

Contratos

Listar Contratos

Permite obtener la lista paginada de todos los contratos de arrendamiento registrados en el sistema. Cada elemento incluye la información completa del contrato: propiedad asociada, propietarios, inquilinos, valores económicos, fechas, estado y observaciones.

¿Para qué sirve este servicio?
Úsalo para sincronizar el inventario de contratos con tu sistema externo, generar reportes de gestión inmobiliaria, alimentar dashboards con información contractual o consultar el estado general de los contratos administrados.

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/contracts/list

¿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 no requiere cuerpo en la petición. Envía los encabezados requeridos y opcionalmente los parámetros de paginación en la URL:

¿Aún no tienes tu Token de acceso?
Para consumir este servicio necesitas un Token vigente. Consulta el servicio de Login para aprender cómo obtenerlo.

Parámetros de consulta (query string):

Ejemplos de petición:

GET https://mi-inmobiliaria.nuby.app/service/v2/public/contracts/list
GET https://mi-inmobiliaria.nuby.app/service/v2/public/contracts/list?page=2
GET https://mi-inmobiliaria.nuby.app/service/v2/public/contracts/list?page_size=50
GET https://mi-inmobiliaria.nuby.app/service/v2/public/contracts/list?page=3&page_size=100

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

Si tu Token es válido, el sistema te devolverá un objeto JSON con el estado de la respuesta, el listado de contratos y la información de paginación. La respuesta se verá similar a esta:

{
    "status": 200,
    "message": null,
    "body": [
        {
            "contrato_id": 45,
            "consecutivo": "45",
            "propiedad_id": 312,
            "propiedad": "312 - Cll 78 # 12 - 34 Apto 501",
            "estrato_propiedad": "Cuatro",
            "propietario": "[1] 52498731 - ANDREA MILENA CASTRO ROJAS",
            "propietarios_id": "18",
            "inquilino": "[1] 80213654 - CARLOS EDUARDO PINEDA VARGAS",
            "inquilinos_id": "42",
            "valor_canon_individual": "2850000",
            "canon_total": 2850000,
            "porcentaje_comision": "10.00 %",
            "periodicidad": "Mensual",
            "escenario": "CANON DE ARRENDAMIENTO SIN IVA, CON RETEFUENTE 3.5%, SIN RETEIVA, SIN RETEICA",
            "estado": "Activo",
            "estado_id": 1,
            "fecha_inicio": "2024-06-01",
            "fecha_fin": "2025-05-31",
            "fecha_terminacion": null,
            "observaciones": "Contrato renovado automáticamente por un año adicional.",
            "uso": "Vivienda",
            "fecha_creacion": "2024-05-28 14:32:10",
            "creado_por": "Sandra"
        },
        {
            "contrato_id": 46,
            "consecutivo": "46",
            "propiedad_id": 589,
            "propiedad": "589 - Cra 45 # 90 - 12 Local 3",
            "estrato_propiedad": "Comercial",
            "propietario": "[1] 900456789 - INVERSIONES HORIZONTE S.A.S.",
            "propietarios_id": "65",
            "inquilino": "[1] 1098745231 - JULIANA PATRICIA RÍOS MENDOZA",
            "inquilinos_id": "73",
            "valor_canon_individual": "4500000",
            "canon_total": 4500000,
            "porcentaje_comision": "8.50 %",
            "periodicidad": "Mensual",
            "escenario": "CANON DE ARRENDAMIENTO CON IVA 19%, CON RETEFUENTE 3.5%, CON RETEIVA 15%, SIN RETEICA",
            "estado": "Activo",
            "estado_id": 1,
            "fecha_inicio": "2023-09-01",
            "fecha_fin": "2025-08-31",
            "fecha_terminacion": null,
            "observaciones": null,
            "uso": "Comercial",
            "fecha_creacion": "2023-08-25 09:15:44",
            "creado_por": "Administrador"
        },
        {
            "contrato_id": 12,
            "consecutivo": "12",
            "propiedad_id": 104,
            "propiedad": "104 - Cll 23 # 56 - 78",
            "estrato_propiedad": "Tres",
            "propietario": "[1] 71654321 - HÉCTOR FABIO MORENO AGUILAR",
            "propietarios_id": "31",
            "inquilino": "[1] 43876123 - DIANA MARCELA OSPINA VELÁSQUEZ",
            "inquilinos_id": "55",
            "valor_canon_individual": "1200000",
            "canon_total": 1200000,
            "porcentaje_comision": "12.00 %",
            "periodicidad": "Mensual",
            "escenario": "CANON DE ARRENDAMIENTO SIN IVA, SIN RETEFUENTE, SIN RETEIVA, SIN RETEICA",
            "estado": "Terminado",
            "estado_id": 2,
            "fecha_inicio": "2022-01-15",
            "fecha_fin": "2023-01-14",
            "fecha_terminacion": "2022-11-30",
            "observaciones": "Terminación anticipada por mutuo acuerdo.",
            "uso": "Vivienda",
            "fecha_creacion": "2021-12-20 16:40:33",
            "creado_por": "Sandra"
        }
    ],
    "pagination": {
        "total_records": 347,
        "total_pages": 116,
        "current_page": 1,
        "page_size": 3,
        "current_page_records": 3,
        "has_next_page": true,
        "has_previous_page": false
    }
}

Estructura principal de la respuesta

Campos de cada contrato (body)

Cada elemento dentro del arreglo body contiene las siguientes claves:

Campos de paginación (pagination)

El objeto pagination contiene las siguientes claves:

Nota sobre contratos sin resultados
Si no existen contratos registrados en el sistema, la respuesta tendrá HTTP 200 con body vacío ([]), un message informativo y los valores de paginación en cero.

4. Seguridad y Posibles Errores

¡Tu pase tiene fecha de caducidad!

Por medidas de seguridad, el token que te entregamos solo dura 1 hora. Una vez transcurrido ese tiempo, el pase expirará y el sistema te bloqueará el acceso devolviéndote un error 401. Cuando esto ocurra, tu sistema simplemente debe volver a consumir el servicio de Login para pedir un pase nuevo y continuar trabajando.

Así se ve el error que te devolverá el sistema cuando tu token se haya vencido o intentes usar un pase inválido:

{
    "statusCode": 401,
    "error": {
        "type": "SERVER_ERROR",
        "description": "JWT Token expired."
    }
}

Si alguno de los parámetros de paginación no cumple con las validaciones, el sistema devolverá un error 400 con la estructura estándar. Por ejemplo:

{
    "status": 400,
    "message": "El parámetro \"page_size\" debe ser un número positivo.",
    "body": null,
    "pagination": null
}

Posibles errores:

5. Ejemplos de integración

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

# Listar contratos con paginación por defecto
curl -X GET "https://{{instancia}}/service/v2/public/contracts/list" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer TU_TOKEN_AQUI"

# Listar contratos página 3 con 100 registros por página
curl -X GET "https://{{instancia}}/service/v2/public/contracts/list?page=3&page_size=100" \
-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 paginación
$page = 1;
$page_size = 50;

$queryParams = http_build_query([
    'page' => $page,
    'page_size' => $page_size
]);

$url = "https://{$instance}/service/v2/public/contracts/list?{$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";

    $info = json_decode($response, true);
    $body = $info['body'] ?? [];

    if ($http_code === 200 && !empty($body)) {
        $pagination = $info['pagination'];
        echo "Contratos encontrados: {$pagination['total_records']} (página {$pagination['current_page']} de {$pagination['total_pages']})\n";

        foreach ($body as $contrato) {
            echo "  [{$contrato['consecutivo']}] {$contrato['propiedad']} - {$contrato['estado']} - Canon: \${$contrato['canon_total']}\n";
        }
    } else {
        echo "Mensaje: " . ($info['message'] ?? 'Sin resultados') . "\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/contracts/list"

params = {
    "page": 1,
    "page_size": 50
}

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:
        info = response.json()
        body = info.get('body', [])
        pagination = info.get('pagination', {})

        if body:
            print(f"Contratos: {pagination['total_records']} total (página {pagination['current_page']} de {pagination['total_pages']})")
            for contrato in body:
                print(f"  [{contrato['consecutivo']}] {contrato['propiedad']} - {contrato['estado']} - Canon: ${contrato['canon_total']}")
        else:
            print(f"Mensaje: {info.get('message', 'Sin resultados')}")
    else:
        print("Error al consultar los contratos.")
        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,
    page_size: 50
});

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

// 3. Función para consultar los contratos
async function consultarContratos() {
    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 info = await response.json();
            const body = info.body || [];
            const pagination = info.pagination || {};

            if (body.length > 0) {
                console.log(`Contratos: ${pagination.total_records} total (página ${pagination.current_page} de ${pagination.total_pages})`);
                body.forEach(contrato => {
                    console.log(`  [${contrato.consecutivo}] ${contrato.propiedad} - ${contrato.estado} - Canon: $${contrato.canon_total}`);
                });
            } else {
                console.log(`Mensaje: ${info.message || 'Sin resultados'}`);
            }
        } else {
            console.log('Error al consultar los contratos.');
            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
consultarContratos();

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/contracts/list?page=1&page_size=1000",

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

    // 4. Decodifica la respuesta JSON
    jsonResponse = Json.Document(response),
    body = jsonResponse[body],

    // 5. Convierte el listado en tabla
    tabla = Table.FromList(body, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    expandido = Table.ExpandRecordColumn(tabla, "Column1",
        {"contrato_id", "consecutivo", "propiedad", "estrato_propiedad", "propietario", "inquilino", "canon_total", "porcentaje_comision", "periodicidad", "estado", "fecha_inicio", "fecha_fin", "fecha_terminacion", "uso", "creado_por"},
        {"ContratoID", "Consecutivo", "Propiedad", "Estrato", "Propietario", "Inquilino", "Canon", "Comision", "Periodicidad", "Estado", "FechaInicio", "FechaFin", "FechaTerminacion", "Uso", "CreadoPor"})
in
    expandido