Contribuintes / Gerenciamento de Empresas (TaxPayers)

Visão geral da API de Contribuintes / API Gerenciamento de Empresas da plataforma NFE.io

Documentação Detalhada

API de Empresas - CRUD completo de empresas

API de Certificados - Gerenciamento de certificados digitais

API de Inscrições Estaduais - Gestão de IE para NF-e/NFC-e

API de Inscrições Municipais - Gestão de IM para NFS-e

O que é o Gerenciamento de Empresas?

O Gerenciamento de Empresas (API de Contribuintes / API Gerenciamento de Empresas / TaxPayers) é o módulo da plataforma NFE.io responsável por centralizar todo o cadastro e a configuração das empresas que emitem documentos fiscais eletrônicos.

Antes de emitir qualquer nota fiscal — seja NF-e, NFC-e ou NFS-e — é necessário que a empresa esteja devidamente cadastrada na plataforma, com seu certificado digital vinculado e suas inscrições fiscais configuradas. Este módulo cuida exatamente disso: ele é o pré-requisito para toda a operação de emissão fiscal.

Por que isso é importante?

No Brasil, a emissão de documentos fiscais eletrônicos exige o cumprimento de requisitos junto a diferentes órgãos:

SEFAZ (Secretaria da Fazenda estadual) — para NF-e e NFC-e, exigindo Inscrição Estadual (IE) e certificado digital
Prefeituras municipais — para NFS-e, exigindo Inscrição Municipal (IM), e frequentemente credenciais de acesso ao webservice da prefeitura

Cada órgão tem suas regras, formatos e requisitos. A NFE.io abstrai essa complexidade, oferecendo uma interface unificada para cadastrar e gerenciar todos esses dados em um único lugar.

Conceito fundamental

Esta API não cadastra sua empresa diretamente na SEFAZ, nas prefeituras ou na Receita Federal. Ela apenas registra na NFE.io os dados que você já possui — como CNPJ, inscrições estaduais, inscrições municipais e certificados digitais.

Em outras palavras: você precisa primeiro obter esses dados junto aos órgãos governamentais. Depois, você usa esta API para informar esses dados à NFE.io, que os armazena e utiliza como base para emitir suas notas fiscais (NF-e, NFC-e e NFS-e).

O que este módulo possibilita?

Com a API de Contribuintes / API Gerenciamento de Empresas, você pode:

Cadastrar e gerenciar empresas emissoras — registrar internamente empresas (pessoas jurídicas identificadas por CNPJ) que emitirão documentos fiscais
Vincular certificados digitais — fazer upload de certificados ICP-Brasil (e-CNPJ A1 ou NF-e A1) necessários para assinar digitalmente os documentos fiscais
Espelhar inscrições estaduais — registrar os dados de IE já obtidos junto à SEFAZ, definir séries de numeração e gerenciar contingência (EPEC) para emissão de NF-e e NFC-e
Espelhar inscrições municipais — registrar os dados de IM já obtidos junto à prefeitura, credenciais, séries RPS e verificar se a NFE.io possui integração homologada com a prefeitura da cidade
Gerenciar múltiplas empresas — uma única conta na NFE.io pode gerenciar dezenas ou centenas de empresas, cada uma com suas próprias inscrições e certificados
Controlar séries e numeração — definir e acompanhar as séries de numeração para NF-e, NFC-e e RPS (NFS-e), evitando conflitos e garantindo sequência correta

Em resumo

Este módulo é o ponto de partida de toda integração com a NFE.io. Sem uma empresa cadastrada, com certificado e inscrição fiscal configurados, não é possível emitir nenhum documento fiscal pela plataforma.

Conceitos Essenciais

Empresa (Company)

A Empresa é a entidade central do sistema, representando a pessoa jurídica emissora de documentos fiscais. Ela atua como um "Hub de Identidade", concentrando:

Identificação fiscal: CNPJ, Razão Social, Nome Fantasia
Localização: Endereço fiscal com código IBGE
Regime tributário: Simples Nacional, Lucro Presumido, etc.
Certificado digital: Para assinatura de documentos
Inscrições fiscais: Estaduais e Municipais vinculadas

→ Documentação completa da API de Empresas

Certificado Digital (Certificate)

O Certificado Digital ICP-Brasil é obrigatório para emissão de documentos fiscais eletrônicos:

Tipos aceitos: e-CNPJ A1 ou NF-e A1 (certificados A3 não são suportados)
Formatos: Arquivo .pfx ou .p12
Requisitos: CNPJ deve corresponder ao da empresa, não pode estar expirado
Função: Assinatura digital de NF-e, NFC-e e NFS-e

Status	Descrição
`Active`	Certificado válido e pronto para uso
`Overdue`	Certificado vencido - emissões bloqueadas
`Inactive`	Certificado excluído
`Pending`	Aguardando processamento

→ Documentação completa da API de Certificados

Inscrição Estadual (StateTax)

Representa o cadastro da empresa junto à SEFAZ estadual, necessário para:

Emissão de NF-e (Nota Fiscal Eletrônica)
Emissão de NFC-e (Nota Fiscal de Consumidor Eletrônica)
Controle de séries e numeração
Gestão de contingência (EPEC)

Importante

Esta API não cadastra sua empresa na SEFAZ estadual. Ela apenas registra na NFE.io os dados de Inscrição Estadual que você já obteve junto à SEFAZ, para utilizá-los como base nas emissões de NF-e e NFC-e.

→ Documentação completa da API de Inscrições Estaduais

Inscrição Municipal (MunicipalTax)

Representa o cadastro da empresa junto à Prefeitura municipal, necessário para:

Emissão de NFS-e (Nota Fiscal de Serviços Eletrônica)
Controle de séries RPS e numeração
Gerenciamento de credenciais da prefeitura

Importante

Esta API não cadastra sua empresa na prefeitura municipal. Ela apenas registra na NFE.io os dados de Inscrição Municipal que você já obteve junto à prefeitura, para utilizá-los como base nas emissões de NFS-e.

→ Documentação completa da API de Inscrições Municipais

Introdução

A API de Contribuintes / API Gerenciamento de Empresas da NFE.io permite gerenciar empresas emissoras de documentos fiscais eletrônicos. A plataforma consolida o gerenciamento em uma única estrutura, diferenciando o tipo de emissão através das inscrições fiscais associadas:

Tipo de Documento	Cadastro Necessário	Órgão
NF-e / NFC-e	Inscrição Estadual	SEFAZ
NFS-e	Inscrição Municipal	Prefeitura

Arquitetura

Account (Conta)
    └── Company (Empresa)
            ├── Certificate (Certificado Digital A1)
            │
            ├── StateTax (Inscrição Estadual) → NF-e / NFC-e
            │       └── Series (Séries de numeração)
            │
            └── MunicipalTax (Inscrição Municipal) → NFS-e
                    └── RPS Series (Séries de RPS)

Hierarquia de Recursos

Recurso	Descrição	Documentação
Company	Pessoa jurídica (CNPJ) emissora de documentos fiscais	API de Empresas
Certificate	Certificado digital A1 ICP-Brasil para assinatura	API de Certificados
StateTax	Cadastro estadual (ICMS) para NF-e/NFC-e	API de Inscrições Estaduais
MunicipalTax	Cadastro municipal (ISS) para NFS-e	API de Inscrições Municipais

Fluxos de Configuração

Habilitar empresa para NF-e/NFC-e

1. Criar Empresa
   POST /v2/companies
       ↓
2. Configurar Certificado A1
   POST /v2/companies/{id}/certificates
       ↓
3. Criar Inscrição Estadual
   POST /v2/companies/{id}/statetaxes
       ↓
✅ Pronta para emitir NF-e/NFC-e

→ Documentação completa: API de Empresas | API de Inscrições Estaduais
→ Para criar empresas pela plataforma: Criar Empresa

Habilitar empresa para NFS-e

1. Criar Empresa
   POST /v2/companies
       ↓
2. Configurar Certificado A1
   POST /v2/companies/{id}/certificates
       ↓
3. Criar Inscrição Municipal
   POST /v2/companies/{id}/municipaltaxes
       ↓
4. Verificar FiscalStatus da prefeitura
       ↓
✅ Pronta para emitir NFS-e

→ Documentação completa: API de Empresas | API de Inscrições Municipais
→ Para criar empresas pela plataforma: Criar Empresa

URLs Base

Ambiente	URL
Produção	`https://api.nfse.io`

Endpoints Principais

Recurso	Endpoint Base	Documentação
Empresas	`/v2/companies`	Ver detalhes
Certificados	`/v2/companies/{company_id}/certificates`	Ver detalhes
Inscrições Estaduais	`/v2/companies/{company_id}/statetaxes`	Ver detalhes
Inscrições Municipais	`/v2/companies/{company_id}/municipaltaxes`	Ver detalhes

Autenticação

Todos os endpoints exigem autenticação via API Key.

→ Saiba como obter sua API Key

Authorization: <sua_api_key>

Exemplo cURL

curl -H "Authorization: sk_live_xxx" \
     https://api.nfse.io/v2/companies

Respostas de Autenticação

Código	Descrição
`401 Unauthorized`	API Key inválida ou expirada
`403 Forbidden`	API Key sem permissão para o recurso

Enums Principais

Status

Nome	Valor	Descrição
`Inactive`	-1	Inativo (excluído/desativado)
`None`	0	Não definido
`Active`	1	Ativo (permite operações)

TaxRegime (Regime Tributário)

Nome	Valor	Descrição
`None`	0	Não definido
`LucroReal`	2	Lucro Real
`LucroPresumido`	4	Lucro Presumido
`SimplesNacional`	8	Simples Nacional
`SimplesNacionalExcessoSublimite`	12	Simples Nacional - Excesso Sublimite
`MicroempreendedorIndividual`	16	MEI
`Isento`	32	Isento

Environment (Ambiente)

Nome	Valor	Descrição
`Development` / `Test`	0	Homologação/Sandbox
`Production`	1	Produção (emissão real)

Contrato de Erros

Todas as respostas de erro seguem o formato:

{
  "Errors": [
    {
      "Code": 40041,
      "Message": "company not found"
    }
  ]
}

Códigos de Erro Comuns

Código	Mensagem	Recurso
40017	name is null or empty	Company
40031	federal tax number is null	Company
40032	federal tax number is not valid	Company
40041	company not found	Company
40042	company is not available to issue	Company
40044	city is null	MunicipalTax
40045	city code is null or empty	MunicipalTax

→ Códigos completos: Empresas | IE | IM

Boas Práticas

Dados Cadastrais

Envie FederalTaxNumber (CNPJ) somente com dígitos (sem pontuação)
Use códigos IBGE válidos de 7 dígitos para City.Code
Mantenha endereços reais; a API valida e pode rejeitar dados inconsistentes

Numeração

Comece com séries simples (ex.: 1, IO, A1)
Inicialize numeração de forma clara (ex.: começar em 1)
Mantenha controle local do último número usado
Não reutilize números dentro da mesma série

Tratamento de Erros

Sempre leia o array Errors nas respostas de erro
Implemente retry com backoff exponencial para erros 5xx
Valide dados localmente antes de enviar à API

Paginação

Use startingAfter com o ID do último item para avançar
Respeite o limite máximo de 50 itens por página
Ordenação varia por recurso:
- Empresas: Name (ascendente)
- Inscrições: CreatedOn (descendente)

Documentação Detalhada

Recurso	Descrição	Link
Empresas	CRUD completo, endereço, regime tributário	api-empresas
Certificados	Upload, consulta e exclusão de certificados A1	api-certificados
Inscrições Estaduais	IE, séries, numeração, contingência EPEC	api-inscricoes-estaduais
Inscrições Municipais	IM, RPS, credenciais, FiscalStatus	api-inscricoes-municipais

Visão geral da API de Contribuintes / API Gerenciamento de Empresas da plataforma NFE.io​

O que é o Gerenciamento de Empresas?​

Por que isso é importante?​

O que este módulo possibilita?​

Conceitos Essenciais​

Empresa (Company)​

Certificado Digital (Certificate)​

Inscrição Estadual (StateTax)​

Inscrição Municipal (MunicipalTax)​

Introdução​

Arquitetura​

Hierarquia de Recursos​

Fluxos de Configuração​

Habilitar empresa para NF-e/NFC-e​

Habilitar empresa para NFS-e​

URLs Base​

Endpoints Principais​

Autenticação​

Exemplo cURL​

Respostas de Autenticação​

Enums Principais​

Status​

TaxRegime (Regime Tributário)​

Environment (Ambiente)​

Contrato de Erros​

Códigos de Erro Comuns​

Boas Práticas​

Dados Cadastrais​

Numeração​

Tratamento de Erros​

Paginação​

Documentação Detalhada​

NFE.io