---
title: "API de Contribuintes / API Gerenciamento de Empresas - Visão Geral | NFE.io | Docs"
description: "Visão geral completa da API de Contribuintes / API Gerenciamento de Empresas (TaxPayers) da plataforma NFE.io para gerenciamento de empresas, certificados e inscrições fiscais."
source_url: https://nfe.io/docs/documentacao/gerenciamento-empresas/visao-geral
last_updated: 2026-02-06
---

# 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](./gerenciamento-empresas.md) - CRUD completo de empresas
> - [API de Certificados](./gerenciamento-certificado.md) - Gerenciamento de certificados digitais
> - [API de Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) - Gestão de IE para NF-e/NFC-e
> - [API de Inscrições Municipais](./gerenciamento-inscricao-municipal.md) - Gestão de IM para NFS-e

:::info[Migração da API legada]
Esta API substitui o antigo grupo `/v1/companies` da [Nota Fiscal de Serviço v1](/docs/desenvolvedores/rest-api/nota-fiscal-de-servico-v1), que está em descontinuação. Consulte o [guia de migração na release-note 2026.1](/docs/release-notes/2026-1-unificacao-api-contribuintes).
:::

---

## 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.

:::warning[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

:::info[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](./gerenciamento-empresas.md)

### 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](./gerenciamento-certificado.md)

### 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)

:::warning[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](./gerenciamento-inscricao-estadual.md)

### 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**

:::warning[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](./gerenciamento-inscricao-municipal.md)

---

## 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](./gerenciamento-empresas.md) |
| **Certificate** | Certificado digital A1 ICP-Brasil para assinatura | [API de Certificados](./gerenciamento-certificado.md) |
| **StateTax** | Cadastro estadual (ICMS) para NF-e/NFC-e | [API de Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) |
| **MunicipalTax** | Cadastro municipal (ISS) para NFS-e | [API de Inscrições Municipais](./gerenciamento-inscricao-municipal.md) |

---

## 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](./gerenciamento-empresas.md) | [API de Inscrições Estaduais](./gerenciamento-inscricao-estadual.md)  
→ Para criar empresas pela plataforma: [Criar Empresa](/docs/documentacao/nossa-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](./gerenciamento-empresas.md) | [API de Inscrições Municipais](./gerenciamento-inscricao-municipal.md)  
→ Para criar empresas pela plataforma: [Criar Empresa](/docs/documentacao/nossa-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](./gerenciamento-empresas.md) |
| Certificados | `/v2/companies/{company_id}/certificates` | [Ver detalhes](./gerenciamento-certificado.md) |
| Inscrições Estaduais | `/v2/companies/{company_id}/statetaxes` | [Ver detalhes](./gerenciamento-inscricao-estadual.md) |
| Inscrições Municipais | `/v2/companies/{company_id}/municipaltaxes` | [Ver detalhes](./gerenciamento-inscricao-municipal.md) |

---

## Autenticação

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

→ **[Saiba como obter sua API Key](/docs/documentacao/nossa-plataforma/chaves-de-autenticacao)**

```http
Authorization: <sua_api_key>
```

### Exemplo cURL

```bash
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:

```json
{
  "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](./gerenciamento-empresas.md#códigos-de-erro) | [IE](./gerenciamento-inscricao-estadual.md#códigos-de-erro) | [IM](./gerenciamento-inscricao-municipal.md#códigos-de-erro)

---

## 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](./gerenciamento-empresas.md) |
| **Certificados** | Upload, consulta e exclusão de certificados A1 | [api-certificados](./gerenciamento-certificado.md) |
| **Inscrições Estaduais** | IE, séries, numeração, contingência EPEC | [api-inscricoes-estaduais](./gerenciamento-inscricao-estadual.md) |
| **Inscrições Municipais** | IM, RPS, credenciais, FiscalStatus | [api-inscricoes-municipais](./gerenciamento-inscricao-municipal.md) |