# API de Seguros Vehiculares - Documentación para DisaShop

## Tabla de Contenidos
1. [Introducción](#introducción)
2. [Autenticación](#autenticación)
3. [URL Base](#url-base)
4. [Flujo Completo de Transacción](#flujo-completo-de-transacción)
5. [Endpoints](#endpoints)
6. [Códigos de Respuesta](#códigos-de-respuesta)
7. [Manejo de Errores](#manejo-de-errores)
8. [Ejemplos de Integración](#ejemplos-de-integración)

---

## Introducción

Esta API permite la emisión automática de pólizas de seguros vehiculares a través de kioskos DisaShop. La integración está diseñada para ser simple y guiar al usuario paso a paso desde la selección del plan hasta la emisión de la póliza.

### Características Principales
- ✅ Validación de datos con MasterOne en tiempo real
- ✅ Verificación por OTP (código de 6 dígitos)
- ✅ Cotización instantánea
- ✅ Emisión de póliza automática
- ✅ Envío de documentos por WhatsApp al cliente

---

## Autenticación

Todas las peticiones a la API requieren dos headers de autenticación:

```http
X-API-Key: su_api_key
X-API-Secret: su_api_secret
```

**Ejemplo:**
```javascript
const headers = {
    'Content-Type': 'application/json',
    'X-API-Key': '13116e49c22e1ffe0885a3634a7c34d3faa29ccfc99f2896eb9202a5b487c49d',
    'X-API-Secret': '9ef94cf5a727e3d0132bb849c0af05650dbeb894246b0b97e79e025900fe5ea0'
};
```

**Nota:** Sus credenciales reales serán proporcionadas por el administrador del sistema.

---

## URL Base

```
https://www.redbajasusa.com/segurosapi/api
```

---

## Flujo Completo de Transacción

El proceso de venta de una póliza sigue estos pasos:

```
1. Consultar Planes Disponibles (GET /products)
   ↓
2. Iniciar Transacción (POST /start-transaction)
   ↓
3. Validar Datos del Cliente (POST /validate-data)
   ↓
4. Enviar Código OTP (POST /send-otp)
   ↓
5. Validar Código OTP (POST /validate-otp)
   ↓
6. Consultar Estado/Cotización (GET /transaction-status)
   ↓
7. Procesar Pago (POST /process-payment)
   ↓
8. Emitir Póliza (POST /emit-policy)
   ↓
9. [Opcional] Descargar Documentos (GET /download-document)
```

---

## Endpoints

### 1. Consultar Planes Disponibles

Obtiene la lista de planes de seguros disponibles según el tipo de vehículo.

**Endpoint:** `GET /products`

**Parámetros Query:**
- `tipo_vehiculo` (requerido): `automovil` o `motocicleta`

**Ejemplo de Petición:**
```javascript
const response = await fetch('https://www.redbajasusa.com/segurosapi/api/products?tipo_vehiculo=automovil', {
    headers: {
        'X-API-Key': 'su_api_key',
        'X-API-Secret': 'su_api_secret'
    }
});
const data = await response.json();
```

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "data": [
        {
            "id": 1,
            "nombre": "Plan Básico",
            "tipo_vehiculo": "automovil",
            "tipo_cobertura": "responsabilidad_civil",
            "vigencia_meses": 12,
            "activo": true
        },
        {
            "id": 2,
            "nombre": "Plan Premium",
            "tipo_vehiculo": "automovil",
            "tipo_cobertura": "todo_riesgo",
            "vigencia_meses": 12,
            "activo": true
        }
    ],
    "timestamp": "2025-11-04 10:30:00"
}
```

---

### 2. Iniciar Transacción

Crea una nueva transacción en el sistema.

**Endpoint:** `POST /start-transaction`

**Body (JSON):**
```json
{
    "tipo_vehiculo": "automovil",
    "tipo_cobertura": "1",
    "cedula": "00112345678",
    "telefono": "8091234567",
    "placa": "A123456",
    "incluye_grua": false,
    "incluye_casa_conductor": false,
    "disashop_id": "KIOSKO_001"
}
```

**Parámetros:**
- `tipo_vehiculo` (string, requerido): `automovil` o `motocicleta`
- `tipo_cobertura` (string, requerido): ID del plan seleccionado
- `cedula` (string, requerido): Cédula sin guiones (11 dígitos)
- `telefono` (string, requerido): Teléfono sin guiones (10 dígitos)
- `placa` (string, requerido): Placa del vehículo (máx 10 caracteres)
- `incluye_grua` (boolean, requerido): Servicio de grúa
- `incluye_casa_conductor` (boolean, requerido): Servicio casa del conductor
- `disashop_id` (string, requerido): Identificador del kiosko

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "data": {
        "transaction_id": "TXN-20251104-ABC123",
        "estado": "iniciado"
    },
    "timestamp": "2025-11-04 10:31:00"
}
```

---

### 3. Validar Datos del Cliente

Valida que los datos del cliente existan en MasterOne.

**Endpoint:** `POST /validate-data`

**Body (JSON):**
```json
{
    "transaction_id": "TXN-20251104-ABC123",
    "cedula": "00112345678",
    "placa": "A123456"
}
```

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "data": {
        "individuo": {
            "nombre_completo": "JUAN PEREZ GARCIA",
            "nombre_oculto": "JUAN P******* G******",
            "cedula": "00112345678"
        },
        "vehiculo": {
            "placa": "A123456",
            "marca": "TOYOTA",
            "modelo": "COROLLA",
            "año": 2020,
            "descripcion_oculta": "TOYOTA COR**** 2020"
        }
    },
    "timestamp": "2025-11-04 10:32:00"
}
```

**Respuesta de Error (400):**
```json
{
    "success": false,
    "error": "Los datos no coinciden en el sistema MasterOne",
    "timestamp": "2025-11-04 10:32:00"
}
```

---

### 4. Enviar Código OTP

Envía un código de verificación de 6 dígitos al teléfono del cliente.

**Endpoint:** `POST /send-otp`

**Body (JSON):**
```json
{
    "transaction_id": "TXN-20251104-ABC123"
}
```

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "data": {
        "mensaje": "Código OTP enviado al teléfono registrado"
    },
    "timestamp": "2025-11-04 10:33:00"
}
```

**Nota:** El código OTP es válido por 10 minutos.

---

### 5. Validar Código OTP

Verifica el código OTP ingresado por el cliente.

**Endpoint:** `POST /validate-otp`

**Body (JSON):**
```json
{
    "transaction_id": "TXN-20251104-ABC123",
    "codigo": "123456"
}
```

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "data": {
        "mensaje": "Código OTP verificado correctamente"
    },
    "timestamp": "2025-11-04 10:34:00"
}
```

**Respuesta de Error (400):**
```json
{
    "success": false,
    "error": "Código OTP incorrecto o expirado",
    "timestamp": "2025-11-04 10:34:00"
}
```

---

### 6. Consultar Estado de Transacción

Obtiene el estado actual de la transacción y la cotización.

**Endpoint:** `GET /transaction-status`

**Parámetros Query:**
- `transaction_id` (requerido): ID de la transacción

**Ejemplo de Petición:**
```javascript
const response = await fetch(
    'https://www.redbajasusa.com/segurosapi/api/transaction-status?transaction_id=TXN-20251104-ABC123',
    {
        headers: {
            'X-API-Key': 'su_api_key',
            'X-API-Secret': 'su_api_secret'
        }
    }
);
```

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "data": {
        "transaction_id": "TXN-20251104-ABC123",
        "estado": "otp_validado",
        "producto_nombre": "Plan Básico",
        "cedula": "00112345678",
        "telefono": "8091234567",
        "placa": "A123456",
        "incluye_grua": false,
        "incluye_casa_conductor": false,
        "monto_total": 12500.00,
        "fecha_creacion": "2025-11-04 10:31:00"
    },
    "timestamp": "2025-11-04 10:35:00"
}
```

---

### 7. Procesar Pago

Marca el pago como recibido en el sistema.

**Endpoint:** `POST /process-payment`

**Body (JSON):**
```json
{
    "transaction_id": "TXN-20251104-ABC123"
}
```

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "data": {
        "mensaje": "Pago procesado correctamente",
        "monto": 12500.00
    },
    "timestamp": "2025-11-04 10:36:00"
}
```

---

### 8. Emitir Póliza

Emite la póliza con Dominicana de Seguros y envía los documentos al cliente.

**Endpoint:** `POST /emit-policy`

**Body (JSON):**
```json
{
    "transaction_id": "TXN-20251104-ABC123"
}
```

**Respuesta Exitosa (200):**
```json
{
    "success": true,
    "data": {
        "numero_poliza": "POL-2025-123456",
        "nombre_titular": "JUAN PEREZ GARCIA",
        "placa": "A123456",
        "fecha_inicio": "2025-11-04",
        "fecha_fin": "2026-11-04",
        "monto_pagado": 12500.00,
        "documentos_enviados": true,
        "mensaje": "Póliza emitida exitosamente. Documentos enviados por WhatsApp."
    },
    "timestamp": "2025-11-04 10:37:00"
}
```

**Respuesta de Error (400):**
```json
{
    "success": false,
    "error": "Error al emitir la póliza con Dominicana de Seguros",
    "timestamp": "2025-11-04 10:37:00"
}
```

---

### 9. Descargar Documento (Opcional)

Descarga un documento específico de la póliza.

**Endpoint:** `GET /download-document`

**Parámetros Query:**
- `transaction_id` (requerido): ID de la transacción
- `type` (requerido): `policy` o `carnet`

**Ejemplo de Petición:**
```javascript
window.open(
    'https://www.redbajasusa.com/segurosapi/api/download-document?transaction_id=TXN-20251104-ABC123&type=policy'
);
```

**Respuesta:** Archivo PDF descargable

---

## Códigos de Respuesta

| Código | Significado |
|--------|-------------|
| 200 | Petición exitosa |
| 400 | Error en los parámetros enviados |
| 401 | No autorizado (credenciales inválidas) |
| 403 | Acceso prohibido (IP no autorizada) |
| 404 | Recurso no encontrado |
| 429 | Límite de peticiones excedido |
| 500 | Error interno del servidor |

---

## Manejo de Errores

Todas las respuestas de error siguen esta estructura:

```json
{
    "success": false,
    "error": "Descripción del error",
    "timestamp": "2025-11-04 10:30:00"
}
```

### Errores Comunes

1. **Datos no encontrados en MasterOne**
   - Verificar que la cédula y placa sean correctas
   - El vehículo debe estar registrado en MasterOne

2. **Código OTP incorrecto**
   - El código tiene 10 minutos de validez
   - Puede reenviar el código usando `/send-otp`

3. **Transacción no encontrada**
   - Verificar que el `transaction_id` sea correcto
   - La transacción puede haber expirado

4. **Pago ya procesado**
   - La transacción ya fue completada
   - Crear una nueva transacción para otra venta

---

## Ejemplos de Integración

### Integración Completa en JavaScript

```javascript
class SegurosAPI {
    constructor(apiKey, apiSecret) {
        this.baseUrl = 'https://www.redbajasusa.com/segurosapi/api';
        this.headers = {
            'Content-Type': 'application/json',
            'X-API-Key': apiKey,
            'X-API-Secret': apiSecret
        };
    }

    // 1. Obtener planes disponibles
    async getProducts(tipoVehiculo) {
        const response = await fetch(
            `${this.baseUrl}/products?tipo_vehiculo=${tipoVehiculo}`,
            { headers: this.headers }
        );
        return await response.json();
    }

    // 2. Iniciar transacción
    async startTransaction(data) {
        const response = await fetch(`${this.baseUrl}/start-transaction`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify(data)
        });
        return await response.json();
    }

    // 3. Validar datos
    async validateData(transactionId, cedula, placa) {
        const response = await fetch(`${this.baseUrl}/validate-data`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ transaction_id: transactionId, cedula, placa })
        });
        return await response.json();
    }

    // 4. Enviar OTP
    async sendOTP(transactionId) {
        const response = await fetch(`${this.baseUrl}/send-otp`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ transaction_id: transactionId })
        });
        return await response.json();
    }

    // 5. Validar OTP
    async validateOTP(transactionId, codigo) {
        const response = await fetch(`${this.baseUrl}/validate-otp`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ transaction_id: transactionId, codigo })
        });
        return await response.json();
    }

    // 6. Obtener estado/cotización
    async getTransactionStatus(transactionId) {
        const response = await fetch(
            `${this.baseUrl}/transaction-status?transaction_id=${transactionId}`,
            { headers: this.headers }
        );
        return await response.json();
    }

    // 7. Procesar pago
    async processPayment(transactionId) {
        const response = await fetch(`${this.baseUrl}/process-payment`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ transaction_id: transactionId })
        });
        return await response.json();
    }

    // 8. Emitir póliza
    async emitPolicy(transactionId) {
        const response = await fetch(`${this.baseUrl}/emit-policy`, {
            method: 'POST',
            headers: this.headers,
            body: JSON.stringify({ transaction_id: transactionId })
        });
        return await response.json();
    }
}

// Uso:
const api = new SegurosAPI('su_api_key', 'su_api_secret');

// Flujo completo
async function venderSeguro() {
    try {
        // 1. Obtener planes
        const planes = await api.getProducts('automovil');
        console.log('Planes disponibles:', planes);

        // 2. Iniciar transacción
        const transaction = await api.startTransaction({
            tipo_vehiculo: 'automovil',
            tipo_cobertura: '1',
            cedula: '00112345678',
            telefono: '8091234567',
            placa: 'A123456',
            incluye_grua: false,
            incluye_casa_conductor: false,
            disashop_id: 'KIOSKO_001'
        });

        const txId = transaction.data.transaction_id;

        // 3. Validar datos
        const validation = await api.validateData(txId, '00112345678', 'A123456');
        console.log('Datos validados:', validation);

        // 4. Enviar OTP
        await api.sendOTP(txId);

        // 5. Usuario ingresa código y validamos
        const otpCode = '123456'; // Código ingresado por el usuario
        const otpResult = await api.validateOTP(txId, otpCode);

        // 6. Obtener cotización
        const status = await api.getTransactionStatus(txId);
        console.log('Monto a pagar:', status.data.monto_total);

        // 7. Procesar pago
        await api.processPayment(txId);

        // 8. Emitir póliza
        const policy = await api.emitPolicy(txId);
        console.log('Póliza emitida:', policy.data.numero_poliza);

    } catch (error) {
        console.error('Error:', error);
    }
}
```

---

## Notas Importantes

1. **Límites de Peticiones:**
   - Por defecto: 10,000 peticiones por día
   - Contactar al administrador para aumentar límite

2. **Tiempo de Espera:**
   - Timeout recomendado: 30 segundos
   - La emisión de póliza puede tardar 10-20 segundos

3. **Reintentos:**
   - Implementar reintentos con backoff exponencial
   - Máximo 3 reintentos por petición

4. **Seguridad:**
   - Nunca exponer las credenciales en el frontend
   - Usar HTTPS para todas las peticiones
   - Whitelist de IPs disponible (contactar admin)

5. **Soporte:**
   - Email: soporte@redbajasusa.com
   - Teléfono: +1 (809) XXX-XXXX
   - Horario: Lunes a Viernes, 8:00 AM - 6:00 PM

---

## Endpoint de Testing: Vehicle Mapper

### `POST /test-vehicle-mapper`

**Descripción:** Endpoint para probar el mapeo de vehículos de MasterOne a Dominicana API.

**Request Body:**
```json
{
    "marca": "TOYOTA",
    "modelo": "FJ CRUISER TRAIL TEAM"
}
```

**Response Exitoso:**
```json
{
    "success": true,
    "data": {
        "input": {
            "marca": "TOYOTA",
            "modelo": "FJ CRUISER TRAIL TEAM"
        },
        "resultado": {
            "cdMarca": "229",
            "cdModelo": "11",
            "cdVersion": "2",
            "deIndiceDato": "229|11|2",
            "nombreMarca": "TOYOTA",
            "nombreModelo": "FJ CRUISER",
            "nombreVersion": "FJ CRUISER TRAIL TEAM"
        },
        "mensaje": "Mapeo exitoso"
    }
}
```

**Response de Error:**
```json
{
    "success": false,
    "error": "No se encontró el modelo: FJ CRUISER TRAIL TEAM para la marca TOYOTA"
}
```

**Ejemplo JavaScript:**
```javascript
async function testVehicleMapper(marca, modelo) {
    const response = await fetch('https://www.redbajasusa.com/segurosapi/api/test-vehicle-mapper', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'su_api_key',
            'X-API-Secret': 'su_api_secret'
        },
        body: JSON.stringify({ marca, modelo })
    });
    return await response.json();
}

// Uso:
const resultado = await testVehicleMapper('TOYOTA', 'FJ CRUISER');
console.log(resultado);
```

**Casos de Uso:**
- Testing de integración
- Validación de datos de vehículos antes de iniciar transacción
- Verificación de compatibilidad de modelos

**Nota:** Este endpoint está disponible para pruebas y debugging. El mapeo se ejecuta automáticamente durante el proceso de emisión de póliza.

---

**Versión de Documentación:** 1.1
**Fecha:** 6 de Noviembre, 2025
**Proveedor:** RedBajasUSA