Flujo de Transferencia Entrante

Cuando alguien envía dinero a una CLABE de Finalitix, STP notifica a la API en tiempo real.

Flujo completo

STP Bank
      │
      │ POST /stp/v1/transaction
      │ { cuentaBeneficiario: "64618001000001237", monto: "5000.00",
      │   nombreOrdenante: "JUAN PEREZ", ... firma: "..." }
      │
      ▼
TransactionNotificationController.postAbono
      │
      ├─ 1. Obtener config STP (Secrets Manager: STP_SECRET_NAME)
      │       → Falla: 401 "faltan credenciales"
      │
      ├─ 2. Verificar firma RSA [solo ENV=prod]
      │    CryptoHandlerAbono.verify(firma, publicKey)
      │       → Inválida: 500 "error validando firma"
      │
      ├─ 3. Buscar cuenta por cuentaBeneficiario
      │       → No existe: 400 { message: "devolver", id: 1 }
      │
      ├─ 4. Verificar cuenta.active === true
      │       → Inactiva: 400 { message: "devolver", id: 2 }
      │
      ├─ 5. Verificar usuario no bloqueado/sellado
      │       → Bloqueado: saveLogTransaction + 400 { message: "devolver", id: 2 }
      │
      ├─ 6. Guardar transacción en MySQL
      │        type = "abono"
      │        state = "liquidation"
      │        api_id = body.id
      │        sign = body.folioCodi
      │
      ├─ 7. Actualizar saldo: account.amount += monto
      │
      ├─ 8. Lambda FinalitixContact: crear/actualizar contacto del ordenante
      │
      ├─ 9. SQS (ACC_MOVE_SQS_URL):
      │        method: "create_post_move"
      │        model: "account.move"
      │        (póliza contable de abono en Odoo)
      │
      ├─ 10. Lambda PubSub: notificación WebSocket al usuario (TRANSACTION_IN)
      │
      ├─ 11. Lambda Notifications:
      │         template: "TRANSACTION_IN"
      │         (email/SMS al usuario)
      │
      ├─ 12. SQS (CUSTOMER_NOTIFICATION_SQS_URL):
      │         type: "abono"
      │         (webhook al sistema del cliente)
      │
      ├─ 13. Verificar 80% del límite del plan:
      │        Si transacciones_del_mes >= 0.8 × límite_mensual:
      │          Crear alerta FABONO
      │          Lambda: LOW_REMAINING_TRANSACTIONS
      │
      ▼
STP Bank
  200 { message: "recibido" }

Respuestas posibles a STP

Respuesta	Significado	Acción de STP
{ message: "recibido" }	Abono procesado	STP cierra la operación
{ message: "devolver", id: 1 }	Cuenta no encontrada	STP devuelve el dinero al remitente
{ message: "devolver", id: 2 }	Cuenta inactiva o usuario bloqueado	STP devuelve el dinero al remitente

Ventana de tiempo

STP espera respuesta en un tiempo limitado. Si la API no responde, STP puede reintentar o devolver el dinero automáticamente. Es crítico que los pasos 1-6 sean rápidos.