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:
- Pase obligatorio: Absolutamente todos los servicios de nuestro sistema te exigirán esta llave antes de procesar tus peticiones.
- Vigencia limitada (1 hora): Por tu seguridad, el token tiene un ciclo de vida corto para evitar accesos no autorizados prolongados.
- Renovación continua: Cuando el tiempo se agote, tu sistema simplemente debe solicitar uno nuevo a través de esta sección para seguir trabajando sin interrupciones.
¡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