- 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
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. Usa un nuevo certificado y un nuevo cliente de OAuth. 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.
Cuando socios originan préstamos en nombre del tenant, registra cada uno como originador. Un originador desactivado no puede enviar ofertas, y 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 hasta que lo reactives.
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. La llamada entonces se ejecuta como se ejecutaría con la credencial propia del fondo o del originador. Un id de ruta que no está en el registro de fondos o de originadores del tenant responde 403.
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. 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 eldados_cadastrais de la averbação no declara esos campos, consignado.contract.registered los toma de esa lectura de margen.
- 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 cada segundo. 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.
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.
4. Registrar y financiar el contrato
El flujo de registro:- envía la averbação a Dataprev
- envía la documentación del contrato a Dataprev
- expone el estado de registro y los documentos del riel
- registra la confirmación de desembolso del cliente
- publica hechos inmutables de contabilización y pago a través del outbox
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 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. 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.
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.
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. 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.
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. 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 averbado por este gateway, o que se importó antes con otros datos de contabilización.
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 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.
- Dar servicio al contrato
La API cubre el ciclo de vida del riel después del registro: suspensión, reactivación, cambios de plazo, 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.
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.
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.
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.
- el seguimiento de la documentación lo lee excluido o terminado en Dataprev
- el informe de terminaciones lo lista
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. Cuando la documentación ya está registrada o en curso, la exclusión responde EXCLUSION_DOCUMENTATION_UNDERWAY. Mientras la averbação esté en attachment_pending, envía de nuevo la misma documentación para completarla, y luego excluye el contrato confirmado.
Renegociación automática
Lerian habilita la renegociación automática por tenant, a pedido. Para un tenant que la tiene habilitada, el gateway envía la renegociación del Manual 006 de un contrato que Dataprev cerró por término de vínculo. El envío sigue el mismo camino que la operación de renegociación. Su resultado publicaconsignado.renegociacao.efetivada o consignado.renegociacao.recusada con iniciada_por gateway.
El gateway considera un contrato que registró o importó, después de que el informe de terminaciones lo liste. Espera hasta 31 días después de la fecha de terminación, en el calendario de Brasília. Luego lee los nuevos vínculos laborales que Dataprev publica para el trabajador. Envía cuando el trabajador tiene exactamente un nuevo vínculo utilizable, a menos que se aplique un motivo de abajo.
El nuevo contrato mantiene la cuota y las tasas del contrato cerrado. Cubre las competencias del contrato cerrado desde la competencia actual en adelante. No libera dinero y no tiene IOF. competencias_puladas en consignado.renegociacao.efetivada lista las competencias del contrato cerrado desde el mes de terminación hasta la anterior a la competencia actual.
El gateway crea el número del nuevo contrato: R seguido de 14 dígitos o letras mayúsculas. El mismo contrato cerrado siempre recibe el mismo número.
De lo contrario, el gateway te devuelve el contrato. No envía nada y publica consignado.renegociacao.recusada con refused_by gateway. reason_code contiene uno de estos motivos:
Hasta 90 días después de la fecha de terminación, el gateway no devuelve por
GARANTIA_INDETERMINADA, SEM_VINCULO_NOVO o PRAZO_ESGOTADO. Espera y vuelve a revisar el contrato en cada pasada.
Antes de verificar los motivos a partir de ANTECIPACAO, el gateway lee el contrato cerrado en Dataprev. Cuando esa lectura ya no muestra el contrato como cerrado por término de vínculo, el gateway se detiene y no publica nada. Envía o devuelve cada contrato cerrado como máximo una vez.
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
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, cesiones, throughput por tenant, y suscripciones de entrega de eventos. Lender también puede ceder un contrato. Cuando Lender publica que un fondo aceptó un contrato, el gateway registra la cesión. 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. Publicaconsignado.cessao.registered, como lo hace para una cesión que registra el cliente. La lectura de créditos cedidos del fondo entonces lista el contrato, también cuando no vino de una subasta. Una cesión del cliente de un contrato que Lender ya cedió a otro fondo responde CESSAO_CEDED_TO_OTHER_FUND. Ninguna de las dos cesiones se aplica a un contrato que una exclusión confirmada o una exclusión de portabilidad aceptada sacó del registro. La cesión del cliente entonces responde CESSAO_CREDIT_NOT_WITNESSED.
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.