Todo sistema que emite nota, cadastra fornecedor ou vende B2B precisa saber o regime tributário do CNPJ do outro lado. A consulta Simples Nacional responde isso: se a empresa é optante, se é MEI no SIMEI, desde quando e se houve exclusão. Parece um detalhe de cadastro. Mas esse dado muda o código de regime tributário da NF-e, a retenção na nota de serviço e até o preço que o seu e-commerce mostra para um cliente empresarial.
Neste guia você vai ver o que é ser optante pelo Simples Nacional e pelo SIMEI, onde esse dado entra no código e as armadilhas de data que fazem sistema maduro emitir nota errada, com exemplos em Python e JavaScript.
O que a consulta Simples Nacional revela sobre um CNPJ
O Simples Nacional é o regime unificado de arrecadação criado pela Lei Complementar 123/2006. Ele junta vários tributos numa guia só, o DAS (Documento de Arrecadação do Simples Nacional), e vale para microempresas (ME) e empresas de pequeno porte (EPP). O limite geral de receita bruta anual é de R$ 4,8 milhões. Existe também um sublimite de R$ 3,6 milhões para o ICMS (estadual) e o ISS (municipal). Acima dele, a empresa continua no Simples para os tributos federais, mas paga ICMS e ISS pelas regras normais, fora do DAS. No XML, é o caso do CRT 2.
A opção não é automática. A empresa pede, os fiscos analisam, e a opção pode ser negada por dívida tributária ou irregularidade cadastral. Ser pequeno não diz nada sobre o regime; só a consulta confirma.
Optante pelo Simples Nacional e SIMEI: qual a diferença
O MEI, microempreendedor individual, também é optante pelo Simples Nacional. A diferença é que ele recolhe por um sistema próprio, o SIMEI, que cobra um valor fixo por mês em vez de um percentual sobre o faturamento. O teto de receita do MEI é bem menor e está definido no art. 18-A da LC 123.
Para o seu sistema, isso gera três situações possíveis, e não duas:
- CNPJ não optante: regime normal (Lucro Presumido, Lucro Real ou Lucro Arbitrado).
- CNPJ optante pelo Simples Nacional, sem SIMEI: ME ou EPP.
- CNPJ optante pelo Simples Nacional e enquadrado no SIMEI: MEI.
Muita integração trata “optante” como booleano e esquece o SIMEI. O resultado é nota de MEI com o código de regime errado, como mostra a parte sobre o CRT.
O que o portal oficial mostra
A Receita mantém a consulta de optantes no Portal do Simples Nacional. Você digita o CNPJ, resolve o captcha e recebe a situação atual no Simples e no SIMEI, com a data de início. A tela também lista os períodos anteriores de opção e de enquadramento, com datas de início e fim, e eventos futuros, quando existirem, como uma exclusão já agendada.
Esse histórico interessa a quem programa. Uma empresa pode ter entrado em 2019, saído em 2022 e voltado em 2024; para reprocessar uma nota de 2022, a situação de hoje não serve.
Onde o dev usa a consulta Simples Nacional por CNPJ no dia a dia
A pergunta “essa empresa é do Simples?” aparece em vários pontos do software. Estes são os mais comuns.
CRT na NF-e: o campo que depende do regime
Todo XML de NF-e e NFC-e (a nota ao consumidor) traz o CRT, código de regime tributário do emitente. Ele decide qual tabela de códigos vale em cada item: o CSOSN, dos optantes, ou o CST, do regime normal. Os valores atuais são:
| CRT | Significado | Tributação do ICMS no item |
|---|---|---|
| 1 | Simples Nacional | CSOSN |
| 2 | Simples Nacional, excesso de sublimite de receita bruta | CST do regime normal |
| 3 | Regime Normal | CST do regime normal |
| 4 | Simples Nacional, Microempreendedor Individual (MEI) | CSOSN |
O código 4 entrou com a Nota Técnica 2024.001 do Portal da NF-e e virou obrigatório para o MEI em setembro de 2024. Antes disso, o MEI emitia com CRT 1. Desde abril de 2025, a SEFAZ também rejeita nota de MEI com CSOSN ou CFOP fora do permitido. Quem ainda deriva o CRT só de um campo “optante sim ou não” gera nota de MEI com código errado.
Aqui, o CRT é do emitente. Se o seu sistema emite para um cliente, a consulta valida o cadastro antes da primeira nota e detecta mudança de regime. Uma empresa excluída do Simples que segue emitindo com CRT 1 calcula o ICMS pela regra errada, e o contador corrige livros e declarações depois. O artigo sobre automação fiscal para evitar rejeições na NF-e mostra outras validações que vale a pena colocar no mesmo fluxo, e a chave de acesso da NF-e explica como o documento é identificado depois de autorizado.
Na prática: derive o CRT da situação no Simples e no SIMEI, e trate o excesso de sublimite como informação do cliente ou do contador. A consulta pública de optantes não mostra o sublimite.
Retenções na NFS-e e no contas a pagar
Na NFS-e, quem paga o serviço (tomador) às vezes retém: desconta o imposto e o recolhe no lugar de quem presta (prestador). O regime do prestador muda o que se retém. As retenções de PIS, Cofins e CSLL entre pessoas jurídicas (arts. 30 e 32, II, da Lei 10.833/2003) não se aplicam a pagamentos feitos a optantes pelo Simples Nacional. Já o ISS retido de um optante segue o art. 21, §4º, da LC 123, com a alíquota que o prestador informa no documento. Pelo inciso IV desse parágrafo, não cabe retenção de ISS de quem recolhe em valores fixos mensais, caso do MEI no SIMEI (Res. CGSN 140, art. 103, IV).
Por isso o módulo de contas a pagar precisa da consulta Simples Nacional do fornecedor antes de calcular o valor líquido. Se o fornecedor foi excluído no meio do ano e o sistema continua a tratá-lo como optante, a empresa deixa de reter o que deveria. O erro aparece na fiscalização, e a conta recai sobre o tomador.
Cadastro de fornecedor e e-commerce B2B
No cadastro de fornecedor, o regime entra junto com CNPJ, inscrição estadual e endereço. O comprador precisa saber que na nota de um optante o crédito de ICMS se limita ao valor informado nos campos de crédito do Simples (CSOSN 101, 201 ou 900), e que sem essa informação não há crédito. A consulta diz quais fornecedores caem nessa regra.
Em e-commerce B2B, a consulta Simples Nacional ajuda a montar preço e regra fiscal no checkout. Um distribuidor que vende para MEI, EPP e Lucro Real pode ter tabelas, CFOP ou mensagens de nota diferentes para cada perfil. Sem a consulta, o cliente declara o regime num formulário, e erra ou omite.
A tabela abaixo resume como cada regime costuma mexer no sistema, seja o do emitente (CRT e código de ICMS), seja o do fornecedor ou cliente (retenções e crédito). Os detalhes variam por estado, município e atividade: é um mapa, não parecer fiscal.
| Ponto do sistema | MEI (SIMEI) | ME/EPP no Simples | Regime normal |
|---|---|---|---|
| CRT da NF-e emitida | 4 | 1 (ou 2 com excesso de sublimite) | 3 |
| Código de ICMS no item | CSOSN | CSOSN (CST no CRT 2) | CST |
| Retenção de PIS, Cofins e CSLL (Lei 10.833) | Não se aplica | Não se aplica | Aplica-se quando cabível |
| ISS retido na NFS-e | Não há retenção (LC 123, art. 21, §4º, IV) | Alíquota informada pelo prestador | Alíquota do município, quando a lei prevê retenção |
| Crédito de ICMS para o comprador | Em regra, não há | Só o valor informado (CSOSN 101, 201 ou 900) | Crédito do ICMS destacado |
| Dado que a API precisa trazer | Situação no SIMEI | Situação no Simples e datas | Ausência de opção |
Se o seu sistema passa por algum desses pontos, crie uma conta e teste a API de Simples Nacional do Hub do Desenvolvedor com os CNPJs reais da sua base. Ela consulta direto na Receita, devolve JSON ou XML e vem no mesmo plano das APIs de CPF, CNPJ e CEP.
Consulta manual no portal ou API Simples Nacional
Para conferir um fornecedor de vez em quando, o portal resolve. O problema é a checagem dentro de um fluxo automático: emissão de nota, aprovação de cadastro, fechamento de contas a pagar.
Por que o portal não serve para sistema
A tela oficial usa captcha para impedir automação. Raspar a página quebra na próxima mudança de layout e arrisca bloqueio do seu IP. E o portal devolve HTML para leitura humana, sem contrato estável de campos.
Uma API resolve isso porque entrega resposta estruturada, com autenticação por token e um contrato de campos que o seu código consegue validar. Na prática, a diferença aparece em três pontos:
- Volume: o portal atende uma consulta por vez, com intervenção humana; a API atende o fluxo inteiro.
- Integração: o portal exige copiar e colar; a API entra no mesmo job que emite a nota.
- Rastreabilidade: o portal não deixa registro; com a API, você grava a resposta e a data da consulta junto do documento fiscal.
A última é subestimada. Quando o fisco perguntar por que a nota do fornecedor, em março, foi paga sem retenção de PIS, Cofins e CSLL, você mostra o registro da consulta Simples Nacional feita naquele dia.
Campos típicos da resposta
Cada API nomeia os campos do seu jeito, mas a origem é a mesma do portal. Espere encontrar:
- CNPJ consultado e razão social;
- situação no Simples Nacional (optante ou não) e data de início da opção atual;
- situação no SIMEI e data de início do enquadramento;
- períodos anteriores de opção pelo Simples e de enquadramento no SIMEI, com data inicial e final, se a API os devolver;
- eventos futuros já agendados, quando o portal os exibe.
Antes de codificar, confira no painel do Hub quais campos vêm, com nomes e formato das datas. Os exemplos usam nomes ilustrativos; troque pelos do painel.
Exemplo em Python com cache de curta duração
O código abaixo consulta a API e guarda o resultado por algumas horas. URL_DA_API e SEU_TOKEN são marcadores; use os valores do seu painel.
import re
import time
import requests
URL_DA_API = "https://URL_DA_API/simples-nacional" # confira no painel do Hub
TOKEN = "SEU_TOKEN"
VALIDADE_CACHE = 6 * 3600 # 6 horas
_cache = {}
def normalizar_cnpj(cnpj):
# mantém letras: o CNPJ pode ser alfanumérico desde julho de 2026
return re.sub(r"[^0-9A-Z]", "", cnpj.upper())
def consultar_simples(cnpj):
cnpj = normalizar_cnpj(cnpj)
item = _cache.get(cnpj)
if item and time.time() - item["quando"] < VALIDADE_CACHE:
return item["dados"]
resp = requests.get(
URL_DA_API,
params={"cnpj": cnpj, "token": TOKEN},
timeout=15,
)
resp.raise_for_status()
dados = resp.json()
_cache[cnpj] = {"quando": time.time(), "dados": dados}
return dados
Valide os dígitos verificadores antes de gastar uma chamada, lembrando que, desde julho de 2026, o CNPJ pode ter letras nas 12 primeiras posições. O post sobre como validar um CNPJ traz o algoritmo completo. Em produção, troque o dicionário em memória por Redis ou pela tabela de cadastro e, nos pontos que emitem nota, descarte resultados de outro dia mesmo dentro da validade. O artigo sobre o que é cache ajuda a escolher a estratégia de expiração.
Armadilhas de datas na consulta Simples Nacional
É aqui que nasce a maioria dos bugs. O regime tem regras de vigência que não combinam com “status atual”.
A opção das ME e EPP passou para setembro
Até 2026, a empresa já em atividade só podia optar em janeiro, e a opção deferida valia desde 1º de janeiro daquele ano. Uma empresa que pediu em 25 de janeiro de 2025 aparece como optante desde o dia 1º, e as notas emitidas nesse intervalo saíram pelo regime normal. Esse caso se acerta com o contador.
A partir da opção para 2027, as Resoluções CGSN 186 e 190, de 2026, mudaram a janela das ME e EPP: o pedido é feito de 1º a 30 de setembro, produz efeitos em 1º de janeiro do ano seguinte e pode ser cancelado até 30 de novembro. Se for indeferido por pendência, a empresa tem 30 dias para regularizar. O MEI não mudou: o enquadramento no SIMEI de empresa já existente continua sendo pedido em janeiro, até o último dia útil.
Para o sistema, a mudança se concentra na virada do ano. Uma ME que optou em setembro segue “não optante” até 31 de dezembro e vira optante em 1º de janeiro. Quem consultou em dezembro e guardou o resultado para sempre não percebe. Reconsulte com mais frequência em janeiro os CNPJs que aparecem como não optantes, inclusive quem pode entrar no SIMEI.
Exclusões podem ter efeito retroativo
A exclusão pode ser pedida pela empresa, ser obrigatória por excesso de receita ou mudança de atividade, ou partir do fisco (exclusão de ofício). Os efeitos estão no art. 31 da LC 123 e variam conforme o motivo. Em algumas hipóteses, o período termina antes da data em que a exclusão aparece na consulta.
Um CNPJ consultado como optante em maio pode, em agosto, mostrar um período encerrado em abril. Em reprocessamento ou auditoria, compare o histórico de períodos com a data de cada operação. A situação atual não responde a essa pergunta.
Atenção: nunca sobrescreva o registro antigo quando o regime mudar. Guarde cada consulta com data e hora. É o que mostra que a nota foi emitida com base na informação disponível naquele momento.
Empresa recém-aberta
Desde a Resolução CGSN 183/2025, a ME ou EPP em início de atividade pede a opção junto com a inscrição no CNPJ, pela Redesim, e a opção vale desde a data da inscrição. Se houver pendência, a opção é indeferida e a empresa tem 30 dias, contados da inscrição, para regularizar. Enquanto os fiscos conferem as inscrições, ou nesse prazo, a consulta pode mostrar “não optante” para quem vai virar optante com data retroativa. No MEI, a opção pelo SIMEI sai na própria formalização.
Para CNPJ aberto há poucas semanas, trate o resultado da consulta Simples Nacional como provisório e agende outra. A data de abertura vem na consulta de CNPJ comum, e o artigo sobre API de consulta de CNPJ mostra como obter esse dado.
Cache com validade curta e consulta na emissão
O regime não é estático como a razão social. Uma validade de algumas horas costuma equilibrar custo e segurança (o exemplo em Python usa 6). Onde se gera documento fiscal, consulte no momento da emissão ou use um resultado obtido no mesmo dia do calendário.
O exemplo em JavaScript abaixo consulta o CNPJ no momento da emissão e decide o CRT. Os nomes dos campos são ilustrativos, e excessoSublimite não vem da consulta pública: sai do cadastro do cliente.
function definirCrt(situacao, excessoSublimite = false) {
if (situacao.optanteSimei) return 4; // MEI
if (situacao.optanteSimples) {
return excessoSublimite ? 2 : 1; // ME/EPP
}
return 3; // regime normal
}
async function crtNaEmissao(cnpj, consultar, excessoSublimite = false) {
const situacao = await consultar(cnpj); // sua função de consulta
const crt = definirCrt(situacao, excessoSublimite); // vem do cadastro
return { cnpj, crt, consultadoEm: new Date().toISOString() };
}
Se a API devolver os campos como texto (“Sim”/”Não”), converta para booleano antes de chamar definirCrt: em JavaScript, qualquer string não vazia é verdadeira. A função devolve a data da consulta junto com o CRT; grave os dois com a nota.
Qual era o regime numa data passada
Para auditoria ou nota complementar, vale o regime na data da operação original. Com o histórico de períodos, a verificação fica assim:
from datetime import date
def optante_em(periodos, dia):
"""periodos: lista de dicts com 'inicio' e 'fim' (date ou None)."""
for p in periodos:
fim = p["fim"] or date.max
if p["inicio"] <= dia <= fim:
return True
return False
periodos = [
{"inicio": date(2019, 1, 1), "fim": date(2022, 12, 31)},
{"inicio": date(2024, 1, 1), "fim": None},
]
print(optante_em(periodos, date(2023, 6, 15))) # False
print(optante_em(periodos, date(2024, 3, 10))) # True
Monte a lista com o período atual e os anteriores, se a API os devolver (confira no painel); se não, guarde o histórico a partir das consultas gravadas. Converta as datas para date antes, por exemplo com datetime.strptime(valor, "%d/%m/%Y").date(), no formato da documentação. Faça o mesmo com o SIMEI.
A API de Simples Nacional do Hub entrega a situação do Simples e do SIMEI sem captcha e sem limite de IPs, o que facilita rodar a checagem dentro do job de emissão. Para ver os dados dos CNPJs da sua base, faça o teste gratuito na página da API e compare com a tela oficial.
Perguntas frequentes sobre a consulta Simples Nacional
A consulta Simples Nacional mostra se a empresa ultrapassou o sublimite?
Não. A consulta pública de optantes mostra a situação no Simples e no SIMEI, com datas. O excesso de sublimite, que leva ao CRT 2, é informação da empresa e do contador; guarde no cadastro do cliente.
O MEI é optante pelo Simples Nacional?
Sim. Todo MEI é optante pelo Simples Nacional e está enquadrado no SIMEI, sistema de recolhimento em valores fixos mensais. Na NF-e, desde setembro de 2024, o MEI usa o CRT 4.
Com que frequência devo refazer a consulta de um CNPJ?
Para documentos fiscais, consulte no momento da emissão ou use um resultado do mesmo dia. Para cadastros sem emissão imediata, uma revalidação periódica basta. Aumente a frequência na virada do ano: as ME e EPP fazem a opção em setembro, com efeito em 1º de janeiro, e o MEI pede o SIMEI em janeiro.
Posso automatizar a consulta no portal da Receita?
O portal usa captcha para impedir automação, e raspar a página quebra com qualquer mudança. Em sistema, o caminho estável é uma API que entrega JSON ou XML.
A situação de hoje serve para uma nota antiga?
Não. Exclusões podem ter efeito retroativo, e as opções antigas feitas em janeiro valiam desde o dia 1º. Para uma operação passada, verifique o histórico de períodos e compare com a data da operação.
Resumo para colocar em produção
Para colocar a consulta Simples Nacional em produção: valide o CNPJ, consulte a API, guarde a resposta com data e hora, derive o CRT a partir da situação no Simples e no SIMEI e reconsulte no momento de emitir. Em auditoria, use o histórico de períodos, nunca a foto atual. Isso evita os erros mais caros: CRT desatualizado, retenção esquecida e nota de MEI emitida como ME.
Boa parte dos bugs de regime vem de tratar a consulta Simples Nacional por CNPJ como uma flag gravada uma vez no cadastro. Tratada como dado com data, com histórico e hora da consulta, ela passa a responder tanto a emissão de hoje quanto a auditoria de amanhã.
Para colocar isso para rodar, crie sua conta e teste a consulta Simples Nacional do Hub do Desenvolvedor. O mesmo plano inclui a API de CNPJ, útil para trazer data de abertura, endereço e atividade do mesmo cadastro numa integração só.
