---
title: "2026.1 - Unificação da API de Contribuintes"
description: "API de Contribuintes v2 / API Gerenciamento de Empresas agora unifica o gerenciamento de empresas para NF-e, NFC-e e NFS-e em uma única API"
source_url: https://nfe.io/docs/release-notes/2026-1-unificacao-api-contribuintes
last_updated: 2026-07-03
---

# Release 2026.1 - Unificação da API de Contribuintes.

## Visão Geral

A API de Contribuintes v2 (também conhecida como API Gerenciamento de Empresas) agora unifica o gerenciamento de empresas emissoras de documentos fiscais em uma **única API**.

Anteriormente utilizada apenas para NF-e e NFC-e, a API v2 passa a suportar também a configuração de **Inscrições Municipais para emissão de NFS-e**.

Com essa mudança, os endpoints de gerenciamento de empresas da API de NFS-e v1 (`/v1/companies/*`) serão **descontinuados** em favor dos endpoints da API v2 (`/v2/companies/*`).

---

## Por que essa mudança?

Até esta release, a plataforma NFE.io mantinha duas APIs separadas:

| API | Domínio | Finalidade |
|-----|---------|------------|
| **NFS-e v1** | `api.nfe.io` | Empresas para emissão de NFS-e |
| **Contribuintes v2 / Gerenciamento de Empresas** | `api.nfse.io` | Empresas para emissão de NF-e e NFC-e |

Essa separação trazia desafios para quem integrava com a plataforma:

| Desafio | Impacto |
|---------|---------|
| **Cadastro duplicado** | Uma empresa que emitia NFS-e e NF-e precisava ser cadastrada nas duas APIs separadamente |
| **Dados desatualizados** | Mudanças de endereço ou certificado precisavam ser replicadas manualmente em ambas as APIs |
| **Maior complexidade** | Desenvolvedores precisavam conhecer e manter integração com duas APIs distintas, em domínios diferentes |

**A unificação resolve isso**: uma empresa cadastrada uma única vez pode emitir qualquer tipo de documento fiscal.

---

## Como funciona hoje

### A API de Contribuintes v2 / API Gerenciamento de Empresas

A API de Contribuintes v2 (também chamada de API Gerenciamento de Empresas) (`/v2/companies/*`) é a API unificada da NFE.io para gerenciamento de empresas emissoras de documentos fiscais. Disponível no domínio `api.nfse.io`, ela permite:

- Cadastrar e gerenciar empresas (dados cadastrais, endereço, regime tributário)
- Vincular certificados digitais ICP-Brasil
- Configurar inscrições estaduais para emissão de NF-e e NFC-e
- Configurar inscrições municipais para emissão de NFS-e (novo)

Cada recurso possui endpoints dedicados, permitindo gerenciamento granular e independente de cada aspecto da empresa.

### Retrocompatibilidade com a API v1

Para facilitar a transição dos clientes que utilizam a API v1, optamos por manter **retrocompatibilidade** até o desligamento dos endpoints v1.

Isso significa que os endpoints da API v1 (`/v1/companies/*`) continuam funcionando normalmente. Internamente, porém, esses endpoints já direcionam as chamadas para a API v2:

```
Você chama                    O sistema executa internamente
-----------                   ------------------------------
POST /v1/companies      -->   POST /v2/companies
                              + POST /v2/companies/{id}/municipaltaxes

GET /v1/companies/:id   -->   GET /v2/companies/:id
                              + GET /v2/companies/:id/municipaltaxes/:im_id

PUT /v1/companies/:id   -->   PUT /v2/companies/:id
                              + PUT /v2/companies/:id/municipaltaxes/:im_id
```

**O que isso significa para você:**

| Aspecto | Implicação |
|---------|------------|
| **Continuidade** | Suas integrações atuais com a v1 continuam funcionando sem alterações até o desligamento |
| **Dados unificados** | Empresas criadas via v1 já existem na estrutura v2 — não há dados "separados" |
| **Migração simplificada** | Não há migração de dados, apenas atualização dos endpoints chamados |
| **Novos recursos** | Para usar funcionalidades exclusivas da v2 (múltiplas cidades, consulta de séries RPS), é necessário chamar os endpoints v2 diretamente |

Essa abordagem permite que você planeje e execute a migração no seu próprio ritmo, sem interrupções no serviço, até a data de descontinuação da v1.

---

## O que mudou

### Novos endpoints para Inscrições Municipais

A API v2 agora inclui endpoints dedicados para gerenciar Inscrições Municipais (necessárias para emissão de NFS-e):

| Método | Endpoint | O que faz |
|--------|----------|-----------|
| `POST` | `/v2/companies/{id}/municipaltaxes` | Cadastra uma nova inscrição municipal |
| `GET` | `/v2/companies/{id}/municipaltaxes` | Lista todas as inscrições da empresa |
| `GET` | `/v2/companies/{id}/municipaltaxes/{im_id}` | Consulta uma inscrição específica |
| `PUT` | `/v2/companies/{id}/municipaltaxes/{im_id}` | Atualiza dados da inscrição |
| `DELETE` | `/v2/companies/{id}/municipaltaxes/{im_id}` | Remove a inscrição |
| `GET` | `.../municipaltaxes/{im_id}/series/{serie}` | Consulta numeração de uma série RPS |

### Estrutura unificada da empresa

Com a unificação, uma empresa na API v2 pode conter:

```
Empresa (Company)
    │
    ├── Certificado Digital
    │   └── Usado para assinar NF-e, NFC-e e NFS-e
    │
    ├── Inscrições Estaduais (StateTax)
    │   └── Para emissão de NF-e e NFC-e
    │
    └── Inscrições Municipais (MunicipalTax)  ← NOVO
        └── Para emissão de NFS-e
```

---

## Benefícios

| Benefício | O que significa na prática |
|-----------|---------------------------|
| **Cadastro único** | Cadastre a empresa uma vez e configure-a para emitir NF-e, NFC-e ou NFS-e conforme necessário |
| **Certificado compartilhado** | O mesmo certificado digital é utilizado para todos os tipos de documento |
| **Inscrição Municipal segregada** | Uma empresa pode ter Inscrição Municipal no modelo aplicado atualmente para Inscrição Estadual |
| **Dados consistentes** | Atualização de endereço ou razão social reflete automaticamente em todas as emissões |
| **Integração simplificada** | Uma única API para aprender, integrar e manter |

---

## Detalhamento técnico

### Mapeamento de campos: v1 para v2

Na API v1, os dados da empresa e da inscrição municipal estavam misturados em um único objeto. Na v2, eles são separados em recursos distintos:

| Campo na v1 | Recurso na v2 | Campo na v2 |
|-------------|---------------|-------------|
| `name` | Company | `name` |
| `tradeName` | Company | `tradeName` |
| `federalTaxNumber` | Company | `federalTaxNumber` |
| `taxRegime` | Company | `taxRegime` |
| `address.*` | Company | `address.*` |
| `municipalTaxNumber` | MunicipalTax | `taxNumber` |
| `rpsSerialNumber` | MunicipalTax | `rpsSerialNumber` |
| `rpsNumber` | MunicipalTax | `rpsNumber` |
| `lastRpsSent` | MunicipalTax | `lastRpsSent` |
| `issRate` | MunicipalTax | `issRate` |
| `environment` | MunicipalTax | `environment` |
| `fiscalStatus` | MunicipalTax | `fiscalStatus` |
| `specialTaxRegime` | MunicipalTax | `specialTaxRegime` |
| `legalNature` | MunicipalTax | `legalNature` |
| `regionalTaxNumber` | MunicipalTax | `regionalTaxNumber` |
| `loginName` | MunicipalTax | `loginName` |
| `loginPassword` | MunicipalTax | `loginPassword` |
| `authIssueValue` | MunicipalTax | `authIssueValue` |
| `federalTaxDetermination` | MunicipalTax | `federalTaxDetermination` |
| `municipalTaxDetermination` | MunicipalTax | `municipalTaxDetermination` |

### Diferenças nas respostas

#### Listagem de empresas

**v1: `GET /v1/companies`**
```json
{
  "companies": [
    {
      "id": "abc123def456",
      "name": "ACME TECNOLOGIA LTDA",
      "federalTaxNumber": 12345678000199,
      "municipalTaxNumber": "123456",
      "rpsSerialNumber": "A1",
      "rpsNumber": 1500,
      "environment": "Production",
      "certificate": {
        "thumbprint": "1A2B3C4D5E6F7890ABCDEF1234567890ABCDEF12",
        "modifiedOn": "2026-01-15T10:30:00+00:00",
        "expiresOn": "2027-01-15T23:59:59+00:00",
        "status": "Active"
      },
      "address": {
        "state": "SP",
        "city": {
          "code": "3550308",
          "name": "São Paulo"
        },
        "district": "Centro",
        "street": "Avenida Paulista",
        "number": "1000",
        "postalCode": "01310100",
        "country": "BRA"
      }
    }
  ],
  "page": 1
}
```

**v2: `GET /v2/companies`**
```json
{
  "hasMore": false,
  "companies": [
    {
      "id": "abc123def456",
      "name": "ACME TECNOLOGIA LTDA",
      "federalTaxNumber": 12345678000199,
      "municipalTaxNumber": "mtx_789xyz",
      "stateTaxes": [],
      "municipalTaxes": ["mtx_789xyz"],
      "certificate": {
        "taxPayerId": "abc123def456",
        "thumbprint": "1A2B3C4D5E6F7890ABCDEF1234567890ABCDEF12",
        "taxId": "12345678000199",
        "subject": "CN=ACME TECNOLOGIA LTDA:12345678000199, OU=RFB e-CNPJ A1, O=ICP-Brasil, C=BR",
        "validUntil": "2027-01-15T23:59:59Z",
        "modifiedOn": "2026-01-15T10:30:00Z",
        "status": "Active"
      },
      "address": {
        "state": "SP",
        "city": {
          "code": "3550308",
          "name": "São Paulo"
        },
        "district": "Centro",
        "street": "Avenida Paulista",
        "number": "1000",
        "postalCode": "01310100",
        "country": "BRA"
      }
    }
  ]
}
```

**Principais diferenças:**

| Aspecto | v1 | v2 |
|---------|----|----|
| Paginação | `"page": 1` | `"hasMore": false` + cursor |
| Dados municipais | Campos inline | Referência por ID em `municipalTaxes` |
| Inscrições estaduais | Não existia | Array `stateTaxes` |

#### Consulta de empresa

**v1: `GET /v1/companies/:id`**
```json
{
  "companies": {
    "id": "abc123def456",
    "name": "ACME TECNOLOGIA LTDA",
    "tradeName": "ACME Tech",
    "federalTaxNumber": 12345678000199,
    "rpsSerialNumber": "A1",
    "rpsNumber": 1500,
    "issRate": 2.5,
    "environment": "Production",
    "fiscalStatus": "Active",
    "loginName": "usuario_prefeitura",
    "loginPassword": "******",
    "authIssueValue": "token_xyz_123"
  }
}
```

**v2: `GET /v2/companies/:id` + `GET /v2/companies/:id/municipaltaxes/:im_id`**
```json
// GET /v2/companies/:id
{
  "company": {
    "id": "abc123def456",
    "name": "ACME TECNOLOGIA LTDA",
    "tradeName": "ACME Tech",
    "federalTaxNumber": 12345678000199,
    "municipalTaxes": ["789xyz"],
    "stateTaxes": []
  }
}

// GET /v2/companies/:id/municipaltaxes/:im_id
{
  "municipalTax": {
    "id": "mtx_789xyz",
    "companyId": "abc123def456",
    "accountId": "56abc",
    "city": {
      "country": "BRA",
      "state": "SP",
      "code": "3550308",
      "name": "São Paulo"
    },
    "taxNumber": "123456",
    "rpsSerialNumber": "A1",
    "rpsNumber": 1500,
    "lastRpsSent": 1499,
    "issRate": 2.5,
    "environment": "Production",
    "fiscalStatus": "Active",
    "loginName": "usuario_prefeitura",
    "loginPassword": "******",
    "authIssueValue": "token_xyz_123",
    "rpsSerialNumbers": ["A1"]
  }
}
```

**Principais diferenças:**

| Aspecto | v1 | v2 |
|---------|----|----|
| Objeto raiz | `"companies": {...}` (singular incorreto) | `"company": {...}` |
| Dados municipais | Inline | Recurso separado |
| Séries RPS | Campo único | Array `rpsSerialNumbers` com histórico |

### IDs são compartilhados

O ID da empresa é o mesmo em ambas as APIs:

```
v1: /v1/companies/abc123def456
v2: /v2/companies/abc123def456
```

Para obter o ID da inscrição municipal, consulte o array `municipalTaxes` na resposta da empresa v2:

```json
{
  "company": {
    "id": "abc123def456",
    "municipalTaxes": ["mtx_789xyz"]
  }
}
```

---

## Como migrar da v1 para v2

Como seus dados já estão na estrutura v2 (graças ao adaptador interno), a migração consiste em atualizar seu código para chamar os novos endpoints.

### Mapeamento de endpoints

| Endpoint v1 (será descontinuado) | Endpoint v2 equivalente |
|---------------------------------|------------------------|
| `GET /v1/companies` | `GET /v2/companies` |
| `POST /v1/companies` | `POST /v2/companies` + `POST .../municipaltaxes` |
| `GET /v1/companies/:id` | `GET /v2/companies/:id` |
| `PUT /v1/companies/:id` | `PUT /v2/companies/:id` |
| `DELETE /v1/companies/:id` | `DELETE /v2/companies/:id` |
| `POST /v1/companies/:id/certificate` | `POST /v2/companies/:id/certificates` |

### Mudança de domínio

| API | Domínio |
|-----|---------|
| v1 (descontinuada) | `api.nfe.io` |
| v2 (usar esta) | `api.nfse.io` |

A autenticação permanece a mesma: `Authorization: <sua_api_key>`

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

### Cenários de migração

#### Cenário A: Empresa usa apenas NFS-e (existe só na v1)

Seus dados já estão na v2 por causa do adaptador. Para migrar:

**1. Obtenha o ID da empresa na v2 (é o mesmo da v1)**
```bash
curl -H "Authorization: sk_live_xxx" \
  https://api.nfse.io/v2/companies/abc123def456
```

**2. Obtenha o ID da inscrição municipal**
```bash
curl -H "Authorization: sk_live_xxx" \
  https://api.nfse.io/v2/companies/abc123def456/municipaltaxes
```
Resposta inclui o ID: `"id": "mtx_789xyz"`

**3. Atualize seu código para usar os novos endpoints**
```diff
- GET api.nfe.io/v1/companies/abc123def456
+ GET api.nfse.io/v2/companies/abc123def456
+ GET api.nfse.io/v2/companies/abc123def456/municipaltaxes/mtx_789xyz
```

#### Cenário B: Empresa usa NF-e/NFC-e e NFS-e

Se você já usa a v2 para NF-e/NFC-e e a v1 para NFS-e:

**1. Verifique se a inscrição municipal já existe na v2**
```bash
curl -H "Authorization: sk_live_xxx" \
  https://api.nfse.io/v2/companies/{company_id}/municipaltaxes
```

**2. Se existir, apenas atualize os endpoints no seu código**

**3. Se não existir, crie a inscrição municipal**
```bash
curl -X POST -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  https://api.nfse.io/v2/companies/{company_id}/municipaltaxes \
  -d '{
    "MunicipalTax": {
      "City": { "Code": "3550308", "Name": "São Paulo", "State": "SP" },
      "TaxNumber": "123456",
      "RpsSerialNumber": "A1",
      "RpsNumber": 1,
      "Environment": "Production"
    }
  }'
```

#### Cenário C: Empresa com múltiplas cidades (novo recurso)

Antes não era possível ter múltiplas inscrições municipais. Agora você pode:

```bash
# Adicionar segunda cidade
curl -X POST -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  https://api.nfse.io/v2/companies/{company_id}/municipaltaxes \
  -d '{
    "MunicipalTax": {
      "City": { "Code": "3304557", "Name": "Rio de Janeiro", "State": "RJ" },
      "TaxNumber": "789012",
      "RpsSerialNumber": "RJ1",
      "RpsNumber": 1,
      "Environment": "Production"
    }
  }'

# Listar todas as cidades
curl -H "Authorization: sk_live_xxx" \
  https://api.nfse.io/v2/companies/{company_id}/municipaltaxes
# Retorna array com São Paulo e Rio de Janeiro
```

---

## Nova documentação disponível

Além da unificação da API, publicamos uma nova seção de documentação com conteúdo mais detalhado sobre o gerenciamento de empresas.

### O que há de novo na documentação

| Seção | O que você encontra |
|-------|---------------------|
| **Visão Geral** | Explicação da arquitetura da API e hierarquia de recursos. Exemplo: diagrama mostrando que Company é o "hub" que conecta Certificate, StateTax e MunicipalTax |
| **API de Empresas** | Detalhamento de cada campo do cadastro. Exemplo: `TaxRegime` define o regime tributário (Simples Nacional, Lucro Presumido, etc.) usado no cálculo de impostos |
| **API de Inscrições Municipais** | Explicação do conceito de "espelhamento" - a API não cadastra na prefeitura, apenas armazena dados já obtidos pelo contribuinte para uso nas emissões |
| **Validações e erros** | Lista completa de regras de validação com códigos de erro. Exemplo: código `40028` indica que o código IBGE da cidade não corresponde à UF informada |
| **Exemplos de requisição** | Cada endpoint possui exemplos em cURL e PowerShell prontos para copiar e executar |
| **Boas práticas** | Recomendações como: enviar CNPJ sem pontuação, usar códigos IBGE de 7 dígitos, inicializar numeração RPS corretamente |

### Links para a documentação

- [Visão Geral - API de Contribuintes](/docs/documentacao/gerenciamento-empresas/visao-geral)
- [API de Empresas](/docs/documentacao/gerenciamento-empresas/api-empresas)
- [API de Certificados](/docs/documentacao/gerenciamento-empresas/api-certificados)
- [API de Inscrições Estaduais](/docs/documentacao/gerenciamento-empresas/api-inscricoes-estaduais)
- [API de Inscrições Municipais](/docs/documentacao/gerenciamento-empresas/api-inscricoes-municipais)

---

## Próximos passos: descontinuação da v1

A camada de compatibilidade que traduz chamadas v1 para v2 será removida em uma data a ser comunicada. A partir desse momento, os endpoints v1 deixarão de funcionar.

### Endpoints que serão descontinuados

- `GET /v1/companies`
- `POST /v1/companies`
- `GET /v1/companies/:company_id_or_tax_number`
- `PUT /v1/companies/:company_id`
- `DELETE /v1/companies/:company_id`
- `POST /v1/companies/:company_id/certificate`

### Cronograma

| Fase | Endpoints v1 | Ação recomendada |
|------|--------------|------------------|
| **Agora** | Funcionam normalmente (via adaptador) | Iniciar planejamento da migração |
| **Período de transição** | Funcionam, mas com avisos de depreciação | Executar a migração |
| **Após descontinuação** | Serão desligados | Usar exclusivamente a v2 |

**Prazo**: A data de descontinuação será comunicada em breve. Recomendamos iniciar a migração o quanto antes.

### Campo `municipalTaxNumber` na Company v2

O campo `municipalTaxNumber` no objeto Company da v2 atualmente contém o ID da MunicipalTax (não o número real da inscrição). Este campo será removido em uma versão futura.

**Recomendação**: Utilize o array `municipalTaxes` para obter os IDs das inscrições municipais e consulte o endpoint `/municipaltaxes/{id}` para obter o número real da inscrição (`taxNumber`).

---

## Precisa de ajuda?

- Consulte a [documentação completa](/docs/documentacao/gerenciamento-empresas/visao-geral)
- Em caso de dúvidas, entre em contato com nosso suporte