Superfícies de comando e leitura
Use a API HTTP autenticada para comandos e consultas do cliente. A API separa comandos de leituras. Cada operação do cliente exige uma ação de autorização e roda no tenant de quem chama. Siga os requisitos de idempotência da operação. Novas tentativas após timeouts são normais e devem reutilizar a mesma identidade de negócio. Um comando de trilho parado emoutcome_unknown (503 OUTCOME_UNKNOWN) é a exceção: nenhuma chave o reenvia, então leia GET /v1/consignado/rail-commands.
Uma operação montada não é prova de que um deployment específico conecta seu adapter Dataprev. Uma integração de trilho indisponível retorna 501 Not Implemented para essa requisição, em vez de desaparecer da API. A operação de capacidades informa quais famílias de operação o seu deployment alcança. Registrar o código de instrumento da B3 de um contrato confirmado não chama o Dataprev, por isso não depende de nenhuma chave do trilho.
O stream de comandos do Lender carrega apenas o comando de exclusão. Ele não substitui a superfície HTTP completa. Veja Eventos do Consignado.
Workers agendados
O gateway executa o trabalho em segundo plano como loops agendados. Eles compartilham execução inicial retardada, escalonamento estável por réplica, isolamento de panic e encerramento gracioso. Todos os loops, exceto a via rápida de leilões, também fazem execuções sem sobreposição com jitter positivo.
A via rápida de leilões, a limpeza de payload de lances e o testemunho de proposta leem sua cadência pelo Systemplane e entram em vigor no próximo intervalo. Os outros loops tomam sua cadência da configuração de ambiente e precisam de uma reinicialização para mudar.
A recuperação de averbação e a recuperação de comandos do trilho existem porque um comando de trilho pode deixar seu desfecho sem estabelecer: o processo morreu no meio da chamada, ou o trilho nunca respondeu. Elas convergem esse estado junto ao próprio registro do trilho, em vez de perdê-lo.
Para uma antecipação ou uma alteração de termos, a recuperação lê o contrato no Dataprev: uma mudança encontrada fecha o comando como aceito, e uma leitura que ainda não mostra mudança uma hora após o prazo da chamada o fecha como rejeitado. A recuperação espaça as releituras de um comando que não consegue fechar: 1 minuto, depois cada espera dobra, até uma vez por hora.
A recondução de lances reenvia um lance cuja resposta do trilho se perdeu, com o número de proposta original. Cada reenvio usa o orçamento de trilho do tenant. A recuperação de averbação, a recuperação de comandos de trilho e a recondução de lances vêm desabilitadas por padrão. Habilite os dois loops de recuperação em qualquer deploy que envie averbações ou comandos de trilho.
Quando o Dataprev recusa a documentação, a requisição responde
422 com os códigos do Dataprev em upstream, e o contrato volta para attachment_pending. Envie a documentação corrigida sob uma nova chave X-Idempotency ou exclua o contrato. Quando a chamada termina sem veredito, como um timeout, um 5xx do Dataprev ou um recibo inutilizável, a requisição responde 503 ou 504. O contrato também volta para attachment_pending: envie a mesma documentação de novo, sob a mesma chave ou uma nova. A leitura da averbação mostra em last_documentation_close a tentativa mais recente que o Dataprev não aceitou.
Um anexo de CCB interrompido no meio da chamada permanece em attachment_invoking até o attachment_invocation_deadline_at dele. Depois desse instante, a próxima documentação ou exclusão do contrato assume a chamada. Uma exclusão responde 409 EXCLUSION_DOCUMENTATION_UNDERWAY apenas enquanto uma chamada de documentação está em andamento (attachment_invoking antes do attachment_invocation_deadline_at), para uma averbação ou um contrato renegociado. Envie a exclusão de novo quando GET /v1/consignado/averbacao-operations listar o contrato como confirmed ou attachment_pending, ou quando o prazo tiver passado. A exclusão descarta a documentação que o gateway nunca enviou (last_documentation_close com o código excluded).
Uma vez por mês, o Dataprev fecha para a virada de competência e recusa requisições. Quatro loops pausam para esse tenant quando um deles encontra essa recusa. São eles a descoberta de leilões, a via rápida de leilões, a descoberta de portabilidade e a recondução de lances. A pausa dura 5 minutos, depois 15, depois 30 a cada nova recusa. A recuperação de averbação, a recuperação de comandos do trilho, a conciliação e o poller de relatório de vínculo empregatício não aguardam essa pausa. Cada execução delas para de chamar o Dataprev na recusa e tenta de novo na próxima execução.
As requisições do cliente continuam chegando ao Dataprev e recebem a recusa dele. O relatório de jobs agendados mostra paused_until para um loop pausado. Na Lerian Cloud, o gateway publica consignado.rail.paused uma vez por virada e consignado.rail.resumed quando uma execução iniciada depois de a pausa abrir é respondida sem a recusa. O fato pode chegar um intervalo de sondagem depois de o Dataprev reabrir.
Janelas do trilho
Os padrões e as restrições do trilho incluem:- uma janela de validade de 24 horas para o leilão de empréstimo, que o Dataprev fornece e o gateway não configura
- um lookback de 72 horas para a solicitação de portabilidade
- 20 dias corridos desde a exclusão de origem para registrar uma portabilidade de entrada, quando a requisição informa a data da exclusão
- 7 dias úteis para reverter um refinanciamento
- 7 dias após uma averbação, ou após uma renegociação aceita por meio do gateway, para enviar sua documentação pelo anexo de CCB. Encontre os contratos que ainda aguardam com
GET /v1/consignado/averbacao-operations?status=attachment_pendinge leiadocumentation_due_atedocumentation_overdueem cada um. Uma averbação cuja exclusão você pediu também continua emattachment_pending. A documentação dela recebe409 AVERBACAO_EXCLUDED, a menos que o Dataprev tenha rejeitado a exclusão. Antes de enviá-la, consulteGET /v1/consignado/contracts/{numero_contrato}/exclusioncom a credencial do próprio tenant. Uma credencial de fundo ou de originador não pode consultá-lo. - uma janela de 48 horas para a descoberta de leilões, com uma tolerância de clock skew de cinco minutos
Vazão e ritmo
O tráfego do Dataprev tem seu ritmo controlado por tenant. A API de vazão define a taxa do tenant, de 0 a 25 requisições por segundo, e nenhuma configuração eleva esse teto. Um tenant sem taxa armazenada opera a 3 requisições por segundo. Um valor armazenado de0 pausa o tráfego do trilho para esse tenant.
Segurança da conciliação
As leituras de escrituração e de repasse são independentes. Uma fonte com falha não deve suprimir a outra. Repasses esperados podem emitir três estados:consignado.repasse.overdue: a movimentação esperada está atrasadaconsignado.repasse.resolved: a movimentação esperada chegou depois do prazo. Ela pode chegar sem umoverdueantesconsignado.repasse.unobserved: o gateway não consegue, no momento, comprovar presença ou ausência
held. Leia primeiro o estado de atualização: uma lista vazia não prova nada, a menos que o estado seja fresh.
Um repasse ausente conta como atrasado apenas depois que o dia útil ANBIMA seguinte ao dia do prazo se encerrou. Quando uma execução lê as duas pontas, escrituração e repasse, sem falhas, ela também lê, pela consulta de contratos do Dataprev, os contratos ativos que a última folha encerrada deixou de fora. Essas leituras gastam o orçamento do Dataprev do tenant mesmo com o acompanhamento da documentação desabilitado. Uma leitura que encontra o contrato excluído, encerrado ou renegociado fora do gateway publica consignado.exclusao.confirmed com evidence_source m005_external_exit.
Ações do back office
Seu back office tem duas ações no caminho do dinheiro. As duas exigem um papel do Access Manager que tenha a permissão correspondente. Os papéisadmin e operator têm as duas.
O fechamento informa o que o portal do Dataprev mostra:
outcome accepted ou refused, e portal_evidence de 1 a 500 caracteres, sem CPF nem nome do trabalhador. Um fechamento bem-sucedido responde 204.
Um fechamento refused não lê nada no Dataprev. Um fechamento accepted de refinanciamento, renegociação ou renegociação de legado lê o novo contrato uma vez e responde 409 RAIL_COMMAND_CLOSE_CONTRADICTED se a leitura o contradiz. Uma alteração de termos accepted não lê nada: o gateway move a obrigação do saldo devedor para os termos informados, sem verificação no Dataprev.
Uma suspensão, uma reativação ou uma inclusão ou exclusão de legado parada permanece em outcome_unknown: confirme o efeito no portal do Dataprev.
A liberação recebe {"competencia":"yyyyMM"}, publica o registro sob esse mês e responde 204. Um mês que não serve responde 409, e o registro continua retido.
Credenciais e artefatos
Rotacione o certificado do tenant, o segredo OAuth, o código de solicitante e a URL do portal pela API de credenciais. Uma troca do código de solicitante chega a todas as réplicas na próxima chamada ao Dataprev. As variáveis de arquivo de certificado local são um fallback de desenvolvimento, não um substituto para a custódia do tenant em deployments gerenciados. Quando o Dataprev recusa as credenciais de cliente OAuth do tenant, as operações que chegam ao Dataprev respondem409 DATAPREV_CREDENTIAL_REJECTED. A averbação e o anexo de CCB respondem esse código antes de reservar qualquer coisa. A exclusão não: ela responde com a operação parada em outcome_unknown. Um comando de trilho também responde esse código e fecha como rejected. Uma execução de garantia de FGTS responde e fecha como refused. Um lance continua aberto sob a sua chave: envie-o de novo sob a mesma chave.
Corrija as credenciais, e as leituras voltam a funcionar. Envie de novo uma averbação ou um anexo de CCB recusado sob a mesma chave. Envie de novo um comando de trilho ou uma execução de garantia de FGTS recusada sob uma nova chave X-Idempotency: a chave antiga repete a recusa. Para um tenant revogado, as operações do trilho e os envios parciais de credenciais respondem 409 DATAPREV_CREDENTIAL_REVOKED. Um envio completo de um novo certificado e de um segredo de cliente OAuth gerado de novo no Dataprev encerra a revogação.
Registrar uma URL base de portal do trabalhador é opcional, para o tenant e para cada originador. Veja Descubra leilões e envie propostas para a ordem em que o gateway seleciona um portal.
Artefatos de CCB e do trilho usam o armazenamento de objetos configurado. Mantenha o bucket privado e entregue o conteúdo apenas pela operação autenticada de artefatos.
A averbação não carrega nenhum documento, e um corpo de 1 MiB ou mais recebe 413. O anexo de CCB aceita uma CCB assinada e, depois de uma averbação com o bloco de contabilização, um pacote de biometria. O texto em base64 de cada um tem até 8 MiB, e um corpo inteiro de 18 MiB ou mais recebe 413. Uma importação de contrato que carrega esses documentos segue os mesmos limites. Uma correção de contrato aceita um recurso corrigido cujo texto em base64 tem até 8 MiB.
Comportamento em falha
O trilho falha de forma fechada quando falta identidade de tenant, com identificadores de comando malformados e com endpoints do Dataprev fora da política de deploy: HTTPS em um deploy gerenciado, HTTP loopback apenas nos demais. Um deploy gerenciado também falha de forma fechada quando faltam credenciais e com adapters sem suporte. Fatos de negócio são gravados pelo outbox e entregues pelo menos uma vez. Consumidores devem deduplicar pela origem e pelo ID do CloudEvent. Uma queda do broker não tira o gateway da rotação: o outbox mantém os fatos duráveis, e o/readyz apenas reporta a verificação streaming. Alerte sobre essa verificação ou sobre o backlog do outbox.
Depois que o banco de dados de um tenant roda o schema da 4.2.0, não volte a imagem para a 4.0.0 ou anterior. Avance a versão.