# API REST Ultranav - Guía del Usuario Final

## 📋 Descripción General

La API REST Ultranav es un servicio web que proporciona acceso a datos de asistencia de empleados desde la base de datos de Producción. Permite consultar registros de marcas de entrada/salida, tiempos de almuerzo y otras métricas de asistencia.

**URL Base:** `https://ultranav.smartime.cl`

---

## 🔐 Autenticación

Todos los requests a la API requieren autenticación mediante token Bearer en el header `Authorization`.

### Token de Autenticación
```
c06ab5c4a51ba98ac02151518cd2ecc06c38e3d24e3d10346bacf9b6210a78c7
```

### Formato del Header
```
Authorization: Bearer c06ab5c4a51ba98ac02151518cd2ecc06c38e3d24e3d10346bacf9b6210a78c7
```

---

## 📡 Endpoints Disponibles

### 1. Health Check (Verificación de Estado)

**Endpoint:** `GET /health`

**Descripción:** Verifica que la API esté operativa.

**Headers:**
```
Content-Type: application/json
```

**Respuesta exitosa (200):**
```json
{
  "status": "ok"
}
```

---

### 2. Resumen de Asistencia

**Endpoint:** `POST /api/v1/asistencia/resumen`

**Descripción:** Obtiene registros de asistencia de empleados para un rango de fechas específico.

**Headers requeridos:**
```
Authorization: Bearer c06ab5c4a51ba98ac02151518cd2ecc06c38e3d24e3d10346bacf9b6210a78c7
Content-Type: application/json
```

**Body (JSON):**
```json
{
  "fecha": "01-01-2026 - 31-01-2026",
  "idNodo": null
}
```

**Parámetros:**

| Parámetro | Tipo | Requerido | Descripción |
|-----------|------|-----------|-------------|
| `fecha` | string | Sí | Rango de fechas en formato "dd-mm-yyyy - dd-mm-yyyy" |
| `idNodo` | number/null | No | ID del nodo. Si es null, usa 26338 por defecto |

**Restricciones:**
- El rango de fechas no puede exceder 30 días
- Formato de fecha obligatorio: `dd-mm-yyyy - dd-mm-yyyy`

**Respuesta exitosa (200):**
```json
{
  "data": [
    {
      "obs": 1,
      "division": "Humboldt - Viña del Mar",
      "nombre": "JUAN PÉREZ GARCÍA",
      "rut": "12345678-9",
      "fecha": "06/01/2026",
      "marca_entrada": "08:30:00",
      "marca_salida": "17:00:00",
      "salida_almorzar": "12:30:00",
      "llegada_almorzar": "13:30:00",
      "tiempo_antes_almuerzo": "04:00:00",
      "almuerzo": "01:00:00",
      "tiempo_despues_almuerzo": "03:30:00"
    }
  ],
  "count": 1,
  "filters": {
    "fecha_inicio": "01-01-2026",
    "fecha_fin": "31-01-2026",
    "id_nodo": 26338
  }
}
```

**Campos de respuesta:**

| Campo | Descripción |
|-------|-------------|
| `obs` | Número de observación/registro |
| `division` | Departamento o división del empleado |
| `nombre` | Nombre completo del empleado |
| `rut` | RUT del empleado |
| `fecha` | Fecha del registro (formato dd/mm/yyyy) |
| `marca_entrada` | Hora de entrada (HH:MM:SS) |
| `marca_salida` | Hora de salida (HH:MM:SS) |
| `salida_almorzar` | Hora de salida a almuerzo (HH:MM:SS) |
| `llegada_almorzar` | Hora de llegada del almuerzo (HH:MM:SS) |
| `tiempo_antes_almuerzo` | Tiempo trabajado antes del almuerzo |
| `almuerzo` | Duración del almuerzo |
| `tiempo_despues_almuerzo` | Tiempo trabajado después del almuerzo |

---

## 🔴 Códigos de Error

| Código HTTP | Mensaje | Causa | Solución |
|-------------|---------|-------|----------|
| 400 | Request body is required | Body JSON vacío | Incluir body JSON en la solicitud |
| 400 | fecha is required | Parámetro fecha faltante | Agregar parámetro "fecha" |
| 400 | fecha format must be: dd-mm-yyyy - dd-mm-yyyy | Formato de fecha incorrecto | Usar formato exacto: "dd-mm-yyyy - dd-mm-yyyy" |
| 400 | Date range cannot exceed 30 days | Rango de fechas > 30 días | Reducir el rango a máximo 30 días |
| 401 | Missing authorization token | Header Authorization faltante | Agregar header Authorization con token Bearer |
| 401 | Invalid authorization token | Token Bearer incorrecto | Verificar que el token sea correcto |
| 500 | Error processing request | Error en la base de datos | Contactar al administrador |

---

## 💻 Ejemplos de Uso

### Ejemplo 1: cURL

```bash
curl -X POST https://ultranav.smartime.cl/api/v1/asistencia/resumen \
  -H "Authorization: Bearer c06ab5c4a51ba98ac02151518cd2ecc06c38e3d24e3d10346bacf9b6210a78c7" \
  -H "Content-Type: application/json" \
  -d '{
    "fecha": "01-01-2026 - 31-01-2026",
    "idNodo": null
  }'
```

### Ejemplo 2: Python

```python
import requests
import json

url = "https://ultranav.smartime.cl/api/v1/asistencia/resumen"
headers = {
    "Authorization": "Bearer c06ab5c4a51ba98ac02151518cd2ecc06c38e3d24e3d10346bacf9b6210a78c7",
    "Content-Type": "application/json"
}
data = {
    "fecha": "01-01-2026 - 31-01-2026",
    "idNodo": None
}

response = requests.post(url, headers=headers, json=data)
print(json.dumps(response.json(), indent=2))
```

### Ejemplo 3: JavaScript/Node.js

```javascript
const token = "c06ab5c4a51ba98ac02151518cd2ecc06c38e3d24e3d10346bacf9b6210a78c7";
const url = "https://ultranav.smartime.cl/api/v1/asistencia/resumen";

const options = {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    fecha: "01-01-2026 - 31-01-2026",
    idNodo: null
  })
};

fetch(url, options)
  .then(response => response.json())
  .then(data => console.log(JSON.stringify(data, null, 2)))
  .catch(error => console.error("Error:", error));
```

### Ejemplo 4: Postman Web

1. Abre https://web.postman.co/
2. Crea una nueva request POST
3. URL: `https://ultranav.smartime.cl/api/v1/asistencia/resumen`
4. Tab "Headers":
   - Key: `Authorization`
   - Value: `Bearer c06ab5c4a51ba98ac02151518cd2ecc06c38e3d24e3d10346bacf9b6210a78c7`
   - Key: `Content-Type`
   - Value: `application/json`
5. Tab "Body" → Raw → JSON:
   ```json
   {
     "fecha": "01-01-2026 - 31-01-2026",
     "idNodo": null
   }
   ```
6. Click "Send"

---

## 📊 Casos de Uso Comunes

### Consultar asistencia de enero 2026
```json
{
  "fecha": "01-01-2026 - 31-01-2026",
  "idNodo": null
}
```

### Consultar asistencia de una semana específica
```json
{
  "fecha": "20-01-2026 - 26-01-2026",
  "idNodo": 26338
}
```

### Consultar asistencia de un nodo específico
```json
{
  "fecha": "15-01-2026 - 20-01-2026",
  "idNodo": 12345
}
```

---

## ⚙️ Información Técnica

**Protocolo:** HTTPS (SSL/TLS)  
**Método de autenticación:** Bearer Token (SHA256)  
**Formato de respuesta:** JSON  
**Zona horaria:** UTC-3 (Chile)  
**Base de datos:** SQL Server (Produccion)  
**Servidor:** ultranav.smartime.cl  
**Puerto:** 443 (HTTPS)

---

## 📞 Soporte y Contacto

Para reportar problemas o solicitar cambios en la API, contactar al equipo de desarrollo.

**Logs del servicio:**
```bash
journalctl -u ultranav-api.service -f
```

**Verificar estado del servicio:**
```bash
systemctl status ultranav-api.service
```

---

## 📝 Notas Importantes

- La API requiere conexión HTTPS (certificado SSL válido)
- El token Bearer es obligatorio para acceder a `/api/v1/asistencia/resumen`
- El endpoint `/health` no requiere autenticación
- Los datos se devuelven en formato JSON
- La API está disponible 24/7 con reinicio automático ante fallos
- Máximo 30 días por consulta para optimizar rendimiento

---

**Versión:** 1.0  
**Fecha de creación:** 22 de enero de 2026  
**Estado:** Producción