Documentación Técnica API – DisaShop Kiosco de Seguros

1. Información General

URL Base

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

Formato de Respuesta

Todas las respuestas son application/json con la siguiente estructura:

// Respuesta exitosa
{
  "success": true,
  "data": { ... },
  "timestamp": "2026-03-15 14:30:00"
}

// Respuesta de error
{
  "success": false,
  "error": "Descripción del error",
  "timestamp": "2026-03-15 14:30:00"
}

Health Check (sin autenticación)

GET /health

// Respuesta:
{
  "success": true,
  "data": {
    "status": "ok",
    "timestamp": "2026-03-15 14:30:00",
    "version": "1.0.0"
  }
}

CORS

La API acepta peticiones de cualquier origen (Access-Control-Allow-Origin: *). Soporta los métodos GET, POST, PUT, DELETE y preflight OPTIONS.

2. Autenticación

Todos los endpoints (excepto /health y /vehicle-types) requieren autenticación mediante dos headers HTTP:

Header	Descripción	Ejemplo
`X-API-Key`	Identificador público de la clave API	`disashop_kiosk_01`
`X-API-Secret`	Secreto de la clave API	`s3cr3t_v4lu3_here`

⚠️ Importante: Las credenciales API son proporcionadas por el administrador del sistema. Nunca exponer el X-API-Secret en código del lado del cliente.

Ejemplo de Headers HTTP

POST /segurosapi/api/start-transaction HTTP/1.1
Host: www.redbajasusa.com
Content-Type: application/json
X-API-Key: disashop_kiosk_01
X-API-Secret: tu_secreto_aqui

Error de Autenticación

HTTP/1.1 401 Unauthorized
{
  "success": false,
  "error": "Invalid API credentials",
  "timestamp": "..."
}

Rate Limiting

Cada API Key tiene un límite de 10,000 peticiones por día. Al superar el límite se retorna HTTP 429.

3. Flujo Completo de Venta

La venta de una póliza sigue un flujo secuencial de 10 pasos obligatorios. Cada paso valida el estado de la transacción antes de ejecutarse.

ℹ️ Concepto clave: Una transacción es el registro de sesión de venta. Se crea al inicio y su transaction_id (ID numérico) es el identificador que se pasa en cada llamada subsiguiente.

Iniciar Transacción — `POST /start-transaction`

Registra la sesión de venta con cédula, placa y teléfono del cliente. Retorna el transaction_id.

Validar Datos — `POST /validate-data`

Verifica que la cédula y placa existan en la base de datos MasterOne. Retorna el tipo de vehículo detectado.

Enviar OTP — `POST /send-otp`

Envía un código de 6 dígitos por SMS al teléfono registrado. El código expira en 10 minutos.

Validar OTP — `POST /validate-otp`

El cliente ingresa el código recibido. Máximo 3 intentos fallidos.

Obtener Versiones del Vehículo — `GET /vehicle-versions`

Carga la lista de variantes (versiones) disponibles en DCS para la marca/modelo del vehículo. Una versión es marcada como sugerida por el algoritmo. Si el vehículo solo tiene una versión, el campo version_unica: true indica que se debe omitir la pantalla de selección y avanzar directamente al paso 6.

Obtener Detalle de Versión + Planes — `GET /vehicle-detail`

Cuando el usuario selecciona una versión, obtiene su cilindraje y los planes disponibles. El plan sugerido se resalta automáticamente por cilindraje.

Confirmar Versión y Plan — `POST /confirm-vehicle-version`

Guarda la versión confirmada y el plan seleccionado. Estado pasa a version_confirmada.

Obtener Cotización — `POST /get-quote`

Llama a DCS para calcular la prima exacta. Se puede incluir grúa y casa conductor como servicios adicionales. Retorna el monto_total actualizado.

Procesar Pago — `POST /process-payment`

Registra el pago. Integrar con el sistema de cobro del kiosko (tarjeta, efectivo, etc.). Estado pasa a pago_procesado.

Emitir Póliza — `POST /emit-policy`

Emite la póliza en DCS, genera los PDFs (póliza + marbete) y envía el link de descarga por SMS al cliente.

Diagrama de Estados

iniciada

→

datos_validados

→

otp_enviado

→

otp_validado

→

version_confirmada

→

pago_procesado

→

poliza_emitida

→

completada

Estados especiales: cancelada, error, vehiculo_no_soportado

ℹ️ Atajo automático — versión única: Cuando /vehicle-versions retorna version_unica: true, el kiosco debe saltar la pantalla de selección de versión (paso 5→6) y llamar directamente a /vehicle-detail. La transacción avanza al estado version_confirmada de la misma manera.

4. Referencia de Endpoints

POST /start-transaction Iniciar transacción de venta

Request Body

Campo	Tipo	Requerido	Descripción
`cedula`	string	Req	Número de cédula dominicana (sin guiones)
`telefono`	string	Req	Teléfono móvil (10 dígitos, ej: 8291234567)
`placa`	string	Req	Placa del vehículo

// Request
{
  "cedula": "40212345678",
  "telefono": "8291234567",
  "placa": "A123456"
}

// Response 200
{
  "success": true,
  "data": {
    "transaction_id": "361",
    "uuid": "ddb8522e-730d-4f46-8c2b-58dd68deb8e2",
    "plan": null
  },
  "timestamp": "2026-03-15 10:00:00"
}

El campo transaction_id (numérico) es el que debe almacenarse localmente y usarse en todos los pasos siguientes. El campo uuid es un identificador interno de referencia.

POST /validate-data Validar cédula y placa en base de datos

Request Body

Campo	Tipo	Requerido	Descripción
`transaction_id`	string	Req	ID numérico de la transacción
`cedula`	string	Req	Cédula del titular
`placa`	string	Req	Placa del vehículo

// Request
{
  "transaction_id": "361",
  "cedula": "40212345678",
  "placa": "A123456"
}

// Response 200
{
  "success": true,
  "data": {
    "individuo": {
      "nombre_oculto": "JU** PE*** GA****"
    },
    "vehiculo": {
      "descripcion_oculta": "TOY*** COR****",
      "tipo_vehiculo": "automovil",        // "automovil" | "jeepeta" | "motocicleta"
      "tipo_vehiculo_raw": "AUTOMOVIL PRIVADO"  // Valor original de MasterOne
    },
    "tiene_renovacion": false
  },
  "timestamp": "2026-03-15 10:01:00"
}

// Error: vehículo no soportado
{
  "success": false,
  "error": "Tipo de vehículo no soportado para seguro: CAMION PESADO"
}

POST /send-otp Enviar código OTP por SMS

// Request
{ "transaction_id": "361" }

// Response 200
{
  "success": true,
  "data": {
    "mensaje": "Código OTP enviado correctamente"
  },
  "timestamp": "2026-03-15 10:02:00"
}

El código OTP expira a los 10 minutos. Si expira, llamar a /send-otp nuevamente para generar uno nuevo.

POST /validate-otp Verificar código OTP ingresado por el cliente

Campo	Tipo	Descripción
`transaction_id`	string	ID numérico de la transacción
`codigo`	string	Código de 6 dígitos ingresado por el cliente

// Request
{
  "transaction_id": "361",
  "codigo": "483920"
}

// Response exitosa
{
  "success": true,
  "data": {
    "mensaje": "Código OTP validado correctamente"
  },
  "timestamp": "2026-03-15 10:03:00"
}

// Error: código incorrecto
{
  "success": false,
  "error": "Código OTP incorrecto. Intentos restantes: 2"
}

GET /vehicle-versions Nuevo Obtener variantes del vehículo disponibles en DCS

Query Parameters

Parámetro	Descripción
`transaction_id`	ID numérico de la transacción (estado debe ser otp_validado o superior)

// Request
GET /vehicle-versions?transaction_id=361

// Response — vehículo con múltiples versiones
{
  "success": true,
  "data": {
    "marca": "TOYOTA",
    "modelo": "COROLLA",
    "marca_dcs": "TOYOTA",
    "modelo_dcs": "COROLLA",
    "total_versiones": 4,
    "version_unica": false,
    "sugerido": "10|1050|20",
    "versiones": [
      {
        "cdTabla": 600013,
        "deIndiceDato": "10|1050|18",
        "deValorDato": "COROLLA 1.6L 4CIL SEDAN",
        "sugerido": false
      },
      {
        "cdTabla": 600013,
        "deIndiceDato": "10|1050|20",
        "deValorDato": "COROLLA 1.8L 4CIL SEDAN",
        "sugerido": true        // Versión sugerida por el algoritmo
      },
      {
        "cdTabla": 600013,
        "deIndiceDato": "10|1050|22",
        "deValorDato": "COROLLA 2.0L 4CIL SEDAN",
        "sugerido": false
      }
    ]
  },
  "timestamp": "2026-03-15 10:04:00"
}

// Response — versión única (saltar pantalla de selección)
{
  "success": true,
  "data": {
    "marca": "HONDA",
    "modelo": "PCX 150",
    "marca_dcs": "HONDA",
    "modelo_dcs": "PCX",
    "total_versiones": 1,
    "version_unica": true,      // ← Solo hay una versión; ya fue guardada automáticamente
    "sugerido": "45|320|1",
    "versiones": [
      { "cdTabla": 600013, "deIndiceDato": "45|320|1", "deValorDato": "PCX 150CC", "sugerido": true }
    ]
  },
  "timestamp": "2026-03-15 10:04:00"
}

ℹ️ Lógica de versión única: Cuando version_unica === true, la API ya guardó el deIndiceDato en la transacción. El kiosco debe saltar la pantalla de selección y llamar directamente a /vehicle-detail con el deIndiceDato de versiones[0].

ℹ️ UX múltiples versiones: Cuando version_unica === false, mostrar la lista al usuario con la versión sugerida destacada visualmente. El campo deIndiceDato es el código que se usará en los pasos siguientes.

GET /vehicle-detail Nuevo Obtener especificaciones y planes disponibles para una versión

Query Parameters

Parámetro	Descripción
`transaction_id`	ID numérico de la transacción
`de_indice_dato`	Código de versión DCS (ej: `10\|1050\|20`)

// Request
GET /vehicle-detail?transaction_id=361&de_indice_dato=10|1050|20

// Response
{
  "success": true,
  "data": {
    "detalle_vehiculo": {
      "cilindraje": "4 CILINDROS",   // Valor textual de DCS
      "tonelaje": 0,
      "tipoVehiculo": "AUTOMÓVIL",
      "claseVehiculo": "SEDAN"
    },
    "tipo_vehiculo": "automovil",     // Tipo local mapeado
    "planes_disponibles": [
      // Solo se retornan planes cuyo rango de cilindraje es compatible con el vehículo
      {
        "id": "cef63792-1c46-11f1-b37a-56000537beeb",
        "cd_tipo_plan": 5,
        "descripcion": "Sedan 4 Cil - 12 meses",
        "tipo_vehiculo": "automovil",
        "vigencia_meses": 12,
        "tipo_cobertura": "COMPLETO",
        "visible": 1,
        "orden": 2,
        "cilindraje_min": 1,          // Rango del plan (cilindros o CC para motos)
        "cilindraje_max": 4,
        "uso_dcs": 1
      }
      // Planes de 6 cil y más de 6 cil NO aparecen (incompatibles con este vehículo)
    ]
  }
}

✅ Planes pre-filtrados por cilindraje: La API retorna únicamente los planes compatibles con el cilindraje detectado. No es necesario filtrar del lado del cliente. El campo sugerido: true indica el plan que mejor coincide; si solo hay un plan compatible, se marca sugerido automáticamente.

El precio en planes_disponibles es orientativo (del catálogo). El precio definitivo lo confirma /get-quote al consultar la prima real en DCS.

POST /confirm-vehicle-version Nuevo Confirmar versión del vehículo y plan seleccionado

Campo	Tipo	Requerido	Descripción
`transaction_id`	string	Req	ID numérico de la transacción
`de_indice_dato`	string	Req	Código de versión confirmado por el usuario (ej: `10\|1050\|20`)
`cd_tipo_plan`	integer	Req	ID del plan seleccionado

// Request
{
  "transaction_id": "361",
  "de_indice_dato": "10|1050|20",
  "cd_tipo_plan": 5
}

// Response
{
  "success": true,
  "data": {
    "detalle_vehiculo": {
      "cilindraje": "4 CILINDROS",
      "tonelaje": "N/A",
      "tipoVehiculo": "AUTOMÓVIL",
      "claseVehiculo": "SEDAN"
    },
    "plan": {
      "id": "cef6ac64-1c46-11f1-b37a-56000537beeb",
      "cd_tipo_plan": 5,
      "descripcion": "Sedan 4 Cil - 12 meses",
      "tipo_vehiculo": "automovil",
      "vigencia_meses": 12,
      "tipo_cobertura": "COMPLETO",
      "precio": "0.00",
      "visible": 1,
      "orden": 2
    },
    "de_indice_dato": "10|1050|20"
  },
  "timestamp": "2026-03-15 10:06:00"
}

POST /get-quote Obtener cotización final con precio definitivo de DCS

Campo	Tipo	Requerido	Descripción
`transaction_id`	string	Req	ID numérico de la transacción
`incluye_grua`	boolean	Opc	Incluir servicio de grúa (default: false)
`incluye_casa_conductor`	boolean	Opc	Incluir casa para el conductor (default: false)

// Request
{
  "transaction_id": "361",
  "incluye_grua": true,
  "incluye_casa_conductor": false
}

// Response — retorna todos los campos de la transacción
{
  "success": true,
  "data": {
    "id": 361,
    "uuid": "ddb8522e-730d-4f46-8c2b-58dd68deb8e2",
    "estado": "version_confirmada",
    "cedula": "40212345678",
    "nombre_completo": "JUAN PEREZ GARCIA",
    "telefono": "8291234567",
    "placa": "A123456",
    "marca": "TOYOTA",
    "modelo": "COROLLA",
    "año": 2020,
    "chasis": "JTDBT923X01234567",
    "color": "BLANCO",
    "monto_total": "8750.50",      // Prima real calculada por DCS
    "numero_cotizacion": "2260001814",
    "incluye_grua": 1,
    "incluye_casa_conductor": 0,
    "plan_nombre": "Sedan 4 Cil - 12 meses",
    "cd_tipo_plan": 5,
    "tipo_vehiculo_masterone": "AUTOMOVIL PRIVADO",
    "de_indice_dato_confirmado": "10|1050|20",
    ...
  },
  "timestamp": "2026-03-15 10:07:00"
}

⚠️ Precio final: El monto_total retornado por este endpoint es el precio exacto y definitivo calculado por DCS según las especificaciones del vehículo. Mostrarlo siempre al cliente antes de procesar el pago.

🚫 Error especial: vehículo con póliza activa (POLIZA_ACTIVA:)

Si el vehículo ya tiene una póliza activa en DCS que no está próxima a vencer, la API retorna success: false con el campo error comenzando con el prefijo POLIZA_ACTIVA::

// Response cuando el vehículo ya tiene póliza activa
{
  "success": false,
  "error": "POLIZA_ACTIVA: Este vehículo ya tiene una póliza activa (N° 1-600-45609-1). Vence el 18/03/2027. Puede renovar a partir del 18/12/2026 (90 días antes del vencimiento).",
  "timestamp": "2026-03-19T10:00:00"
}

El kiosco debe detectar este prefijo y mostrar un mensaje claro al cliente, por ejemplo:
"Este vehículo ya tiene una póliza activa. La renovación estará disponible a partir del [fecha]."

Detección recomendada:

if (!data.success && data.error?.startsWith('POLIZA_ACTIVA:')) {
  // Extraer fecha de renovación del mensaje y mostrar aviso específico
  showActivePolicyWarning(data.error);
}

POST /process-payment Registrar el pago del cliente

// Request
{ "transaction_id": "361" }

// Response
{
  "success": true,
  "data": {
    "mensaje": "Pago procesado correctamente"
  },
  "timestamp": "2026-03-15 10:08:00"
}

Integración de pago: Este endpoint marca la transacción como pagada en el sistema. El kiosco debe procesar el cobro real (tarjeta POS, efectivo, etc.) antes de llamar a este endpoint. Si el cobro falla en el hardware, NO llamar este endpoint.

POST /emit-policy Emitir póliza en DCS y generar documentos

// Request
{ "transaction_id": "361" }

// Response (puede tardar hasta 30 segundos)
{
  "success": true,
  "data": {
    "numero_poliza": "1-600-45648-1",
    "numero_cotizacion": "2260001814",
    "prima": 599.98,
    "nombre_titular": "JUAN PEREZ GARCIA"
  },
  "timestamp": "2026-03-15 10:09:00"
}

Después de la emisión exitosa, el cliente recibe automáticamente un SMS con el link para descargar sus documentos. Las URLs de documentos también se pueden mostrar en pantalla para descarga inmediata en el kiosco.

Este endpoint puede tardar hasta 30 segundos. Configurar el timeout del cliente HTTP a mínimo 60 segundos.

GET /transaction-status Consultar estado actual de una transacción

// Request
GET /transaction-status?transaction_id=361

// Response — retorna todos los campos de la transacción
{
  "success": true,
  "data": {
    "id": 361,
    "uuid": "ddb8522e-730d-4f46-8c2b-58dd68deb8e2",
    "estado": "poliza_emitida",
    "cedula": "40212345678",
    "nombre_completo": "JUAN PEREZ GARCIA",
    "telefono": "8291234567",
    "placa": "A123456",
    "marca": "TOYOTA",
    "modelo": "COROLLA",
    "año": 2020,
    "numero_poliza": "1-600-45648-1",
    "numero_cotizacion": "2260001814",
    "monto_total": "8750.50",
    "created_at": "2026-03-15 10:00:00",
    "updated_at": "2026-03-15 10:09:00",
    ...
  },
  "timestamp": "2026-03-15 10:10:00"
}

GET /download-document Descargar póliza o marbete en PDF

Query Parameters

Parámetro	Requerido	Descripción
`transaction_id`	Req	ID numérico de la transacción
`tipo`	Opc	`poliza` (default) o `marbete`

// Descargar póliza
GET /download-document?transaction_id=361&tipo=poliza

// Descargar marbete (sticker)
GET /download-document?transaction_id=361&tipo=marbete

// Respuesta: binario PDF con headers:
// Content-Type: application/pdf
// Content-Disposition: attachment; filename="poliza_1-600-45409-1.pdf"

Autenticación para este endpoint: puede enviarse en headers (X-API-Key / X-API-Secret) o como query parameters (api_key / api_secret).

GET /products Listar planes de seguro disponibles por tipo de vehículo

Query Parameters

Parámetro	Descripción
`tipo_vehiculo`	`automovil` \| `jeepeta` \| `motocicleta` — usar si no se tiene `transaction_id`
`transaction_id`	ID numérico de transacción. Recomendado. El tipo de vehículo se detecta automáticamente y, si ya se confirmó el plan, los precios de servicios opcionales se ajustan a la duración del plan (6 o 12 meses).

⚠ Importante — cuándo llamar este endpoint: Para obtener los precios correctos de los servicios opcionales, este endpoint debe llamarse después de confirmar el plan (/confirm-plan), pasando el transaction_id. Si se llama antes de confirmar el plan, o solo con tipo_vehiculo, los precios devueltos corresponden al plan anual (12 meses) por defecto.

// Llamar DESPUÉS de /confirm-plan para obtener precios correctos
GET /products?transaction_id=361

// Response — plan de 12 meses confirmado
{
  "success": true,
  "data": {
    "planes": [
      {
        "id": 5,
        "nombre": "Sedan 4 Cil - 12 meses",
        "tipo_vehiculo": "automovil",
        "vigencia_meses": 12,
        "tipo_cobertura": "COMPLETO",
        "precio": 8500.00,
        "cilindraje_min": 1,
        "cilindraje_max": 4
      }
    ],
    "servicios_opcionales": [
      {
        "id": "casa_conductor",
        "campo": "incluye_casa_conductor",  // nombre del campo a enviar en /get-quote
        "nombre": "Casa del Conductor",
        "descripcion": "Servicio de casa del conductor incluido en la póliza",
        "precio": 1400.00,    // plan 12 meses → RD$1,400 | plan 6 meses → RD$705.74
        "disponible": true
      },
      {
        "id": "asistencia_vial",
        "campo": "incluye_grua",            // nombre del campo a enviar en /get-quote
        "nombre": "Asistencia Vial (Grúa)",
        "descripcion": "Servicio de grúa y asistencia en carretera",
        "precio": 800.00,     // plan 12 meses → RD$800 | plan 6 meses → RD$403.28
        "disponible": true
        // ⚠ Este servicio NO aparece para tipo_vehiculo=motocicleta
      }
    ]
  }
}

La respuesta tiene dos secciones: planes con los planes de seguro disponibles, y servicios_opcionales con los servicios adicionales que el cliente puede contratar. El campo campo de cada servicio indica el nombre exacto del parámetro a enviar en /get-quote.

Los precios de servicios opcionales varían según la duración del plan elegido:

Servicio	Plan 12 meses	Plan 6 meses
Casa del Conductor	RD$1,400.00	RD$705.74
Asistencia Vial (Grúa)	RD$800.00	RD$403.28

⚠ Asistencia Vial (Grúa) solo aplica para automóviles. Para tipo_vehiculo=motocicleta este servicio no aparece en la respuesta. Si se envía incluye_grua: true en /get-quote para una moto, el backend lo ignora automáticamente.

5. Estados de la Transacción

Estado	Descripción	Próximo endpoint
`iniciada`	Transacción creada	`/validate-data`
`datos_validados`	Cédula y placa verificadas en MasterOne	`/send-otp`
`otp_enviado`	Código SMS enviado al cliente	`/validate-otp`
`otp_validado`	Identidad del cliente confirmada	`/vehicle-versions`
`version_confirmada`	Versión del vehículo y plan seleccionados	`/get-quote`
`pago_procesado`	Pago registrado	`/emit-policy`
`poliza_emitida`	Póliza emitida en DCS	`/download-document`
`completada`	Proceso finalizado completamente	—
`cancelada`	Transacción cancelada manualmente	—
`error`	Error no recuperable en el proceso	Iniciar nueva transacción
`vehiculo_no_soportado`	El tipo de vehículo no tiene cobertura disponible	—

Si una transacción queda en estado error o vehiculo_no_soportado, se debe iniciar una nueva transacción desde /start-transaction.

6. Manejo de Errores

Códigos HTTP

Código	Significado	Acción recomendada
`200`	Éxito	Continuar flujo
`400`	Parámetros incorrectos o faltantes	Revisar el body de la petición
`401`	Credenciales API inválidas	Verificar X-API-Key y X-API-Secret
`404`	Transacción no encontrada	Verificar transaction_id
`429`	Rate limit excedido	Esperar o contactar administrador
`500`	Error interno del servidor	Reintentar una vez; si persiste, registrar y notificar

Errores Comunes

Error	Causa probable
"Cédula no encontrada en el sistema"	La cédula no está registrada en MasterOne
"Placa no encontrada o no pertenece a esta cédula"	Datos incorrectos o vehículo no registrado
"Código OTP incorrecto"	El usuario ingresó mal el código
"OTP expirado"	Pasaron más de 10 minutos; llamar `/send-otp` otra vez
"Tipo de vehículo no soportado"	El vehículo es de un tipo sin cobertura (camión pesado, etc.)
"Estado de transacción inválido"	Se llamó un endpoint fuera de orden; verificar el flujo

7. Ejemplos de Integración Completa

JavaScript / Fetch API

const API_BASE = 'https://www.redbajasusa.com/segurosapi/api';
const HEADERS = {
  'Content-Type': 'application/json',
  'X-API-Key': 'TU_API_KEY',
  'X-API-Secret': 'TU_API_SECRET'
};

// Helper genérico
async function apiCall(method, path, body = null) {
  const opts = { method, headers: HEADERS };
  if (body) opts.body = JSON.stringify(body);
  const res = await fetch(API_BASE + path, opts);
  const json = await res.json();
  if (!json.success) throw new Error(json.error);
  return json.data;
}

// ─── Flujo completo ───────────────────────────────────────

// Paso 1: Iniciar transacción
const txData = await apiCall('POST', '/start-transaction', {
  cedula: '40212345678',
  telefono: '8291234567',
  placa: 'A123456'
});
const txId = txData.transaction_id;  // ID numérico (ej: "361")

// Paso 2: Validar datos
const validated = await apiCall('POST', '/validate-data', {
  transaction_id: txId,
  cedula: '40212345678',
  placa: 'A123456'
});
console.log('Tipo vehículo:', validated.tipo_vehiculo); // "automovil"

// Paso 3 & 4: OTP
await apiCall('POST', '/send-otp', { transaction_id: txId });
const codigoCliente = await pedirCodigoAlUsuario(); // UI del kiosco
await apiCall('POST', '/validate-otp', {
  transaction_id: txId,
  codigo: codigoCliente
});

// Paso 5: Versiones del vehículo
const versData = await apiCall('GET', `/vehicle-versions?transaction_id=${txId}`);
const versionElegida = await mostrarVersionesAlUsuario(versData.versiones);

// Paso 6: Detalle + planes
const detail = await apiCall('GET',
  `/vehicle-detail?transaction_id=${txId}&de_indice_dato=${encodeURIComponent(versionElegida)}`
);
const planElegido = await mostrarPlanesAlUsuario(detail.planes_disponibles);

// Paso 7: Confirmar versión
await apiCall('POST', '/confirm-vehicle-version', {
  transaction_id: txId,
  de_indice_dato: versionElegida,
  cd_tipo_plan: planElegido.cd_tipo_plan
});

// Paso 7b: Consultar servicios opcionales (ya obtenidos en /products)
// data.servicios_opcionales contiene nombre, precio y el campo a enviar
// Mostrar al cliente para que seleccione

// Paso 8: Cotización (con los servicios que haya elegido el cliente)
const quote = await apiCall('POST', '/get-quote', {
  transaction_id: txId,
  incluye_casa_conductor: true,   // campo indicado en servicios_opcionales[0].campo
  incluye_grua: true              // campo indicado en servicios_opcionales[1].campo (solo autos)
});
console.log('Precio final:', quote.monto_total, 'RD$');

// Paso 9: Pago (después de cobrar al cliente)
await cobrarAlCliente(quote.monto_total); // Tu lógica de pago
await apiCall('POST', '/process-payment', { transaction_id: txId });

// Paso 10: Emitir póliza
const policy = await apiCall('POST', '/emit-policy', { transaction_id: txId });
console.log('Póliza:', policy.numero_poliza);
console.log('Descargar:', policy.documentos.poliza_url);

PHP / cURL

function apiCall($method, $endpoint, $data = null) {
    $url  = 'https://www.redbajasusa.com/segurosapi/api' . $endpoint;
    $ch   = curl_init($url);
    $hdrs = [
        'Content-Type: application/json',
        'X-API-Key: TU_API_KEY',
        'X-API-Secret: TU_API_SECRET'
    ];

    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => $hdrs,
        CURLOPT_TIMEOUT        => 60,
    ]);

    if ($data) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }

    $resp = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (!$resp['success']) {
        throw new Exception($resp['error']);
    }
    return $resp['data'];
}

// Paso 1
$tx = apiCall('POST', '/start-transaction', [
    'cedula'   => '40212345678',
    'telefono' => '8291234567',
    'placa'    => 'A123456'
]);
$txId = $tx['transaction_id'];

8. Consideraciones de Implementación

Timeouts Recomendados

Endpoint	Timeout sugerido	Razón
Todos excepto /emit-policy	15 segundos	Respuesta rápida esperada
`/get-quote`	30 segundos	Llamada externa a DCS para calcular prima
`/emit-policy`	60 segundos	Emisión + generación de PDF + SMS

Manejo de Interrupciones en el Kiosco

Si el kiosco pierde conexión durante /emit-policy, consultar /transaction-status al reconectar. Si el estado es poliza_emitida, la póliza fue emitida exitosamente aunque no recibiste la respuesta.
Si el estado es pago_procesado y la póliza no se emitió aún, se puede reintentar /emit-policy.
Si el kiosco se reinicia, guardar localmente el transaction_id en sesión para poder recuperar el estado.

Sesión de Kiosco

Una transacción no tiene expiración automática impuesta por la API, pero por UX se recomienda cancelar (o reiniciar la UI) si el usuario lleva más de 15 minutos inactivo.
El OTP expira a los 10 minutos. El resto del flujo no expira.

Selección de Versión del Vehículo

El paso de selección de versión fue agregado para garantizar que el precio cotizado coincida exactamente con el precio final emitido. El algoritmo hace su mejor suposición (marcada como sugerido: true), pero el usuario puede cambiarla si la descripción no coincide con su vehículo.

Seguridad

Siempre usar HTTPS para todas las llamadas.
El X-API-Secret no debe aparecer en logs, reportes de errores, ni en código front-end expuesto.
Si el kiosco está en producción y tiene IP fija, solicitar al administrador habilitar IP whitelisting para su API Key.

Ambiente de Pruebas

El backend actualmente apunta al servidor de pruebas de DCS (apptest.dominicanadeseguros.com). Confirmar con el administrador la fecha de cambio al servidor de producción antes del go-live.

Soporte

Para dudas técnicas, acceso a credenciales o reporte de incidentes, contactar al administrador del sistema de DISASHOP.

SegurosAPI v2.3 — Documentación Técnica para DisaShop — Abril 2026 — Confidencial

Guía de Integración para KioscosDisaShop

Tabla de Contenido

1. Información General

URL Base

Formato de Respuesta

Health Check (sin autenticación)

CORS

2. Autenticación

Ejemplo de Headers HTTP

Error de Autenticación

Rate Limiting

3. Flujo Completo de Venta

Iniciar Transacción — POST /start-transaction

Validar Datos — POST /validate-data

Enviar OTP — POST /send-otp

Validar OTP — POST /validate-otp

Obtener Versiones del Vehículo — GET /vehicle-versions

Obtener Detalle de Versión + Planes — GET /vehicle-detail

Confirmar Versión y Plan — POST /confirm-vehicle-version

Obtener Cotización — POST /get-quote

Procesar Pago — POST /process-payment

Emitir Póliza — POST /emit-policy

Diagrama de Estados

4. Referencia de Endpoints

Request Body

Request Body

Query Parameters

Query Parameters

Query Parameters

Query Parameters

5. Estados de la Transacción

6. Manejo de Errores

Códigos HTTP

Errores Comunes

7. Ejemplos de Integración Completa

JavaScript / Fetch API

PHP / cURL

8. Consideraciones de Implementación

Timeouts Recomendados

Manejo de Interrupciones en el Kiosco

Sesión de Kiosco

Selección de Versión del Vehículo

Seguridad

Ambiente de Pruebas

Soporte

Guía de Integración para Kioscos
DisaShop

Iniciar Transacción — `POST /start-transaction`

Validar Datos — `POST /validate-data`

Enviar OTP — `POST /send-otp`

Validar OTP — `POST /validate-otp`

Obtener Versiones del Vehículo — `GET /vehicle-versions`

Obtener Detalle de Versión + Planes — `GET /vehicle-detail`

Confirmar Versión y Plan — `POST /confirm-vehicle-version`

Obtener Cotización — `POST /get-quote`

Procesar Pago — `POST /process-payment`

Emitir Póliza — `POST /emit-policy`