Listar Contratos

Permite obtener unala lista paginada de elementos,todos dondelos cadacontratos de arrendamiento registrados en el sistema. Cada elemento contieneincluye 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 cadacontratos unacon tu sistema externo, generar reportes de gestión inmobiliaria, alimentar dashboards con información contractual o consultar el estado general de los contratos registradasadministrados.

1. El Endpoint (La dirección web)

Apunta tu sistema a la inmobiliaria.

Endpoint: https://dirección. Recuerda reemplazar {{instancia}}.arrendasoft.co/ 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}}:? Hace
Es referenciamuy sencillo: corresponde a la instanciadirecció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 cadano inmobiliaria.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 peticionespetición:

GET https://{{instancia}}.arrendasoft.co/mi-inmobiliaria.nuby.app/service/v2/public/contracts/list

GET https://{{instancia}}.arrendasoft.co/mi-inmobiliaria.nuby.app/service/v2/public/contracts/list?page=1

GET https://{{instancia}}.arrendasoft.co/mi-inmobiliaria.nuby.app/service/v2/public/contracts/list?page_size=100

GET https://{{instancia}}.arrendasoft.co/mi-inmobiliaria.nuby.app/service/v2/public/contracts/list?page=13&page_size=100

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

ListaSi tu Token es válido, el sistema te devolverá un objeto JSON con el estado de elementos,la donderespuesta, cadael elementolistado contienede contratos y la información de lospaginación. datosLa obtenidos,respuesta estado,se mensaje,verá listadosimilar dea las facturas y paginación.esta:

{
    "status": 200,
    "message": null,
    "body": [
        {
            "contrato_id": 1,45,
            "consecutivo": 1,"45",
            "propiedad_id": 7774,312,
            "propiedad": "7774312 - CRCll 9278 # 3312 - 49"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] 2000000171654321 - DENISHÉCTOR RUIZ"FABIO MORENO AGUILAR",
            "propietarios_id": "94"31",
            "inquilino": "[1] 8001112223343876123 - GOBERNACIONDIANA DEMARCELA ANTIOQUIA"OSPINA VELÁSQUEZ",
            "inquilinos_id": "92"55",
            "valor_canon_individual": "28000000"1200000",
            "canon_total": 28000000,1200000,
            "porcentaje_comision": "9.7112.00 %",
            "periodicidad": "Mensual",
            "escenario": "Estatales"CANON DE ARRENDAMIENTO SIN IVA, SIN RETEFUENTE, SIN RETEIVA, SIN RETEICA",
            "estado": "Terminado",
            "estado_id": 2,
            "fecha_inicio": "2014-02-01"2022-01-15",
            "fecha_fin": "2014-12-31"2023-01-14",
            "fecha_terminacion": "2014-05-31"2022-11-30",
            "observaciones": "NINGUNA"Terminación anticipada por mutuo acuerdo.",
            "uso": "Comercial"Vivienda",
            "fecha_creacion": "2014-04-142021-12-20 09:41:54"16:40:33",
            "creado_por": "Administrador"
        },
        {
            "contrato_id": 2,
            "consecutivo": 2,
            "propiedad_id": 129,
            "propiedad": "129 - Cra 34 # 40 - 35",
            "estrato_propiedad": "Comercial",
            "propietario": "[1] 900000001 - INMOBILIARIA CONSULTORES INMOBILIARIOS S.A.S.",
            "propietarios_id": "100",
            "inquilino": "[1] 350000004 - MÓNICA CANO",
            "inquilinos_id": "8",
            "valor_canon_individual": "401594",
            "canon_total": 401594,
            "porcentaje_comision": "8.62 %",
            "periodicidad": "Mensual",
            "escenario": "(2) (F.I.) CANON DE ARRENDAMIENTO CON IVA 19 %, SIN RETEFUENTE, SIN RETEIVA, SIN RETEICA --- (F.P.) COMISIÓN CON IVA (19%), SIN RETEFUENTE  SIN RETEIVA, SIN RETEICA.",
            "estado": "Terminado",
            "estado_id": 2,
            "fecha_inicio": "2013-01-01",
            "fecha_fin": "2014-12-30",
            "fecha_terminacion": "2014-09-30",
            "observaciones": null,
            "uso": "Comercial",
            "fecha_creacion": "2014-04-15 12:12:52",
            "creado_por": "Administrativo"Sandra"
        }
    ],
    "pagination": {
        "total_records": 1082,347,
        "total_pages": 541,116,
        "current_page": 1,
        "page_size": 2,3,
        "current_page_records": 2,3,
        "has_next_page": true,
        "has_previous_page": false
    }
}

Claves y Descripciones del JSON de Contratos

Esta tabla enumera las claves presentes en el JSONEstructura principal de la respuesta y proporciona una breve descripción de cada una, explicando su propósito y el tipo de información que contienen.

CuerpoCampos de cada contrato (body)

Cada elemento dentro dedel la listaarreglo body, tienecontiene las siguientes claves:

PaginaciónCampos de paginación (pagination)

CadaEl elemento dentro de la listaobjeto pagination tiene 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.

Ejemplos4. 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}}.arrendasoft.co//service/v2/public/contracts/list?page_size=100&page=3"list" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_AUTHENTICATION_TOKEN"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 = 'your_instance'tu_instancia'; // ReemplaceReemplaza con sutu instancia actualreal
$token = 'YOUR_AUTHENTICATION_TOKEN'TU_TOKEN_AQUI'; // Reemplace con el tokenToken obtenido desde eldel servicio de loginLogin

// Parámetros de ejemplo para listar contratospaginación
$page = 1;
$page_size = 50;

$url = "https://{$instance}.arrendasoft.co/service/v2/public/contracts/list?";
$queryParams = http_build_query([
    'page' => $page,
    'page_size' => $page_size
]);

$url .= http_build_query("https://{$queryParams)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 ' . {$tokentoken}"
]);

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

if (curl_errno($ch)) {
    echo 'Error: ' . curl_error($ch);
} else {
    echo "HTTPCódigo Statusde Code:estado HTTP: " . $http_code . "\n";
    echo "Response: " . $response . "\n";
    
    // Procesar la respuesta

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

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

        //foreach Ejemplo: Imprimir los números de los contratos
        foreach(($body as $contract)contrato) {
            echo "Contrato  número: " . [{$contract[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