Como funciona a API para lotes de contratos consignados?

Última atualização: 12 de agosto de 2026

Principais lições deste artigo

• A API eSocial para recepção de lotes de contratos consignados utiliza autenticação JWT e aceita dados em formato JSON.

• Campos obrigatórios como nrInscricaoEmpregador e Id único garantem conformidade e idempotência.

• Validações prévias de vínculo empregatício S-2200 e respeito aos limites de lote reduzem rejeições antes do envio.

• Erros de negócio exigem correção do payload, enquanto erros temporários permitem retry controlado.

• A Celcoin oferece APIs modulares, sandbox e suporte técnico para acelerar a integração em produção.

Empresas que oferecem crédito consignado precisam registrar contratos no eSocial para garantir conformidade regulatória e viabilizar descontos em folha. A API de recepção de lotes de contratos consignados automatiza esse processo e exige atenção a autenticação, estrutura do lote, validações de vínculo e tratamento de erros.

O que é um lote e fluxo geral?

Um lote é um conjunto de eventos enviados em uma única requisição ao webservice do eSocial. Cada lote agrupa eventos de mesmo tipo e de um único empregador, respeitando limites de quantidade definidos por ambiente.

O fluxo de integração envolve autenticação, estruturação do payload, validação de pré-requisitos, envio, consulta de status e tratamento de erros. As seções seguintes detalham cada um desses pontos para apoiar a construção de uma integração estável.

Autenticação na API para eSocial

A autenticação da API de recepção de lotes de contratos consignados utiliza o padrão JWT. Esse padrão define como gerar e validar tokens que identificam a aplicação e o usuário responsável pelo envio.

O transporte utiliza HTTPS. O eSocial valida a cadeia de confiança do certificado, o período de validade e as listas de certificados revogados. Certificados revogados ou expirados geram rejeição na camada de transporte.

A assinatura digital dos eventos deve usar XML Digital Signature com algoritmo SHA-256. O certificado incluído na assinatura deve ser o do usuário final, e não de uma autoridade certificadora intermediária.

Dica de sandbox: no ambiente de Produção Restrita, use um certificado de homologação ICP-Brasil válido. Certificados autoassinados são rejeitados mesmo em ambiente de teste. Validar a cadeia de confiança antes de qualquer envio reduz falhas iniciais de integração.

Com a autenticação estabelecida, o próximo passo é estruturar o payload do lote. A organização correta dos campos obrigatórios e a geração de identificadores únicos influenciam diretamente a aceitação do lote antes mesmo da validação das regras de negócio.

Estrutura JSON do lote de contratos consignados

O eSocial opera nativamente com XML, mas muitas integrações montam os dados em JSON e depois convertem para o envelope XML. Os campos obrigatórios do lote incluem o identificador do empregador, o identificador do transmissor e os dados do evento de consignado.

O exemplo abaixo mostra a estrutura de um lote com um único contrato consignado. Esse exemplo destaca o uso de Id único para idempotência e o par CPF mais matrícula para validação de vínculo.

{ "envioLoteEventos": { "ideEmpregador": { "tpInsc": "1", "nrInscricaoEmpregador": "12345678000195" }, "ideTransmissor": { "tpInsc": "1", "nrInsc": "98765432000100" }, "eventos": { "evento": [ { "Id": "ID1234567890123456789012345678901234", "evtConsig": { "ideEvento": { "indRetif": "1", "nrRec": "", "tpAmb": "2", "procEmi": "1", "verProc": "1.0.0" }, "ideEmpregador": { "tpInsc": "1", "nrInscricaoEmpregador": "12345678000195" }, "ideTrabalhador": { "cpfTrab": "12345678901", "matricula": "MAT001" }, "infoConsig": { "nrContrato": "CONT2026001", "tpConsig": "1", "vlrEmprestimo": 5000.00, "vlrParcela": 250.00, "qtdParcelas": 20, "dtIniDesc": "2026-09-01" } } } ] } } }

O campo nrInscricaoEmpregador deve estar consistente com as informações do empregador no eSocial. O atributo Id de cada evento deve ser único e seguir o padrão definido no leiaute do eSocial para garantir idempotência e rastreabilidade.

Limites de lote em Produção Restrita e Produção

Os ambientes de Produção Restrita e Produção aplicam limites diferentes de quantidade de eventos por lote. Em Produção Restrita, o limite por lote é menor e favorece testes controlados. Em Produção, o limite é maior, mas lotes muito grandes podem gerar timeouts ou filas de processamento prolongadas.

As regras gerais aplicáveis a ambos os ambientes garantem consistência e rastreabilidade:

• Cada lote deve conter eventos de um único empregador, pois o eSocial processa lotes por CNPJ.

• Eventos de tipos distintos não podem ser misturados no mesmo lote quando o serviço não aceita tipos múltiplos, o que evita rejeições parciais difíceis de controlar.

• O intervalo mínimo entre envios consecutivos deve ser respeitado para evitar bloqueio por rate limiting, que pode suspender temporariamente o acesso da aplicação.

• O identificador de lote idLote deve ser único por transmissor para permitir rastreamento e evitar duplicidade em caso de falha de rede.

Dica de controle de idempotência: armazene o idLote e o Id de cada evento em banco de dados antes do envio. Em caso de falha de rede, consulte o status antes de reenviar para evitar duplicidade. O eSocial retorna a mensagem 0106 quando um evento com a mesma chave de identificação já existe na base.

Respeitar os limites de lote reduz rejeições por volume, mas não garante a aceitação dos contratos. A próxima etapa é validar se o vínculo empregatício está corretamente registrado no RET.

Validação de vínculo S-2200 antes do envio

O envio de um lote de contratos consignados depende de um vínculo empregatício ativo no Repositório de Eventos Trabalhistas. O par CPF mais matrícula precisa existir no RET antes da aceitação de eventos dependentes.

Os pré-requisitos de validação seguem uma hierarquia, em que primeiro o empregador deve existir, depois o trabalhador e, por fim, o vínculo entre eles:

• S-1000 ativo: deve existir um registro válido de informações do empregador na data de referência do evento, pois o eSocial precisa reconhecer a origem do lote.

• S-2200 processado: o evento de admissão deve ter sido aceito e o vínculo deve estar ativo na data de referência, estabelecendo a relação empregador e trabalhador.

• Matrícula única: a matrícula deve ser única para o empregador no RET, o que garante identificação inequívoca do trabalhador.

• CPF no RET: o CPF do trabalhador deve estar registrado para o empregador antes de eventos dependentes, permitindo vincular o contrato ao trabalhador correto.

• Validação CNIS: quando o NIS é informado, o eSocial cruza CPF, NIT e data de nascimento com a base do CNIS para confirmar a identidade.

Consulta de status e tratamento de erros da API

Após o envio, o lote entra em fila de processamento assíncrono. A aplicação deve consultar o status pelo endpoint de consulta de lotes, informando o nrRec retornado no envio.

Os principais códigos de retorno do sistema Crédito do Trabalhador DATAPREV incluem:

• Erro de margem consignável: margem consignável excedida.

• Empréstimo já cadastrado.

• Vínculo inelegível para empréstimo pelo trabalhador.

• OZ: operação suspensa.

• GE: campos com valores inválidos.

• MS0019: possível falha temporária no processamento.

• MS0017: assinatura do evento inválida.

• MS0101: tipo de evento não aceito para esse lote ou serviço.

Erros de negócio exigem correção do contrato antes do reenvio. Erros temporários permitem retry após intervalo definido pela política da aplicação. Erros de assinatura exigem revisão do payload e da configuração de certificados.

Manter um controle estruturado por lote ajuda a aplicar a estratégia correta de retry e correção.

Tabela de controle de lotes para retry

Registrar o ciclo de vida de cada lote permite rastrear status, controlar tentativas de retry e identificar padrões de erro. O modelo abaixo mostra como diferentes tipos de erro pedem ações distintas, como correção de dados, novo envio ou simples reconsulta.

idLote	Status	dataEnvio	Tentativas	próximoPasso
LOTE-2026-001	Processado	2026-08-10 09:00	1	Nenhum
LOTE-2026-002	Erro temporário	2026-08-10 09:15	2	Retry após 15 min
LOTE-2026-003	Erro de negócio (margem consignável)	2026-08-10 09:30	1	Revisar margem consignável
LOTE-2026-004	Erro de assinatura	2026-08-10 09:45	1	Corrigir e reenviar
LOTE-2026-005	Aguardando consulta	2026-08-10 10:00	1	Consultar status em 5 min

Diferenças entre ambiente de teste e produção 2026

Os ambientes de Produção Restrita e Produção apresentam diferenças que impactam diretamente a estratégia de testes e o plano de go-live.

• Produção Restrita: aceita certificados de homologação ICP-Brasil, aplica limites de lote reduzidos, não gera efeitos jurídicos e é adequada para validar fluxos completos antes do início da operação.

• Produção: exige certificado ICP-Brasil válido e vigente, aplica limites de lote maiores e processa todos os eventos com validade legal no RET definitivo.

• Endpoints distintos: as URLs de webservice são diferentes em cada ambiente, por isso a configuração de endpoints deve separar claramente teste e produção.

• Comportamento de erros: em Produção Restrita, alguns erros de integração com sistemas externos como CNIS e CAEPF podem ter comportamento diferente do ambiente produtivo, o que exige validação final em Produção com volume controlado.

Dica de logs de auditoria: registre em log estruturado o idLote, o timestamp de envio, o código de retorno e o payload sem dados sensíveis para cada requisição. Esse registro facilita auditorias regulatórias e a rastreabilidade de contratos consignados em caso de contestação.

Como a Celcoin simplifica a integração com a API para eSocial

A complexidade da integração com o eSocial, que envolve certificados mTLS, validações de vínculo, controle de lotes e tratamento de erros, representa uma barreira relevante para fintechs, ERPs e correspondentes bancários. A solução de crédito da Celcoin fornece uma infraestrutura modular que abstrai essa complexidade e permite que empresas concentrem esforços no produto e na experiência do cliente.

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 esforço de engenharia.
Capacidade de lançamento rápido	Módulos pré-construídos e entrega via SaaS aceleram lançamentos e antecipam geração de receita.
Distribuição white-label e embutida (embedded)	Suporte a produtos financeiros com marca própria, mantendo a experiência dentro do seu canal.
Escalabilidade com confiabilidade	Infraestrutura com alta disponibilidade em nuvem mantém serviços estáveis mesmo com altos volumes.
Cobertura de diversas possibilidades de pagamentos, incluindo crédito	Oferta integrada de pagamentos e crédito aumenta conversão, ARPU e fidelização.
Acesso a dados e personalização	Dados e análises via Open Finance permitem ofertas personalizadas e maior retenção.
Compliance e conformidade como princípio	KYC, AML e relatórios integrados reduzem risco regulatório e simplificam auditorias.
Prevenção de fraude e controles de risco	Monitoramento baseado em IA e autenticação robusta reduzem estornos e perdas.
Força do ecossistema de parceiros da Celcoin	Parcerias com bancos, redes e fintechs ampliam cobertura e velocidade de entrada no mercado.

A Celcoin não oferece nenhum tipo de empréstimo para consumidores. A Celcoin fornece a infraestrutura tecnológica para que empresas consigam ofertar produtos de crédito aos seus clientes. Conheça como a infraestrutura da Celcoin pode acelerar sua integração com o eSocial e reduzir custos de desenvolvimento.

Perguntas frequentes

O eSocial realmente usa autenticação JWT para receber lotes de contratos consignados?

Sim. A API eSocial para recepção de lotes de contratos de empréstimos consignados utiliza o padrão JWT JSON Web Token, com dados enviados no formato JSON. A especificação oficial da API detalha o formato do token, os campos obrigatórios e os fluxos de autenticação.

Qual é o pré-requisito obrigatório antes de enviar um lote de contratos consignados?

O vínculo empregatício do trabalhador deve estar registrado no RET, o Repositório de Eventos Trabalhistas. As informações do empregador S-1000 e do trabalhador S-2200 precisam ter sido processadas com sucesso antes do envio do lote de consignado. O par CPF mais matrícula deve existir no RET na data de referência do evento.

Como diferenciar erros que exigem retry de erros que exigem correção do contrato?

Erros temporários indicam problemas de infraestrutura e permitem retry após um intervalo configurado. Erros de negócio indicam inconsistências nos dados do contrato, como margem consignável, cadastro de empréstimo ou elegibilidade de vínculo, e exigem correção antes de qualquer reenvio. Erros de assinatura exigem revisão do payload e da configuração de certificados. Manter uma tabela de controle com o tipo de erro por lote é a prática recomendada.

Quais são as diferenças práticas entre Produção Restrita e Produção para testes de integração?

Em Produção Restrita, os limites de quantidade de eventos por lote são menores, os dados não têm validade jurídica e é possível usar certificados de homologação ICP-Brasil. Esse ambiente é indicado para validar o fluxo completo de integração sem risco para registros reais. Em Produção, todos os eventos têm efeito legal, os limites de lote são maiores e o certificado deve ser válido e vigente. Os endpoints de webservice são distintos entre os dois ambientes e não devem ser confundidos durante o desenvolvimento.

Como a Celcoin ajuda empresas a integrar crédito consignado via eSocial?

A Celcoin fornece APIs modulares, ambiente de sandbox, documentação técnica e suporte ao desenvolvedor para que fintechs, ERPs e correspondentes bancários integrem crédito consignado público e privado com agilidade. A infraestrutura da Celcoin cobre toda a jornada de crédito, da originação à cobrança, incluindo a integração com convênios públicos e privados. Empresas que utilizam a solução de crédito da Celcoin reduzem o tempo de desenvolvimento e os custos de engenharia, sem precisar construir e manter internamente uma infraestrutura de integração com sistemas governamentais.