Documentação de API para contratos de consignado privado

março 20, 2026

Última atualização: 30 de julho de 2026

Principais lições deste artigo

Autenticar a API exige JWT assinado com certificado A1 ICP-Brasil e procuração eletrônica válida.
Montar lotes eSocial requer estrutura XML com rubrica 9253 e assinatura digital individual por evento.
Consultar a margem via Dataprev garante o limite de 35% em tempo real antes da averbação.
Executar a averbação automática vincula o contrato à folha e atualiza o status via webservice de consulta.
A Celcoin fornece infraestrutura tecnológica completa para empresas que desejam operar consignado privado com conformidade regulatória.

Como autenticar na API do consignado privado

A integração com os webservices do eSocial e da Dataprev exige autenticação mútua via HTTPS (TLS) com certificado digital ICP-Brasil. O fluxo padrão combina um JWT assinado com o certificado A1 e-CNPJ da instituição financeira ou correspondente bancário com uma procuração eletrônica válida registrada na plataforma.

O cabeçalho HTTP de cada requisição deve incluir o token Bearer gerado a partir da assinatura RSA-SHA256 do payload JWT. O exemplo abaixo mostra a estrutura mínima do payload:

{ "iss": "cnpj-da-instituicao", "sub": "cpf-do-trabalhador", "aud": "https://webservices.consignado.dataprev.gov.br", "exp": 1753920000, "iat": 1753916400, "procuracao": "uuid-da-procuracao-eletronica" }

Falhas de validação do certificado, como cadeia não confiável, certificado revogado, expirado ou de tipo incorreto, geram códigos de rejeição específicos (148, 149, 150, 151, 152, 153 ou 4) e causam rejeição do lote inteiro ou do evento individual. Toda comunicação utiliza SOAP 1.1 sobre HTTPS com mensagens UTF-8 no estilo Document/Literal, seguindo o WS-I Basic Profile 1.1.

Estrutura do lote eSocial para averbação

Uma vez autenticado, o próximo passo é construir o lote eSocial que será enviado. O eSocial disponibilizou a rubrica 9253 para cadastramento de descontos de empréstimo consignado do programa Crédito do Trabalhador. Sem essa rubrica, o sistema não reconhece o desconto como consignado privado, o que torna seu uso obrigatório em todos os eventos de folha. Essa obrigatoriedade foi consolidada na versão S-1.3 do eSocial, que entrou em produção em 02/12/2024 e deve ser seguida por todas as integrações atuais.

Os eventos obrigatórios para averbação de consignado privado são três, cada um cobre um cenário distinto de desconto em folha mensal, rescisão ou trabalhador sem vínculo. A tabela a seguir resume a finalidade de cada evento e as incidências obrigatórias:

Evento	Finalidade	Incidências obrigatórias
S-1200	Remuneração mensal com desconto da parcela	FGTS 31 / INSS 00 / IRRF 09
S-2299	Desligamento com desconto na rescisão	FGTS 31 / INSS 00 / IRRF 09
S-2399	Trabalhador sem vínculo (TSVE)	FGTS 31 / INSS 00 / IRRF 09

Cada evento dentro do lote deve ser assinado individualmente com o mesmo certificado usado na autenticação, seguindo o padrão XML Digital Signature Enveloped com RSA-SHA256 e digest SHA-256. O fragmento XML mínimo de um evento S-1200 com rubrica 9253 segue o padrão:

&lt;eSocial&gt; &lt;evtRemun&gt; &lt;infoPerApur&gt; &lt;ideEstabLot&gt; &lt;remunPerApur&gt; &lt;itensRemun&gt; &lt;codRubr&gt;9253&lt;/codRubr&gt; &lt;ideTabRubr&gt;CONSIG-PRIV&lt;/ideTabRubr&gt; &lt;qtdRubr&gt;1&lt;/qtdRubr&gt; &lt;vrRubr&gt;450.00&lt;/vrRubr&gt; &lt;/itensRemun&gt; &lt;/remunPerApur&gt; &lt;/ideEstabLot&gt; &lt;/infoPerApur&gt; &lt;/evtRemun&gt; &lt;/eSocial&gt;

Simplifique a construção de lotes eSocial com a API da Celcoin.

Consulta de margem em tempo real via Dataprev

Controlar a margem consignável antes da averbação evita rejeições e retrabalho. O limite consignável é de 35% da remuneração líquida disponível do trabalhador, validado em tempo real pela Dataprev antes de qualquer averbação. A consulta utiliza o CPF do trabalhador como parâmetro principal e retorna a margem disponível, os contratos ativos e o saldo devedor atualizado.

A tabela abaixo apresenta os parâmetros mínimos da requisição de consulta de margem:

Parâmetro	Tipo	Descrição
cpfTrabalhador	string(11)	CPF sem pontuação
competencia	string(6)	Formato AAAAMM
cnpjEmpregador	string(14)	CNPJ da empresa empregadora

A resposta inclui os campos margemDisponivel, margemUtilizada e contratoAtivo como booleano. A atualização do saldo devedor na Plataforma do Crédito do Trabalhador é requisito essencial para que empregadores identifiquem corretamente as obrigações remanescentes de contratos ativos e apliquem descontos na rescisão.

Fluxo completo de averbação automática

Agora que a autenticação, a estrutura de lote e a consulta de margem estão claras, o próximo passo é entender como essas etapas se conectam no fluxo completo de averbação. O processamento eSocial é assíncrono e utiliza dois webservices distintos, um para envio de lotes, EnviarLoteEventos, e outro para consulta do resultado do processamento. Essa característica define a ordem das chamadas e a forma de tratar o retorno.

A sequência completa de chamadas para averbação é:

Autenticação: geração do JWT assinado com certificado A1 e obtenção do token Bearer.
Consulta de margem: chamada ao webservice Dataprev com CPF e competência, validação do limite de 35%.
Montagem do lote: construção do XML com evento S-1200 ou S-2299 ou S-2399, rubrica 9253 e assinatura individual por evento.
Envio do lote: POST ao endpoint EnviarLoteEventos, recebimento do Protocolo de Envio.
Aguardo de processamento: inclusão em fila assíncrona, validação nível 1 de estrutura e certificado e validação nível 2 de regras de negócio por evento.
Consulta de resultado: GET ao endpoint ConsultarLoteEventos com o protocolo recebido.
Averbação confirmada: status de sucesso com retorno do número de averbação vinculado ao contrato.

O ambiente eSocial possui horários de operação definidos. Fora desse intervalo ou durante suspensões, o sistema retorna o código OZ. Empregadores devem realizar a consulta no Portal Emprega Brasil entre os dias 21 e 25 de cada mês, quando a Dataprev disponibiliza o CSV de contratos ativos por CPF.

Monitoramento de status e repasses

Após a averbação, o acompanhamento contínuo garante que eventos de folha, rescisões e repasses financeiros permaneçam alinhados. Esse monitoramento ocorre por webhooks configurados no endpoint de notificação da plataforma e por consultas periódicas ao webservice de status.

A tabela a seguir resume os principais códigos de erro, suas origens e as ações recomendadas:

Código	Origem	Descrição	Ação recomendada
148–153	eSocial	Falha de certificado, como cadeia, revogação, expiração ou tipo	Renovar ou corrigir o certificado utilizado
4	eSocial	Rejeição por certificado inválido no evento	Verificar a assinatura XML individual
OZ	eSocial	Sistema fora da janela operacional, 22h a 06h	Reagendar o envio para a janela permitida
MARGEM_INSUFICIENTE	Dataprev	Margem disponível inferior à parcela solicitada	Recalcular a parcela ou aguardar a próxima competência

Em caso de inadimplência de parcelas retidas a partir de fevereiro de 2026, o empregador arca com o valor principal acrescido de encargos. Tanto os repasses regulares quanto os valores de inadimplência devem ser processados exclusivamente pelo FGTS Digital, que centraliza toda a movimentação financeira do programa.

Sandbox e casos de teste

Testar o fluxo completo em ambiente controlado reduz falhas em produção e acelera homologações com parceiros. A Celcoin disponibiliza ambiente de sandbox com cobertura dos principais cenários de integração para consignado privado.

Os casos de teste recomendados cobrem situações de sucesso, rejeições técnicas e regras de negócio críticas:

Sucesso com margem disponível: CPF com 35% de margem livre, lote enviado com rubrica 9253 e averbação confirmada com número de protocolo.
Rejeição por margem insuficiente: CPF com margem zerada, resposta Dataprev com margemDisponivel: 0 e interrupção do fluxo antes do envio do lote.
Rejeição por certificado inválido: evento assinado com certificado expirado, retorno de código 149 e rejeição do lote na validação nível 1.
Desligamento com desconto na rescisão: evento S-2299 com rubrica 9253, validação da Portaria MTE nº 1.115/2026 e confirmação de desconto na competência do desligamento.
Janela fora do horário: envio após 22h, retorno de código OZ e retry automático às 06h.

O sandbox da Celcoin replica os esquemas XSD da versão S-1.3, NT 06/2026, e os contratos de resposta da Dataprev. Essa abordagem permite validação completa do fluxo antes da entrada em produção.

Infraestrutura da Celcoin para consignado privado

A Celcoin oferece um conjunto de funcionalidades que reduz o custo e o tempo de integração para empresas que desejam operar consignado privado. A tabela a seguir relaciona cada funcionalidade ao benefício direto para o seu negócio.

Funcionalidade da Celcoin	Benefício para sua empresa
APIs modulares	Integrações mais rápidas, com redução de custos e prazos de desenvolvimento.
Experiência e suporte ao desenvolvedor	Documentação, SDKs e sandboxes que reduzem ciclos de integração e custos de engenharia.
Capacidade de lançamento rápido	Módulos pré-construídos e entrega via SaaS aceleram lançamentos e reduzem o tempo para geração de receita.
Distribuição white-label e embutida, embedded	Suporte a produtos financeiros com marca própria.
Escalabilidade com confiabilidade	Solução com alta disponibilidade e escalável na nuvem, que mantém serviços funcionando mesmo com altos volumes.
Cobertura de diversas possibilidades de pagamentos, incluindo crédito	Oferta combinada de pagamentos e emissão de crédito, com aumento de conversão, ARPU e fidelização.
Acesso a dados e personalização	Dados e análises via Open Finance permitem ofertas personalizadas, com melhora de conversão e retenção.
Compliance e conformidade como princípio	KYC, AML e relatórios integrados reduzem risco regulatório e encurtam ciclos de vendas.
Prevenção de fraude e controles de risco	Monitoramento baseado em IA e autenticação robusta reduzem estornos, perdas e exposição regulatória.
Força do ecossistema de parceiros da Celcoin	Parcerias e integrações com bancos, redes e fintechs ampliam cobertura, recursos e velocidade de entrada no mercado.

Explore como a Celcoin acelera sua integração de consignado privado.

Perguntas frequentes (FAQ)

O que é a rubrica 9253 e por que ela é obrigatória no eSocial para consignado privado?

A rubrica 9253 identifica descontos de consignado privado no eSocial. A ausência ou uso incorreto dessa rubrica impede a averbação correta do contrato na folha de pagamento e expõe o empregador a penalidades regulatórias, porque o sistema não reconhece o desconto sem essa marcação específica.

Qual é o limite de margem consignável para trabalhadores CLT no consignado privado?

O limite de 35% é calculado sobre a remuneração líquida disponível do trabalhador, considerando o total agregado de todos os contratos ativos com diferentes instituições financeiras. Esse cálculo ocorre de forma centralizada na Dataprev. Contratos que ultrapassem esse limite são rejeitados pelo webservice de consulta de margem.

Como funciona a integração de API para consignado privado em termos de conformidade regulatória?

A integração deve seguir a Lei nº 10.820/2003, alterada pela Medida Provisória nº 1.292/2025, e a Portaria MTE nº 435/2025, que regulamentam o Crédito do Trabalhador. Fintechs e correspondentes bancários sem licença própria podem operar por meio de estruturas de correspondente bancário reguladas pela Resolução CMN nº 4.935/2021 ou por arranjos BaaS sob a Resolução Conjunta CMN/BCB nº 16/2025, com responsabilidade regulatória integral da instituição financeira licenciada. Toda entidade que processa dados pessoais na integração deve observar a LGPD. A emissão do CET, custo efetivo total, ao tomador é obrigatória antes da formalização do contrato.

Quais são os principais erros de integração com o eSocial e como tratá-los?

Os erros mais comuns envolvem falhas de certificado digital, que causam rejeição do lote inteiro ou do evento individual e exigem renovação ou correção do certificado utilizado. O código OZ indica que o envio ocorreu fora da janela operacional do eSocial, das 06h às 22h, e requer reagendamento. Erros de margem insuficiente retornam da Dataprev antes do envio do lote e exigem recálculo da parcela. A validação ocorre em dois níveis, com verificação de estrutura e certificado na recepção do lote e validação de cada evento individualmente após o enfileiramento.

Como a Celcoin apoia empresas na integração de API para consignado privado?

A Celcoin fornece infraestrutura tecnológica modular que cobre toda a jornada de crédito consignado privado para empresas: autenticação com certificado A1, montagem e envio de lotes eSocial, consulta de margem via Dataprev, averbação automática, monitoramento via webhooks e ambiente de sandbox para testes. A solução de crédito da Celcoin é compatível com os leiautes S-1.3, NT 06/2026, e opera com conformidade regulatória contínua, permitindo que fintechs, ERPs, correspondentes bancários e originadores reduzam o tempo de integração e o risco de não conformidade sem precisar construir essa infraestrutura internamente.

Conclusão

A integração de APIs para contratos de empréstimo consignado privado exige domínio simultâneo de autenticação JWT com certificado A1 ICP-Brasil, estrutura de lotes eSocial com rubrica 9253 na versão S-1.3, NT 06/2026, consulta de margem em tempo real via webservice Dataprev e fluxo assíncrono de averbação com tratamento estruturado de erros. Integrações fragmentadas ou baseadas em documentação desatualizada aumentam o risco regulatório e atrasam o time-to-market antes do próximo ciclo de folha.

A solução de crédito da Celcoin entrega esses fluxos em produção, com documentação técnica, sandbox e suporte ao desenvolvedor, permitindo que empresas operem consignado privado com conformidade regulatória e escala. Comece sua integração com a solução de crédito da Celcoin.

The best service for growth Infratech financeira para potencializar negócios

Oferecemos uma infraestrutura completa e pioneira para conectar empresas de todos os segmentos a oportunidades do mercado financeiro, com soluções incorporadas às necessidades de seus clientes.

Contratar