Cómo funciona Lerian Consignado — Dataprev

El flujo de extremo a extremo de Consignado sobre Dataprev: configuración del tenant, margen del trabajador, subastas, registro, gestión, portabilidad, garantías, y conciliación.

Lerian Consignado combina comandos HTTP síncronos con hechos asíncronos y lecturas programadas de Dataprev. La API HTTP admite trabajo y responde consultas. El outbox publica hechos de negocio. Los workers en segundo plano descubren o recuperan el estado que Dataprev expone como flujos en lugar de callbacks.

1. Configurar un tenant

Antes de que un tenant pueda llamar al riel, registra:

• un certificado de cliente ICP-Brasil A1 y su clave privada
• credenciales de cliente OAuth2
• el código de solicitante de Dataprev de tres dígitos del tenant
• opcionalmente, la URL base del portal del trabajador ofrecida como contacto de formalización en las propuestas de oferta

El estado de la credencial devuelve presencia, huella del certificado, y metadatos de vencimiento. Nunca devuelve el certificado, la clave privada, o el secreto de OAuth. En un despliegue gestionado, una operación del riel para un tenant sin el certificado, las credenciales de OAuth o el código de solicitante responde DATAPREV_CREDENTIAL_REQUIRED. Una credencial revocada responde DATAPREV_CREDENTIAL_REVOKED. Solo una carga completa del certificado y del cliente de OAuth juntos termina la revocación. Carga un nuevo certificado y un secreto de cliente OAuth recién generado en Dataprev. El id del cliente OAuth puede seguir siendo el mismo. certPem y keyPem aceptan como máximo 65,536 caracteres cada uno. Cuando Dataprev rechaza las credenciales de cliente de OAuth del tenant, una lectura responde DATAPREV_CREDENTIAL_REJECTED, y una escritura puede quedar detenida. Corrige las credenciales en la custodia y consulta Credenciales y artefactos antes de enviar una escritura de nuevo.

El gateway te avisa antes de que venza el certificado de Dataprev del tenant. Publica consignado.certificate.expiring como máximo dos veces por certificado: 30_days cuando quedan 30 días o menos, y 7_days cuando quedan 7 días o menos. Un certificado vencido, una custodia revocada y una custodia sin certificado no generan aviso. Un certificado renovado avisa de nuevo. Solo las suscripciones propias del tenant lo reciben.

Cuando socios originan préstamos en nombre del tenant, registra cada uno como originador. Un originador desactivado no puede enviar ofertas, y su credencial de socio es rechazada en toda ruta de socio con 403 ORIGINADOR_DEACTIVATED. El gateway conserva su registro. Reactívalo para que vuelva a actuar con la misma referencia.

Cuando el tenant cede créditos a fondos, registra cada fondo. Un fondo que el gateway conoce por los hechos de fondo de Lender no necesita registro aquí. Hasta que el gateway conozca el fondo, una averbação que lo nombra responde FUNDO_NOT_REGISTERED. Un fondo desactivado no acepta nuevo crédito, y su credencial de socio es rechazada en toda ruta de socio con 403 FUNDO_PARTNER_DEACTIVATED, hasta que lo reactives. Cada desactivación o reactivación de un originador o de un fondo publica consignado.registry.status_changed.

Una averbação nombra un fondo de Lender por su id de Lender, igual que una cesión de Lender. El CNPJ del fondo solo importa para un hecho de cesión de Lender sin id de fondo. El gateway entonces cede el contrato al fondo registrado con ese CNPJ.

Un fondo o un originador también puede llamar al gateway con una credencial de socio de Access Manager limitada a su id de registro. Usa las rutas bajo /v1/consignado/fundos/{fundo_id}/ o /v1/consignado/originadores/{originador_id}/, con ese id de registro en la ruta. Un id de ruta que no está en el registro de fondos o de originadores del tenant responde 403.

La credencial de socio de un originador también puede llamar a las rutas bajo /v1/consignado/originador/, que no nombran ningún id de registro. GET /v1/consignado/originador devuelve el originador en cuyo nombre actúa la credencial. Cuando el alcance de la credencial tiene más de un originador, esas rutas responden 403 AUT-1022. El socio entonces usa las rutas /v1/consignado/originadores/{originador_id}/ o limita su alcance en Access Manager. Estas rutas requieren Access Manager 3.14.0 o posterior. En una versión anterior, responden 503.

2. Leer los datos y el margen del trabajador

El endpoint de margen autentica al tenant, obtiene el contexto de autorización del trabajador en Dataprev, y devuelve la respuesta del riel sin convertirla en una decisión de suscripción. Cuando Dataprev los devuelve, la respuesta también incluye los registros del trabajador, del vínculo de empleo y del empleador. La API también expone nuevos vínculos de empleo, informes de terminación, registros de FGTS autorizados, y lecturas de saldo de FGTS.

La respuesta de margen también puede traer alerts. Cada entrada es un evento eSocial que Dataprev recolectó para el vínculo de empleo: typeCode 1 es una ausencia, y typeCode 2 es una terminación, incluido el preaviso. No trates ese conjunto de tipos como cerrado. Cada entrada trae sus fechas de referencia y el código de motivo eSocial tal como lo envió Dataprev, así que completa con un cero a la izquierda, hasta dos dígitos, un código que empieza con 0. eventId está presente cuando Dataprev lo envía. Dataprev recolecta las alertas a diario, por lo que no son en tiempo real. Un originador ve las alertas solo en esta lectura. El tenant también recibe cada una como consignado.afastamento.reported.

El término de autorización modelo de Dataprev no lista los datos de registro de la respuesta de margen: el nombre de la madre del trabajador, la nacionalidad, el CBO, el nombre del empleador, el inicio de actividad del empleador y el CNAE. Tu propio instrumento de consentimiento debe cubrir esos campos. El gateway no lo impone.

El gateway guarda la categoría eSocial y la fecha de admisión de la lectura de margen más reciente de cada vínculo de empleo. Las borra 30 días después de la última lectura. Cuando el dados_cadastrais de la averbação no declara esos campos, consignado.contract.registered los toma de esa lectura de margen.

3. Descubrir subastas y enviar propuestas

Un bucle programado de descubrimiento lista las solicitudes de préstamo abiertas y publica cada solicitud nueva. Una vía rápida opcional repite ese listado, por defecto, cada 10 segundos. En un despliegue multi-tenant, una sola lectura atiende a cada tenant cuyas credenciales de Dataprev Dataprev acepta. Un tenant en pausa a tasa 0 sigue recibiendo las solicitudes. Un cliente puede entonces enviar una oferta a través de la API HTTP autenticada. El gateway conserva el payload duradero de la oferta necesario para demostrar lo que el cliente envió y luego publica el testigo de la propuesta aceptada.

Una oferta puede nombrar un originador. El gateway rechaza una oferta para un originador desconocido o desactivado. Un originador que se autentica con su propia credencial envía ofertas bajo su propia referencia.

Cuando la llamada a Dataprev falla antes de que Dataprev la reciba, la oferta queda sin resultado y responde 503 DATAPREV_UNAVAILABLE. Solo un código que Dataprev publicó rechaza un primer intento. Reenvía bajo la misma clave X-Idempotency: responde 409 mientras corre el primer intento y luego envía las mismas propuestas. Después de que vence el plazo del intento anterior, los reenvíos de una oferta con resultado desconocido bajo la misma clave esperan intervalos progresivos: 30 segundos, que se duplican hasta 30 minutos; durante esa espera, responden 503 OUTCOME_UNKNOWN sin una nueva llamada a Dataprev. Cuando el resultado de una oferta nunca se resuelve, la aceptación por parte de Dataprev de una averbação para uno de sus números de propuesta la resuelve como accepted. Un reenvío bajo la misma clave entonces repite 200 con una lista propostas vacía. Mientras el resultado sea desconocido, nunca reenvíes la oferta bajo una clave nueva. Corrige un rechazo local bajo una clave nueva. En el libro de ofertas, fundo_ref es el fondo al que se cedió el crédito, y queda nulo hasta que se registra una cesión.

Toda propuesta debe llegar al trabajador a través de al menos un contacto. El gateway agrega un portal de formalización como contacto cuando encuentra uno: primero en la oferta, después en el originador nombrado, después en el tenant. Cuando ninguno de los tres tiene portal, cada propuesta debe llevar un contacto del cliente. De lo contrario, el gateway rechaza la oferta antes de llamar a Dataprev.

Las subastas de portabilidad usan una operación de respuesta separada y una ventana acotada de solicitud a Dataprev.

Presubasta entre originadores

La presubasta es una ronda de cotizaciones antes de la oferta. Varios originadores, y tu propia cuenta, cotizan la misma solicitud de préstamo, cada uno por un fondo. El gateway elige una cotización y la envía a Dataprev. Nada llega a Dataprev antes de la elección. La presubasta viene desactivada por defecto.

Para activarla, ejecuta el gateway con CONSIGNADO_PRELEILAO_ENABLED=true, como dice la página de variables de entorno. Después, define la configuración con ativo igual a true. Un gateway que corre sin el worker responde a esa llamada con PRELEILAO_WORKER_UNAVAILABLE.

La configuración contiene:

• janelaSegundos: la ventana de cotización, de 60 a 14.400 segundos
• criterio: cet_anual para el menor CET anual, parcela para la menor cuota, prazo para más cuotas
• fundoPreferidoRef: un fondo preferido opcional
• fechamento: prazo cierra la ventana en su plazo final, y todos_responderam también la cierra cuando todos los pares esperados respondieron
• rodizio: una rotación opcional entre fondos, donde faixaCetMensalBps limita las cotizaciones que compiten, en centésimas de punto porcentual de CET mensual por encima de la menor cotización. Sin valor, todas las cotizaciones compiten.

Una configuración rige para las solicitudes de préstamo que el gateway descubre después de que la guardas. Una ventana que ya está abierta conserva la configuración con la que abrió. El plazo de cotización de una solicitud es el fin de la ventana, o 120 segundos antes de que la solicitud venza, lo que ocurra primero. Una solicitud con 120 segundos o menos de vigencia restante no abre ventana, y las ofertas sobre ella van directo a Dataprev. consignado.solicitacao.received lleva el plazo en prazo_cotacao.

Define una política para cada fondo:

• participa y peso: si el fondo participa, y su peso en la rotación
• horario: el horario en que el fondo recibe cotizaciones, en hora de São Paulo
• limites: quantidadeDiaria, valorDiario y capital
• restricoes: el monto liberado, el número de cuotas, el monto de la cuota, la tasa mensual, y si el fondo acepta garantía del FGTS

Un fondo sin política participa con peso 1, todo el día, sin límite y sin restricción. Un límite no rechaza una cotización al ingreso. La elección lo aplica. La lectura de la política agrega el uso del fondo: las cotizaciones y el monto elegidos en el día de São Paulo, el monto reservado y confirmado, y el capital restante.

Define el mandato de cada originador: los fondos por los que puede cotizar, de 0 a 50. Una cotización por un fondo fuera del mandato responde BID_FUND_OUTSIDE_MANDATE. Tu propia cuenta no tiene mandato.

Cotiza por la ruta de oferta, con fundoRef. Para una solicitud con ventana abierta, fundoRef es obligatorio, y la ruta responde 202 con situacao recebida. No llama a Dataprev. Para una solicitud sin ventana de presubasta, fundoRef responde BID_FUND_NOT_ACCEPTED. Las propuestas deben incluir una sin garantía. El gateway da a cada propuesta su número al recibir la cotización, y Dataprev recibe ese número si la cotización gana.

Un originador puede enviar una nueva cotización por el mismo fondo bajo una nueva clave X-Idempotency. La nueva cotización reemplaza los términos, hasta 10 revisiones por cada originador y fondo. La misma clave repite la primera respuesta. Después de que la ventana cierra, una clave nueva responde BID_QUOTE_WINDOW_CLOSED.

La ventana cierra en su plazo final. Cierra antes cuando llega una cotización del fondo preferido y el fondo aún tiene capacidad para ella y, con todos_responderam, cuando todos los pares esperados respondieron. Un par esperado es un originador activo con un fondo en su mandato, donde el fondo participa y está dentro de su horario cuando el gateway descubre la solicitud. Tu propia cuenta no es un par. Un par responde con una cotización o con un rechazo. Un par que rechazó aún puede cotizar mientras la ventana está abierta. Un par que nunca responde retiene el cierre hasta el plazo final. Un rechazo no publica un hecho.

Cuando la ventana cierra, el gateway elige una cotización:

1. Descarta las cotizaciones de un fondo que dejó de participar y de un fondo sin capacidad restante para la cotización: la cantidad diaria, el monto diario o el capital.
2. Las cotizaciones del fondo preferido van primero. El criterio ordena las demás, y un empate va a la menor CET anual y, después, a la cotización más antigua.
3. Con una rotación, y sin cotización del fondo preferido, el fondo más por debajo de la parte de su peso en el monto elegido hoy pasa primero entre los fondos que tienen una cotización dentro de la banda.

El gateway reserva la capacidad del fondo para la cotización elegida y envía sus propuestas a Dataprev con los números que les dio. La reserva es el mayor monto liberado de la cotización. Cuando Dataprev rechaza todas las propuestas de la cotización elegida con un código que concierne a los términos de la cotización, el gateway libera la reserva, reserva la capacidad para la siguiente cotización y la envía. Cuando la respuesta no es clara, el gateway envía la misma cotización de nuevo y no pasa a la siguiente.

El gateway libera una reserva cuando Dataprev rechaza la cotización y cuando las propuestas vencen sin averbação. Cuando la averbação de la cotización se confirma y lleva el bloque de contabilización, el gateway confirma la reserva con el liberated_amount de la averbação. Cada cotización termina con un hecho consignado.cotacao.resolved: accepted, refused, not_elected o no_answer.

Puedes listar las ventanas y leer una con sus cotizaciones en orden de clasificación, el motivo por el que una cotización no fue elegida y el cálculo de la rotación. También puedes listar las cotizaciones. Un originador lista solo sus propias cotizaciones en su ruta de socio, y una llamada que nombra a otro originador responde 403. El gateway borra una ventana cerrada y sus cotizaciones 30 días después de que la ventana cierra y sus propuestas terminan. Conserva una ventana mientras una de sus cotizaciones tiene una reserva.

Una averbação que cita el número de una cotización debe nombrar en fundo_ref el fondo de esa cotización. De lo contrario, responde FUNDO_DIFFERS_FROM_QUOTE, y nada llega a Dataprev. Una averbação que nombra un fondo con política escrita debe respetar sus restricciones, con o sin el bloque de contabilización. De lo contrario, responde FUNDO_POLICY_VIOLATION. Cuando la averbação cita una cotización viva, el gateway comprueba las restricciones que la cotización registró, y no la política de hoy.

4. Registrar y financiar el contrato

El flujo de registro:

1. envía la averbação a Dataprev
2. envía la documentación del contrato a Dataprev
3. expone el estado de registro y los documentos del riel
4. registra la confirmación de desembolso del cliente
5. publica hechos inmutables de contabilización y pago a través del outbox

La averbação ejecuta solo el Manual 003 de Dataprev y no lleva ningún documento ni instante de firma. Requiere nome_trabalhador, el nombre completo del trabajador. Tú creas el número del contrato: de 2 a 15 letras o dígitos, sin espacios, acentos ni símbolos. La misma regla se aplica al nuevo contrato de un refinanciamiento, una renegociación o una portabilidad entrante. La averbação responde 422 MATRICULA_DIFFERS_FROM_PROPOSAL antes de llamar a Dataprev cuando numero_proposta nombra una propuesta que registró una matricula y la averbação lleva otra. Responde 422 antes de llamar a Dataprev cuando tem_garantias y los valores de garantía del FGTS no concuerdan: true sin ningún valor, o false con un valor.

Con el bloque de contabilización, el gateway verifica la contabilización antes de llamar a Dataprev y responde 422 cuando Lender no puede contabilizarla, y liberated_amount debe ser igual a principal_amount menos iof_amount y origination_fee_amount. Cuando el tenant tiene versiones de Lender, el gateway también rechaza una loan_product_version que no recibió de Lender y una versión que no admite persona física. El detalle del problema nombra la regla, y la lista de errores da cada código. Cuando Dataprev acepta la averbação, la operación responde attachment_pending y el gateway publica consignado.averbacao.accepted. Dataprev entonces tiene el mandato de descuento en nómina, y el contrato espera su documentación.

Envía la documentación en una segunda solicitud, bajo su propia clave X-Idempotency. Ejecuta solo el Manual 004. Lleva la CCB firmada, la evidencia de firma y data_hora_assinatura, el instante en que el trabajador firmó la CCB. El trabajador puede firmar días después de la averbação.

Cuando la averbação llevó el bloque de contabilización, la documentación también lleva el paquete de evidencias y signature_evidence_ref. Sin el bloque, ambos se rechazan. Con el bloque, un instante de firma posterior a formalization_deadline responde FORMALIZATION_DEADLINE_EXCEEDED. Un instante más de 5 minutos por delante del reloj del gateway responde DECLARED_DATES_OUT_OF_ORDER.

La documentación también completa el nuevo contrato de una renegociación que Dataprev aceptó a través de este gateway. Envía solo la CCB firmada del contrato reemplazado. La respuesta es confirmed, y el gateway no publica ningún hecho. Ese contrato recibe la misma ventana de 7 días que una averbação, contada desde el instante en que Dataprev aceptó la renegociación. Aparece en GET /v1/consignado/averbacao-operations con los mismos campos, con booking_profile rail_only. Su lectura de averbação responde 404.

Sin una averbação aceptada o una renegociación de ese tipo, la documentación responde AVERBACAO_NOT_ACCEPTED y nada llega a Dataprev. El rechazo es definitivo solo cuando la averbação lee rejected, porque la recuperación de averbações (DATAPREV_AVERBACAO_RECOVERY_ENABLED, desactivada por defecto) todavía puede aceptar una averbação que lee averbacao_unknown. Sin ella, contacta a Lerian con el número del contrato.

Cuando Dataprev rechaza una averbação, el número del contrato queda libre de nuevo. Envía la averbação corregida bajo un nuevo contract_id y una nueva clave X-Idempotency. El contract_id rechazado sigue consumido y responde AVERBACAO_CLAIM_CONFLICT. Una averbação en curso, aceptada o averbacao_unknown todavía retiene el número.

Un contrato admite una única documentación aceptada. La misma documentación bajo una clave nueva repite la primera respuesta. Una documentación distinta responde AVERBACAO_DOCUMENTATION_CONFLICT mientras la primera está aceptada o en camino a Dataprev. También responde ese código para un contrato leído de vuelta en el registro cuya propuesta de subasta ya está resuelta. Cuando Dataprev acepta la documentación, la operación responde confirmed y el gateway publica consignado.averbacao.confirmed. La confirmación entrega a Lender, para contabilización y desembolso, el contrato enviado con el bloque de contabilización.

Cuando Dataprev rechaza la documentación, la solicitud responde 422 con los códigos de Dataprev en upstream, y el contrato vuelve a esperar su documentación. Envía la documentación corregida bajo una clave nueva, o excluye el contrato. Cuando la llamada termina sin veredicto, la solicitud responde 503 o 504, y el contrato también vuelve a esperar. Envía de nuevo la misma documentación.

El Manual 004 le da a la institución financiera 7 días después de la averbação para enviar la documentación. El gateway no impone ese plazo. La lectura de la averbação muestra documentation_due_at, 7 días calendario después de la averbação, y documentation_overdue mientras la documentación está atrasada. Dos bucles opcionales te ayudan a vigilarlo, y ambos vienen desactivados por defecto. La señal de plazo publica consignado.averbacao.documentation_deadline. El seguimiento de la documentación lee en Dataprev cada contrato que espera, una vez al día, y muestra lo que encuentra en dataprev_follow_up. También lee, una vez por semana, un contrato que la terminación de vínculo cerró mientras la deuda sigue en pie. Una lectura que encuentra el contrato de vuelta en el registro, activo de nuevo, levanta la terminación, y la documentación vuelve a aceptarse. El gateway publica consignado.rescisao.revertida cuando el contrato vuelve bajo el mismo vínculo de empleo, y consignado.migracao.efetivada cuando vuelve bajo otro.

Un prestamista downstream o un ledger decide qué significan esos hechos para sus propios libros. El gateway no contabiliza directamente en el ledger.

Después de la confirmación, informa el código de instrumento B3 que B3 devolvió al aceptar el registro de la CCB. Solo la credencial propia del tenant puede informarlo o leerlo, no una credencial de fondo o de originador. El gateway guarda el código una sola vez y publica consignado.registro_b3.registered. Reenviar el mismo código y la misma fecha responde el registro original. Un código o una fecha distintos responden REGISTRO_B3_JA_INFORMADO, y la API no ofrece corrección. El gateway no se comunica con B3 y no verifica el código contra la CCB.

Importa un contrato que ya está registrado en el riel fuera de este gateway. La importación lee el contrato en Dataprev y no mueve dinero. Solo se puede importar un contrato activo o suspendido. Una contabilización se acepta solo para un contrato que Dataprev lee como averbação de banco (origemAverbacao 0), tombamento obligatorio (7), migración automática (8) o sin origemAverbacao. Para cualquier otro origen, la importación con contabilización responde 422 y no escribe nada. Importa ese contrato sin la contabilización. Sin los datos de contabilización, un contrato que ya tiene una obligación de saldo devedor aquí responde CONTRACT_ALREADY_REGISTERED.

Una importación también puede llevar los datos de contabilización, en dos objetos enviados juntos. El objeto booking es el cuerpo de la averbação con su bloque de contabilización completo y un numero_proposta vacío. También lleva la documentación: la CCB firmada, el paquete de evidencias, signature_evidence_ref, y la evidencia de firma.

El objeto registration lleva lo que Dataprev devolvió en la averbação original. Incluye averbado_at, el response_code de la averbação y el hash_operacao del Manual 004 de la documentación. Su averbado_at debe quedar a menos de un minuto del instante de inclusión en la lectura de Dataprev. Enviar solo uno de los dos se rechaza.

El gateway verifica la contabilización y el averbado_at contra la lectura de Dataprev, guarda los documentos bajo su custodia, y publica consignado.contract.registered. Lender luego contabiliza el contrato como contabiliza uno registrado por averbação aquí. La importación no envía averbação ni CCB a Dataprev.

Con los datos de contabilización, una obligación que el contrato ya tiene no es un conflicto. El gateway la deja intacta, y saldo_devedor_dispatch_scheduled responde false. En este modo, CONTRACT_ALREADY_REGISTERED significa que el contrato fue registrado por este gateway, o que se importó antes con otros datos de contabilización. La importación corre las mismas verificaciones de versión de producto de Lender que la averbação.

Registra una corrección contra el contrato registrado cuando algo que el cliente ya afirmó resulta estar equivocado. Ejemplos son el archivo CCB incorrecto y una confirmación de desembolso con la evidencia incorrecta. Una primera corrección de CCB para un número de contrato que el tenant nunca registró ni importó responde 404, y el gateway no retiene nada. Una corrección no cruza ningún límite gubernamental: los propios campos de rectificación del riel están retirados, por lo que el cliente sigue siendo la única autoridad. El gateway toma custodia de los bytes corregidos, publica el hecho que los nombra, y los sirve de vuelta bajo autenticación. Las correcciones se encadenan: cada una reemplaza al evento anterior. Solo la credencial propia del tenant registra una corrección. Un fondo lee las correcciones de un contrato que se le cedió y de un nuevo contrato que hereda ese fondo.

5. Dar servicio al contrato

La API cubre el ciclo de vida del riel después del registro: suspensión, reactivación, cambios de términos, anticipación y reversión de cuotas, y exclusión. También cubre refinanciamiento y reversión, renegociación, registro de portabilidad, y operaciones de contratos heredados. El resultado de una renegociación publica consignado.renegociacao.efetivada o consignado.renegociacao.recusada.

La portabilidad funciona en ambas direcciones. Como institución proponente, registra la portabilidad entrante. Como institución de origen, excluye el contrato del que se alejó el trabajador. El gateway acepta eso solo para un contrato que mantiene para ti: registrado a través de él, o importado. Rechaza cualquier otra cosa antes de llamar al riel.

La averbação de portabilidad entrante requiere que la exclusión en el origen corra primero. Dataprev la rechaza con la regla PT cuando la exclusión no corrió, y con la regla PW cuando la portabilidad ya está cerrada. Cualquiera de los dos rechazos libera el número del contrato. El gateway verifica la ventana de 20 días calendario solo cuando envías dataExclusaoOrigem. Sin él, Dataprev evalúa el orden y la ventana.

El gateway reclama el número del contrato antes de llamar a Dataprev. Un número que el tenant ya tiene responde 409 CONTRACT_ALREADY_REGISTERED. Un reenvío bajo una clave nueva nunca envía dos veces. Mientras la primera llamada todavía puede estar corriendo, un reenvío responde 409 CLT-0007. Después de eso, responde 503 OUTCOME_UNKNOWN hasta que el gateway lea el contrato en Dataprev. Con la recuperación de averbações activada, esa lectura registra una aceptación o libera el número. En esta ruta, reenviar bajo cualquier clave durante esa espera es seguro.

Cuando Dataprev acepta la compra, el contrato espera su documentación: su lectura de averbação muestra attachment_pending, y su obligación de saldo devedor empieza. El gateway no publica consignado.averbacao.accepted para una compra. Envía la documentación como para una averbação.

La averbação de portabilidad acepta un objeto booking opcional. El gateway nunca lo envía a Dataprev. Envía todos sus miembros u omite el objeto: iof_amount, expected_disbursement_date, loan_product_version, formalization_deadline, margin_snapshot y origins[]. Esta contabilización requiere Lender 4.0.0 o posterior; actualiza Lender antes del gateway 4.2.0. Cada entrada de origins[] nombra un contrato de origen que la compra liquida:

• origin_institution, el código COMPE de 3 dígitos del banco de origen, con ceros a la izquierda
• external_operation_ref, de 2 a 15 letras o dígitos
• transferred_principal, la parte positiva de valorPago que liquida ese contrato

Las entradas deben sumar valorPago y nombrar cada contrato una sola vez. El monto liberado contabilizado es valorEmprestimo menos iof_amount. El gateway responde 422 con los códigos de contabilización antes de llamar a Dataprev cuando iof_amount no es menor que valorEmprestimo, cuando valorPago es cero o mayor que el monto liberado, cuando los orígenes no suman o cuando Lender rechazaría la contabilización.

Después de que Dataprev acepta la documentación, el gateway publica consignado.contract.registered con portability_in. Espera hasta que el registro de estado de portabilidad de Dataprev muestre exactamente los contratos de origen contabilizados como excluidos, como máximo 20 días calendario desde la documentación confirmada. Un contrato excluido que la contabilización no nombra, o el fin de los 20 días, deja el contrato detenido para la operación de Lerian, sin hecho. Sin booking, el contrato queda solo en el riel y Lender no recibe ningún hecho.

Revertir un refinanciamiento funciona de la misma manera. Solo puedes revertir un refinanciamiento a través de este gateway si el gateway lo registró. La ventana de 7 días hábiles se evalúa contra el propio registro del gateway de cuándo ese refinanciamiento hizo commit. La reversión acepta un numeroContratoOriginal opcional. Cuando el refinanciamiento no reemplazó ese contrato, la reversión responde 422 REVERSAO_ORIGINAL_NOT_REPLACED antes de llamar a Dataprev, y el gateway no registra nada. El campo nunca llega a Dataprev.

La solicitud de refinanciamiento acepta un objeto booking opcional que Lender usa para contabilizar el nuevo contrato. El gateway nunca lo envía a Dataprev. Envía expected_disbursement_date, loan_product_version, formalization_deadline y margin_snapshot, con un origination_fee_amount opcional, u omite el objeto. Con él, competenciaInicioDesconto es obligatoria. valorEmprestimo menos valorIOF y la tarifa debe ser igual a valorPago más valorTroco, o la solicitud responde 422 DECLARED_TERMS_INCONSISTENT. Los códigos de contabilización se aplican, excepto FORMALIZATION_DEADLINE_EXCEEDED, porque el refinanciamiento no tiene etapa de documentación. Sin el bloque, el nuevo contrato existe solo en el riel y Lender no contabiliza nada.

El gateway publica el resultado de un refinanciamiento que envió. consignado.refinanciamento.efetivado nombra los contratos liquidados y los nuevos términos, y trae novo_contrato cuando enviaste la contabilización. consignado.refinanciamento.revertido informa una reversión que excluyó el nuevo contrato, incluida una hecha en el portal de Dataprev que la lectura de seguimiento de 14 días ve. consignado.refinanciamento.recusado informa un rechazo y nombra los contratos que siguen activos. Un refinanciamiento hecho fuera del gateway no publica ninguno de estos hechos.

Con la contabilización, el gateway publica novo_contrato solo con términos que Dataprev confirmó. Cuando Dataprev responde con una competenciaInicioDesconto distinta de la contabilizada, la solicitud responde 503 OUTCOME_UNKNOWN. Reintenta solo bajo la misma clave X-Idempotency. El comando entonces queda detenido en outcome_unknown. La recuperación publica el hecho solo cuando su lectura del nuevo contrato muestra los términos contabilizados. Si Dataprev aceptó el refinanciamiento con términos diferentes, contacta a operaciones de Lerian.

El gateway informa el saldo devedor a Dataprev para cada contrato que mantiene en el registro. Son los contratos que registra por averbação, refinanciamiento, renegociación o portabilidad entrante, y los contratos que importa. Para un contrato que registra, la obligación empieza cuando Dataprev acepta esa operación. Para una averbação, eso ocurre antes de la documentación.

El saldo informado es el valor presente de las cuotas impagas aún por vencer, en la fecha de Brasília del informe. El gateway descuenta cada cuota a la tasa mensual del contrato y supone el pago en la fecha de vencimiento. Envía un informe cuando la deuda cambia, cuando una cuota vence sin pago, y el último día hábil de un mes sin informe.

Cuando Dataprev acepta un cambio de términos, el saldo informado sigue los nuevos términos. Las cuotas vencidas antes de la competencia inicial del cambio siguen debidas por el valor que tenían. Desde esa competencia, rigen la nueva cantidad y el nuevo valor, y el gateway pone en cola un nuevo informe de inmediato. Las dos lecturas de saldo devedor agregan valores_parcela, que asigna a cada competencia inicial (yyyyMM) el valor de la cuota desde ese mes. El campo está ausente hasta que se acepta un cambio de términos. numero_parcelas cuenta las cuotas desde competencia_inicio_desconto bajo los términos cambiados.

Los informes se detienen cuando el contrato sale del registro. Un contrato sale del registro cuando:

• Dataprev confirma su exclusión, o acepta su exclusión de portabilidad del lado de origen
• un refinanciamiento o una renegociación aceptada lo reemplaza, y ninguna reversión lo deshace
• una reversión deshace el refinanciamiento que lo creó. Con el seguimiento de la documentación activado, esto incluye una reversión en el portal de Dataprev en los 14 días posteriores al refinanciamiento.
• una lectura del contrato en Dataprev, por el seguimiento de la documentación o por la lectura de ausencia en la nómina, lo muestra excluido o terminado (situación 2, 3 o 16)
• una exclusión se cierra como rechazada porque la lectura de estado de Dataprev encontró el contrato ya fuera. Un refinanciamiento o una renegociación que el gateway registró para el contrato prevalece sobre esa lectura.

Lee la situación de un contrato para saber si todavía está vivo. alive es true cuando los comandos que actúan sobre un contrato, como suspensión, cambio de términos y anticipación, lo aceptan. arrival informa cómo el contrato pasó a existir, averbacao, refinanciamento, renegociacao o importacao, y cuándo. exit es null mientras el contrato está vivo. En caso contrario, informa por qué el contrato salió, exclusao, exclusao_portabilidade, reversao_refinanciamento o saida_dataprev, y cuándo. La lectura responde con los registros del propio gateway y nunca llama a Dataprev. Un número que el tenant nunca tuvo responde 404 CLT-0005. Solo la credencial propia del tenant puede leerla.

Un contrato que la terminación de vínculo cerró (situación 15) no sale del registro. La deuda sigue en pie, así que el gateway sigue informando el saldo hasta el pago total o la renegociación. Su documentación sigue rechazada, y las señales de plazo de la documentación se detienen.

Un contrato que un refinanciamiento aceptado o una exclusión de portabilidad del lado de origen liquida recibe un informe final de 0.00 antes de que los informes se detengan. Lo mismo vale para un contrato que una lectura de Dataprev muestra como salido por portabilidad o refinanciamiento.

La exclusión es una operación recuperable. El comando autenticado inicial registra la intención, y un bucle programado de recuperación lleva el trabajo admitido a un estado terminal del riel. Repetir el mismo comando idempotente no crea una segunda exclusión. También puedes excluir un contrato sin averbação en este gateway mientras el gateway informa su saldo devedor. Ejemplos son un contrato importado y el nuevo contrato de un refinanciamiento. La recuperación de comandos del riel converge un comando cuyo resultado nadie estableció contra el registro del riel, en lugar de perderlo. Cubre refinanciamiento, reversión, renegociación, exclusión de portabilidad del lado de origen, anticipación de cuota y su remoción, y cambios de términos. Para una anticipación o un cambio de términos, una lectura que empieza una hora o más después del plazo de la llamada y todavía no muestra cambio cierra el comando como rechazado, con GW-M005-NAO-EXECUTADO. Reenvíalo bajo una nueva clave de idempotencia. Suspensión, reactivación y operaciones heredadas no tienen lectura que decida.

Tu back office puede cerrar un refinanciamiento, una renegociación, un cambio de términos, una renegociación heredada o una exclusión por portabilidad del lado de origen en outcome_unknown. Consulta Acciones de back office para hacer el cierre.

Una exclusión también puede cancelar una averbação que espera su documentación. Desde la solicitud de exclusión, la documentación de ese contrato responde AVERBACAO_EXCLUDED, a menos que Dataprev rechace la exclusión. La documentación de un contrato que salió del registro también responde AVERBACAO_EXCLUDED. La documentación que el gateway recibió pero nunca envió a Dataprev no bloquea la exclusión. La exclusión la descarta, y last_documentation_close muestra excluded. Mientras una llamada de documentación a Dataprev está en curso, la exclusión responde EXCLUSION_DOCUMENTATION_UNDERWAY. Esto incluye el nuevo contrato de una renegociación. 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 de la llamada.

Una exclusión de un contrato que una renegociación reemplazó va a Dataprev bajo el número que lo reemplazó, por sucesivas renegociaciones hasta la última. Nunca sigue el contrato reemplazado de un refinanciamiento. Una exclusión de un contrato que Dataprev movió a un nuevo vínculo de empleo va a Dataprev bajo el nuevo vínculo una vez que el gateway registró esa migración. Antes de eso, va bajo el vínculo de la contabilización. El numeroContrato de la respuesta es el número que se pidió a Dataprev excluir, y GET .../exclusion también encuentra la exclusión bajo el número que indicaste. Los hechos de exclusión responden bajo el número que indicaste y nombran el número excluido en numero_contrato_excluido cuando difiere.

Una exclusión y una renegociación se bloquean entre sí. Mientras una renegociación no tiene respuesta de Dataprev, la exclusión responde 409 EXCLUSION_RENEGOTIATION_UNDERWAY. Envíala de nuevo cuando GET /v1/consignado/rail-commands muestre la renegociación aceptada o rechazada. Una renegociación responde 409 RENEGOTIATION_EXCLUSION_UNDERWAY mientras existe una exclusión del contrato cerrado que Dataprev no rechazó.

El gateway rechaza una exclusión antes de llamar a Dataprev, con 404 CLT-0005, cuando mantiene el contrato pero el contrato ya salió del registro: un refinanciamiento lo reemplazó sin reversión, se aceptó una exclusión de portabilidad del lado de origen de él, o una lectura de Dataprev lo vio excluido o terminado. Un contrato cerrado por terminación de vínculo (situación 15) todavía puede excluirse.

Cuando una lectura de Dataprev encuentra un contrato que el gateway mantiene ya fuera del registro, sin ninguna exclusión por el gateway detrás, el gateway publica consignado.exclusao.confirmed una vez, con evidence_source m005_external_exit y un reason_code que empieza con contract_left_registry. Eso cubre un contrato excluido en el portal o por otro origen, terminado, o renegociado fuera del gateway. El seguimiento de la documentación (DATAPREV_DOCUMENTATION_FOLLOWUP_ENABLED, desactivado por defecto) y la lectura de ausencia en la nómina de abajo hacen esas lecturas. El gateway no publica nada para un contrato en situación 15, para una reversión de refinanciamiento, que consignado.refinanciamento.revertido informa, ni para una salida que el propio gateway hizo. Una salida por refinanciamiento solo publica si una segunda lectura 14 días después todavía encuentra el contrato fuera. Una salida por renegociación espera mientras un refinanciamiento o una renegociación de ese contrato por el gateway no tiene respuesta.

Cuando Dataprev mueve un contrato al nuevo vínculo de empleo del trabajador por su cuenta (Manual 018), el gateway publica consignado.migracao.efetivada, una vez por cada contrato y nuevo vínculo. Cubre todo contrato bajo el código de solicitante del tenant, incluidos los contratos no registrados por el gateway. La lectura diaria que lo encuentra viene desactivada por defecto: define DATAPREV_MIGRACAO_ENABLED=true, que requiere DATAPREV_ENABLED=true. Una lectura de contrato del Manual 005 que el gateway hace, como la del seguimiento de la documentación, publica el mismo hecho para un contrato que encuentra migrado, también con ese valor false. El gateway publica un hecho por cada contrato y vínculo, sea cual sea la lectura que lo vio primero. Una suscripción que lista event_types explícitos solo lo recibe cuando la lista nombra consignado_migracao.efetivada. Edita la lista de una suscripción del tenant, o crea una suscripción que lo nombre.

6. Conciliar la nómina y el repasse

El worker de conciliación lee dos fuentes independientes de Dataprev:

• registros de contabilidad, indexados por la competencia de nómina y el contexto del contrato
• registros de repasse de la CEF, que representan el movimiento de liquidación

El gateway emite un hecho de conciliación por cada registro de repasse, excepto uno retenido, y uno por empleador, contrato y mes de contabilidad, y hace seguimiento de los repasses esperados. Un repasse puede volverse vencido, resolverse después, o volverse inobservable cuando el gateway no puede establecer una vista actual del riel. Los consumidores no deben tratar el silencio como liquidación.

Un repasse ausente genera consignado.repasse.overdue solo después de que cerraron el día del plazo y un día hábil más de ANBIMA. El plazo es el cierre, en hora de Brasília, del día que cae dos días hábiles de ANBIMA después del vencimiento de la guía del FGTS. La guía vence el día 20 del mes siguiente a la competencia. Un repasse que llega dentro del día extra produce consignado.repasse.resolved sin overdue antes de él.

En el mes en que se despide a un trabajador, Dataprev registra dos descuentos para un contrato: la cuota de la nómina y el descuento sobre las verbas rescisorias. El gateway espera dos repasses y da alarma por cada uno. Un repasse cierra solo la expectativa de su propio origen. Los hechos de la expectativa de verbas rescisorias traen verbas_rescisorias: true. Cada elemento del tablero de repasses esperados trae verbas_rescisorias. El gateway publica un hecho de conciliación para los dos registros de contabilidad de ese empleador, contrato y mes, a partir del registro que lee primero, así que su valor_parcela y su tipo_evento_esocial pueden pertenecer a cualquiera de los dos registros.

Cada lectura cubre a todos los empleadores del tenant. En un despliegue multi-tenant, el worker concilia cada tenant activo que tiene una credencial de Dataprev. El gateway empareja un repasse con su repasse esperado por contrato y competencia de nómina, no por empleador. Un registro de repasse que no nombra al empleador o la competencia, y que ningún repasse esperado puede suplir, queda retenido. El gateway no publica ningún hecho para él hasta que un repasse esperado nombre ambos. Un registro de verbas rescisorias que no nombra la competencia cierra la expectativa de verbas rescisorias de su contrato y se publica bajo ese mes. Un registro con cargos por mora y sin competencia sigue retenido.

Tu back office puede listar y liberar repasses retenidos. Consulta Acciones de back office.

Con DATAPREV_RECONCILIATION_ENABLED=true, una pasada que lee las dos fuentes sin fallas también lee en Dataprev, mediante la consulta de contratos (Manual 005), los contratos vivos que la nómina de la última competencia cerrada dejó fuera. Lee como máximo 50 contratos por tenant en una pasada. Esas lecturas corren aun con el seguimiento de la documentación desactivado y gastan el presupuesto con ritmo del tenant en Dataprev. Una lectura que encuentra el contrato excluido o terminado detiene sus informes de saldo devedor y publica el hecho de exclusión descrito en la sección 5.

7. Operar carteras y garantías

Familias adicionales de la API cubren calendarios operativos, terminaciones de empleo, ejecución de garantía de FGTS, fondos, originadores, créditos cedidos, throughput por tenant, y suscripciones de entrega de eventos.

El gateway publica consignado.garantia.execution_window cuando se abre la ventana de ejecución de la garantía de FGTS del contrato de un trabajador despedido, y de nuevo 48 horas antes de que cierre, 30 días después del despido. Publica consignado.garantia.block_failed una vez cuando el bloqueo de FGTS de un contrato en Dataprev falló o fue rechazado, de modo que el FGTS no garantiza el contrato. Ambos hechos son solo señales: el gateway no ejecuta la garantía por sí mismo y nunca modifica el contrato. Tu back office ejecuta la garantía con la ejecución de garantía de FGTS.

Lender cede un contrato a un fondo. Cuando Lender publica que un fondo aceptó un contrato, el gateway registra la cesión y publica consignado.cessao.registered. El contrato es uno que este gateway confirmó por averbação o importó con su contabilización. También puede ser el nuevo contrato de un refinanciamiento o de una renegociación que este gateway registró como aceptado. La lectura de créditos cedidos del fondo entonces lista el contrato, también cuando no vino de una subasta.

El gateway no registra cesión para un contrato que salió del registro: una exclusión confirmada, una exclusión de portabilidad aceptada, un original que un refinanciamiento o una renegociación aceptada reemplazó sin reversión, o un contrato que una lectura de Dataprev vio excluido o terminado (situación 2, 3 o 16). Un contrato que la terminación de vínculo cerró (situación 15) todavía puede cederse.

Usa la página de la operación en la referencia de la API para conocer los headers exactos requeridos, las reglas de idempotencia, los rangos de validación, y los esquemas de respuesta.