Integración con Lerian Consignado — Dataprev

Integración a través de la API HTTP autenticada, los flujos de comandos y de hechos de Lender, los hechos de negocio de Consignado, y las suscripciones de entrega de eventos.

Usa la API HTTP para la superficie completa de Consignado orientada al cliente. Usa CloudEvents para consumir hechos de negocio inmutables y, al integrar a través de Lender, para enviar los comandos admitidos. Las dos interfaces son complementarias. El flujo de eventos no es la autoridad para toda operación del riel.

API HTTP

La API cubre las credenciales del tenant, el margen y los datos del trabajador, las subastas y las ofertas, los documentos, y el desembolso. Cubre la averbação y su documentación, la importación de contratos, y los códigos de instrumento B3. También cubre las correcciones de contrato, el ciclo de vida del contrato, la portabilidad en ambas direcciones, el refinanciamiento, la renegociación, y las garantías. Las operaciones restantes cubren la conciliación, el saldo devedor, los fondos, los originadores, el throughput, y las suscripciones de entrega. Las operaciones de presubasta definen la ronda de cotizaciones entre originadores, las políticas de los fondos y los mandatos de los originadores, y leen las ventanas y las cotizaciones.

Un fondo o un originador también puede llamar a sus propias rutas, bajo /v1/consignado/fundos/{fundo_id}/ y /v1/consignado/originadores/{originador_id}/, con una credencial de socio de Access Manager. Una credencial de originador que tiene un solo originador también puede llamar estas rutas sin el id, bajo /v1/consignado/originador/. GET /v1/consignado/originador devuelve el originador en cuyo nombre actúa la credencial. Una llamada con una credencial que tiene más de un originador responde 403 AUT-1022: usa las rutas con el id. Las rutas sin el id requieren Access Manager 3.14.0 o posterior. En una versión anterior, responden 503. Usan los mismos permisos de socio que las rutas con el id. GET /v1/consignado/originador también exige el permiso get de originador-binding. Consulta Configurar un tenant.

Empieza con obtener el margen del trabajador, y luego usa la navegación de la Referencia de la API para encontrar las demás familias de operaciones.

Comandos de Lender consumidos

El gateway lee un único flujo de comandos de aplicación y despacha según el source y la clave de evento de CloudEvent. La selección se hace por clave, nunca por nombre de tema. El gateway pone en cuarentena una clave que no maneja en su propia dead-letter queue, en lugar de omitirla.

Clave de evento

Comportamiento en runtime

consignado_exclusao.requested

Usa el mismo servicio de exclusión idempotente que la operación HTTP cuando el runtime está disponible; de lo contrario, devuelve un error de indisponibilidad con nombre. Un comando que encuentra una llamada de documentación a Dataprev en curso se reentrega hasta que la llamada termina, y entonces excluye. En estos casos, nada llega a Dataprev y el gateway publica consignado.exclusao.rejected con evidence_source gateway_refusal: la renegociación del contrato aún no tiene respuesta de Dataprev (renegotiation_underway), el contrato ya está fuera del registro (contract_left_registry.situacao_N, con origem_M cuando Dataprev informa una) o la credencial de Dataprev del tenant falta o fue revocada (dataprev_credential_unavailable).

La averbação, su documentación y la lectura de margen del trabajador no son comandos de Lender. Envíalas a través de las operaciones HTTP autenticadas.

Hechos de Lender consumidos

El mismo consumidor también lee el tema de hechos de Lender. Actúa sobre cuatro claves de hecho y omite todos los demás hechos de Lender.

Clave de evento	Comportamiento en runtime
assignment_fund.registered, assignment_fund.updated	Registra el fondo de Lender para el tenant. En un tenant cuyo registro de fondos pertenece a Lender, una averbação puede entonces nombrar ese fondo en fundo_ref por su id de Lender, el texto UUID en minúsculas de assignment_fund_id. Antes de que llegue ese hecho, una averbação que nombra el fondo responde FUNDO_NOT_REGISTERED. En otro tenant, responde el registro de fondos del propio gateway y esos hechos no agregan ningún fondo.
assignment_receivable.accepted	Registra la cesión del contrato nombrado al fondo nombrado y publica consignado.cessao.registered. El gateway cede un contrato que confirmó por averbação o que importó con sus datos de contabilización. También cede el nuevo contrato de un refinanciamiento o de una renegociación que registró como aceptado. El hecho debe nombrar el fondo en assignment_fund_id: el gateway no encuentra un fondo por su CNPJ. No registra nada para un contrato ya cedido a otro fondo. Tampoco registra nada para un contrato que salió del registro. Eso incluye uno que sacó una exclusión confirmada o una exclusión de portabilidad aceptada. Incluye también uno que un refinanciamiento o una renegociación reemplazó sin reversión y uno que una lectura de Dataprev vio excluido, terminado o renegociado.
loan_product_version.created	Registra el rango de tasa anual de la versión de producto de Lender y si la versión admite persona física. Una solicitud con el bloque de contabilización responde LOAN_PRODUCT_VERSION_UNKNOWN, VERSION_ADMITS_NO_PESSOA_FISICA o RATE_OUTSIDE_PRODUCT_RANGE, en ese orden; el último aplica cuando la tasa anual efectiva de monthly_rate, (1 + monthly_rate/100)^12 − 1, queda fuera del rango. El rango incluye sus límites. Esto vale para la averbação, la importación de contrato con sus datos de contabilización, el refinanciamiento y la averbação por portabilidad. El primer código aplica una vez que el tenant recibió alguna versión. Una versión creada antes de vincular el gateway al tenant nunca llega: crea una nueva versión en Lender.

Hechos de negocio declarados y operacionales

STREAMING_EVENT_POLICIES puede desactivar un hecho de Consignado, excepto consignado.registry.status_changed: una política que lo deshabilita detiene el arranque. Cuando una política desactiva un hecho, la escritura de negocio igual hace commit, y el gateway no publica ese hecho después.

El descubrimiento de portabilidad entrante está desactivado por defecto. El hecho consignado.portability_proposal.received aparece solo donde ese flujo está habilitado. Hace commit de forma atómica junto con su marcador duradero cuando el poller programado de descubrimiento de portabilidad encuentra una oferta activa. Lo mismo aplica para cualquier comando del riel que un despliegue no ejecute. Los hechos operacionales cubren:

• solicitudes de subasta y propuestas de portabilidad entrante
• margen, empleo, e informes de ausencia
• aceptación de propuesta, registro de contrato (consignado.contract.registered, incluida la evidencia del artefacto CCB firmado), desembolso, y disponibilidad de corrección
• aceptación de la averbação, además de resultados de averbação, exclusión, portabilidad del lado de origen, y renegociación
• resultados de refinanciamiento, un refinanciamiento hecho fuera del gateway que el portal revirtió (consignado.refinanciamento_externo.revertido), migración de contrato a un nuevo vínculo de empleo y una terminación de vínculo cancelada (consignado.rescisao.revertida)
• conciliación, excepciones de repasse, y calendarios
• cesiones, códigos de instrumento B3, y cambios de throughput
• pausa y reanudación del riel para un tenant durante el cambio de competencia de Dataprev, en Lerian Cloud
• el aviso antes de que venza el certificado de Dataprev en custodia. Solo lo recibe una suscripción de todo el tenant
• la ventana de ejecución de la garantía de FGTS de un trabajador despedido. Solo la recibe una suscripción de todo el tenant
• un bloqueo de FGTS que falló (consignado.garantia.block_failed). Una suscripción de todo el tenant lo recibe, y una suscripción limitada a un fondo lo recibe cuando fundo_ref nombra a ese fondo
• la desactivación o la reactivación de un originador o de un fondo (consignado.registry.status_changed). Solo lo recibe una suscripción de todo el tenant
• el resultado de cada cotización de la presubasta (consignado.cotacao.resolved). Una suscripción de todo el tenant lo recibe, y una suscripción limitada a un originador lo recibe cuando originador_ref nombra a ese originador

Consulta Eventos de Consignado para ver el catálogo completo y el mapeo exacto de resource/event de CloudEvent.

Flujos de aplicación

Cada aplicación publica hechos en un tema, y Lender envía comandos en un tema propio:

• los hechos van a lerian.streaming.consignado-gw
• el gateway lee los comandos de Lender desde lerian.streaming.lender.commands
• el gateway lee los hechos de Lender desde lerian.streaming.lender
• los tipos de hecho usan studio.lerian.consignado-gw.<resource>.<event>
• los tipos de comando usan studio.lerian.lender.<resource>.<event>

Enruta por el source, el tipo de resource, y el tipo de event de CloudEvent. No infieras un evento únicamente a partir de un nombre de tema.

Suscripciones de entrega

Usa la API de suscripciones para registrar un destino de entrega, leer el estado de su entrega (last_probe_at, last_probe_outcome, last_probe_error_class, last_success_at, last_failure_at y next_verification_attempt_at mientras un webhook espera verificación; cada uno está ausente hasta que Streaming Hub tenga algo que informar, y un valor en last_failure_at significa que el endpoint está fallando ahora), rotar su secreto de firma, probar la entrega, pausarla y reanudarla, editar el destino o revocarlo. Solo las respuestas de creación y de rotación llevan el secreto de firma. Ninguna lectura lo devuelve. Las lecturas muestran un destino enmascarado. Solo el rol admin puede leer el destino completo, porque la ruta de un webhook puede llevar un token de callback.

Crear, rotar, editar y revocar requieren el header X-Idempotency. Una creación repetida con la misma clave (X-Idempotency-Replayed: true) devuelve el secreto de firma anterior, no uno nuevo.

Una suscripción recibe el major de schema 1 de cada tipo de evento, a menos que defina schema_major. Su mapa event_majors reemplaza el major para los tipos de evento que nombra.

Una prueba exitosa demuestra la entrega al endpoint configurado. No cambia la semántica de al menos una vez de los eventos de negocio.

Pausar detiene la entrega de inmediato y cancela las entregas que esperan en la cola. Reanudar entrega los eventos publicados después de la reanudación. Cuando Streaming Hub detuvo una suscripción tras fallos repetidos, pausar y reanudar responden 409 con upstream.code subscription_stopped_by_hub. Una suscripción en pausa lee paused true, y su estado lee Paused.

Editar cambia el nombre, el endpoint, los tipos de evento, los majors de evento, schema_major y timeout_ms. schema_major es obligatorio en toda edición, y null lo borra. Un nuevo endpoint solo entra en vigor después de que pasa una sonda de verificación. Cuando la sonda falla, la edición responde 422 con upstream.code destination_probe_failed, nada cambia, y la respuesta trae el error_class de la sonda y, cuando el destino respondió, su status_code. Envía el ETag de una lectura como If-Match en la edición. Una suscripción que cambió después de esa lectura responde 412 CLT-0012. Sin If-Match, gana la última escritura.

Los roles admin y operator pueden pausar, reanudar y editar una suscripción. Estas tres operaciones existen solo en las rutas del propio tenant.

Un fondo o un originador puede gestionar sus propias suscripciones con su credencial de socio de Access Manager. Usa las operaciones de crear, leer, estado, rotar, probar y revocar en las rutas de socio: /v1/consignado/fundos/{fundo_id}/subscriptions, /v1/consignado/originadores/{originador_id}/subscriptions y /v1/consignado/originador/subscriptions. Un socio ve solo las suscripciones que creó por las rutas de su propio registro. Cualquier otra suscripción responde 404. La suscripción de un originador recibe cada solicitud de préstamo abierta (consignado.solicitacao.received). Mientras mantengas desactivado al originador o al fondo, Streaming Hub no entrega nada a las suscripciones de ese socio, y sus rutas de socio responden 403.

Contrato de confiabilidad

• Los hechos de negocio entran en un outbox transaccional antes de la publicación.
• La entrega es al menos una vez.
• Deduplica por (ce-source, ce-id).
• Los valores monetarios viajan como cadenas decimales, nunca como punto flotante binario.
• Los campos del payload usan snake_case, excepto consignado.registro_b3.registered, que usa camelCase. Las marcas de tiempo usan UTC RFC 3339.
• Un identificador de negocio requerido faltante es terminal y va a la DLQ del consumidor en lugar de a Dataprev.