# API Pública CartecWeb

Documentación de la API REST para integración con sistemas externos.

---

## Información General

| Concepto | Valor |
|----------|-------|
| **URL Base** | `http://192.168.100.87:8080/api` |
| **Formato** | JSON |
| **Autenticación** | Ninguna (modo pruebas) |
| **Límite** | 60 peticiones/minuto |
| **Versión** | 1.0.0 |

---

## Endpoints

### 1. Estado del Servicio

Verificar que la API está operativa.

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/health` |

**Parámetros Query:**

| Parámetro | Tipo | Descripción |
|-----------|------|-------------|
| `db` | int | Si es `1`, prueba conexión a base de datos |

**Ejemplos:**
```bash
# Sin prueba de BD
curl http://192.168.100.87:8080/api/health

# Con prueba de BD
curl "http://192.168.100.87:8080/api/health?db=1"
```

**Respuesta:**
```json
{
  "success": true,
  "message": "API CartecWeb operativa",
  "version": "1.0.0",
  "timestamp": "2026-02-03T12:00:00-03:00",
  "db": "connected"
}
```

---

### 2. Listar Órdenes de Trabajo

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/ot/list` |

**Parámetros Query:**

| Parámetro | Tipo | Por defecto | Descripción |
|-----------|------|-------------|-------------|
| `estado` | string | - | Filtrar: `pendiente`, `completado`, `cancelado` |
| `rut_tecnico` | string | - | Filtrar por RUT del técnico |
| `limit` | int | 10 | Cantidad máxima de resultados (máx: 100) |

**Ejemplo:**
```bash
curl "http://192.168.100.87:8080/api/ot/list?estado=pendiente&limit=20"
curl "http://192.168.100.87:8080/api/ot/list?rut_tecnico=11111111-1"
```

**Respuesta:**
```json
{
  "success": true,
  "count": 5,
  "data": [
    {
      "id_ot": 1655,
      "rut_cliente": "12345678-5",
      "rut_tecnico": "11111111-1",
      "empresa": "gpsimple",
      "estado_ot": "pendiente",
      "motivo": "Instalación GPS",
      "creado_en": "2026-02-03 10:00:00"
    }
  ]
}
```

---

### 3. Últimas 10 Órdenes de Trabajo

Devuelve las 10 OT más recientes (por `id_ot` descendente).

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/ot/latest` |

**Ejemplo:**
```bash
curl http://192.168.100.87:8080/api/ot/latest
```

**Respuesta:** Igual estructura que `/api/ot/list` (count + data con hasta 10 registros).

---

### 4. Detalle de Orden de Trabajo

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/ot/{id}` |

**Ejemplo:**
```bash
curl http://192.168.100.87:8080/api/ot/1655
```

**Respuesta:**
```json
{
  "success": true,
  "data": {
    "ot": {
      "id_ot": 1655,
      "rut_cliente": "12345678-5",
      "rut_tecnico": "11111111-1",
      "empresa": "gpsimple",
      "taller": "domicilio",
      "estado_ot": "pendiente",
      "direccion_instalacion": "Av. Providencia 123",
      "comuna_instalacion": "Providencia",
      "motivo": "Instalación GPS"
    },
    "cliente": {
      "rut_cliente": "12345678-5",
      "nombre_cliente": "Juan Cliente"
    },
    "vehiculos": [
      {"id_ot": 1655, "patente": "ABCD12"}
    ]
  }
}
```

---

### 5. Crear Orden de Trabajo

| Método | Endpoint |
|--------|----------|
| `POST` | `/api/ot/create` |

**Cuerpo de la Petición:**
```json
{
  "cliente": {
    "rut": "12345678-5",
    "nombre": "Juan Cliente",
    "direccion": "Av. Providencia 123",
    "comuna": "Providencia",
    "telefono": "+56912345678",
    "email": "cliente@email.cl"
  },
  "tecnico": {
    "rut": "11111111-1"
  },
  "servicio": {
    "presGPS": "gpsimple",
    "tiposerv": "instalacion_gps",
    "taller_install": "domicilio"
  },
  "vehiculos": [
    {
      "patente": "ABCD12",
      "marca": "Toyota",
      "modelo": "Corolla",
      "color": "Blanco",
      "anio": 2020
    }
  ]
}
```

**Campos Cliente:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `rut` | string | **Sí** | RUT chileno |
| `nombre` | string | **Sí** | Nombre completo |
| `direccion` | string | **Sí** | Dirección |
| `comuna` | string | **Sí** | Comuna |
| `telefono` | string | No | Teléfono |
| `email` | string | No | Correo electrónico |

**Campos Técnico:**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `rut` | string | **Sí** | RUT del técnico asignado |

**Campos Servicio:**

| Campo | Tipo | Requerido | Valores permitidos |
|-------|------|-----------|-------------------|
| `presGPS` | string | **Sí** | `gpsimple`, `entel`, `tattersall`, `cemin`, `carflex` |
| `tiposerv` | string | **Sí** | `instalacion_gps`, `desinstalacion_gps`, `visita_tecnica`, `visita_fallida`, `servicio_mecanico` |
| `taller_install` | string | **Sí** | `cartec`, `domicilio`, `taller_externo` |

**Campos Vehículo (arreglo):**

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `patente` | string | **Sí** | Patente del vehículo |
| `marca` | string | No | Marca |
| `modelo` | string | No | Modelo |
| `color` | string | No | Color |
| `anio` | int | No | Año |

**Ejemplo:**
```bash
curl -X POST http://192.168.100.87:8080/api/ot/create \
  -H "Content-Type: application/json" \
  -d '{
    "cliente": {"rut": "12345678-5", "nombre": "Test", "direccion": "Av. Test 123", "comuna": "Santiago"},
    "tecnico": {"rut": "11111111-1"},
    "servicio": {"presGPS": "gpsimple", "tiposerv": "instalacion_gps", "taller_install": "domicilio"},
    "vehiculos": [{"patente": "TEST99"}]
  }'
```

**Respuesta (201):**
```json
{
  "success": true,
  "message": "Orden de trabajo creada exitosamente",
  "id_ot": 1656
}
```

---

### 6. Completar Orden de Trabajo

| Método | Endpoint |
|--------|----------|
| `PATCH` | `/api/ot/{id}/complete` |

**Cuerpo de la Petición:**
```json
{
  "hora_llegada": "09:30",
  "hora_salida": "11:45",
  "observaciones": "Instalación exitosa",
  "firma": {
    "rut": "12345678-5",
    "nombre": "Juan Cliente",
    "imagen": "data:image/png;base64,iVBORw0..."
  }
}
```

| Campo | Tipo | Requerido | Descripción |
|-------|------|-----------|-------------|
| `hora_llegada` | string | No | Formato HH:mm |
| `hora_salida` | string | No | Formato HH:mm |
| `observaciones` | string | No | Máximo 1000 caracteres |
| `firma.rut` | string | Si hay firma | RUT del firmante |
| `firma.nombre` | string | Si hay firma | Nombre del firmante |
| `firma.imagen` | string | Si hay firma | Imagen en Base64 (PNG/JPEG) |

**Ejemplo:**
```bash
curl -X PATCH http://192.168.100.87:8080/api/ot/1655/complete \
  -H "Content-Type: application/json" \
  -d '{"hora_llegada": "09:00", "hora_salida": "10:30", "observaciones": "OK"}'
```

---

### 7. Obtener Cliente por RUT

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/cliente/{rut}` |

**Ejemplo:**
```bash
curl http://192.168.100.87:8080/api/cliente/12345678-5
```

**Respuesta:**
```json
{
  "success": true,
  "data": {
    "rut_cliente": "12345678-5",
    "nombre_cliente": "Juan Cliente",
    "direccion_cliente": "Av. Providencia 123",
    "comuna_cliente": "Providencia"
  }
}
```

---

### 8. Posición GPS por IMEI

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/gps/position/{imei}` |

**Ejemplo:**
```bash
curl http://192.168.100.87:8080/api/gps/position/123456789012345
```

**Respuesta:**
```json
{
  "success": true,
  "data": {
    "imei": "123456789012345",
    "lat": "-33.4489",
    "lng": "-70.6693",
    "dt_tracker": "2026-02-03 12:30:00"
  }
}
```

---

### 9. Info GPS por ID

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/gps/info/{id}` |

---

### 10. Datos Vehículo por VIN

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/vehiculo/vin/{vin}` |

**Ejemplo:**
```bash
curl http://192.168.100.87:8080/api/vehiculo/vin/3TMJU62N39M043123
```

---

### 11. Listar Técnicos

| Método | Endpoint |
|--------|----------|
| `GET` | `/api/tecnicos` |

**Respuesta:**
```json
{
  "success": true,
  "count": 5,
  "data": [
    {"id": 1, "nombre": "Juan Pérez", "email": "juan@cartec.cl", "rut": "11111111-1"}
  ]
}
```

---

## Códigos HTTP

| Código | Significado |
|--------|-------------|
| `200` | OK - Petición exitosa |
| `201` | Creado - Recurso creado correctamente |
| `400` | Solicitud incorrecta - Datos inválidos |
| `404` | No encontrado - Recurso no existe |
| `422` | Entidad no procesable - Error de validación |
| `500` | Error del servidor |

---

## Notas Importantes

1. **RUT**: Se acepta con o sin guión (`12345678-5` o `123456785`). Se valida con algoritmo Módulo 11.
2. **UPSERT Cliente**: Si el cliente no existe en la base de datos, se crea automáticamente. Si ya existe, se actualizan sus datos.
3. **Base64**: Para firmas, puede incluir o no el prefijo `data:image/...;base64,`

---

## Pruebas Rápidas

```bash
# Estado del servicio (sin BD)
curl http://192.168.100.87:8080/api/health

# Estado del servicio (con BD)
curl "http://192.168.100.87:8080/api/health?db=1"

# Listar OTs
curl http://192.168.100.87:8080/api/ot/list

# Últimas 10 OT creadas
curl http://192.168.100.87:8080/api/ot/latest

# Ver detalle de OT
curl http://192.168.100.87:8080/api/ot/1655

# Crear OT
curl -X POST http://192.168.100.87:8080/api/ot/create \
  -H "Content-Type: application/json" \
  -d '{
    "cliente": {"rut": "12345678-5", "nombre": "Test", "direccion": "Test 123", "comuna": "Santiago"},
    "tecnico": {"rut": "11111111-1"},
    "servicio": {"presGPS": "gpsimple", "tiposerv": "instalacion_gps", "taller_install": "domicilio"},
    "vehiculos": [{"patente": "TEST99"}]
  }'

# Completar OT
curl -X PATCH http://192.168.100.87:8080/api/ot/1655/complete \
  -H "Content-Type: application/json" \
  -d '{"hora_llegada": "09:00", "hora_salida": "10:30"}'

# Obtener cliente
curl http://192.168.100.87:8080/api/cliente/12345678-5

# Listar técnicos
curl http://192.168.100.87:8080/api/tecnicos
```

---

**Versión:** 1.0.0  
**Última actualización:** Febrero 2026