Saltar al contenido principal
SILOC liquida sobre una base de neto diferido, por día hábil. Con su conexión MQ de SILOC configurada, el servicio mantiene abierta la conexión de gateway y envía sus mensajes admitidos. No mantiene ninguna posición contable.

Licencia

Lerian SILOC necesita una licencia de Lerian en todos los entornos, definida en LICENSE_KEY (consulta Variables de entorno). Sin ella, el servicio se niega a iniciar. Toda ruta bajo /api/v1/siloc pasa por la compuerta de licencia. Una solicitud que la licencia rechaza responde 403 con un código LCS-. /health, /readyz y /version quedan abiertos. /readyz informa una verificación license que nunca aparece como down, descrita en la página de variables de entorno.

Ventanas de liquidación

SILOC liquida sobre una base neta multilateral diferida, en días hábiles. Núclea define las ventanas de liquidación diarias para los productos de boleto y tarjetas. Lerian SILOC registra y aplica los mensajes de orden de transferencia que abren, avanzan, concilian y cierran el estado de su ciclo. No calcula la posición neta monetaria.

Certificados regulados

Registras los certificados del gateway como un certificado público más una referencia de custodia externa. El servicio no mantiene ninguna clave privada. Cuando registras un certificado, el servicio analiza su asunto, número de serie y ventana de validez. Revocas el certificado a través de la API cuando lo retiras. Un estado de credencial deshabilitada detiene el gateway. Un certificado deshabilitado o revocado falla de forma cerrada la conexión en lugar de seguir funcionando con credenciales inválidas. Mientras el certificado de firma o el certificado de la câmara está revocado o fuera de su vigencia, un servicio en ejecución sigue en rotación y rechaza cada nueva solicitud saliente con 503 SILOC-0024. No almacena nada.

Contingencia y recuperación

La ruta de ingesta de SFN tiene resultados definidos ante fallos. No promete retener cada frame. Tampoco promete que cada operación tenga un único efecto de extremo a extremo:
  • Un mensaje decodificado sin un BCMSG.NUOp no vacío, o un par (CodProdt, CodMsg) no admitido falla de forma cerrada hacia una excepción operativa. El servicio no admite LDL0020 ni LDL0006, y nunca los retransmite como financiamiento de liquidación.
  • La retransmisión a SLC es al menos una vez. Para un frame de financiamiento de SLC decodificado correctamente, el servicio verifica la desduplicación duradera mediante BCMSG.NUOp y el número de parte (NumSeq) antes de retransmitir. Escribe el registro de mensaje procesado solo después de que la retransmisión tenga éxito. Esto no es una garantía incondicional de exactamente una vez de extremo a extremo.
  • Mensajes aparcados y rechazados. GET /api/v1/siloc/dlq/deferred enumera los mensajes entrantes aparcados para su repetición. Filtra con status=SEMANTIC_REJECTED para ver los mensajes que el servicio rechazó por su contenido y nunca aplica.
  • Frames en cuarentena. GET /api/v1/siloc/dlq/quarantine enumera los frames que el servicio rechazó más de MQ_BACKOUT_THRESHOLD veces y aparcó en su base de datos. Cada entrada devuelve los bytes del frame en frame. Después de ocuparte del frame, resuelve el frame. Entonces el feed deja de devolverlo. El servicio no lo vuelve a procesar, y limpia INBOUND_QUARANTINED cuando no queda ningún frame sin resolver.
  • Caída de Núclea. Mientras el queue manager de SILOC de Núclea no es accesible, el servicio sigue en rotación y mantiene disponibles sus lecturas. Rechaza cada nueva solicitud saliente con 503 SILOC-0024 y no almacena nada. Cuando el queue manager rechaza la configuración de este despliegue, detail nombra el ajuste que hay que corregir. Envía la solicitud de nuevo con el mismo X-Idempotency después de que vuelva la conexión.
  • Fallos de retransmisión. GET /api/v1/siloc/dlq/relay-failures enumera los frames de financiamiento aparcados durante una caída de la retransmisión. Vuelve a procesar un frame después de que la retransmisión se recupere. La repetición de una parte de mensaje ya retransmitida resuelve el frame sin una segunda retransmisión.

Conciliación

La conciliación se ejecuta en varias granularidades:
  • Ledger de desduplicación de mensajes procesados. Para los frames de financiamiento de SLC decodificados correctamente con un NUOp no vacío, el ledger identifica cada parte de mensaje por BCMSG.NUOp y NumSeq. Registra una parte solo después de una retransmisión exitosa. Los mensajes no decodificados y no admitidos no reciben un registro de mensaje procesado.
  • Feed de auditoría de la retransmisión. El feed de retransmisión enumera los mensajes de financiamiento que el servicio retransmitió a Lerian SLC.
  • Estado por participante e historial de estados. Cada participante lleva su estado operativo por producto. El servicio registra cada cambio de estado como una entrada del historial de eventos de estado.
  • Conciliación de los ciclos OT. Con RECONCILE_ENABLED=true, el servicio compara la obligación de cada ciclo con el resultado multilateral GEN0015 más reciente de la câmara. Un ciclo solo se liquida cuando el resultado coincide, la obligación tiene su prueba del STR y su período de depósito tiene su PAG0103.

Monitoreo, alertas y auditoría

Lerian SILOC expone una superficie de operador para observar los ciclos de liquidación de OT, la salud de la conexión y la retransmisión, las solicitudes salientes y el estado de los participantes. Las superficies de ciclo y conciliación reportan el estado registrado y los conjuntos de conciliación. No calculan cifras de posición agregadas al leer.
  • Ciclos de liquidación de OT. GET /api/v1/siloc/cycles y GET /api/v1/siloc/cycles/{cycleId} enumeran e inspeccionan los ciclos. Ambas lecturas traen el objeto reconciliation del ciclo cuando existe una conciliación. Nombra el resultado comparado en resultNoticeId y el lado de ese resultado en clearingSide. GET /api/v1/siloc/cycles/{cycleId}/recalculations devuelve la cadena de rondas de recálculo del ciclo, incluido el cierre de la ventana de complemento/depósito de cada ronda.
  • Instrucciones de liquidación. GET /api/v1/siloc/settlement-instructions y GET /api/v1/siloc/settlement-instructions/{instructionId} devuelven las patas de obligación de cada ciclo. Un débito lleva depositAdvisoryId, el aviso que recibe el comando de depósito de Lerian SPB. Un depósito rechazado deja el débito abierto para un nuevo depósito. Un depósito que Lerian SPB cierra sin respuesta del STR, porque su cuadrícula cerró, su día de movimiento terminó o dos operadores lo cerraron, también deja el débito abierto. La obligación registra entonces el motivo en lastFundingAck.refusal.railClose (GRADE_CLOSED, DAY_ENDED u OPERATORS_CLOSED) y no tiene lastFundingAck.refusal.messageCode. Un PAG0101 que excluye a esta institución del ciclo cierra sus débitos no depositados.
  • Resultados multilaterales. GET /api/v1/siloc/ot-multilateral-results enumera los resultados multilaterales que la câmara envía en el GEN0015, del más reciente al más antiguo, tal como la câmara los envió. GET /api/v1/siloc/ot-multilateral-results/{noticeId} devuelve el resultado almacenado de una notificación GEN0015, como la que nombra el resultNoticeId de un ciclo. Una notificación sin resultado legible responde 404 SILOC-0007.
  • Solicitudes salientes. GET /api/v1/siloc/outbound/messages enumera las solicitudes que envió la institución, de la más reciente a la más antigua. Filtra por status: para una solicitud FAILED, lastError indica el motivo. O nunca salió hacia Núclea, o dos operadores la cerraron porque Núclea nunca respondió. Una solicitud REFUSED volvió de Núclea con un error. Una solicitud SLC0004 también termina REFUSED cuando su respuesta SLC0004R1 trae una situación distinta de éxito, y lastError indica SitLancSLC=<code>. Filtra por held=true para las solicitudes retenidas a la espera de una respuesta que Núclea nunca envió. Cómo funciona Lerian SILOC describe el cierre por dos operadores.
  • Alertas operativas. GET /api/v1/siloc/alerts devuelve un feed paginado por keyset que incluye solo las alertas activas. Pasa activeOnly=false para incluir las alertas desactivadas como historial. Los tipos de alerta son:
    • Ciclo de liquidación: WINDOW_CLOSING (se acerca un plazo de depósito/complemento), RECALCULATION (un ciclo está en una ronda de recálculo), SCHEDULE_CHANGE (un operador registró un anuncio de cambio de cronograma de contingencia) y OT_CYCLE_NOT_SETTLED. OT_CYCLE_NOT_SETTLED indica un ciclo que sigue abierto 60 minutos después de su PAG0103.
    • Conexión y workers: CONNECTION_DOWN, RELAY_DOWN, CERTIFICATE_EXPIRY, OUTBOUND_DISPATCHER_DOWN, OT_REPLAY_DOWN y XSD_VALIDATOR_DOWN.
    • Estado del participante: PARTICIPANT_EXCLUDED (un PAG0101 aplicado mueve a una institución a un estado distinto de 1 que difiere del estado que el servicio tenía para ella: el estado del último PAG0101, o 1 para una institución registrada). La alerta se genera con o sin un ciclo en liquidación. Sus detalles incluyen product, ispb, participantName (cuando la institución está registrada), status, statusMeaning, previousStatus, noticeAt, movementDate y sourceNuOp. Una notificación reentregada no genera una segunda alerta.
    • Avisos de la câmara: CAMARA_CLOSED, CAMARA_INTERRUPTED, COLLATERAL_REQUIRED, COLLATERAL_SUBSTITUTION y ELIGIBLE_ASSETS_CHANGED.
    • Mensajes entrantes y solicitudes: INBOUND_QUARANTINED, INBOUND_SEMANTIC_REJECTED, MULTILATERAL_RESULT_UNREADABLE (un GEN0015 de la câmara trae un resultado que el servicio no puede leer) y UNANSWERED_REQUEST.
  • Reconocimiento de alertas. POST /api/v1/siloc/alerts/{id}/acknowledge registra que un operador vio la alerta, con una nota opcional de hasta 500 caracteres, y mueve la alerta al historial. No termina la condición. Cuando el servicio verifica una alerta periódicamente, como RELAY_DOWN, genera la alerta de nuevo mientras su condición persiste. Una alerta que ya está inactiva responde 409. INBOUND_SEMANTIC_REJECTED, MULTILATERAL_RESULT_UNREADABLE y PARTICIPANT_EXCLUDED solo se cierran por reconocimiento. Una alerta de condición, como RELAY_DOWN o RECALCULATION, también se limpia cuando se resuelve su condición. Por ejemplo, un ciclo que liquida limpia su alerta RECALCULATION en la ruta de liquidación.
  • Escenarios de homologación. GET /api/v1/siloc/homologation/scenarios enumera los escenarios de certificación y el estado de cada uno. Ejecutar un escenario verifica su criterio de aprobación contra el propio estado del riel y registra la evidencia. No envía nada a Núclea.
  • Registro de auditoría. GET /api/v1/siloc/audit-records devuelve una lectura paginada y textual del registro de auditoría, por ejemplo para exportar el registro de una acción de operador o un cambio de estado de participante. Los límites from y to son instantes RFC3339 (el servicio rechaza los valores de solo fecha).

Cronograma y contingencia

La cuadrícula canónica de ventanas de OT y el calendario de días hábiles son artefactos compilados del servicio. El servicio proyecta de forma textual las cuadrículas de horarios y los avisos de sesión que envía Núclea.
  • Calendario y ventanas. GET /api/v1/siloc/schedule/calendar devuelve el calendario de días hábiles, y GET /api/v1/siloc/schedule/windows devuelve la cuadrícula canónica compilada de ventanas de OT. La cuadrícula es un artefacto estático, no una lectura por día, y el servicio la devuelve incluso cuando el almacén de datos está caído.
  • Cuadrículas y sesión de la câmara. GET /api/v1/siloc/schedule/grids devuelve las cuadrículas de horarios que envió Núclea, a partir de sus avisos de cambio y de las respuestas a las consultas de horarios de la institución. GET /api/v1/siloc/schedule/camara-session devuelve los avisos más recientes de apertura, cierre, interrupción y reanudación.
  • Cambios de cronograma por contingencia. POST /api/v1/siloc/schedule/changes registra un anuncio de contingencia que el operador recibió fuera de banda desde Núclea. El cuerpo lleva reason (≤500 caracteres), origin (el canal del anuncio o la referencia upstream, ≤256 caracteres), effectiveAt, el instante RFC 3339 anunciado en que el cambio entra en vigor, y un windowSeq opcional que nombra la ventana canónica afectada. Con windowSeq 1 o 2, effectiveAt pasa a ser el cierre de depósito de esa ventana para WINDOW_CLOSING. Debe caer en la fecha de São Paulo de la ventana, no antes de que abra. Con windowSeq 3, effectiveAt es el cierre LBTR posterior que Núclea anuncia cuando extiende la cuadrícula. effectiveAt debe caer después de las 17h30 del día de movimiento y antes de las 06h40 del día siguiente, así que un cierre pasada la medianoche extiende el día anterior. Un cambio con windowSeq 3 para un día de movimiento que no es día hábil responde 422 SILOC-0022, porque el ciclo LBTR de ese día está cerrado todo el día. Los mensajes LTR0002, LTR0008 y SLC0004 de ese día quedan abiertos hasta ese cierre en lugar de hasta las 17h30, y las demás solicitudes del día quedan abiertas hasta él en lugar de hasta la medianoche. Un cierre registrado después de las 17h30 no reabre lo que ya falló. El registro es de solo anexado: un anuncio posterior nunca reescribe uno anterior. El anuncio más reciente sí se convierte en la única alerta activa SCHEDULE_CHANGE. Registrar uno limpia la alerta anterior y genera una nueva cuyo plazo es effectiveAt de forma textual. GET /api/v1/siloc/schedule/changes devuelve los cambios registrados, del más reciente al más antiguo.
Registra un cambio de cronograma por contingencia: