Ir para o conteúdo principal

Consulta de regime tributário por CNPJ: histórico da ECF pela API da Sintegrapi

Integre regimes tributários, histórico anual e vínculos de SCP ao seu ERP ou cadastro de fornecedores por 1 crédito por consulta.

O cadastro de um fornecedor informa seu CNPJ e sua razão social. Mas, quando a equipe precisa analisar a forma de tributação registrada em determinado ano, uma classificação sem período de referência pode gerar mais dúvidas do que respostas. Qual ano foi consultado? Há mais de um regime informado? O registro pertence à própria empresa ou a uma Sociedade em Conta de Participação?

A consulta de regimes tributários da Sintegrapi organiza essas informações para sua integração: regimes do ano mais recente disponível, histórico anual, identificadores de SCP e quantidade de escriturações. Tudo em uma chamada de API por 1 crédito, inclusive quando a pesquisa é concluída sem localizar registros.

Neste artigo, veja o que a consulta entrega, como interpretar os campos e como utilizá-los em ERP, software contábil ou processos de cadastro de clientes e fornecedores.

O que é a ECF e por que o ano importa

A Escrituração Contábil Fiscal (ECF) é uma obrigação relacionada à apuração de IRPJ e CSLL. A Receita Federal explica que sua entrega ocorre, em regra, até o último dia útil de julho do ano seguinte ao período escriturado. Consulte a descrição oficial da ECF.

Isso muda a forma de ler o resultado. Uma resposta obtida hoje com ano_referencia: 2024 descreve os registros disponíveis de 2024. Ela não deve ser exibida como “regime confirmado hoje”, nem receber automaticamente o ano atual no cadastro.

Também é importante separar três informações: o ano da escrituração, o momento em que sua integração fez a consulta e o período de reutilização do resultado pela API. Esses marcos têm funções diferentes. Manter os três em sua rotina evita que a data da chamada seja confundida com a atualidade fiscal da informação.

Quais informações a consulta retorna

Informação Como ajuda sua equipe
CNPJ e razão social disponível Vincular o resultado ao documento consultado.
Fonte e ano de referência Identificar de onde veio a informação e a qual período se refere.
Regimes do último ano disponível Analisar todas as formas de tributação retornadas para o período.
Histórico por ano Comparar os registros existentes ao longo do tempo.
Identificação e tipo de SCP Separar registros vinculados a uma Sociedade em Conta de Participação.
Razão social da SCP, quando localizada Facilitar a leitura do vínculo cadastral.
Quantidade de escriturações Entender a quantidade registrada em cada agrupamento.
Identificador da requisição Relacionar a consulta ao histórico de consumo e ao atendimento.

Os textos de regime podem incluir Lucro Real, Lucro Presumido, Lucro Arbitrado, imunes e isentas do IRPJ, conforme os registros disponíveis. A resposta preserva os valores da base e admite múltiplos itens no mesmo ano. O consumidor não precisa escolher uma categoria única para guardar os dados.

A API não promete uma sequência completa de anos para todos os CNPJs. O histórico corresponde aos fatos disponíveis para o documento exato pesquisado. Uma filial não é substituída automaticamente pela matriz, e a falta de registros para ela não autoriza atribuir-lhe o resultado de outro estabelecimento.

Por que pode haver mais de um regime no mesmo ano

O campo regimes é uma lista. Essa escolha permite preservar diferentes formas de tributação e vínculos de SCP existentes nos dados, em vez de ocultar informação atrás de um rótulo único.

Para sua integração, a consequência é objetiva: não use apenas regimes[0] como uma classificação definitiva de toda a empresa. Examine a coleção completa, os identificadores e o ano. A posição na lista é uma ordenação de apresentação; ela não representa um regime preferencial ou uma sequência temporal dentro do ano.

O resultado também não fornece, por si só, datas de início e fim para cada forma de tributação. Se dois itens aparecem em 2024, não invente meses de vigência nem conclua automaticamente que houve uma mudança entre eles. Preserve os registros e encaminhe a interpretação necessária à equipe fiscal.

Como interpretar uma SCP

A Sociedade em Conta de Participação exige atenção ao vínculo entre os registros. A orientação oficial informa que cada SCP transmite sua própria ECF, com a identificação da sócia ostensiva e da SCP. Fonte: perguntas frequentes da Receita Federal.

Na consulta da Sintegrapi, três campos ajudam nessa leitura:

  • cnpj_scp: identificador da SCP conforme a base. Apesar do nome do campo, registros históricos podem conter outro tipo de identificador.
  • scp_tipo: permite interpretar esse identificador; o valor CNPJ habilita o vínculo cadastral com a razão social da SCP.
  • razao_social_scp: nome localizado nesse vínculo, quando disponível.

Um nome nulo não apaga o fato ECF. Significa apenas que o nome não está disponível naquele resultado. Da mesma forma, não transfira automaticamente o regime de uma SCP para a empresa consultada: mantenha cada item associado ao identificador recebido.

quantidade_escrituracoes também merece um campo próprio. Esse número descreve a quantidade registrada no agrupamento; não é uma contagem de fornecedores, estabelecimentos ou regimes vigentes.

Exemplo de consulta e resposta

A nova rota utiliza a API key já adotada pela Sintegrapi. Configure a integração com o endereço oficial https://api.sintegrapi.com.br.

curl 'https://api.sintegrapi.com.br/consultas/v2/regimes-tributarios/11222333000181' \
  -H 'x-api-key: SUA_API_KEY' \
  -H 'Accept: application/json'

Exemplo inteiramente fictício, para demonstrar a estrutura:

{
  "request_id": "b328aa70-146b-48bd-a280-4fb47836cf70",
  "success": true,
  "error": false,
  "cnpj": "11222333000181",
  "razao_social": "EMPRESA FICTÍCIA LTDA",
  "encontrado": true,
  "fonte": "Receita Federal / ECF",
  "ano_referencia": 2024,
  "regimes": [
    {
      "regime": "LUCRO REAL",
      "cnpj_scp": null,
      "razao_social_scp": null,
      "scp_tipo": null,
      "quantidade_escrituracoes": 2
    },
    {
      "regime": "LUCRO PRESUMIDO",
      "cnpj_scp": "00000000000001",
      "razao_social_scp": "SCP FICTÍCIA",
      "scp_tipo": "CNPJ",
      "quantidade_escrituracoes": 1
    }
  ],
  "historico": [
    {
      "ano_referencia": 2024,
      "regimes": [
        {
          "regime": "LUCRO REAL",
          "cnpj_scp": null,
          "razao_social_scp": null,
          "scp_tipo": null,
          "quantidade_escrituracoes": 2
        },
        {
          "regime": "LUCRO PRESUMIDO",
          "cnpj_scp": "00000000000001",
          "razao_social_scp": "SCP FICTÍCIA",
          "scp_tipo": "CNPJ",
          "quantidade_escrituracoes": 1
        }
      ]
    },
    {
      "ano_referencia": 2023,
      "regimes": [
        {
          "regime": "LUCRO PRESUMIDO",
          "cnpj_scp": null,
          "razao_social_scp": null,
          "scp_tipo": null,
          "quantidade_escrituracoes": 1
        }
      ]
    }
  ]
}

Nesse exemplo, 2024 é o último ano disponível. A lista regimes traz os itens daquele ano, incluindo um registro associado a uma SCP. O historico repete o grupo de 2024 e acrescenta 2023. Essa repetição permite tanto uma leitura rápida do período mais recente quanto uma análise histórica; não some regimes e historico como conjuntos independentes.

Os nomes e documentos ilustram o contrato. Os anos do exemplo não representam uma promessa de cobertura da base.

O que significa não encontrar registros

Uma consulta concluída sem registros retorna HTTP 404, encontrado=false, success=false e error=false. O ano de referência vem nulo e as listas de regimes e histórico ficam vazias. A razão social ainda pode ser preenchida se houver informação cadastral disponível.

Esse retorno é diferente de uma falha técnica e consome 1 crédito. Ele informa que a pesquisa foi realizada, mas não encontrou fatos ECF para aquele CNPJ na base disponível.

Não transforme esse resultado em uma classificação tributária. Ausência de ECF não prova opção pelo Simples Nacional, enquadramento como MEI, inatividade ou inexistência do CNPJ. A Receita Federal lista situações em que a entrega da ECF não é exigida; elas não podem ser identificadas individualmente apenas por um retorno vazio. Veja as orientações oficiais sobre obrigatoriedade.

Para verificar Simples Nacional e SIMEI, utilize a consulta específica da Sintegrapi, com consumo próprio. As duas consultas respondem a perguntas diferentes e podem compor a mesma rotina de análise.

Três aplicações práticas para sua operação

ERP e software fiscal

Armazene os dados em uma estrutura com CNPJ, ano e lista de regimes, preservando os vínculos de SCP. Mostre o período ao lado do resultado, como “informação ECF — ano de referência 2024”. Guarde também o request_id para facilitar rastreabilidade e atendimento.

Se a rotina já possui uma classificação atual validada pela equipe, apresente a informação histórica como evidência adicional. Uma divergência deve gerar uma revisão, sem substituir silenciosamente um campo operacional por informação de outro período.

Cadastro e revisão de fornecedores

Use o histórico para organizar uma fila de análise: fornecedores sem registros disponíveis, cadastros com formas diferentes entre os anos e registros que precisam de avaliação por vínculo de SCP. O retorno estruturado ajuda a padronizar essa triagem e reduz a necessidade de transcrever resultados manualmente.

A consulta pode integrar uma revisão cadastral mais ampla, junto de situação do CNPJ, inscrições estaduais e certidões pertinentes. Cada fonte deve conservar seu significado e sua data. O histórico da ECF não é uma certidão de regularidade fiscal.

Contabilidade e atendimento a clientes

A apresentação por ano facilita uma conversa objetiva sobre o que consta na base: qual forma aparece, em qual exercício, com qual vínculo e quantidade de escriturações. O escritório pode registrar os pontos que exigem confirmação e comparar o resultado com a documentação já fornecida pelo cliente.

O ganho está na organização da informação. A API não substitui a análise contábil, não escolhe o regime mais vantajoso para a empresa e não calcula tributos.

Como tratar cache, erros e novas tentativas

Os dados de uma consulta podem ser reutilizados por até 24 horas. Consultas repetidas nesse intervalo continuam sendo chamadas individuais, com identificadores e consumo próprios. O prazo de cache não significa que a fonte ECF seja atualizada diariamente.

Uma indisponibilidade da fonte de dados ou timeout da consulta retorna HTTP 503, com error=true. Esse retorno não confirma cobrança: a reserva é compensada. Não substitua uma informação conhecida por listas vazias de uma resposta de erro.

CNPJ inválido, falta de autenticação, saldo insuficiente e limites de requisição também devem ser tratados pelo código HTTP e pelo contrato da API. Em uma interrupção de conexão, verifique o histórico da requisição antes de repetir, pois pode ter havido conclusão sem que a resposta chegasse ao seu sistema.

A documentação técnica de regimes tributários reúne os exemplos, tipos, códigos e JSON Schema para implementar esses cenários.

E a relação com IBS e CBS?

Organizar informações tributárias de clientes e fornecedores pode apoiar o trabalho das equipes durante a transição fiscal. Entretanto, o regime de IRPJ registrado historicamente na ECF não determina, sozinho, a situação atual de IBS/CBS ou o direito a créditos em uma operação.

Mantenha essas informações separadas em sua modelagem e utilize as fontes e regras pertinentes a cada tributo. O objetivo desta consulta é entregar os fatos ECF disponíveis, com ano e vínculos preservados, para que sua equipe tenha contexto na análise.

Quanto custa e como começar

O consumo normal é de 1 crédito por requisição concluída, com ou sem registros e também quando os dados são reutilizados. Não há acréscimo por ano histórico, regime ou SCP retornada. O valor financeiro do crédito depende do plano contratado.

Conheça os planos e adquira a API da Sintegrapi. Escolha a opção adequada ao volume de consultas da sua operação e acompanhe o consumo no histórico.

Para projetos com maior volume, necessidades específicas de integração ou atendimento dedicado, entre em contato para um plano Enterprise com suporte prioritário. Nossa equipe pode conversar sobre o cenário da sua empresa e as condições de contratação.

Já é cliente? Consulte a documentação da nova rota, ajuste o tratamento de HTTP 404 e inclua o ano de referência na apresentação dos resultados.