Cómo funciona Lerian STA

Lerian STA mueve archivos en dos direcciones. Cada intercambio es una transferencia, un único archivo que se mueve entre la institución y BACEN. Un número de protocolo rastrea la transferencia a lo largo del ciclo de vida del protocolo de BACEN. Cada extremo verifica el SHA-256.

Envío saliente

La institución, o un producto upstream de Lerian, almacena el archivo en el bucket de Lerian STA y crea una transferencia cuya referencia de archivo es outbound/<file name>. Cuando TRANSFER_SCHEDULER_ENABLED es true, un worker calcula el SHA-256 y el tamaño del archivo y obtiene de BACEN un número de protocolo que los declara. Sube los bytes del archivo. BACEN valida los bytes contra el SHA-256 declarado. Una creación de transferencia por POST /v1/transfers necesita un header X-Idempotency de como máximo 256 bytes. Sin él, Lerian STA responde 400 con STA-0001. Si tu servicio crea transferencias en reacción a un evento, envía una clave derivada del identificador de ese evento. Así, los reintentos de un mismo disparador llevan la misma clave. Lerian CCS v1.0.0 envía sus lotes ACCS001 sin el header X-Idempotency, y Lerian STA v1.2.0 y posteriores los rechazan. Si ejecutas Lerian CCS v1.0.0, mantén Lerian STA en v1.1.0. Durante 7 días, una repetición con la misma clave y la misma solicitud reproduce la primera respuesta con X-Idempotency-Replayed: true. La misma clave con una solicitud diferente devuelve 422. Después de los 7 días, Lerian STA sigue sin crear una segunda transferencia para la clave mientras exista la primera transferencia. Después de un 4xx con un código STA-NNNN, envía la solicitud corregida con la misma clave. Después de un 5xx, reintenta con la misma clave. Si Lerian STA creó la transferencia antes del fallo, el reintento responde 201 con X-Idempotency-Replayed: true y no crea una segunda transferencia. Un 503 con STA-0008 significa que nada se ejecutó. Una respuesta con el header X-Idempotency-Fenced, incluida una 2xx, significa que Lerian STA perdió el registro de la clave después de que la solicitud se ejecutó. Con true, Lerian STA rechaza toda repetición de la clave durante 7 días. Con false, una repetición se responde a partir de la transferencia. La lista de errores de STA describe cada respuesta de idempotencia. Cuando BACEN STA no está disponible, la conexión con BACEN falla o la credencial está en rotación, Lerian STA retiene la carga y no gasta ningún intento. También retiene la carga cuando BACEN rechaza la contraseña de la credencial. La transferencia pasa entonces a llevar heldUntil. Lerian STA reintenta cada 5 minutos. Después de una contraseña rechazada, espera hasta que un operador informe la contraseña actual de la credencial y entonces envía los archivos retenidos de inmediato. Una carga retenida espera, como máximo, hasta el plazo de envío de 48 horas de BACEN. El plazo se cuenta desde que BACEN asigna el protocolo, o desde la creación de la transferencia si la propia solicitud de protocolo fue retenida. En el plazo, Lerian STA cancela la transferencia con PROTOCOL_EXPIRED. La transferencia avanza a través del ciclo de vida de BACEN:

Estado	Significado
Protocolo generado	Lerian STA aceptó la transferencia. BACEN asigna el número de protocolo mientras la transferencia está en este estado.
Transmisión iniciada / terminada	Lerian STA está subiendo los bytes y, luego, terminó de subirlos.
Verificación de integridad	BACEN está validando el SHA-256 declarado.
Recibido	BACEN recibió el archivo.
Entregado	BACEN entregó el archivo a su destino.
En procesamiento	BACEN está procesando el archivo.
Aceptado	BACEN aceptó el archivo. Un éxito terminal.
Inconsistente	Los bytes fallaron la verificación de integridad de BACEN. Un fallo terminal.
Rechazado	BACEN rechazó el archivo después del procesamiento. Un fallo terminal.
Cancelado	La transferencia terminó antes de un veredicto de BACEN, por ejemplo por un operador, en el tope de intentos, en el plazo de envío de BACEN o en el TTL. Un estado terminal.
Respondido fuera de banda	Lerian STA encontró una respuesta entrante separada para el protocolo. Este estado terminal local confirma la llegada de la respuesta, no si BACEN aceptó o rechazó el archivo; registra el historial de auditoría pero no emite ningún evento de resultado de transferencia.
Creación de protocolo no confirmada	Un estado terminal local. Lerian STA no puede confirmar que BACEN asignó un protocolo. Un operador debe conciliarlo.
Evaluación no confirmada	Un estado terminal local. El TTL se agotó mientras BACEN aún debía un veredicto. No emite ningún evento de resultado de transferencia.

Un intento que falla sin ser retenido gasta un intento. En el tope (TRANSFER_MAX_ATTEMPTS), Lerian STA cancela la transferencia. Después de que el archivo se envía, cada paso de BACEN también tiene un TTL de reloj de pared (44 horas de forma predeterminada), contado desde el último cambio de estado. Cuando el TTL se agota, Lerian STA cancela la transferencia, o la marca como Evaluación no confirmada si BACEN aún debía un veredicto.

Descubrimiento y descarga entrantes

Cuando TRANSFER_INBOUND_ENABLED es true, Lerian STA consulta a BACEN por archivos disponibles. Cada configuración de fuente entrante define su intervalo de polling, de 15 a 1,800 segundos. Para iniciar una consulta entrante en el momento, envía POST /v1/inbound-source-configs/{id}/trigger-poll con un header X-Idempotency. Durante 7 días, una repetición con la misma clave reproduce una respuesta 200 o 202 y no consulta de nuevo. Para cada archivo, Lerian STA compara el código de sistema de BACEN del archivo contra las configuraciones de fuente entrante. Un archivo que no coincide con ninguna recibe el producto de origen unrouted. Luego Lerian STA descarga los bytes. Verifica los bytes contra el SHA-256 reportado por BACEN. Almacena el archivo de forma duradera en el almacenamiento de objetos. Cuando el archivo verificado es un archivo ZIP con una sola entrada, Lerian STA extrae la entrada y la entrega en lugar del archivo ZIP. El claim-check describe entonces el archivo extraído: object_key, file_name, size_bytes y sha256 se refieren a la entrada. Lerian STA calcula ese sha256 sobre los bytes extraídos. TRANSFER_INBOUND_EXTRACT_MAX_EXPANSION_RATIO y TRANSFER_INBOUND_EXTRACT_MAX_EXTRACTED_BYTES limitan el tamaño extraído. Cuando Lerian STA no extrae una entrada, entrega el archivo tal como lo recibió. El claim-check lleva entonces el hash y el tamaño que BACEN reportó. Cuando el hash no coincide, Lerian STA hace hasta 3 intentos de forma predeterminada y luego termina la transferencia como inconsistente. Cuando una descarga falla, hace hasta 5 intentos de forma predeterminada y luego cancela la transferencia. Cuando BACEN se niega a autorizar la descarga, la transferencia termina de inmediato como no autorizada. En cada caso, Lerian STA no entrega el archivo a su producto de origen.

Acciones del operador

Un operador solo puede actuar donde el estado y la configuración de la transferencia lo permiten:

Cancelar cuando la máquina de estados permite una transición a Canceled, lo que excluye Verificación de integridad y Entregado. La cancelación es local. Lerian STA no envía nada a BACEN.
Reintentar una carga saliente retenida, la transferencia que lleva heldUntil. Reintentar adelanta el próximo intento a ahora. No gasta ningún intento y conserva el error que hizo que la transferencia quedara retenida. Cualquier otra transferencia responde 409, y una retenida también responde así después del plazo de envío de BACEN.
Marcar como urgente, cuando TRANSFER_INBOUND_ENABLED es true, una transferencia entrante en AvailableForDownload cuyo producto de origen tiene la urgencia habilitada en todas las configuraciones habilitadas. De lo contrario, falla de forma cerrada.