Vouchers nominados (becas) — Consumo desde Lambda contra el motor de Humming

1. Qué es un voucher nominado

Un voucher nominado es un instrumento de descuento personal, emitido a un documento (no a una cuenta, no a un passengerId). Es la base del programa de becas y de los pasajes abiertos personales.

Se distingue del voucher de cuenta (prepago corporativo) en que:

La regla de oro: un voucher nominado solo aplica si uno de los pasajeros del booking tiene el documento del voucher. Ese match es la validación central y el mecanismo de seguridad.

2. Autenticación

Todos los endpoints se consumen por POST al motor de Humming:

POST  {BASE_URL}/intranet/sys/mods/flights/motor.php

{BASE_URL} depende del entorno (PRD / DEV / LOC).

Header obligatorio:

Authorization: Bearer {HUMMING_API_TOKEN}
Content-Type: application/x-www-form-urlencoded   (o JSON; el motor acepta ambos)

No hay gate de rol. Cualquier cliente autenticado por Bearer (incluido un Lambda) puede consumir estos endpoints. La seguridad no es el rol, es el match de documento: no se puede aplicar la beca de otra persona a un booking donde esa persona no viaja.

3. El flujo completo

1. OFFER      getBookingSummary       ->  qué pasajeros son elegibles (nominal_vouchers)
2. VERIFY     verifyPassengerVoucher  ->  ¿el código aplica? (dry-run, NO consume, devuelve preview)
3. REDEEM     redeemPassengerVoucher  ->  aplica + consume el descuento
4. REFRESH    getBookingSummary       ->  el total ya refleja el descuento

El paso VERIFY es opcional (para previsualizar antes de aplicar). REDEEM revalida todo internamente, así que se puede ir directo de OFFER a REDEEM.

4. Endpoint 1 — getBookingSummary (el OFFER)

Devuelve el resumen del booking incluyendo nominal_vouchers: qué reservas/pasajeros son sujetos de aplicar un voucher nominado.

Request

POST /intranet/sys/mods/flights/motor.php
Authorization: Bearer {HUMMING_API_TOKEN}

{
  "execute": "getBookingSummary",
  "id": "{md5(bookingId)}"
}

⚠️ Ojo con el identificador: getBookingSummary recibe id = md5 del bookingId (no el entero). Los otros dos endpoints reciben bookingId (entero). Es una asimetría del contrato actual — tenerla presente.

Response (fragmento relevante)

{
  "nominal_vouchers": {
    "148264": {
      "reservationId": 148264,
      "passengerId": 2954,
      "passengerName": "Perez, Juan",
      "IDNumber": "17923900",
      "IDCountry": "AR",
      "vouchers": [
        {
          "voucherId": 130,
          "voucherCode": "XW9I7PSGZ4",
          "discount": 50.0,
          "untilDate": "2027-02-28",
          "remaining": 35,
          "applied": false
        }
      ]
    }
  }
}

Estructura de nominal_vouchers

Objeto keyed por reservationId. Cada entrada:

• Si el booking no tiene pasajeros elegibles → nominal_vouchers viene vacío ([] o {}).
• Un voucher ya agotado y no aplicado a esta reserva no aparece.

5. Endpoint 2 — verifyPassengerVoucher (validar, sin consumir)

Valida un código contra el booking en modo dry-run: corre todas las validaciones y devuelve el preview del descuento, sin insertar nada ni tocar la facturación. Ideal para el momento en que el usuario ingresa el código.

Request

POST /intranet/sys/mods/flights/motor.php
Authorization: Bearer {HUMMING_API_TOKEN}

{
  "execute": "verifyPassengerVoucher",
  "voucherCode": "XW9I7PSGZ4",
  "bookingId": 73269
}

Se puede pasar voucherCode o voucherId. bookingId es el entero.

Response

{
  "status": 1000,
  "msg": "OK",
  "reservations": [148264],
  "discountAmount": 107.50,
  "discount": 50.0
}

6. Endpoint 3 — redeemPassengerVoucher (aplicar + consumir)

Valida (igual que verify) y, si pasa, aplica el descuento (registra la línea per-reserva) y refresca la facturación. Es idempotente: reaplicar el mismo voucher al mismo booking recalcula, no duplica.

Request

POST /intranet/sys/mods/flights/motor.php
Authorization: Bearer {HUMMING_API_TOKEN}

{
  "execute": "redeemPassengerVoucher",
  "voucherCode": "XW9I7PSGZ4",
  "bookingId": 73269
}

Response: idéntica a verifyPassengerVoucher (status, reservations, discountAmount, discount, err).

Tras un redeem status=1000, volvé a llamar getBookingSummary para que el total refleje el descuento.

7. Reglas de validación (lo que el motor verifica)

Al verificar/redimir, el motor aplica en orden:

1. Es nominado: discount > 0 y tiene IDNumber. Si no → error (no es una beca).
2. Vigencia: untilDate >= hoy. Si venció → rechazo (1026).
3. Consumo: cantidad de bookings distintos que ya redimieron el voucher < tripCount. Si se agotó → rechazo (1026).
4. Documento (el central): algún pasajero del booking debe tener el mismo documento normalizado que el voucher (upper(regexp_replace(IDNumber,'[^A-Za-z0-9]','')) + upper(trim(IDCountry))). Si ninguno → rechazo (1026, "el código es del documento X, que no está entre los pasajeros").
5. Cálculo per-pasajero: el descuento aplica solo a la(s) reserva(s) del becado, y sobre (tarifa base + equipaje de esa reserva) × discount%. Los demás pasajeros del booking pagan full.

8. Códigos de estado

Regla para el cliente Lambda: 1026 es esperable y accionable (mostrar el motivo). 2000 es un problema de integración (loguear).

9. Secuencia recomendada para el Lambda

1) getBookingSummary(id = md5(bookingId))
     -> leer nominal_vouchers
     -> si vacío: no hay becas, seguir el checkout normal

2) Por cada reservationId elegible:
     mostrar el pasajero y pedir/confirmar el código

3) verifyPassengerVoucher(voucherCode, bookingId)
     -> status 1000: mostrar "aplica {discount}% — ahorro USD {discountAmount}"
     -> status 1026: mostrar err (documento/vencido/agotado)

4) Al confirmar o cerrar:
     redeemPassengerVoucher(voucherCode, bookingId)
     -> status 1000: aplicado

5) getBookingSummary(...) de nuevo
     -> el total ya viene con el descuento

10. Notas y advertencias

• Idempotencia: redeemPassengerVoucher se puede llamar varias veces sin duplicar (borra el descuento previo de ese voucher en el booking y recalcula). Útil para reintentos.
• Snapshot: el monto del descuento se congela al redimir. Si después cambia la tarifa base del booking, hay que re-redimir para recalcularlo.
• Un voucher, varias reservas: si el becado tiene más de una reserva en el booking (ej. ida y vuelta como dos filas), el descuento se aplica a todas las del becado, y consume 1 uso por booking (no por reserva).
• Asimetría de identificador: getBookingSummary usa id = md5(bookingId); verify/redeem usan bookingId entero.
• El voucherCode viaja en el OFFER: hoy nominal_vouchers expone el voucherCode de los vouchers disponibles. Si el modelo de negocio exige que la persona presente el código (y no que el sistema lo sugiera), pedir que se oculte del offer.
• Seguridad: no hace falta gate de rol porque el match de documento ya impide aplicar la beca de un tercero. Aun así, el Bearer token es obligatorio y no debe exponerse en clientes públicos.