Guia: documentação para API de empréstimo consignado privado

Principais lições deste artigo

1. A documentação governamental para empréstimo consignado privado está fragmentada em PDFs distribuídos entre MTE, Dataprev e eSocial, o que dificulta a automação sem uma solução full stack.
2. A autenticação exige certificado digital A1, configuração JWT/OAuth e registro DET no Banco Central, e erros como 401 e 403 costumam ser evitados com validação prévia de credenciais e permissões.
3. Os endpoints principais incluem POST /lotes/recebimento e eventos S-2299 para descontos, com regras de 2026 que limitam a margem a 35% do salário mais 10% adicional de FGTS e definem carência obrigatória de 60 dias.
4. A integração com Celcoin simplifica o processo com SDKs, sandbox e APIs modulares, o que permite lançamento rápido e escalabilidade de operações até R$ 30 bilhões por mês sem lidar diretamente com toda a complexidade governamental.
5. A Celcoin oferece infraestrutura completa white label com compliance, prevenção a fraude e ecossistema de parceiros, e você pode acessar o sandbox gratuito.

Finalidade e integração com eSocial para consignado privado

O empréstimo consignado privado opera por meio de especificações governamentais definidas pelo MTE e pelo Dataprev e eSocial. Essas especificações determinam o uso do evento S-1200 para folha de pagamento e do evento S-2299 para descontos consignados.

As regras de 2026 estabelecem limite de comprometimento de até 35% do salário na contratação, mais 10% adicional para FGTS pela rubrica 9253, com carência obrigatória de 60 dias para início do desconto das parcelas.

A diferenciação entre empréstimo consignado privado para trabalhadores CLT e consignado público para beneficiários do INSS está na autonomia dos convênios empresariais e na definição da margem consignável. Para trabalhadores CLT, a liberação considera o perfil financeiro do CPF e a situação da empresa empregadora. Essa combinação permite taxas a partir de 1,99% ao mês com desconto direto em folha.

A tabela abaixo apresenta as principais rubricas usadas no consignado privado, com seus limites regulatórios para 2026 e a relação com os eventos do eSocial.

O fluxo de alto nível segue esta sequência: originação via API, validação de margem, formalização da CCB, envio ao eSocial e desconto automático em folha.

Autenticação e certificados na API consignado

A autenticação para APIs de consignado privado segue padrões governamentais rigorosos que garantem a segurança das transações. Esse processo cria a identidade digital da instituição e habilita o acesso aos sistemas oficiais.

O processo envolve três etapas obrigatórias que se complementam:

1. Gerar certificado digital A1, obtido junto a uma autoridade certificadora credenciada, para identificar a instituição perante os sistemas governamentais.
2. Configurar autenticação JWT/OAuth com a RSFN (Rede do Sistema Financeiro Nacional), o que estabelece o canal seguro de comunicação para as chamadas de API.
3. Registrar as chaves DET (Declaração de Empréstimos e Financiamentos) no Banco Central, o que autoriza a instituição a operar consignado privado.

Após concluir essas etapas, a instituição pode realizar chamadas autenticadas. Veja um exemplo de autenticação com curl:

curl -X POST https://api.gov.br/auth/token \ -H “Content-Type: application/json” \ -d ‘{ “certificate”: “base64_cert_a1”, “private_key”: “base64_private_key”, “scope”: “consignado_privado” }’

Alguns erros de autenticação são recorrentes. A tabela a seguir resume os códigos mais comuns e as ações recomendadas.

Endpoints principais da API para contratos e lotes

Com a autenticação configurada corretamente, a instituição pode acessar os endpoints governamentais para processar contratos de consignado privado. A integração exige uma sequência específica de chamadas para manter a conformidade regulatória e garantir o processamento correto dos lotes.

Os passos principais de integração são:

1. POST /lotes/recebimento, para enviar o lote de contratos consignados que será processado pelos sistemas governamentais.
2. GET /consultas/lotes, para consultar o status de processamento de cada lote enviado e tratar retornos de erro ou pendências.
3. POST /contratos/consignado, para formalizar contratos individuais após a validação de margem e de dados trabalhistas.

O exemplo abaixo mostra um payload JSON típico para envio de um lote.

curl -X POST https://api.empregabrasil.gov.br/lotes/recebimento \ -H “Authorization: Bearer jwt_token” \ -H “Content-Type: application/json” \ -d ‘{ “lote_id”: “LOTE_2026_001”, “contratos”: [ { “cpf_trabalhador”: “12345678901”, “cnpj_empregador”: “12345678000199”, “valor_emprestimo”: 5000.00, “margem_consignavel”: 0.35, “prazo_meses”: 24, “taxa_juros”: 0.0199 } ] }’

Esse payload inicia o fluxo completo de processamento, que segue esta ordem: originação de dados, validação de margem, geração da CCB, envio ao eSocial com evento S-2299, confirmação DET e desconto automático em folha. Cada etapa depende da anterior, e falhas em qualquer ponto interrompem o processo até correção.

Elimine a complexidade de múltiplas integrações governamentais com a infraestrutura completa da Celcoin.

Regras de negócio e validações para empréstimo consignado privado

As atualizações de 2026 introduzem importação automática de dados trabalhistas e consultas ao programa “crédito do trabalhador” por meio de webhooks DET. Essas mudanças operacionais vêm acompanhadas de novos requisitos regulatórios.

A Resolução BCB nº 494 de setembro de 2025 passou a exigir autorização prévia para instituições de pagamento operarem nessa modalidade, com prazo para solicitação que se encerra em maio de 2026, o que torna a adequação urgente.

As regras de margem e de transparência definem o que cada operação precisa validar. As margens máximas de 35% do salário base mais 10% adicional de FGTS, detalhadas na seção anterior, devem ser verificadas em cada proposta. A exigência de transparência reforçada inclui divulgação clara do custo total do crédito e impede aumentos unilaterais de limites.

A tabela a seguir resume validações comuns, as regras de 2026 associadas e os erros recorrentes em integrações.

Integração prática com APIs Celcoin para consignado privado

As regras e validações descritas exigem integração com vários sistemas governamentais, o que aumenta a complexidade técnica e o risco de erros. A solução de crédito da Celcoin reduz essa complexidade ao concentrar essas integrações em uma única API e em um fluxo padronizado.

Um passo a passo típico de implementação com a solução de crédito da Celcoin inclui:

1. Registrar-se no sandbox da Celcoin, para configurar o ambiente de testes e validar o fluxo de ponta a ponta sem impacto em produção.
2. Emitir CCBs pelas APIs da Celcoin, utilizando os endpoints de crédito consignado privado para formalizar contratos.
3. Integrar com eSocial e DET por meio da infraestrutura da Celcoin, que já encapsula as chamadas governamentais necessárias.
4. Gerenciar a carteira completa pelo painel unificado, com visão de contratos, liquidações, inadimplência e conciliações.

Veja um exemplo em Node.js para integração com a solução de crédito da Celcoin:

const celcoin = require(‘@celcoin/sdk’); const client = new celcoin.CreditClient({ apiKey: ‘seu_api_key’, environment: ‘sandbox’ }); const contratoConsignado = await client.consignado.create({ cpf: ‘12345678901’, cnpj_empregador: ‘12345678000199’, valor: 5000.00, prazo: 24, modalidade: ‘consignado_privado’ }); console.log(‘Contrato criado:’, contratoConsignado.id);

A solução de crédito da Celcoin mantém neutralidade em relação a SCDs e IPs, oferece parcerias com múltiplos convênios e reduz a dependência de soluções governamentais fragmentadas e de ERPs legados como TOTVS. Essa abordagem permite lançamento mais rápido, operação em modelo white label e capacidade de escalar até R$ 30 bilhões mensais, como demonstram os cases de Neon e outras fintechs parceiras.

Critérios de sucesso

Uma integração bem-sucedida atinge implementação completa em menos de uma semana, sem erros de compliance regulatório e com 100% de automação no processamento de lotes. Com a infraestrutura da Celcoin, empresas conseguem atingir a escala mencionada anteriormente, seguindo o exemplo de cases como Zé Pagou e Neon.

Próximos passos

O próximo estágio de maturidade inclui integrações avançadas com APIs Dataprev para uso de scores alternativos e com Open Finance para personalização de ofertas de crédito. Comece a testar no sandbox da Celcoin hoje mesmo e acelere seu lançamento.

Perguntas frequentes

Quais são as novas regras do consignado privado em 2026?

As principais mudanças incluem margem consignável de até 35% do salário base, mais 10% adicional para FGTS por meio da rubrica 9253, carência obrigatória de 60 dias para início dos descontos e maior transparência nos custos totais do crédito. A Resolução BCB nº 494 também passou a exigir autorização prévia para instituições de pagamento operarem nessa modalidade.

Quais são os endpoints essenciais da API eSocial para consignado?

Os endpoints principais são POST /lotes/recebimento para envio de contratos em lote, GET /consultas/lotes para verificação de status de processamento e POST /contratos/consignado para formalização individual. Os eventos relevantes do eSocial são S-1200 para folha de pagamento e S-2299 para descontos consignados, integrados por meio de webhooks DET.

Como integrar com as APIs da Celcoin para consignado privado?

A integração envolve registro no sandbox, configuração de autenticação por API key, uso das APIs da Celcoin para emissão de CCBs em crédito consignado privado e integração com eSocial pela infraestrutura full stack. A Celcoin disponibiliza documentação completa, SDKs e suporte especializado para desenvolvedores.

Quais são os erros mais comuns nas APIs de lotes consignados?

Os erros frequentes incluem código 401 por certificados A1 inválidos, código 403 por ausência de permissões DET no Banco Central, código 422 por certificados digitais expirados e divergências com dados Dataprev por folhas de pagamento desatualizadas. A solução envolve validação prévia de certificados e sincronização regular com as bases governamentais.

A Celcoin mantém neutralidade em relação a gestoras de fundos?

A Celcoin mantém princípio de neutralidade total e não favorece gestoras específicas nem compete com parceiros. A plataforma conecta originadores e investidores de forma imparcial, oferece condições de mercado equilibradas para todas as partes e incentiva concorrência saudável no ecossistema de crédito privado.