Saltar al contenido principal
Version: 0.52.0-rc.1

Suscripciones en Tiempo Real

Lana proporciona notificaciones en tiempo real a través de suscripciones GraphQL sobre WebSocket. En lugar de sondear la API para detectar cambios, su aplicación puede suscribirse a eventos específicos y recibir actualizaciones en el momento en que ocurren.

Cómo Funciona​

Las suscripciones GraphQL utilizan una conexión WebSocket persistente para enviar eventos desde el servidor a su cliente.

Endpoint: ws://admin.localhost:4455/graphql (desarrollo) o wss://<su-dominio>/graphql (producción)

Protocolo: GraphQL sobre WebSocket (graphql-transport-ws)

Autenticación: La conexión WebSocket requiere la misma autenticación JWT que las consultas GraphQL regulares. Pase el token de autorización como parámetro de conexión al iniciar el handshake de WebSocket.

Ciclo de vida de la conexión​

  1. Abra una conexión WebSocket al endpoint de GraphQL
  2. Envíe el mensaje connection_init con su token de autenticación
  3. Envíe un mensaje subscribe con su consulta de suscripción
  4. Reciba eventos a medida que ocurren
  5. Envíe complete para cancelar la suscripción, o cierre la conexión

Suscripciones Persistentes​

Las suscripciones persistentes entregan eventos de manera confiable a través del patrón outbox. Los eventos sobreviven a los reinicios del servidor y se garantiza su entrega. Utilícelas para eventos críticos del negocio.

KYC de Cliente Actualizado​

Se dispara cuando el estado de verificación KYC de un cliente cambia (por ejemplo, de PENDING_VERIFICATION a VERIFIED o REJECTED).

Campos del payload:

CampoTipoDescripción
kycVerificationKycVerification!Nuevo estado de verificación: PENDING_VERIFICATION, VERIFIED o REJECTED
customerCustomer!El objeto de cliente completo con datos actualizados
subscription CustomerKycUpdated($customerId: UUID!) {
  customerKycUpdated(customerId: $customerId) {
    kycVerification
    customer {
      customerId
      email
      level
    }
  }
}

Colateralización de Línea de Crédito Pendiente Actualizada​

Se dispara cuando el nivel de colateralización de una línea de crédito pendiente cambia debido a movimientos de precios o depósitos de garantía.

Campos del payload:

CampoTipoDescripción
statePendingCreditFacilityCollateralizationState!FULLY_COLLATERALIZED o UNDER_COLLATERALIZED
collateralSatoshis!Cantidad actual de garantía en satoshis
priceUsdCents!Precio BTC/USD al momento de la actualización
recordedAtTimestamp!Cuándo se registró el evento
effectiveDate!Fecha efectiva del cambio de colateralización
pendingCreditFacilityPendingCreditFacility!El objeto completo de línea de crédito pendiente
subscription PendingFacilityCollateral($id: UUID!) {
  pendingCreditFacilityCollateralizationUpdated(pendingCreditFacilityId: $id) {
    state
    collateral
    price
    recordedAt
    effective
    pendingCreditFacility {
      pendingCreditFacilityId
      creditFacilityId
      status
      facilityAmount
    }
  }
}

Línea de Crédito Pendiente Completada​

Se activa cuando una línea de crédito pendiente transiciona a un estado terminal (aprobada y activada, o denegada).

Campos del payload:

CampoTipoDescripción
statusPendingCreditFacilityStatus!PENDING_COLLATERALIZATION o COMPLETED
recordedAtTimestamp!Cuándo se registró la finalización
pendingCreditFacilityPendingCreditFacility!El objeto completo de la línea de crédito pendiente
subscription PendingFacilityCompleted($id: UUID!) {
  pendingCreditFacilityCompleted(pendingCreditFacilityId: $id) {
    status
    recordedAt
    pendingCreditFacility {
      pendingCreditFacilityId
      creditFacilityId
      status
      facilityAmount
    }
  }
}

Propuesta de Línea de Crédito Concluida​

Se activa cuando un proceso de aprobación para una propuesta de línea de crédito alcanza una decisión final (aprobada o denegada).

Campos del payload:

CampoTipoDescripción
statusCreditFacilityProposalStatus!Estado final: APPROVED, DENIED, CUSTOMER_DENIED, etc.
creditFacilityProposalCreditFacilityProposal!El objeto completo de la propuesta
subscription ProposalConcluded($proposalId: UUID!) {
  creditFacilityProposalConcluded(creditFacilityProposalId: $proposalId) {
    status
    creditFacilityProposal {
      creditFacilityProposalId
      facilityAmount
      status
    }
  }
}

Colateralización de Línea de Crédito Actualizada​

Se activa cuando el nivel de colateralización de una línea de crédito activa cambia debido a movimientos de precios, cambios en el colateral o cambios en el saldo pendiente.

Campos del payload:

CampoTipoDescripción
stateCollateralizationState!FULLY_COLLATERALIZED, UNDER_MARGIN_CALL_THRESHOLD, UNDER_LIQUIDATION_THRESHOLD, NO_COLLATERAL o NO_EXPOSURE
collateralSatoshis!Cantidad actual de colateral en satoshis
outstandingInterestUsdCents!Interés acumulado pendiente
outstandingDisbursalUsdCents!Principal desembolsado pendiente
recordedAtTimestamp!Cuándo se registró el evento
effectiveDate!Fecha efectiva del cambio
priceUsdCents!Precio BTC/USD al momento de la actualización
creditFacilityCreditFacility!El objeto completo de la línea de crédito
subscription FacilityCollateral($facilityId: UUID!) {
  creditFacilityCollateralizationUpdated(creditFacilityId: $facilityId) {
    state
    collateral
    outstandingInterest
    outstandingDisbursal
    price
    recordedAt
    effective
    creditFacility {
      creditFacilityId
      status
      facilityAmount
    }
  }
}

Suscripciones Efímeras​

Las suscripciones efímeras entregan eventos transitorios únicamente mientras un cliente está activamente suscrito. Los eventos que ocurren mientras está desconectado no se reproducen. Utilízalas para actualizaciones de interfaz de usuario y notificaciones no críticas.

Exportación CSV de Cuenta de Libro Mayor Cargada​

Se activa cuando una exportación CSV de transacciones de cuenta de libro mayor termina de cargarse y está lista para descargar.

Campos de carga útil:

CampoTipoDescripción
documentIdUUID!ID del documento CSV generado, utilizado para generar un enlace de descarga
subscription CsvExportReady($accountId: UUID!) {
  ledgerAccountCsvExportUploaded(ledgerAccountId: $accountId) {
    documentId
  }
}

Precio en Tiempo Real Actualizado​

Se activa cada vez que cambia el tipo de cambio BTC/USD. No se requieren argumentos.

Campos de carga útil:

CampoTipoDescripción
usdCentsPerBtcUsdCents!Precio actual de 1 BTC en centavos de dólar
subscription PriceUpdates {
  realtimePriceUpdated {
    usdCentsPerBtc
  }
}

Ejecución de Informe Actualizada​

Se activa cuando se crea una ejecución de informe o cambia su estado (por ejemplo, de QUEUED a RUNNING a SUCCESS o FAILED). No se requieren argumentos — entrega actualizaciones para todas las ejecuciones de informes.

Campos de carga útil:

CampoTipoDescripción
reportRunIdUUID!ID de la ejecución de informe que fue actualizada
subscription ReportUpdates {
  reportRunUpdated {
    reportRunId
  }
}

Mejores Prácticas​

  • Manejo de reconexión: Las conexiones WebSocket pueden caerse. Implementa reconexión automática con retroceso exponencial en tu cliente.
  • Procesamiento idempotente: Las suscripciones persistentes pueden volver a entregar eventos en casos excepcionales. Diseña tus manejadores para procesar de forma segura el mismo evento más de una vez.
  • Usa suscripciones persistentes para flujos críticos: Los cambios de KYC de clientes, transiciones de estado de facilidades crediticias y actualizaciones de garantías se entregan de manera confiable. Confía en estas para integraciones críticas del negocio.
  • Usa suscripciones efímeras para la interfaz de usuario: Las actualizaciones de precios y notificaciones de exportación CSV son más adecuadas para retroalimentación de interfaz de usuario en tiempo real, no para procesamiento duradero.
  • Suscríbete a entidades específicas: La mayoría de las suscripciones aceptan un ID de entidad para filtrar eventos. Suscríbete solo a las entidades que necesitas en lugar de procesar todos los eventos del lado del cliente.