# API Intermediarios

# Bienvenido al API de Intermediarios

El **API de Intermediarios** ha sido diseñado para que puedas acceder e integrar fácilmente las principales funcionalidades que ofrecemos a nuestros socios y aliados.

## Con esta API podrás:

- **Cotizar** productos de Salud, Generales y Vida
- **Emitir** pólizas de manera digital
- **Consultar** tus pólizas, facturas, consumos y más

Todo **en un solo lugar**, con seguridad, rapidez y disponibilidad 24/7.

## ¿Qué encontrarás en esta documentación?

En esta página encontrarás toda la información necesaria para comenzar a usar el API, incluyendo:

- **Descripción general** del API
- **Especificación OpenAPI** en formato YAML, lista para ser utilizada en Postman, Swagger u otras herramientas
- **Ejemplos prácticos** de uso para integrarte más rápido
- **Guías paso a paso** para autenticación, cotización, emisión y consulta de información

## Primeros pasos

1. Consulta la especificación OpenAPI
2. Explora los endpoints disponibles en la sección de referencia
3. Integra las funcionalidades en tus sistemas internos para comenzar a operar

## Beneficios clave

### 🔄 Automatización
Automatización de procesos de cotización y emisión.

### 🔒 Seguridad
Seguridad con estándares modernos de autenticación.

### ⚡ Disponibilidad 24/7
Siempre tengas acceso a tu información.

### 📈 Escalabilidad
Lista para crecer con tus operaciones.

Version: 1.0.0
License: MIT

## Servers

DEV API
```
https://devapi.humano.com.do/api
```

Production API
```
https://huapi.humano.com.do/api
```

## Security

### Ocp-Apim-Subscription-Key

Llave de suscripción proporcionada por Humano Seguros.

Esta llave es única para cada intermediario y debe ser incluida en todas las peticiones al API.

**Ejemplo:**
Ocp-Apim-Subscription-Key: 5fd0ebcd8ead4d019b6fdb4c18e3fbd51


Type: apiKey
In: header
Name: Ocp-Apim-Subscription-Key

### x-user-key

Llave de usuario proporcionada por Humano Seguros.

Esta llave identifica al usuario específico que realiza la petición.

**Ejemplo:**
x-user-key: 8c3a9f0e1b5d6a7f2e4c3b1d0f8a7e6c

Para obtener tu llave de usuario, contacta al equipo de APIs: apis@humano.com.do


Type: apiKey
In: header
Name: x-user-key

### x-codigo-mediador

Código del intermediario; identifica al intermediario que realiza la petición.
Debe ser el intermediario al que le corresponde el x-user-key que se proporcione.

**Ejemplo:**
x-codigo-mediador: 79999


Type: apiKey
In: header
Name: x-codigo-mediador

## Download OpenAPI description

[API Intermediarios](https://intermediarios-api.humano.com.do/_bundle/apis/index.yaml)

## Servicio de Pólizas

Endpoints para consultar información de tus pólizas

### Consultar Pólizas de Generales y Vida

 - [GET /poliza/consulta](https://intermediarios-api.humano.com.do/apis/polizas/consultarpolizasgeneralesvida.md): Obtiene información detallada de las pólizas emitidas, modificadas y/o renovadas.

Este servicio debe ser consumido al final del día para sincronizar la información de las pólizas.

Tipos de Consulta:
- 0: Todo
- 1: Emisión
- 2: Modificación
- 3: Renovación

Indicador de Certificado:
- 0: Todo
- 1: Matriz
- 2: Certificados (Recomendado)

### Consultar Pólizas de Salud

 - [GET /poliza/consulta-polizas](https://intermediarios-api.humano.com.do/apis/polizas/consultarpolizassalud.md): Obtiene información de los movimientos de las pólizas de Salud según los parámetros indicados.

Tipos de Movimiento:
- 0: Todos
- 1: Inclusión
- 2: Cambio de Póliza
- 3: Cambio de Plan Categoría
- 4: Cambio Tipo Dependiente
- 5: Exclusión

Parámetros opcionales: compania, ramo y secuencial

### Cargar Archivo de Inspección de Automóvil

 - [POST /poliza/inspeccion/cargar-documento](https://intermediarios-api.humano.com.do/apis/polizas/cargarinspeccionautomovil.md): Permite cargar documentos de inspección de automóvil para una cotización específica.

Los archivos deben enviarse codificados en Base64.

Campos obligatorios: Todos los campos son requeridos.

Nota: Se requiere especificar al menos un documento en el array.

## Servicio de Facturas

Endpoints para consultar información de facturas

### Consultar Facturas de Salud

 - [GET /facturas/consulta/salud](https://intermediarios-api.humano.com.do/apis/facturas/consultarfacturassalud.md): Retorna las facturas de salud que han sido procesadas por Humano en el rango de fechas indicado.

Este servicio soporta paginación para manejar grandes volúmenes de datos.

Parámetros obligatorios: todos los parámetros son requeridos.

### Consultar Facturas de Generales y Vida

 - [GET /facturas/consulta](https://intermediarios-api.humano.com.do/apis/facturas/consultarfacturasgeneralesvida.md): Consulta las facturas emitidas para los productos de Seguros Generales y Vida.

Este servicio retorna todas las facturas procesadas en el rango de fechas especificado.

Parámetros obligatorios: todos los parámetros son requeridos.

## Servicio de Comisiones

Endpoints para consultar comisiones generadas

### Consultar Comisiones de Periodo Salud

 - [GET /comisiones/periodo](https://intermediarios-api.humano.com.do/apis/comisiones/consultarcomisionesperiodosalud.md): Obtiene las comisiones generadas en un período específico para productos de Salud.

Este servicio retorna el detalle de comisiones voluntarias y complementarias por cada factura/recibo procesado.

Parámetros obligatorios: todos los parámetros son requeridos.

## Servicio de Cobros

Endpoints para consultar cobros e ingresos aplicados a pólizas

### Consultar Cobros de Generales y Vida

 - [GET /cobros/consulta](https://intermediarios-api.humano.com.do/apis/cobros/consultarcobrosgeneralesvida.md): Consulta los cobros de un rango de fecha para productos de Seguros Generales y Vida.

Este servicio retorna información detallada de los ingresos/pagos aplicados a las pólizas.

Identificador único de ingreso: P_CD_ENTIDAD + P_CD_SUCURSAL + P_NU_INGRESO

Parámetros obligatorios: todos los parámetros son requeridos.

## Servicio de Catálogos

Endpoints para consultar catálogos y datos de referencia

### Catálogo de Provincias

 - [GET /catalogos/catalogo/provincias](https://intermediarios-api.humano.com.do/apis/catalogos/consultarprovincias.md): Consulta el catálogo completo de provincias de República Dominicana para servicios que requieren especificar direcciones físicas del cliente.

Este endpoint retorna las 32 provincias sin requerir parámetros.

### Catálogo de Municipios

 - [GET /catalogos/catalogo/municipios](https://intermediarios-api.humano.com.do/apis/catalogos/consultarmunicipios.md): Consulta el catálogo de municipios para servicios que requieren especificar direcciones físicas del cliente.

Los municipios están organizados jerárquicamente por provincia.

Parámetro obligatorio: cdProvincia es requerido.

### Catálogo de Sectores

 - [GET /catalogos/catalogos/sectores](https://intermediarios-api.humano.com.do/apis/catalogos/consultarsectores.md): Consulta el catálogo de sectores para servicios que requieren especificar direcciones físicas del cliente.

Los sectores están organizados jerárquicamente por provincia y municipio.

Parámetros obligatorios: todos los parámetros son requeridos.

## Servicio de Cotizaciones

Endpoints para gestionar cotizaciones

### Cotizar Seguro de Automóvil

 - [POST /cotizacion/productos/cotizar](https://intermediarios-api.humano.com.do/apis/cotizaciones/cotizarautomovil.md): Genera una cotización para un seguro de automóvil basándose en las características del vehículo y del asegurado.

Nota importante: La fecha de cotización (fechaDesde) debe ser la fecha del día en que se envía la petición.

Vigencias disponibles:
- M - Mensual (renueva mensualmente)
- B - Bimestral (renueva cada dos meses)
- T - Trimestral (renueva cada tres meses)
- C - Cuatrimestral (renueva cada cuatro meses)
- S - Semestral (renueva cada seis meses)
- N - 9 meses (renueva cada nueve meses)
- A - Anual (renueva al año) - Recomendado
- U - Única (renueva al año)
- BA - Bianual (renueva cada dos años)

Monedas disponibles:
- 1 - Peso Dominicano (RD$)
- 2 - Dólar Americano (US$)
- 3 - Euro (€)

### Consultar Detalle de Cotización Generales y Vida

 - [GET /cotizacion/detalle](https://intermediarios-api.humano.com.do/apis/cotizaciones/consultardetallecotizaciongeneralesvida.md): Obtiene el detalle completo de una cotización de Seguros Generales y Vida.

Este servicio retorna información exhaustiva incluyendo:
- Datos del asegurado y del intermediario
- Información del producto y plan
- Bienes asegurados con todos sus datos
- Coberturas detalladas con primas y deducibles
- Estado de inspección

Parámetro obligatorio: nuCotizacion es requerido.

## Servicio de Vehículos

Endpoints para consultar información de vehículos (marcas, modelos, versiones)

### Obtener Marcas de Vehículos

 - [GET /vehiculos/marcas](https://intermediarios-api.humano.com.do/apis/vehiculos/obtenermarcas.md): Obtiene el listado de marcas de automóviles elegibles según el código de plan especificado.

Las marcas disponibles varían dependiendo del plan seleccionado.

Parámetro obligatorio: cdPlan es requerido.

### Obtener Modelos de Vehículos

 - [GET /vehiculos/modelos](https://intermediarios-api.humano.com.do/apis/vehiculos/obtenermodelos.md): Obtiene el listado de modelos de automóviles elegibles según el código de plan y código de marca especificados.

Los modelos disponibles varían dependiendo del plan y la marca seleccionados.

Parámetros obligatorios: cdPlan y cdMarca son requeridos.

### Obtener Versiones de Vehículos

 - [GET /vehiculos/versiones](https://intermediarios-api.humano.com.do/apis/vehiculos/obtenerversiones.md): Obtiene el listado de versiones de modelos de automóviles elegibles según el código de plan, código de marca y código de modelo especificados.

Las versiones disponibles varían dependiendo del plan, la marca y el modelo seleccionados.

Parámetros obligatorios: cdPlan, cdMarca y cdModelo son requeridos.

## Servicio de Buen Viaje

Endpoints para cotizar, emitir pólizas y pagar el seguro de viaje Buen Viaje

### Cotizar Buen Viaje

 - [POST /v2/productos/buen-viaje/cotizaciones](https://intermediarios-api.humano.com.do/apis/buen-viaje/cotizarbuenviaje.md): Calcula la cotización del seguro de viaje Buen Viaje para un destino y un grupo de personas.

Retorna tarifas y totales en USD y DOP, la tasa de cambio aplicada y, cuando corresponde,
un enlace PDF con el detalle de la cotización.

Flujo recomendado: Cotizar → Emitir → Pagar.

### Emitir póliza Buen Viaje

 - [POST /v2/productos/buen-viaje/polizas](https://intermediarios-api.humano.com.do/apis/buen-viaje/emitirpolizabuenviaje.md): Emite la póliza del seguro de viaje Buen Viaje a partir de los datos de viaje (destino),
asegurados, contratante y facturación.

Flujo recomendado: Cotizar → Emitir → Pagar.

### Obtener clave pública (PEM) para pago encriptado

 - [GET /v2/productos/buen-viaje/crypto/publickey/{kid}](https://intermediarios-api.humano.com.do/apis/buen-viaje/obtenerpublickeybuenviaje.md): Devuelve la clave pública asociada al kid indicado en formato PEM.

Se utiliza para cifrar el payload sensible del pago con JWE (RSA-OAEP-256 + A256GCM).
Flujo criptográfico típico:
1) Obtén la clave pública por kid
2) Cifra JSON sensible con JWE
3) Firma el JWE con JWS (RS256)
4) Envía el POST de pago

### Pagar póliza Buen Viaje

 - [POST /v2/productos/buen-viaje/pagos](https://intermediarios-api.humano.com.do/apis/buen-viaje/pagarbuenviaje.md): Procesa el pago de una póliza/factura de Buen Viaje.

Seguridad (pago encriptado v2):
- Cifra datos sensibles del medio de pago con JWE (RSA-OAEP-256 + A256GCM)
- Firma el JWE con JWS (RS256) usando firmaKid
- Envío de nonce único y timestamp UTC (anti-replay)

Prerrequisito: obtener la clave pública del servidor:
GET /v2/productos/buen-viaje/crypto/publickey/{kid}

## Servicio de Reembolsos

Endpoints para crear y consultar solicitudes de reembolsos

### Crear solicitud de reembolso

 - [POST /v2/reembolso/solicitudes](https://intermediarios-api.humano.com.do/apis/reembolsos/crearsolicitudreembolso.md): Permite crear una solicitud de reembolso.

Este endpoint recibe los datos del asegurado, información del servicio médico,
datos de la póliza y datos bancarios para procesar el reembolso.

IMPORTANTE:
- El request es multipart/form-data ya que permite adjuntar soportes (facturas, comprobantes de pago, etc.).
- Se pueden enviar múltiples archivos usando el índice soportesn.

Ejemplo:
- soportes0
- soportes1

Los documentos deben ser válidos, sellados y emitidos por médico y/o centro médico legítimo.

### Consultar solicitudes de reembolso de cartera

 - [GET /reembolso/consulta-solicitudes-cartera](https://intermediarios-api.humano.com.do/apis/reembolsos/consultarsolicitudesreembolsocartera.md): Permite consultar las solicitudes de reembolso registradas dentro de un rango de fechas.

La consulta retorna información general de cada solicitud, incluyendo estado,
monto pagado o reclamado, tipo de servicio, plan, afiliado y fechas relevantes
del proceso de reembolso.

Parámetros obligatorios:
- fechaDesde
- fechaHasta

Formato de fecha requerido: yyyy-mm-dd