Autenticación

Bienvenido al filtro de seguridad de nuestra API. Antes de consultar o enviar información, necesitamos validar que tu conexión tenga los permisos necesarios para proteger tus datos en todo momento.

¿Cómo funciona el acceso? Piensa en esta sección como la recepción de un edificio privado. Aquí te explicamos cómo tu aplicación debe "identificarse" para obtener un token (tu llave de acceso temporal).

Reglas clave de tu token de acceso:

¡Explora cómo generar tu primera llave para comenzar a integrarte de forma segura!

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"
}
username Es el ID del Cliente (OAuth2) que generaste previamente en el sistema.
password Es la Clave Secreta (Secret Key / OAuth2) vinculada a tu usuario.

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
}
token Tu llave de acceso. A partir de ahora, en todas tus siguientes consultas a nuestra plataforma, deberás incluir este código en los encabezados (Headers) de tu petición usando el formato: Authorization: Bearer TU_TOKEN_AQUI
expiration La fecha y hora exacta (en formato timestamp) en la que este pase dejará de funcionar.
message Mensaje de confirmación o texto explicativo (en caso de presentarse alguna novedad).

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

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