- Configure um tenant
Antes que um tenant possa chamar o trilho, registre:
- um certificado de cliente ICP-Brasil A1 e a chave privada
- credenciais de cliente OAuth2
- o código de solicitante Dataprev de três dígitos do tenant
- opcionalmente, a URL base do portal do trabalhador oferecida como contato de formalização nas propostas de lance
DATAPREV_CREDENTIAL_REQUIRED. Uma credencial revogada responde DATAPREV_CREDENTIAL_REVOKED. Apenas um envio completo do certificado e do cliente OAuth juntos encerra a revogação. Use um novo certificado e um novo cliente OAuth. Quando o Dataprev recusa as credenciais de cliente OAuth do tenant, uma leitura responde DATAPREV_CREDENTIAL_REJECTED, e uma escrita pode ficar parada. Corrija as credenciais na custódia e veja Credenciais e artefatos antes de enviar uma escrita de novo.
Quando parceiros originam empréstimos em nome do tenant, registre cada um como originador. Um originador desativado não pode enviar lances, e o gateway mantém o registro dele. Reative o originador para que ele volte a agir sob a mesma referência.
Quando o tenant cede créditos a fundos, registre cada fundo. Um fundo que o gateway conhece pelos fatos de fundo do Lender não precisa de registro aqui. Até o gateway conhecer o fundo, uma averbação que o nomeia responde FUNDO_NOT_REGISTERED. Um fundo desativado não aceita novo crédito até você reativá-lo.
Uma averbação nomeia um fundo do Lender pelo id do Lender, assim como uma cessão do Lender. O CNPJ do fundo só importa para um fato de cessão do Lender sem id de fundo. O gateway então cede o contrato ao fundo registrado com esse CNPJ.
Um fundo ou um originador também pode chamar o gateway com uma credencial de parceiro do Access Manager restrita ao seu id de registro. Ele usa as rotas sob /v1/consignado/fundos/{fundo_id}/ ou /v1/consignado/originadores/{originador_id}/, com esse id de registro no caminho. A chamada então roda como rodaria a credencial própria do fundo ou do originador. Um id de caminho que não está no registro de fundos ou de originadores do tenant responde 403.
2. Leia dados e margem do trabalhador
O endpoint de margem autentica o tenant, obtém o contexto de autorização do trabalhador no Dataprev e retorna a resposta do trilho sem transformá-la em uma decisão de underwriting. Quando o Dataprev os retorna, a resposta também traz os registros do trabalhador, do vínculo empregatício e do empregador. A API também expõe novos vínculos empregatícios, relatórios de rescisão, registros de FGTS autorizados e leituras de saldo de FGTS. O gateway guarda a categoria eSocial e a data de admissão da leitura de margem mais recente de cada vínculo empregatício. Ele as apaga 30 dias após a última leitura. Quando odados_cadastrais da averbação não declara esses campos, consignado.contract.registered os traz dessa leitura de margem.
- Descubra leilões e envie propostas
Um loop de descoberta agendado lista as solicitações de empréstimo abertas e publica cada nova solicitação. Uma via rápida opcional repete essa listagem a cada segundo. O cliente pode então enviar um lance pela API HTTP autenticada. O gateway retém o payload durável do lance necessário para comprovar o que o cliente enviou e, depois, publica o testemunho da proposta aceita.
Um lance pode nomear um originador. O gateway recusa um lance para um originador desconhecido ou desativado. Um originador que se autentica com a própria credencial envia lances sob a própria referência.
Toda proposta deve chegar ao trabalhador por pelo menos um contato. O gateway adiciona um portal de formalização como contato quando encontra um: primeiro no lance, depois no originador nomeado, depois no tenant. Quando nenhum dos três tem portal, cada proposta deve levar um contato do cliente. Caso contrário, o gateway recusa o lance antes de chamar o Dataprev.
Os leilões de portabilidade usam uma operação de resposta separada e uma janela de requisição limitada no Dataprev.
4. Registre e financie o contrato
O fluxo de registro:- envia a averbação ao Dataprev
- envia a documentação do contrato ao Dataprev
- expõe o status de registro e os documentos do trilho
- registra a confirmação de desembolso do cliente
- publica fatos imutáveis de registro contábil e de pagamento pelo outbox
nome_trabalhador, o nome completo do trabalhador. Você cria o número do contrato: de 2 a 15 letras ou dígitos, sem espaços, acentos ou símbolos. A mesma regra vale para o novo contrato de um refinanciamento, de uma renegociação ou de uma portabilidade de entrada. A averbação responde 422 antes de chamar o Dataprev quando tem_garantias e os valores de garantia do FGTS não concordam: true sem nenhum valor, ou false com um valor.
Com o bloco de contabilização, o gateway verifica a contabilização antes de chamar o Dataprev e responde 422 quando o Lender não consegue contabilizá-la. O detalhe do problema nomeia a regra, e a lista de erros traz cada código. Quando o Dataprev aceita a averbação, a operação responde attachment_pending e o gateway publica consignado.averbacao.accepted. O Dataprev então detém o mandato de desconto em folha, e o contrato aguarda a documentação.
Envie a documentação em uma segunda requisição, sob a própria chave X-Idempotency. Ela executa apenas o Manual 004. Ela leva a CCB assinada, a evidência de assinatura e data_hora_assinatura, o instante em que o trabalhador assinou a CCB. O trabalhador pode assinar dias depois da averbação.
Quando a averbação trouxe o bloco de contabilização, a documentação leva também o pacote de evidências e signature_evidence_ref. Sem o bloco, os dois são recusados. Com o bloco, um instante de assinatura posterior a formalization_deadline responde FORMALIZATION_DEADLINE_EXCEEDED. Um instante mais de 5 minutos à frente do relógio do gateway responde DECLARED_DATES_OUT_OF_ORDER.
A documentação também completa o novo contrato de uma renegociação que o Dataprev aceitou por meio deste gateway. Envie apenas a CCB assinada do contrato substituído. A resposta é confirmed, e o gateway não publica nenhum fato.
Sem uma averbação aceita ou uma renegociação desse tipo, a documentação responde AVERBACAO_NOT_ACCEPTED e nada chega ao Dataprev. A recusa é definitiva apenas quando a averbação lê rejected, porque a recuperação de averbações (DATAPREV_AVERBACAO_RECOVERY_ENABLED, desligada por padrão) ainda pode aceitar uma averbação que lê averbacao_unknown. Sem ela, contate a Lerian com o número do contrato.
Um contrato aceita uma única documentação aceita. A mesma documentação sob uma nova chave repete a primeira resposta. Uma documentação diferente responde AVERBACAO_DOCUMENTATION_CONFLICT enquanto a primeira está aceita ou a caminho do Dataprev. Quando o Dataprev aceita a documentação, a operação responde confirmed e o gateway publica consignado.averbacao.confirmed. A confirmação entrega ao Lender, para contabilização e desembolso, o contrato enviado com o bloco de contabilização.
Quando o Dataprev recusa a documentação, a requisição responde 422 com os códigos do Dataprev em upstream, e o contrato volta a aguardar a documentação. Envie a documentação corrigida sob uma nova chave ou exclua o contrato. Quando a chamada termina sem veredito, a requisição responde 503 ou 504, e o contrato também volta a aguardar. Envie a mesma documentação de novo.
O Manual 004 dá à instituição financeira 7 dias após a averbação para enviar a documentação. O gateway não impõe esse prazo. A leitura da averbação mostra documentation_due_at, 7 dias corridos após a averbação, e documentation_overdue enquanto a documentação está atrasada. Dois loops opcionais ajudam você a acompanhá-lo, e os dois vêm desabilitados por padrão. O sinal de prazo publica consignado.averbacao.documentation_deadline. O acompanhamento da documentação lê no Dataprev cada contrato que aguarda, uma vez por dia, e mostra o que encontra em dataprev_follow_up.
Um lender ou ledger downstream decide o que esses fatos significam para seus próprios livros. O gateway não lança diretamente no ledger.
Após a confirmação, informe o código de instrumento B3 que a B3 retornou ao aceitar o registro da CCB. Apenas a credencial do próprio tenant pode informá-lo ou lê-lo, não uma credencial de fundo ou de originador. O gateway grava o código uma única vez e publica consignado.registro_b3.registered. Reenviar o mesmo código e a mesma data responde o registro original. Um código ou uma data diferente responde REGISTRO_B3_JA_INFORMADO, e a API não oferece correção. O gateway não se comunica com a B3 e não confere o código com a CCB.
Importe um contrato que já está registrado no trilho fora deste gateway. A importação lê o contrato no Dataprev e não movimenta dinheiro. Apenas um contrato ativo ou suspenso pode ser importado. Sem os dados de contabilização, um contrato que já tem uma obrigação de saldo devedor aqui responde CONTRACT_ALREADY_REGISTERED.
Uma importação também pode levar os dados de contabilização, em dois objetos enviados juntos. O objeto booking é o corpo da averbação com o bloco de contabilização completo e um numero_proposta vazio. Ele também leva a documentação: a CCB assinada, o pacote de evidências, signature_evidence_ref e a evidência de assinatura.
O objeto registration traz o que o Dataprev devolveu na averbação original. Ele leva averbado_at, o response_code da averbação e o hash_operacao do Manual 004 da documentação. O averbado_at deve ficar a até um minuto do instante de inclusão na leitura do Dataprev. Enviar apenas um dos dois é recusado.
O gateway confere a contabilização e o averbado_at com a leitura do Dataprev, guarda os documentos sob sua custódia e publica consignado.contract.registered. O Lender então contabiliza o contrato como contabiliza um registrado por averbação aqui. A importação não envia averbação nem CCB ao Dataprev.
Com os dados de contabilização, uma obrigação que o contrato já tem não é um conflito. O gateway a mantém intacta, e saldo_devedor_dispatch_scheduled responde false. Nesse modo, CONTRACT_ALREADY_REGISTERED significa que o contrato foi averbado por este gateway ou foi importado antes com outros dados de contabilização.
Registre uma correção contra o contrato registrado quando algo que o cliente já afirmou se revela incorreto. Exemplos são o arquivo CCB errado e uma confirmação de desembolso com a evidência errada. Uma correção não cruza nenhuma fronteira governamental: os próprios campos de retificação do trilho foram desativados, então o cliente permanece como a única autoridade. O gateway assume a custódia dos bytes corrigidos, publica o fato que os nomeia e os serve de volta mediante autenticação. As correções formam uma cadeia: cada uma substitui o evento anterior a ela. Apenas a credencial do próprio tenant registra uma correção. Um fundo lê as correções de um contrato cedido a ele e de um novo contrato que herda esse fundo.
- Administre o contrato
A API cobre o ciclo de vida do trilho após o registro: suspensão, reativação, alterações de prazo, antecipação e reversão de parcela, e exclusão. Ela também cobre refinanciamento e reversão, renegociação, registro de portabilidade e operações de contrato legado. O desfecho de uma renegociação publica consignado.renegociacao.efetivada ou consignado.renegociacao.recusada.
A portabilidade funciona nos dois sentidos. Como instituição proponente, registre a portabilidade de entrada. Como instituição de origem, exclua o contrato do qual o trabalhador migrou. O gateway aceita isso apenas para um contrato que ele mantém para você: registrado por meio dele, ou importado. Ele recusa qualquer outro caso antes de chamar o trilho.
Reverter um refinanciamento funciona da mesma forma. Você apenas pode reverter um refinanciamento por este gateway se o gateway o registrou. A janela de 7 dias úteis é avaliada em relação ao próprio registro do gateway sobre quando esse refinanciamento foi efetivado.
O gateway informa o saldo devedor ao Dataprev para cada contrato que mantém no registro. São os contratos que ele registra por averbação, refinanciamento, renegociação ou portabilidade de entrada, e os contratos que importa. Para um contrato que ele registra, a obrigação começa quando o Dataprev aceita essa operação. Para uma averbação, isso acontece antes da documentação.
O saldo informado é o valor presente das parcelas não pagas ainda por vencer, na data de Brasília do informe. O gateway desconta cada parcela pela taxa mensal do contrato e considera o pagamento na data de vencimento. Ele envia um informe quando a dívida muda, quando uma parcela vence sem pagamento e no último dia útil de um mês sem informe.
Os informes param quando o contrato sai do registro. Um contrato sai do registro quando:
- o Dataprev confirma a exclusão dele ou aceita a exclusão por portabilidade do lado de origem
- um refinanciamento ou uma renegociação aceita o substitui, e nenhuma reversão desfaz isso
- uma reversão desfaz o refinanciamento que o criou. Com o acompanhamento da documentação ligado, isso inclui uma reversão no portal do Dataprev nos 14 dias após o refinanciamento.
- o acompanhamento da documentação o lê excluído ou encerrado no Dataprev
- o relatório de rescisões o lista
AVERBACAO_EXCLUDED, a menos que o Dataprev rejeite a exclusão. A documentação de um contrato que saiu do registro também responde AVERBACAO_EXCLUDED. Quando a documentação já está registrada ou em andamento, a exclusão responde EXCLUSION_DOCUMENTATION_UNDERWAY. Enquanto a averbação estiver em attachment_pending, envie a mesma documentação de novo para concluí-la e depois exclua o contrato confirmado.
Renegociação automática
A Lerian habilita a renegociação automática por tenant, a pedido. Para um tenant com ela habilitada, o gateway envia a renegociação do Manual 006 de um contrato que o Dataprev encerrou por término de vínculo. O envio segue o mesmo caminho da operação de renegociação. O desfecho publicaconsignado.renegociacao.efetivada ou consignado.renegociacao.recusada com iniciada_por gateway.
O gateway considera um contrato que ele registrou ou importou, depois que o relatório de rescisões o lista. Ele espera até 31 dias após a data de desligamento, no calendário de Brasília. Depois, lê os novos vínculos empregatícios que o Dataprev publica para o trabalhador. Ele envia quando o trabalhador tem exatamente um novo vínculo utilizável, a menos que um motivo abaixo se aplique.
O novo contrato mantém a parcela e as taxas do contrato encerrado. Ele cobre as competências do contrato encerrado a partir da competência atual. Ele não libera nenhum valor e não tem IOF. competencias_puladas em consignado.renegociacao.efetivada lista as competências do contrato encerrado do mês do desligamento até a anterior à competência atual.
O gateway cria o número do novo contrato: R seguido de 14 dígitos ou letras maiúsculas. O mesmo contrato encerrado sempre recebe o mesmo número.
Caso contrário, o gateway devolve o contrato a você. Ele não envia nada e publica consignado.renegociacao.recusada com refused_by gateway. reason_code contém um destes motivos:
Até 90 dias após a data de desligamento, o gateway não devolve por
GARANTIA_INDETERMINADA, SEM_VINCULO_NOVO ou PRAZO_ESGOTADO. Ele espera e verifica o contrato de novo a cada execução.
Antes de verificar os motivos a partir de ANTECIPACAO, o gateway lê o contrato encerrado no Dataprev. Quando essa leitura não mostra mais o contrato como encerrado por término de vínculo, o gateway para e não publica nada. Ele envia ou devolve cada contrato encerrado no máximo uma vez.
6. Concilie a folha de pagamento e o repasse
O worker de conciliação lê duas fontes independentes do Dataprev:- registros de escrituração, indexados pela competência da folha de pagamento e pelo contexto do contrato
- registros de repasse da CEF, que representam a movimentação de liquidação
7. Opere portfólios e garantias
Famílias adicionais de API cobrem calendários operacionais, rescisões de vínculo empregatício, execução de garantia de FGTS, fundos, originadores, créditos cedidos, cessões, vazão por tenant e subscriptions de entrega de eventos. O Lender também pode ceder um contrato. Quando o Lender publica que um fundo aceitou um contrato, o gateway registra a cessão. O contrato é um que este gateway confirmou por averbação ou importou com a contabilização. Ele também pode ser o novo contrato de um refinanciamento ou de uma renegociação que este gateway registrou como aceito. Ele publicaconsignado.cessao.registered, como faz para uma cessão que o cliente registra. A leitura de créditos cedidos do fundo passa então a listar o contrato, também quando ele não veio de um leilão. Uma cessão do cliente para um contrato que o Lender já cedeu a outro fundo responde CESSAO_CEDED_TO_OTHER_FUND. Nenhuma das duas cessões se aplica a um contrato que uma exclusão confirmada ou uma exclusão por portabilidade aceita tirou do registro. A cessão do cliente então responde CESSAO_CREDIT_NOT_WITNESSED.
Use a página da operação na referência da API para conhecer os cabeçalhos obrigatórios exatos, as regras de idempotência, os intervalos de validação e os esquemas de resposta.