Al reportar, el integrador declara que procesó y confirmó el pago en su propio sistema.
Arquitectura
Un espacio seguro para tu integración
Cada credencial accede únicamente al espacio asignado en Portal Emisión. Allí estarán disponibles sus productos, configuraciones y ventas, sin parámetros adicionales en cada solicitud.
Portal Emisión vuelve a calcular precios, edades, días, promociones, recargos y riders.
La integración solo consulta y administra la información disponible en su espacio asignado.
order_idUUID público e inmutable de Portal Emisión.system_codeCódigo visible generado por nuestro sistema.external_codeCódigo único de la venta en el sistema integrador.Primeros pasos
Flujo recomendado
Paso 1Obtener token JWT
Paso 2Consultar catálogo
Paso 3Reportar la venta
Paso 4Guardar los 3 códigos
ℹ
No generes un token por cada método.
Reutiliza el JWT mientras esté vigente. Solicita uno nuevo al expirar.
Autenticación
Obtener un token
Usa las credenciales de integración suministradas por Portal Emisión. Por defecto, el token dura 15 minutos.
/auth/tokenPúblicoCrear token de acceso
Devuelve un Bearer JWT con los permisos habilitados para la integración.
| Campo | Tipo | Uso |
|---|---|---|
| email REQUERIDO | Correo asignado a la integración. | |
| password REQUERIDO | string | Contraseña asignada a la integración. |
Productos
Catálogo disponible
Consulta siempre el catálogo antes de integrar un plan. La respuesta contiene la información comercial necesaria para seleccionar productos, beneficios y riders.
GET
/catalog/countriesOrigen y nacionalidadGET
/catalog/territoriesTerritorios de destinoGET
/catalog/plansPlanes habilitadosGET
/catalog/plans/{planId}Condiciones, beneficios y riders◎
Los destinos son territorios.
Envía Europa, Latinoamérica, Estados Unidos y Canadá u otro territorio configurado; no una lista de países de destino.
Operación principal
Reportar una venta estándar
Este método representa el 95% de las integraciones previstas. La venta ya debe haber sido procesada y confirmada como pagada por el sistema externo.
/reported-ordersorders:reportCrear una orden desde una venta externa
!
No envíes forma de pago, referencia, cotización ni importes.
La venta debe estar procesada y pagada en el sistema externo. Portal Emisión validará el producto y calculará el valor oficial con la configuración vigente.
Encabezado obligatorio
| Header | Tipo | Descripción |
|---|---|---|
| Authorization REQUERIDO | Bearer | Token obtenido en /auth/token. |
| Idempotency-Key REQUERIDO | string | Identifica este intento lógico y evita ventas duplicadas. |
Campos de la solicitud
| Campo | Tipo | Descripción |
|---|---|---|
| external_code REQUERIDO | string | Código único de la venta dentro del espacio de integración. |
| plan_id REQUERIDO | integer | ID obtenido del catálogo. |
| trip REQUERIDO | object | Origen, territorio, inicio y fin del viaje. |
| emergency_contact REQUERIDO | object | Nombre completo, correo y teléfono. |
| passengers REQUERIDO | array | Uno o más pasajeros con correo y teléfono. |
| riders OPCIONAL | array | Riders asociados por documento de pasajero. |
Operación especializada
Reportar Brasil y emitir con HERO
Mantiene la estructura estándar y añade únicamente la información regulatoria solicitada por HERO. Admite exactamente un pasajero.
/reported-orders/brazilorders:report| Campo Brasil | Tipo | Regla |
|---|---|---|
| brazil.has_cpf REQUERIDO | boolean | Define si el documento del pasajero es CPF o pasaporte. |
| brazil.civil_status_id REQUERIDO | integer | Identificador de estado civil aceptado por HERO. |
| brazil.responsible CONDICIONAL | object | Nombre y CPF obligatorios cuando el pasajero no posee CPF. |
| brazil.address REQUERIDO | object | CEP, calle, número, barrio, ciudad y estado. |
!
issue_failed no significa solicitud rechazada.La venta fue aceptada localmente, pero HERO no confirmó la emisión. Debe revisarse o reintentarse con el flujo operativo correspondiente.
Ciclo de vida
Consultar una orden
/orders/{orderId}orders:readDevuelve el estado, los tres identificadores, vigencia, importes calculados y estado del proveedor cuando aplique.
Ciclo de vida
Corregir datos de contacto
/orders/{orderId}orders:updatePermite corregir contacto de emergencia, correo, teléfono y condiciones médicas antes de las 00:00 del inicio de vigencia en Venezuela.
Ciclo de vida
Cancelar antes de la vigencia
/orders/{orderId}orders:cancelCancela una orden estándar. Brasil utiliza solicitud y confirmación separadas con HERO.
POST
/orders/{id}/cancellation-requestsSolicita la cancelación BrasilPOST
/orders/{id}/cancellation-confirmationsConfirma dentro de 5 minutosAuditoría
Consultar aceptadas y rechazadas
/submissions?status=rejectedorders:readLista intentos procesados por la credencial. Una solicitud rechazada conserva sus errores para consulta, pero no crea una orden válida ni activa una cobertura.
Notificaciones
Webhooks firmados
Registra un receptor HTTPS. El secreto se devuelve una sola vez y cada evento se firma con HMAC-SHA256.
/webhookswebhooks:manage| Evento | Cuándo se emite |
|---|---|
| order.created | Orden aceptada y activa. |
| order.updated | Datos de contacto corregidos. |
| order.cancelled | Cancelación confirmada. |
| order.issue_failed | Orden aceptada, pero proveedor externo falló. |
✓
Verifica la firma antes de procesar.
Calcula HMAC-SHA256 sobre X-Portal-Timestamp + "." + cuerpo_json y compara el resultado en tiempo constante.
Confiabilidad
Errores e idempotencia
Todas las respuestas de negocio incluyen un código estable y un request_id para soporte y trazabilidad.
| HTTP | Significado | Acción recomendada |
|---|---|---|
| 401 | Token inválido o expirado. | Obtén un token nuevo. |
| 403 | La cuenta o el alcance no permite la operación. | Revisa las credenciales y permisos habilitados. |
| 409 | Conflicto de código, idempotencia o vigencia. | No repitas la venta; consulta su estado. |
| 422 | Estructura o regla comercial inválida. | Corrige los datos y usa una llave nueva. |
| 500/502 | Fallo técnico interno o de proveedor. | Reintenta con la misma llave. |
!
¿Misma llave o llave nueva?
Reutiliza la misma Idempotency-Key cuando el contenido no cambió y solo hubo un fallo de red. Si corriges una solicitud rechazada, genera una llave nueva.