# Asociación de usuarios V12 con la plataforma Induxsoft

## Introducción

Para que los usuarios de un sistema V12 o de cualquier sistema de terceros puedan acceder a los servicios en la nube de Induxsoft que requieren 
autenticación por perfil sin necesidad de reintroducir las credenciales, es necesario obtener una **sesión Induxsoft** válida.

Este documento describe el mecanismo de asociación entre usuarios externos y Perfiles Induxsoft, los dos flujos de autenticación disponibles, y 
la especificación técnica completa del endpoint de integración.

---

## Conceptos clave

| Concepto | Descripción |
|----------|-------------|
| **Perfil Induxsoft** | Identidad de un usuario en la plataforma cloud de Induxsoft. Se identifica por correo electrónico, número de teléfono o ID de perfil. |
| **Sesión Induxsoft (`induxsoft_sid`)** | Token de sesión de corta duración que otorga acceso a los servicios cloud de Induxsoft. Se obtiene mediante el endpoint descrito en este documento y se usa como credencial en todos los demás endpoints. |
| **Token secreto de larga duración (`secret`)** | Credencial generada desde el Portal Administrativo de Induxsoft, asociada a un Perfil. Permite obtener sesiones sin contraseña. Equivale a una clave de API personal. |
| **Servicio V12 en la nube (`svc_id`)** | Identificador de una instancia V12 alojada en la infraestructura cloud de Induxsoft. |
| **Sesión V12 (`ids`)** | Token de sesión emitido por una instancia V12 cloud al autenticar a un usuario. |

---

## Endpoint de autenticación

```
POST https://api.induxsoft.net/auth/from-v12/
Content-Type: application/json
```

Este endpoint unificado soporta dos modalidades de autenticación según el contexto del sistema integrador.

---

### Modalidad 1: V12 cloud (sesión V12 → sesión Induxsoft)

Para instancias V12 alojadas en la nube de Induxsoft. El usuario ya tiene una sesión V12 activa y se desea obtener una sesión Induxsoft 
equivalente para acceder a servicios cloud.

**Requisito previo:** El usuario V12 debe estar asociado previamente a un Perfil Induxsoft desde el Portal Administrativo de la nube V12.

**Request:**
```json
POST https://api.induxsoft.net/auth/from-v12/
{
  "svc_id": "Id de servicio V12 en la nube",
  "ids": "Id de sesión de usuario de V12"
}
```

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `svc_id` | string | Identificador de la instancia V12 cloud. Se obtiene en el Portal Administrativo de la instancia. |
| `ids` | string | Token de sesión activo del usuario en V12. Se obtiene al autenticar al usuario en V12. |

**Funcionamiento interno:**
1. Induxsoft valida que `svc_id` corresponde a una instancia V12 cloud activa
2. Valida que `ids` es una sesión V12 activa para esa instancia
3. Recupera el Perfil Induxsoft asociado al usuario de esa sesión
4. Emite y retorna una sesión Induxsoft

---

### Modalidad 2: Token secreto (para V12 on-premise y sistemas de terceros)

Para instancias V12 on-premise o cualquier sistema externo que requiera acceder a servicios cloud de Induxsoft en nombre de un usuario. 
No requiere sesión V12 previa.

**Requisito previo:** El Perfil Induxsoft debe tener un token secreto de larga duración generado desde el Portal Administrativo.

**Request:**
```json
POST https://api.induxsoft.net/auth/from-v12/
{
  "uid": "correo@ejemplo.com",
  "secret": "token_secreto_de_larga_duracion"
}
```

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `uid` | string | Correo electrónico, número de teléfono o ID del Perfil Induxsoft. |
| `secret` | string | Token secreto de larga duración asociado al perfil. |

**Funcionamiento interno:**
1. Induxsoft localiza el Perfil por `uid`
2. Valida que `secret` es un token activo asociado a ese perfil
3. Valida la IP de origen contra la IP registrada en el token (si aplica)
4. Emite y retorna una sesión Induxsoft

---

### Respuesta (ambas modalidades)

```json
{
  "success": true,
  "data": {
    "induxsoft_sid": "Id de sesión del perfil de Induxsoft",
    "profile": "Id del perfil de Induxsoft",
    "name": "Nombre del usuario del perfil"
  }
}
```

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `success` | boolean | `true` si la autenticación fue exitosa, `false` en caso contrario. |
| `data.induxsoft_sid` | string | Token de sesión Induxsoft. Usar como credencial en todos los servicios cloud de Induxsoft. Tiene duración limitada. |
| `data.profile` | string | ID único del Perfil Induxsoft autenticado. |
| `data.name` | string | Nombre del usuario asociado al perfil. |

**Respuesta en caso de error:**
```json
{
  "success": false,
  "message": "Mensaje descriptivo del error"
}
```

---

## Uso del `induxsoft_sid`

Una vez obtenido, el `induxsoft_sid` se usa como credencial de autorización en todos los endpoints de servicios cloud de Induxsoft:

```
GET https://api.induxsoft.net/[servicio]/
Authorization: Bearer {induxsoft_sid}
```

El `induxsoft_sid` tiene una duración limitada. Cuando expire, el sistema integrador debe obtener uno nuevo llamando nuevamente al endpoint de autenticación.

---

## Configuración del token secreto (Modalidad 2)

Para sistemas que requieran la Modalidad 2, el propietario del Perfil Induxsoft debe generar un token secreto desde el Portal Administrativo:

1. Ingrese al Portal Administrativo de Induxsoft
2. Navegue a su Perfil → sección "Tokens de acceso"
3. Haga clic en "Generar token"
4. Configure la IP (o lista de IPs) permitida(s) si desea restricción por origen (recomendado)
5. **Copie el token inmediatamente** — por seguridad se muestra una sola vez

Si el token se pierde, debe revocarlo y generar uno nuevo.

---

## Seguridad

### Recomendaciones

- **Nunca exponga el `secret` en código fuente, logs o interfaces públicas.** Trátelo como una contraseña.
- **Utilice restricción por IP** al generar tokens para sistemas on-premise o de terceros. Esto limita el uso del token a solicitudes originadas desde una IP específica.
- **Rote los tokens periódicamente** y siempre que sospeche que pudieron ser comprometidos. La revocación es inmediata desde el Portal Administrativo.
- **El `induxsoft_sid` es de corta duración** — no lo almacene de forma persistente. Obtenga uno nuevo cuando sea necesario.
- **Toda comunicación debe realizarse sobre HTTPS.** Las solicitudes HTTP sin cifrado serán rechazadas.

### Auditoría

Cada solicitud al endpoint de autenticación queda registrada en la plataforma cloud de Induxsoft. El administrador del perfil puede consultar el historial de accesos desde el Portal Administrativo, incluyendo fecha, hora, IP de origen y resultado de cada solicitud.

---

## Resumen de flujos

```
Sistema externo / V12 on-premise          V12 cloud
          │                                    │
          │  uid + secret                      │  svc_id + ids
          │                                    │
          └────────────────┬───────────────────┘
                           │
                           ▼
             POST /auth/from-v12/
                           │
                           ▼
              { success, induxsoft_sid,
                profile, name }
                           │
                           ▼
          Usar induxsoft_sid en servicios cloud
```

---

## Preguntas frecuentes

**¿Puedo usar este endpoint desde cualquier lenguaje o plataforma?**
Sí. Es un endpoint HTTP/REST estándar que acepta y retorna JSON. Compatible con cualquier lenguaje o plataforma que soporte solicitudes HTTP.

**¿Con qué frecuencia debo llamar al endpoint?**
Solo cuando necesite obtener o renovar una sesión. El `induxsoft_sid` tiene duración limitada — obtenga uno nuevo cuando expire o antes de realizar operaciones críticas.

**¿Puedo usar el mismo token secreto desde múltiples servidores?**
Depende de si configuró restricción por IP al generar el token. Si usó restricción, el token solo funcionará desde la IP registrada. Si necesita acceso desde múltiples IPs, genere un token por origen o un token sin restricción de IP (menos recomendado).

**¿Qué sucede si el Perfil Induxsoft asociado es desactivado?**
El endpoint retornará `success: false` para cualquier intento de autenticación con credenciales asociadas a ese perfil.