Ir al contenido principal

Buscar Asesor por Documento

Permite obtener la información de un elementoasesor queespecí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 delde asesor.un agente puntual con tu sistema externo.


1. El Endpoint (La dirección web)

Endpoint: https://Apunta tu sistema a la siguiente dirección. Recuerda reemplazar {{instancia}}.arrendasoft.co/ 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}}:? 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. Solo necesitas construir la URL con el número de documento del asesor como parte de la ruta e incluir los encabezados requeridos:

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

¿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:

correspondeal número
ParámetroTipoRequeridoDescripción
Parámetrodocument {{document}},string Número de documento de identidad del asesor aque consultarse desea consultar. Se envía directamente en la URL.

Ejemplo de peticiónpetición:

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

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

Elemento 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 dedel laasesor. propiedad.La respuesta se verá similar a esta:

{
    "id": "6"3",
    "documento": "1216727504"52498731",
    "nombre": "KARENANDREA CANO"MILENA CASTRO ROJAS",
    "telefono": "4447417"3104567890",
    "email": "karen.cano@interservicios.andrea.castro@miredinmobiliaria.com",
    "path_photo": "https://localhost/arrendasoft/mi-inmobiliaria.nuby.app/pic/iconos/user_photo.png"usuarios/foto_andrea_castro.jpg"
}

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

ClaveCampo TipoDescripción
id stringIdentificador único del usuario en el sistema.
documento stringNúmero de documento de identificaciónidentidad del usuarioasesor.
nombre stringNombre completo del usuarioasesor (compuesto por primer nombre, segundo nombre, primer apellido y segundo apellido).
telefono stringNúmero de teléfono del usuarioasesor.
email stringDirección de correo electrónico del usuarioasesor.
path_photo stringURL acompleta de la fotofotografía del usuarioasesor. Si el asesor no tiene foto registrada, se devuelve la imagen genérica del sistema.

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:

Código HTTPDescripción
200Respuesta exitosa. Contiene el objeto JSON del asesor, o un arreglo vacío [] si no se encontró ningún asesor con ese documento.
400Token no enviado o con formato incorrecto. Asegúrate de incluir el encabezado Authorization: Bearer TU_TOKEN.
401Token expirado o inválido. Solicita uno nuevo a través del servicio de Login.
403El cliente OAuth no tiene el scope necesario para esta operación. Para endpoints GET se requiere el scope read. Mensaje: "Insufficient scope. Required: 'read', granted: '{scope_actual}'."

5. Ejemplos de integración

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

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

?>
Python
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}")
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 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();
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
    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