POST /stp/v1/transaction

STP llama este endpoint cuando un usuario de Finalitix recibe una transferencia SPEI (abono). Este endpoint nunca es llamado por el backend de Finalitix.

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

Request body

{
  "id": 1234567,
  "fechaOperacion": 20240415,
  "institucionOrdenante": 00000,
  "institucionBeneficiaria": 00000,
  "claveRastreo": "INTL20240415001",
  "monto": "5000.00",
  "nombreOrdenante": "JUAN PEREZ GARCIA",
  "tipoCuentaOrdenante": 40,
  "cuentaOrdenante": "002180012345678901",
  "rfcCurpOrdenante": "PEGJ800101ABC",
  "nombreBeneficiario": "MARIA LOPEZ MARTINEZ",
  "tipoCuentaBeneficiario": 40,
  "cuentaBeneficiario": "64618001000001234",
  "nombreBeneficiario2": "",
  "tipoCuentaBeneficiario2": 0,
  "cuentaBeneficiario2": "",
  "rfcCurpBeneficiario": "LOMM850202XYZ",
  "conceptoPago": "Pago de factura 001",
  "referenciaNumerica": 1234567,
  "empresa": "FINALITIX",
  "tipoPago": 30,
  "tsLiquidacion": 1713139200000,
  "folioCodi": "",
  "firma": "<RSA-SHA256 en Base64>"
}

Campo	Tipo	Descripción
`id`	integer	ID único de la transacción en STP
`fechaOperacion`	integer	Fecha en formato `YYYYMMDD`
`institucionOrdenante`	integer	Código de banco del remitente
`institucionBeneficiaria`	integer	Código de banco del beneficiario (00000 = STP/Finalitix)
`claveRastreo`	string	Clave de rastreo SPEI del banco ordenante
`monto`	string	Monto en MXN (ej. `"5000.00"`)
`nombreOrdenante`	string	Nombre del remitente
`tipoCuentaOrdenante`	integer	Tipo de cuenta (40 = CLABE)
`cuentaOrdenante`	string(18)	CLABE del remitente
`rfcCurpOrdenante`	string	RFC o CURP del remitente
`nombreBeneficiario`	string	Nombre del beneficiario (usuario Finalitix)
`tipoCuentaBeneficiario`	integer	Tipo de cuenta beneficiaria
`cuentaBeneficiario`	string(18)	CLABE del beneficiario
`rfcCurpBeneficiario`	string	RFC o CURP del beneficiario
`conceptoPago`	string	Descripción del pago
`referenciaNumerica`	integer	Referencia numérica del pago
`empresa`	string	Siempre `"FINALITIX"`
`tipoPago`	integer	Siempre `30`
`tsLiquidacion`	bigint	Timestamp de liquidación en milisegundos
`folioCodi`	string	Folio CoDi (puede estar vacío)
`firma`	string	Firma RSA-SHA256. Se extrae antes de verificar

Lógica de procesamiento

1. Verificar firma RSA (solo ENV=prod)
2. Buscar cuenta por cuentaBeneficiario en tabla account
   → No existe: responder devolver id=1
3. Verificar que cuenta.active === true
   → Inactiva: responder devolver id=2
4. Verificar que usuario no esté bloqueado/sellado
   → Bloqueado: registrar en LogsTransaction, responder devolver id=2
5. Guardar transacción tipo "abono" en tabla transaction
6. Actualizar saldo: account.amount += monto
7. Crear/actualizar contacto del ordenante vía Lambda FinalitixContact
8. Publicar en SQS (ACC_MOVE_SQS_URL): create_post_move → account.move en Odoo
9. Notificar usuario vía WebSocket (Lambda PubSub)
10. Notificar usuario por email/SMS (Lambda Notifications, template TRANSACTION_IN)
11. Enviar webhook al cliente vía SQS (CUSTOMER_NOTIFICATION_SQS_URL)
12. Verificar si se alcanzó el 80% del límite de transacciones del plan
    → Sí: crear alerta y notificar

Respuesta

// 200 — Abono registrado exitosamente
{ "message": "recibido" }

// 400 — Cuenta no encontrada
{ "message": "devolver", "id": 1 }

// 400 — Cuenta inactiva o usuario bloqueado
{ "message": "devolver", "id": 2 }

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