Como integrar API de margem consignável para servidor

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

Principais lições deste artigo

• A partir de 2027, o governo federal reduziu gradualmente a margem consignável de servidores públicos federais de 45% para 40%, com prazo máximo ampliado para 120 meses conforme a MP 1.355/2026.

• Cada órgão público, federal, estadual ou municipal, expõe endpoints distintos, com credenciamento, OAuth2 e fluxos de consentimento específicos.

• Aplicar o adapter pattern permite consultar e averbar margem em qualquer ente público com um único ponto de integração, sem manter 15 ou mais adaptadores fragmentados.

• Atender à LGPD exige registrar consentimento por finalidade de forma imutável, com suporte a revogação propagada a todos os sistemas dependentes.

• Transforme seu negócio com a infraestrutura de crédito completa da Celcoin.

Passo 1 – O desafio das integrações fragmentadas

Fintechs, correspondentes bancários e ERPs que operam crédito consignado público lidam com um problema estrutural. Cada órgão pagador, como SIAPE para o governo federal, Dataprev para o INSS, Prodesp para São Paulo e sistemas estaduais e municipais próprios, utiliza endpoints, esquemas de autenticação e regras de averbação diferentes. Manter integrações individuais para cada ente consome tempo de engenharia, aumenta custos operacionais e cria pontos de falha difíceis de monitorar.

Adotar o adapter pattern resolve esse cenário. Uma camada de abstração neutra traduz chamadas padronizadas da aplicação cliente para os protocolos específicos de cada órgão e devolve respostas normalizadas. A Celcoin atua como essa camada, conectando originadores a convênios públicos sem que a empresa precise construir ou manter cada integração individualmente.

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.

Passo 2 – Credenciamento por órgão federal, estadual e municipal

Iniciar a operação exige credenciar a instituição em cada ente público relevante.

• Federal (SIAPE/SouGov): a instituição financeira deve ser habilitada como consignatária junto ao Ministério da Gestão e Inovação (MGI). O acesso ao sistema ocorre por canais seguros, com trilha de auditoria.

• Estadual: cada estado mantém um sistema próprio de gestão de pessoal. Estados como Goiás e Paraná já ajustaram sua legislação para convergir com o padrão federal. Outros, como Minas Gerais, ainda tramitam projetos de lei para alinhamento.

• Municipal: municípios de maior porte operam sistemas próprios ou contratam plataformas de folha terceirizadas, cada uma com API e processo de credenciamento específicos.

Em todos os casos, o credenciamento exige documentação jurídica da instituição, certificados digitais válidos e, no âmbito federal, conformidade com as regras operacionais do MGI. Após concluir essa etapa, o próximo passo é obter tokens de acesso via OAuth2 para autenticar cada requisição.

Passo 3 – Fluxo OAuth2 e obtenção de token

A maioria dos sistemas de margem consignável utiliza OAuth2 com client credentials ou authorization code flow. Em sistemas federais, o fluxo básico segue estas etapas:

1. A aplicação envia client_id e client_secret ao authorization server do órgão via HTTPS, com TLS 1.2 ou superior, em linha com o perfil FAPI para APIs financeiras.

2. O servidor retorna um access_token com escopo e tempo de expiração definidos.

3. Todas as requisições seguintes incluem o token no header Authorization: Bearer {token}.

4. O resource server valida se o token não está expirado nem revogado e se o escopo autoriza o recurso solicitado.

Veja um exemplo de requisição de token em Node.js:

const axios = require('axios'); async function getToken(clientId, clientSecret, tokenUrl) { const params = new URLSearchParams(); params.append('grant_type', 'client_credentials'); params.append('client_id', clientId); params.append('client_secret', clientSecret); params.append('scope', 'margem:consulta margem:averbacao'); const response = await axios.post(tokenUrl, params, { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }); return response.data.access_token; } 

Veja o exemplo equivalente em Python:

import requests def get_token(client_id, client_secret, token_url): payload = { 'grant_type': 'client_credentials', 'client_id': client_id, 'client_secret': client_secret, 'scope': 'margem:consulta margem:averbacao' } r = requests.post(token_url, data=payload) r.raise_for_status() return r.json()['access_token'] 

Passo 4 – Autorização de consentimento via SouGov

Para servidores públicos federais, a Portaria MGI nº 984/2026 determina que cada contrato de consignado tenha autorização expressa do servidor pela plataforma gov.br/SouGov. A autorização deve apresentar previamente as condições, a taxa de juros e o Custo Efetivo Total. Contratos de consignado federal de servidores públicos não podem ser firmados por telefone ou aplicativos de mensagens, conforme Portaria MGI nº 984/2026 (vigência 14/04/2026).

O fluxo de consentimento no adapter deve seguir estes passos:

1. Redirecionar o servidor para a interface SouGov com os parâmetros da operação.

2. Aguardar o callback com o código de autorização.

3. Registrar o evento de consentimento com identidade do titular, timestamp, versão do termo apresentado, finalidade e mecanismo de captura, em linha com a LGPD.

4. Armazenar o registro de forma imutável para auditoria.

⚠️ LGPD, caixa de conformidade: o controlador deve provar que obteve o consentimento de forma válida, conforme o Art. 8º, §2º da LGPD. O adapter precisa suportar revogação centralizada com propagação a todos os sistemas dependentes. Consentimentos agrupados em termos gerais não atendem ao requisito de especificidade. Cada finalidade de tratamento deve ter um registro próprio de consentimento.

Passo 5 – Consulta de margem com exemplos JSON

Depois de autenticar e obter o consentimento, a consulta de margem retorna a margem disponível, comprometida e os limites por rubrica. O adapter normaliza a requisição e a resposta para simplificar o consumo pela aplicação.

// Requisição GET /v1/margem/consulta?cpf=000.000.000-00&orgao=SIAPE Authorization: Bearer {access_token} // Resposta normalizada { "cpf": "000.000.000-00", "orgao": "SIAPE", "remuneracao_bruta": 10000.00, "margem_total_percentual": 40, "margem_disponivel": 2500.00, "margem_comprometida": 1500.00, "margem_cartao_disponivel": 500.00, "prazo_maximo_meses": 120, "data_consulta": "2026-08-20T10:00:00Z" } 

Consulte margem em convênios públicos com a API unificada da Celcoin.

Passo 6 – Averbação e tratamento de erros

A averbação registra o desconto futuro na folha do servidor. O adapter envia os dados do contrato ao sistema do órgão e precisa tratar os principais códigos de erro retornados. Erros da faixa 4xx indicam problemas na requisição ou na autorização. Erros da faixa 5xx indicam indisponibilidade temporária do órgão e exigem estratégias de retry.

• 400 – Margem insuficiente: a parcela solicitada excede a margem disponível, por isso o sistema deve retornar ao originador com o valor máximo permitido.

• 401 – Token expirado: o adapter deve executar refresh automático e tentar novamente a requisição.

• 403 – Consentimento ausente: o fluxo precisa redirecionar para o SouGov antes de prosseguir.

• 409 – Contrato duplicado: o sistema deve verificar idempotência pelo número de proposta antes de reenviar.

• 503 – Indisponibilidade do órgão: o adapter deve aplicar retry exponencial com backoff e acionar o time de operações.

⚙️ Rate limits e renovação de tokens: sistemas federais aplicam limites de requisições por minuto por consignatária. Implemente filas com controle de concorrência e renove tokens antes da expiração, com recomendação de renovação 60 segundos antes. O acesso à margem de servidores federais segue as regras estabelecidas pelo órgão pagador.

Passo 7 – Tabela comparativa das regras de margem federal

A tabela a seguir resume diferenças de margem, sublimites e prazos entre âmbitos federal, estadual e municipal. A tabela destaca também a trajetória de redução gradual prevista para servidores federais a partir de 2027.

Âmbito	Margem total (2026)	Sublimite cartão	Prazo máximo
Federal (SIAPE)	40% da remuneração	Conforme norma do órgão	120 meses
Estadual (referência MG)	Até 45% do líquido, com projeto de lei em tramitação	Varia por estado	Definido por lei estadual
Municipal	Varia por município	Varia por município	Varia por município
Federal, trajetória futura	Redução gradual a partir de 2027 até 30% em 2031	–	–

Passo 8 – Diagrama de arquitetura com adapter pattern

Uma arquitetura baseada em adapter pattern centraliza a integração e faz o roteamento dinâmico por órgão. A aplicação do originador conversa com uma única API, que distribui as chamadas para cada conector especializado.

[Aplicação do originador] | v [Adapter Layer, Celcoin API] _____|_____ | | | v v v SIAPE Dataprev Sistemas (Fed) (INSS) estaduais/ municipais 

O adapter recebe uma chamada padronizada, identifica o órgão pelo CPF ou pelo código de convênio, seleciona o conector correspondente, executa a autenticação e retorna a resposta normalizada. Erros específicos de cada órgão são mapeados para códigos de erro unificados antes de chegar ao originador.

Passo 9 – Código de adapter pronto em Node.js e Python

Centralizar o roteamento por órgão em um adapter reduz complexidade na aplicação do originador. O exemplo a seguir mostra uma implementação simples.

// Node.js, adapter com roteamento dinâmico const connectors = { SIAPE: require('./connectors/siape'), DATAPREV: require('./connectors/dataprev'), PRODESP: require('./connectors/prodesp'), }; async function consultarMargem({ cpf, orgao }) { const connector = connectors[orgao]; if (!connector) throw new Error(`Órgão não suportado: ${orgao}`); const token = await connector.getToken(); return connector.consultarMargem(cpf, token); } async function averbarContrato({ cpf, orgao, contrato }) { const connector = connectors[orgao]; if (!connector) throw new Error(`Órgão não suportado: ${orgao}`); const token = await connector.getToken(); return connector.averbar(cpf, contrato, token); } module.exports = { consultarMargem, averbarContrato }; 

# Python, adapter com roteamento dinâmico from connectors import siape, dataprev, prodesp CONNECTORS = { 'SIAPE': siape, 'DATAPREV': dataprev, 'PRODESP': prodesp, } def consultar_margem(cpf: str, orgao: str) -> dict: connector = CONNECTORS.get(orgao) if not connector: raise ValueError(f'Órgão não suportado: {orgao}') token = connector.get_token() return connector.consultar_margem(cpf, token) def averbar_contrato(cpf: str, orgao: str, contrato: dict) -> dict: connector = CONNECTORS.get(orgao) if not connector: raise ValueError(f'Órgão não suportado: {orgao}') token = connector.get_token() return connector.averbar(cpf, contrato, token) 

Passo 10 – Caixas de destaque sobre LGPD, tokens e rate limits

🔒 LGPD, checklist de conformidade para o adapter:

• Registrar cada evento de consentimento com identidade do titular, timestamp, versão do termo, finalidade e mecanismo de captura.

• Suportar revogação expressa com propagação imediata a todos os sistemas dependentes.

• Evitar agrupar consentimentos de finalidades distintas em um único checkbox.

• Designar e publicar os dados de contato do DPO, conforme o Art. 41 da LGPD.

• Documentar a base legal e o contexto de consentimento por finalidade e categoria de dado.

🔄 Renovação de tokens: implementar refresh automático com antecedência de 60 segundos em relação à expiração. Monitorar as regras de credenciamento do órgão e iniciar o processo de renovação com antecedência adequada.

⏱️ Rate limits: utilizar filas com controle de concorrência por órgão. Implementar retry com backoff exponencial para erros 429 e 503. Registrar métricas de latência por conector para identificar degradações antes de impactar o originador.

Passo 11 – Critérios de sucesso para operar sem 15 integrações

Uma operação de crédito consignado público escalável, baseada em adapter pattern, atinge maturidade quando cumpre alguns critérios objetivos.

• Um único endpoint de consulta e averbação atende todos os órgãos conveniados, sem lógica específica por ente na aplicação do originador.

• Novos convênios são adicionados no adapter sem alteração no código do originador.

• Todos os eventos de consentimento são registrados de forma imutável e auditável, com suporte a revogação centralizada.

• Tokens são renovados automaticamente, sem interrupção de operações em andamento.

• Erros de cada órgão são mapeados para códigos unificados, com alertas operacionais para falhas persistentes.

• As regras de margem federal com trajetória de redução gradual são validadas no adapter antes de cada averbação.

Opere crédito consignado público sem manter 15 integrações, conheça a solução da Celcoin.

Passo 12 – A Celcoin como camada de abstração neutra

Usar a Celcoin como camada de abstração neutra permite operar crédito consignado público sem construir e manter integrações fragmentadas. A plataforma conecta originadores a convênios públicos e privados e cobre toda a jornada, da consulta de margem à averbação, formalização via CCB e gestão da carteira.

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 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 mantém serviços funcionando em altos volumes e protege a receita.
Cobertura de diversas possibilidades de pagamentos, incluindo crédito	Oferecer pagamentos e emissão de 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 melhoram conversão e retenção.
Compliance e conformidade como princípio	KYC, AML e relatórios integrados reduzem risco regulatório e aceleram 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.

Passo 13 – FAQ

Como autorizar consulta de margem no portal do servidor?

Para servidores públicos federais, a autorização ocorre exclusivamente pela plataforma SouGov, acessível via gov.br. O servidor acessa o portal, localiza a proposta de crédito enviada pela instituição financeira credenciada, confere as condições de taxa, CET, prazo e valor da parcela e autoriza de forma expressa. Contratos não podem ser firmados por telefone ou aplicativos de mensagens desde a entrada em vigor da Portaria MGI nº 984, em abril de 2026. Para servidores estaduais e municipais, o canal de autorização varia conforme o sistema de gestão de pessoal do ente, e cada órgão define seu próprio portal ou mecanismo de consentimento.

Como acessar a API da Dataprev?

O acesso à API da Dataprev para consulta e averbação de margem consignável do INSS exige credenciamento prévio da instituição financeira junto à Dataprev, com assinatura de contrato de prestação de serviços e fornecimento de certificado digital ICP-Brasil. Após o credenciamento, a Dataprev disponibiliza as credenciais OAuth2, com client_id e client_secret, para o ambiente de homologação. A liberação para produção ocorre depois da aprovação dos testes. O adapter deve implementar renovação automática de tokens e tratamento dos códigos de erro específicos da Dataprev, mapeando-os para respostas normalizadas antes de retornar ao originador.

Qual é a diferença entre consulta de margem e averbação?

A consulta de margem é uma operação de leitura. Essa operação retorna a margem disponível, comprometida e os sublimites por rubrica, como empréstimo e cartão, para um servidor em um órgão específico. A averbação é uma operação de escrita. Essa operação registra o desconto futuro na folha de pagamento do servidor e vincula o contrato de crédito ao sistema de gestão de pessoal do órgão. A averbação só pode ocorrer após o consentimento expresso do servidor e dentro dos limites de margem vigentes para servidores federais.

Como garantir conformidade com a LGPD em integrações de margem consignável?

Garantir conformidade com a LGPD em integrações de margem consignável exige registrar cada evento de consentimento com identidade do titular, timestamp, versão do termo apresentado, finalidade específica e mecanismo de captura. O adapter deve suportar revogação centralizada com propagação imediata a todos os sistemas dependentes. Consentimentos agrupados em termos gerais de serviço não atendem ao requisito de especificidade. Cada finalidade de tratamento de dados, como consulta de margem, averbação e compartilhamento com gestoras, deve ter um registro próprio de consentimento.