PUT /stp/v1/transaction

STP llama este endpoint cuando el estado de una transferencia saliente de Finalitix cambia. Este endpoint nunca es llamado por el backend de Finalitix.

URL: PUT /stp/v1/transaction
Caller: STP Bank (directo)

Request body

{
  "id": 1234567,
  "empresa": "FINALITIX",
  "folioOrigen": "FNLTX9876543",
  "estado": "Liquidación",
  "causaDevolucion": "",
  "tsLiquidacion": 1713139200000,
  "firma": "<RSA-SHA256 en Base64>"
}

Campo	Tipo	Descripción
id	integer	ID de la transacción en STP (el mismo api_id guardado al enviar)
empresa	string	Siempre "FINALITIX"
folioOrigen	string	Folio/clave de rastreo original de Finalitix
estado	string	Ver valores posibles abajo
causaDevolucion	string	Motivo de devolución (vacío si no aplica)
tsLiquidacion	bigint	Timestamp de liquidación en milisegundos
firma	string	Firma RSA-SHA256. Se extrae antes de verificar

Valores de estado

Estado	Acción
Liquidación	Transacción exitosa. Actualiza api_state = "Liquidación" y state = "liquidation"
Cancelación	Transacción cancelada. Devuelve el monto al saldo, notifica al usuario (TRANSACTION_RETURNED)
Devolución	Igual que cancelación

Lógica de procesamiento

1. Verificar firma RSA con CryptoHandlerNotificacionEstadoTransaccion (solo ENV=prod)
2. Buscar transacción por api_id en tabla transaction
3. Actualizar api_state y state según el estado recibido
4. Si estado = "Cancelación" o "Devolución":
   a. account.amount += transaccion.amount (devolver saldo)
   b. Actualizar plan: remaining_transactions += 1
   c. Notificar usuario: Lambda Notifications (template TRANSACTION_RETURNED)
   d. Publicar en SQS: nota de crédito en Odoo
5. Notificar portal admin vía WebSocket (Lambda PubSub)

Respuesta

// 200 — Estado actualizado
{ "mensaje": "recibido" }

// 500 — Firma inválida (solo en prod)
{ "message": "error validando firma" }