Ir al contenido principal

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:

Método PATCH
Content-Type application/json
Authorization Bearer token, Token obtenido al consumir el servicio Login.

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:

Parámetro Tipo Requerido Descripción
code integer Código numérico único del inmueble cuyo estado se desea actualizar.

Cuerpo de la petición (Body):

Campo Tipo Requerido Descripción
status integer Nuevo estado que se desea asignar a la propiedad. Los valores válidos son:
1 = Activa
2 = Inactiva
3 = Vendida

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
ID Estado Descripción
0 Arrendada El inmueble tiene un contrato de arrendamiento vigente. No se puede asignar vía API.
1 Activa El inmueble está disponible en el mercado para arriendo o venta.
2 Inactiva El inmueble fue retirado temporalmente del mercado.
3 Vendida El inmueble fue vendido.
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:

Estado actual Puede cambiar a
Activa (1) 2 (Inactiva) o 3 (Vendida)
Inactiva (2) 1 (Activa) o 3 (Vendida)
Arrendada (0) No se permite cambiar el estado vía API.
Vendida (3) No se permite cambiar el estado vía API.

¿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"
}
Clave Descripción
message Mensaje indicando que el estado de la propiedad fue actualizado 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:

Código HTTP Descripción Ejemplo de respuesta
400 Token faltante o inválido. Posibles causas:
— No se envió el encabezado Authorization. Mensaje: "JWT Token required."
— El encabezado no tiene el formato Bearer {token}. Mensaje: "JWT Token not send."
— El token no fue encontrado en el sistema. Mensaje: "JWT Token not found."

Parámetros inválidos. El campo status no fue enviado o no es numérico.
{
    "error": "El estado(status) es requerido"
}
401 El token ha expirado. Debes generar uno nuevo consumiendo el servicio de Login.
"JWT Token expired."
403 El cliente OAuth no tiene el scope necesario. Para endpoints PATCH se requiere el scope update.
"Insufficient scope. Required: 'update', granted: '{scope_actual}'."
404 No se encontró ninguna propiedad con el código indicado.
{
    "error": "No se encontró la propiedad"
}
422 El valor de status no corresponde a un estado válido del sistema (no es 0, 1, 2 o 3).
{
    "error": "El estado no es válido"
}
422 El estado actual de la propiedad no permite la modificación (por ejemplo: la propiedad está en estado "Arrendada" o "Vendida").
{
    "error": "El estado actual de la propiedad no permite este tipo de modificación."
}
500 Error interno del servidor. No se pudo ejecutar la actualización en la base de datos.
{
    "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:

cURL
# 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
<?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);

?>
Python
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}")
JavaScript
// 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();
Power Query M (Excel / Power BI)
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