# Autenticación

<span>Bienvenido al </span>**filtro de seguridad**<span> 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.</span>

**¿Cómo funciona el acceso?**<span> 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 </span>**token**<span> (tu llave de acceso temporal).</span>

**Reglas clave de tu token de acceso:**

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

¡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).

<p class="callout warning">**¿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í](https://docs.nuby.ai/books/herramientas/page/como-crear-un-nuevo-cliente-oauth2-en-nuby-para-consumo-de-la-api).</p>

---

#### **1. El Endpoint (La dirección web)**

Apunta tu sistema a la siguiente dirección. Recuerda reemplazar <span style="color: rgb(241, 196, 15);">**{{instancia}}**</span> por la dirección web completa que utilizas para ingresar a tu plataforma.

```http
POST https://{{instancia}}/service/v2/public/auth/login
```

<p class="callout info">**¿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.</p>

#### **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í:

```json
{
    "username": "TU_CLIENT_ID",
    "password": "TU_SECRET_KEY"
}
```

<table border="1" id="bkmrk-username-es-el-id-de" style="border-collapse: collapse; width: 100%;"><colgroup> <col style="width: 20%;"></col> <col style="width: 80%;"></col> </colgroup><tbody><tr><td>**username**</td><td>Es el **ID del Cliente** (OAuth2) que generaste previamente en el sistema.</td></tr><tr><td>**password**</td><td>Es la **Clave Secreta** (Secret Key / OAuth2) vinculada a tu usuario.</td></tr></tbody></table>

#### **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:

```json
{
  "message": null,
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "expiration": 1690540790
}
```

<table border="1" id="bkmrk-token-tu-llave-de-ac" style="border-collapse: collapse; width: 100%;"><colgroup> <col style="width: 20%;"></col> <col style="width: 80%;"></col> </colgroup><tbody><tr><td>**token**</td><td>**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`</td></tr><tr><td>**expiration**</td><td>La fecha y hora exacta (en formato *timestamp*) en la que este pase dejará de funcionar.</td></tr><tr><td>**message**</td><td>Mensaje de confirmación o texto explicativo (en caso de presentarse alguna novedad).</td></tr></tbody></table>

#### **4. Seguridad y Posibles Errores**

<p class="callout danger">**¡Tu pase tiene fecha de caducidad!**</p>

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:

```json
{
    "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:

<details id="bkmrk-ejemplo-usando-curl-"><summary>cURL</summary>

```bash
curl -X POST "https://{{instancia}}/service/v2/public/auth/login" \
-H "Content-Type: application/json" \
-d '{
  "username": "TU_CLIENT_ID", 
  "password": "TU_SECRET_KEY"
}'
```

</details><details id="bkmrk-ejemplo-usando-php-%3C"><summary>PHP</summary>

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

?>
```

</details><details id="bkmrk-python-import-reques"><summary>Python</summary>

```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}")

```

</details><details id="bkmrk-javascript-%2F%2F-1.-con"><summary>JavaScript</summary>

```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();

```

</details><details id="bkmrk-power-query-m-%28excel"><summary>Power Query M (Excel / Power BI)</summary>

```powerquery
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
```

</details>