Skip to content

API Intermediarios (1.0.0)

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.

Download OpenAPI description
index.json
index.yaml
Overview
Equipo de APIs Humano Seguros
apis@humano.com.do
License
MIT
Languages
Servers
Mock server
https://intermediarios-api.humano.com.do/_mock/apis
DEV API
https://devapi.humano.com.do/api
Production API
https://huapi.humano.com.do/api

Servicio de Pólizas

Endpoints para consultar información de tus pólizas

Operations

Servicio de Facturas

Endpoints para consultar información de facturas

Operations

Servicio de Comisiones

Endpoints para consultar comisiones generadas

Operations

Servicio de Cobros

Endpoints para consultar cobros e ingresos aplicados a pólizas

Operations

Servicio de Catálogos

Endpoints para consultar catálogos y datos de referencia

Operations

Servicio de Cotizaciones

Endpoints para gestionar cotizaciones

Operations

Servicio de Vehículos

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

Operations

Servicio de Buen Viaje

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

Operations

Emitir póliza Buen Viaje

Request

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.

Security
Ocp-Apim-Subscription-Key and x-user-key and x-codigo-mediador
Bodyapplication/jsonrequired
contratanteEsTitularbooleanrequired
Example: true
contratanteContratanteV2Dto (object) or null

No requerido si contratanteEsTitular=true

One of:

No requerido si contratanteEsTitular=true

aseguradosArray of objects(AseguradoV2Dto)non-emptyrequired
asegurados[].​tipoAseguradostringrequired
Enum"TITULAR""DEPENDIENTE"
Example: "TITULAR"
asegurados[].​primerNombrestringrequired
Example: "Juan"
asegurados[].​segundoNombrestring
Example: null
asegurados[].​primerApellidostringrequired
Example: "Pérez"
asegurados[].​segundoApellidostring
Example: null
asegurados[].​fechaNacimientostring(date-time)required
Example: "1988-05-10T00:00:00Z"
asegurados[].​sexostringrequired
Enum"M""F"
Example: "M"
asegurados[].​estadoCivilstringrequired
Enum"C""S"
Example: "S"
asegurados[].​documentoobject(emitir-request_DocumentoV2Dto)required
asegurados[].​documento.​tipostringrequired
Enum"CEDULA""PASAPORTE"
Example: "CEDULA"
asegurados[].​documento.​numerostringrequired
Example: "00112345678"
asegurados[].​codigoIsoPaisstringrequired
Example: "DO"
asegurados[].​emailstring(email)
Example: null
facturacionobject(FacturacionV2Dto)required
facturacion.​generarEnlaceDePagobooleanrequired
Example: true
codigoIntermediariostringrequired
Example: "79999"
codigoCanalstringrequired
Example: "WEB"
destinoobject(emitir-request_DestinoV2Dto)required
destino.​fechaInicialstring(date-time)required
Example: "2026-02-01T00:00:00Z"
destino.​fechaFinalstring(date-time)required
Example: "2026-02-10T00:00:00Z"
destino.​codigoIsoPaisstringrequired
Example: "US"
destino.​requiereCartaSchengenbooleanrequired
Example: false
curl -i -X POST \
  https://intermediarios-api.humano.com.do/_mock/apis/v2/productos/buen-viaje/polizas \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_API_KEY_HERE' \
  -H 'x-codigo-mediador: YOUR_API_KEY_HERE' \
  -H 'x-user-key: YOUR_API_KEY_HERE' \
  -d '{
    "contratanteEsTitular": true,
    "contratante": null,
    "asegurados": [
      {
        "tipoAsegurado": "TITULAR",
        "primerNombre": "Juan",
        "segundoNombre": null,
        "primerApellido": "Pérez",
        "segundoApellido": null,
        "fechaNacimiento": "1988-05-10T00:00:00Z",
        "sexo": "M",
        "estadoCivil": "S",
        "documento": {
          "tipo": "CEDULA",
          "numero": "00112345678"
        },
        "codigoIsoPais": "DO",
        "email": null
      }
    ],
    "facturacion": {
      "generarEnlaceDePago": true
    },
    "codigoIntermediario": "79999",
    "codigoCanal": "WEB",
    "destino": {
      "fechaInicial": "2026-02-01T00:00:00Z",
      "fechaFinal": "2026-02-10T00:00:00Z",
      "codigoIsoPais": "US",
      "requiereCartaSchengen": false
    }
  }'

Responses

Póliza emitida

Bodyapplication/json
dataobjectrequired
data.​numeroPolizastringrequired
Example: "BV-2026-000001"
data.​enlaceDePagostring(uri)
Example: "https://pay.humano.com.do/bv/FAC-2026-001"
data.​facturaFacturaDto (object) or null
One of:
metaobject(emitir-response_MetaDto)required
meta.​timestampstring(date-time)required
Example: "2026-01-19T14:30:00Z"
meta.​requestIdstringrequired
Example: "0d7a7a7e-6d70-4d2f-a7e1-6b0cbd4e61b3"
Response
application/json
{
  "data": {
    "numeroPoliza": "BV-2026-000001",
    "enlaceDePago": "https://pay.humano.com.do/bv/FAC-2026-001",
    "factura": { … }
  },
  "meta": {
    "timestamp": "2026-01-19T14:30:00Z",
    "requestId": "0d7a7a7e-6d70-4d2f-a7e1-6b0cbd4e61b3"
  }
}

Obtener clave pública (PEM) para pago encriptado

Request

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
Security
Ocp-Apim-Subscription-Key and x-user-key and x-codigo-mediador
Path
kidstringrequired

Identificador de la clave pública (por ambiente y cliente)

Example: crt-pago-buen-viaje-pub
curl -i -X GET \
  https://intermediarios-api.humano.com.do/_mock/apis/v2/productos/buen-viaje/crypto/publickey/crt-pago-buen-viaje-pub \
  -H 'Ocp-Apim-Subscription-Key: YOUR_API_KEY_HERE' \
  -H 'x-codigo-mediador: YOUR_API_KEY_HERE' \
  -H 'x-user-key: YOUR_API_KEY_HERE'

Responses

Clave pública en formato PEM

Bodytext/plain
string(PublicKeyPem)

Clave pública en formato PEM

Response
text/plain
-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
-----END PUBLIC KEY-----

Pagar póliza Buen Viaje

Request

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}

Security
Ocp-Apim-Subscription-Key and x-user-key and x-codigo-mediador
Bodyapplication/jsonrequired
numeroFacturastringrequired
Example: "FAC-2026-001"
montonumberrequired
Example: 100.5
impuestonumberrequired
Example: 18.09
monedastringrequired

ISO 4217

Example: "USD"
metodoPagoobject(MetodoPagoDto)required
metodoPago.​tipostringrequired

Enum en snake_case (ej. tarjeta_credito)

Example: "tarjeta_credito"
metodoPago.​detallesobject(MetodoPagoDetallesDto)required
metodoPago.​detalles.​datosTarjetaCifradosobject(DatosTarjetaCifradosDto)required
metodoPago.​detalles.​datosTarjetaCifrados.​jwestringrequired

JWE compacto (RSA-OAEP-256 + A256GCM)

Example: "<JWE-compacto>"
metodoPago.​detalles.​datosTarjetaCifrados.​kidstringrequired

kid del servidor (clave pública usada para cifrar)

Example: "crt-pago-buen-viaje-pub"
metodoPago.​detalles.​datosTarjetaCifrados.​noncestringrequired

GUID único por solicitud (anti-replay)

Example: "d3e7e5e8-8a26-4346-9a9c-8e5f8a7a1c1a"
metodoPago.​detalles.​datosTarjetaCifrados.​timestampstring(date-time)required

Timestamp ISO-8601 en UTC (con sufijo Z)

Example: "2026-01-19T14:35:00Z"
metodoPago.​detalles.​datosTarjetaCifrados.​firmaJwsstringrequired

JWS compacto RS256 firmado sobre el string del JWE

Example: "<JWS-compacto-sobre-JWE>"
metodoPago.​detalles.​datosTarjetaCifrados.​firmaKidstringrequired

kid de la clave pública del cliente registrada para validar la firma

Example: "cliente-bv-firma-001"
metadatosobject

Metadatos opcionales (clave/valor)

curl -i -X POST \
  https://intermediarios-api.humano.com.do/_mock/apis/v2/productos/buen-viaje/pagos \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_API_KEY_HERE' \
  -H 'x-codigo-mediador: YOUR_API_KEY_HERE' \
  -H 'x-user-key: YOUR_API_KEY_HERE' \
  -d '{
    "numeroFactura": "FAC-2026-001",
    "monto": 100.5,
    "impuesto": 18.09,
    "moneda": "USD",
    "metodoPago": {
      "tipo": "tarjeta_credito",
      "detalles": {
        "datosTarjetaCifrados": {
          "jwe": "<JWE-compacto>",
          "kid": "crt-pago-buen-viaje-pub",
          "nonce": "d3e7e5e8-8a26-4346-9a9c-8e5f8a7a1c1a",
          "timestamp": "2026-01-19T14:35:00Z",
          "firmaJws": "<JWS-compacto-sobre-JWE>",
          "firmaKid": "cliente-bv-firma-001"
        }
      }
    },
    "metadatos": {
      "canal": "web",
      "campania": "promo_vuelta_clases",
      "extra": {
        "reintentos": 0
      }
    }
  }'

Responses

Pago procesado

Bodyapplication/json
numeroFacturastringrequired
Example: "FAC-2026-001"
numeroRecibostring
Example: "RC-2026-000123"
numeroAutorizacionstring
Example: "4F7A92"
montoPagadonumberrequired
Example: 118.59
monedastringrequired
Example: "USD"
mensajestringrequired
Example: "Pago procesado exitosamente"
fechaTransaccionstring(date-time)required
Example: "2026-01-19T14:35:41Z"
duracionMsinteger(int64)
Example: 842
Response
application/json
{
  "numeroFactura": "FAC-2026-001",
  "numeroRecibo": "RC-2026-000123",
  "numeroAutorizacion": "4F7A92",
  "montoPagado": 118.59,
  "moneda": "USD",
  "mensaje": "Pago procesado exitosamente",
  "fechaTransaccion": "2026-01-19T14:35:41Z",
  "duracionMs": 842
}