Saltar al contenido principal
Opera Lerian Consignado como un riel aislado por tenant, no como un proxy sin estado. Los comandos, las lecturas en segundo plano, el outbox, y el estado de recuperación participan todos en el contrato.

Superficies de comando y lectura

Usa la API HTTP autenticada para los comandos y consultas del cliente. La API separa los comandos de las lecturas. Cada operación del cliente requiere una acción de autorización y se ejecuta en el tenant de quien llama. Sigue los requisitos de idempotencia de la operación. Los reintentos después de timeouts son normales y deben reutilizar la misma identidad de negocio. Un comando del riel detenido en outcome_unknown (503 OUTCOME_UNKNOWN) es la excepción: ninguna clave lo reenvía, así que lee GET /v1/consignado/rail-commands. Añade numero_contrato para preguntar por un contrato: el número es exacto, de 1 a 20 caracteres. Un número bien formado que el libro no tiene da una página vacía, y un valor más largo responde 422. Una fila de refinanciamiento o de renegociación también trae contratos_substituidos, los contratos que reemplazó. Que una operación esté montada no es prueba de que un despliegue específico tenga conectado su adaptador de Dataprev. Una integración de riel no disponible devuelve 501 Not Implemented para esa solicitud, en lugar de desaparecer de la API. La operación de capacidades informa qué familias de operaciones alcanza tu despliegue. Registrar el código de instrumento de B3 de un contrato confirmado no llama a Dataprev, así que no depende de ningún interruptor del riel. El flujo de comandos de Lender lleva solo el comando de exclusión. No es un reemplazo de la superficie HTTP completa. Consulta Eventos de Consignado.

Workers programados

El gateway ejecuta su trabajo en segundo plano como bucles programados. Comparten ejecución inicial retrasada, escalonamiento estable por réplica, aislamiento de panics, y cierre ordenado. Todos los bucles, excepto la vía rápida de subastas, también hacen pasadas sin solapamiento con jitter positivo. La vía rápida de subastas, Limpieza de payload de ofertas y Testigo de propuesta leen su cadencia a través de Systemplane y surten efecto en el siguiente retraso. Los otros bucles toman su cadencia de la configuración de entorno y necesitan un reinicio para cambiar. Recuperación de averbação y Recuperación de comandos del riel existen porque un comando del riel puede dejar su resultado sin establecer: el proceso murió a mitad de la llamada, o el riel nunca respondió. Convergen ese estado contra el propio registro del riel en lugar de perderlo. Para una anticipación o un cambio de términos, la recuperación lee el contrato en Dataprev: un cambio encontrado cierra el comando como aceptado, y una lectura que aún no muestra cambio una hora después del plazo de la llamada lo cierra como rechazado. La recuperación espacia las relecturas de un comando que no puede cerrar: 1 minuto, luego cada espera se duplica, hasta una vez por hora. La reconducción de ofertas reenvía una oferta cuya respuesta del riel se perdió, con su número de propuesta original. Cada reenvío usa el presupuesto de riel del tenant. La recuperación de averbação, la recuperación de comandos del riel y la reconducción de ofertas están desactivadas por defecto. Habilita los dos bucles de recuperación en cualquier despliegue que envíe averbações o comandos del riel. Cuando Dataprev rechaza la documentación, la solicitud responde 422 con los códigos de Dataprev en upstream, y el contrato vuelve a attachment_pending. Envía la documentación corregida bajo una clave X-Idempotency nueva, o excluye el contrato. Cuando la llamada termina sin veredicto, como un timeout, un 5xx de Dataprev o un recibo inutilizable, la solicitud responde 503 o 504. El contrato también vuelve a attachment_pending: envía de nuevo la misma documentación, bajo la misma clave o una nueva. La lectura de la averbação muestra en last_documentation_close el intento más reciente que Dataprev no aceptó. Un anexo de CCB interrumpido a mitad de la llamada permanece en attachment_invoking hasta su attachment_invocation_deadline_at. Después de ese instante, la siguiente documentación o exclusión del contrato toma la llamada. Una exclusión responde 409 EXCLUSION_DOCUMENTATION_UNDERWAY solo mientras una llamada de documentación está en curso (attachment_invoking antes de su attachment_invocation_deadline_at), para una averbação o un contrato renegociado. Envía la exclusión de nuevo cuando GET /v1/consignado/averbacao-operations liste el contrato como confirmed o attachment_pending, o cuando haya pasado el plazo. La exclusión descarta la documentación que el gateway nunca envió (last_documentation_close con el código excluded). Una vez al mes, Dataprev cierra por el cambio de competencia y rechaza las solicitudes. Cinco bucles se pausan cuando uno de ellos encuentra ese rechazo. Son el descubrimiento de subastas, la vía rápida de subastas, el descubrimiento de portabilidad, la reconducción de ofertas y la elección de la presubasta. La pausa dura 5 minutos, después 15, después 30 por cada rechazo posterior. La recuperación de averbação, la recuperación de comandos del riel, la conciliación y el poller de informes de empleo no esperan esa pausa. Cada una de sus pasadas deja de llamar a Dataprev ante el rechazo y vuelve a intentarlo en la siguiente pasada. Las solicitudes del cliente siguen llegando a Dataprev y reciben su rechazo. El informe de jobs programados muestra paused_until para un bucle pausado. En Lerian Cloud, el gateway publica consignado.rail.paused una vez por cambio de competencia y consignado.rail.resumed cuando una pasada que empezó después de que se abrió la pausa recibe respuesta sin el rechazo. El hecho puede llegar un intervalo de sondeo después de que Dataprev reabre.

Ventanas del riel

Los valores por defecto y las restricciones del riel incluyen:
  • una ventana de validez de subasta de préstamo de 24 horas que Dataprev proporciona y que el gateway no configura
  • una ventana retrospectiva de solicitud de portabilidad de 72 horas
  • 20 días corridos desde la exclusión de origen para registrar una portabilidad entrante, cuando la solicitud indica la fecha de la exclusión
  • 7 días hábiles para revertir un refinanciamiento
  • 7 días después de una averbação, o de una renegociación aceptada a través del gateway, para enviar su documentación por el anexo de CCB. Encuentra los contratos que siguen esperando con GET /v1/consignado/averbacao-operations?status=attachment_pending, y lee documentation_due_at y documentation_overdue en cada uno. Una averbação cuya exclusión pediste también sigue en attachment_pending. Su documentación recibe 409 AVERBACAO_EXCLUDED, salvo que Dataprev haya rechazado la exclusión. Antes de enviarla, consulta GET /v1/consignado/contracts/{numero_contrato}/exclusion con la credencial propia del tenant. Una credencial de fondo o de originador no puede consultarlo.
  • una ventana de descubrimiento de subastas de 48 horas, con una tolerancia de desfase de reloj de cinco minutos
Trata estos valores como restricciones del riel, no como timeouts internos. Configura solo los ajustes que expone el gateway cuando el contrato de Dataprev para el entorno de destino requiere un valor distinto. El gateway no permite cambiar los valores fijos que proporciona Dataprev, incluida la ventana de validez de la subasta de préstamo.

Throughput y ritmo

El tráfico de Dataprev se controla con un ritmo por tenant. La API de throughput define la tasa del tenant, de 0 a 25 solicitudes por segundo, y ningún ajuste eleva ese tope. Un tenant sin tasa almacenada opera a 3 solicitudes por segundo. Un valor almacenado de 0 pausa el tráfico del riel para ese tenant.

Seguridad de la conciliación

Las lecturas de contabilidad y de repasse son independientes. Una fuente que falla no debe suprimir a la otra. Los repasses esperados pueden emitir tres estados:
  • consignado.repasse.overdue: el movimiento esperado está atrasado
  • consignado.repasse.resolved: el movimiento esperado llegó después de su plazo. Puede llegar sin un overdue antes
  • consignado.repasse.unobserved: el gateway actualmente no puede probar presencia ni ausencia
La conciliación lee todos los empleadores de cada tenant que atiende. Un repasse cierra su expectativa por contrato, competencia y origen (cuota de la nómina o descuento de verbas rescisorias), nunca por empleador. Un registro de repasse cuyo empleador o competencia ninguna expectativa puede aportar queda retenido: el gateway no lo publica. La lista de expectativas de repasse cuenta las expectativas abiertas por empleador y muestra los registros retenidos en su bloque held. Lee primero su estado de actualización: una lista vacía no prueba nada, salvo que el estado sea fresh. Un repasse ausente cuenta como atrasado solo después de que se cierra el día hábil ANBIMA siguiente al día de su plazo. Cuando una pasada lee sin fallos las dos puntas, contabilidad y repasse, también lee, con la consulta de contratos de Dataprev, los contratos vivos que la última nómina cerrada dejó fuera. Esas lecturas gastan el presupuesto de Dataprev del tenant aunque el seguimiento de la documentación esté desactivado. Una lectura que encuentra el contrato excluido, terminado o renegociado fuera del gateway publica consignado.exclusao.confirmed con evidence_source m005_external_exit.

Presubasta

La presubasta viene desactivada por defecto. Actívala con CONSIGNADO_PRELEILAO_ENABLED y la configuración de la presubasta. Cómo funciona Consignado describe el flujo. Solo la credencial del bancarizador puede usar los permisos consignado-preleilao.

Acciones del back office

Tu back office tiene dos acciones en la ruta del dinero. Las dos requieren un rol de Access Manager que tenga el permiso correspondiente. Los roles admin y operator tienen las dos. El cierre indica lo que muestra el portal de Dataprev: outcome accepted o refused, y portal_evidence de 1 a 500 caracteres, sin CPF ni nombre del trabajador. Un cierre exitoso responde 204. Un cierre refused no lee nada en Dataprev. Un cierre accepted de refinanciamiento, renegociación o renegociación de legado lee el nuevo contrato una vez y responde 409 RAIL_COMMAND_CLOSE_CONTRADICTED si la lectura lo contradice. Un cierre accepted de exclusión por portabilidad lee el contrato una vez y responde el mismo código, a menos que la lectura muestre el contrato excluido por portabilidad. Luego envía el informe final de saldo deudor de 0.00 y publica consignado.portabilidade.efetivada. Un cierre refused publica consignado.portabilidade.rejeitada. Un cambio de términos accepted no lee nada: el gateway mueve la obligación del saldo deudor a los términos indicados, sin verificación en Dataprev. Una suspensión, una reactivación o una inclusión o exclusión de legado detenida permanece en outcome_unknown: confirma su efecto en el portal de Dataprev. La liberación recibe {"competencia":"yyyyMM"}, publica el registro bajo ese mes y responde 204. Un mes que no corresponde responde 409, y el registro sigue retenido.

Credenciales y artefactos

Rota el certificado del tenant, el secreto de OAuth, el código de solicitante, y la URL del portal a través de la API de credenciales. Un cambio del código de solicitante llega a todas las réplicas en su siguiente llamada a Dataprev. Las variables de archivo de certificado local son un fallback de desarrollo, no un sustituto de la custodia por tenant en despliegues gestionados. Cuando Dataprev rechaza las credenciales de cliente OAuth del tenant, las operaciones que llegan a Dataprev responden 409 DATAPREV_CREDENTIAL_REJECTED. La averbação y el anexo de CCB responden ese código antes de reservar nada. La exclusión no: responde con la operación detenida en outcome_unknown. Un comando del riel también responde ese código y cierra como rejected. Una ejecución de garantía de FGTS responde y cierra como refused. Una oferta sigue abierta bajo su clave: envíala de nuevo con la misma clave. Corrige las credenciales, y las lecturas vuelven a funcionar. Envía de nuevo una averbação o un anexo de CCB rechazado con la misma clave. Envía de nuevo un comando del riel o una ejecución de garantía de FGTS rechazada con una clave X-Idempotency nueva: la clave anterior repite el rechazo. Para un tenant revocado, las operaciones del riel y las cargas parciales de credenciales responden 409 DATAPREV_CREDENTIAL_REVOKED. Una carga completa de un nuevo certificado y de un secreto de cliente OAuth generado de nuevo en Dataprev termina la revocación. Registrar una URL base de portal del trabajador es opcional, para el tenant y para cada originador. Consulta Descubrir subastas y enviar propuestas para el orden en que el gateway selecciona un portal. Los artefactos CCB y del riel usan el almacén de objetos configurado. Mantén el bucket privado y entrega el contenido solo a través de la operación de artefactos autenticada. Lista los artefactos que retiene un contrato, signed_ccb y biometrics_documents_pack, con el tipo de contenido, el tamaño y el SHA-256 registrados en la retención. La lista no descarga nada. Un contrato que el tenant no tiene, o uno sin nada retenido, responde 200 con una lista vacía. Solo la credencial propia del tenant puede listarlos. La averbação no lleva ningún documento, y un cuerpo de 1 MiB o más recibe 413. El anexo de CCB acepta una CCB firmada y, después de una averbação con el bloque de contabilización, un paquete de biometría. El texto en base64 de cada uno tiene hasta 8 MiB, y un cuerpo completo de 18 MiB o más recibe 413. Una importación de contrato que lleva esos documentos sigue los mismos límites. Una corrección de contrato acepta un recurso corregido cuyo texto en base64 tiene hasta 8 MiB.

Comportamiento ante fallos

El riel falla en modo cerrado ante la identidad de tenant faltante, los identificadores de comando malformados, y los endpoints de Dataprev fuera de la política de despliegue: HTTPS en un despliegue gestionado, HTTP loopback solo en los demás. Un despliegue gestionado también falla en modo cerrado ante credenciales faltantes y adaptadores no admitidos. Los hechos de negocio se escriben a través del outbox y se entregan al menos una vez. Los consumidores deben deduplicar por source e ID de CloudEvent. Una caída del broker no saca al gateway de la rotación: el outbox mantiene los hechos duraderos, y /readyz en el puerto de salud solo reporta la verificación streaming. Alerta sobre esa verificación o sobre el backlog del outbox. Una vez que la base de datos de un tenant ejecuta el esquema de la 4.2.0, no regreses la imagen a la 4.0.0 ni a una anterior. Avanza de versión.