Pular para o conteúdo principal

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:

APIDomínioFinalidade
NFS-e v1api.nfe.ioEmpresas para emissão de NFS-e
Contribuintes v2 / Gerenciamento de Empresasapi.nfse.ioEmpresas para emissão de NF-e e NFC-e

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

DesafioImpacto
Cadastro duplicadoUma empresa que emitia NFS-e e NF-e precisava ser cadastrada nas duas APIs separadamente
Dados desatualizadosMudanças de endereço ou certificado precisavam ser replicadas manualmente em ambas as APIs
Maior complexidadeDesenvolvedores 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ê:

AspectoImplicação
ContinuidadeSuas integrações atuais com a v1 continuam funcionando sem alterações até o desligamento
Dados unificadosEmpresas criadas via v1 já existem na estrutura v2 — não há dados "separados"
Migração simplificadaNão há migração de dados, apenas atualização dos endpoints chamados
Novos recursosPara 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étodoEndpointO que faz
POST/v2/companies/{id}/municipaltaxesCadastra uma nova inscrição municipal
GET/v2/companies/{id}/municipaltaxesLista 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ícioO que significa na prática
Cadastro únicoCadastre a empresa uma vez e configure-a para emitir NF-e, NFC-e ou NFS-e conforme necessário
Certificado compartilhadoO mesmo certificado digital é utilizado para todos os tipos de documento
Inscrição Municipal segregadaUma empresa pode ter Inscrição Municipal no modelo aplicado atualmente para Inscrição Estadual
Dados consistentesAtualização de endereço ou razão social reflete automaticamente em todas as emissões
Integração simplificadaUma ú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 v1Recurso na v2Campo na v2
nameCompanyname
tradeNameCompanytradeName
federalTaxNumberCompanyfederalTaxNumber
taxRegimeCompanytaxRegime
address.*Companyaddress.*
municipalTaxNumberMunicipalTaxtaxNumber
rpsSerialNumberMunicipalTaxrpsSerialNumber
rpsNumberMunicipalTaxrpsNumber
lastRpsSentMunicipalTaxlastRpsSent
issRateMunicipalTaxissRate
environmentMunicipalTaxenvironment
fiscalStatusMunicipalTaxfiscalStatus
specialTaxRegimeMunicipalTaxspecialTaxRegime
legalNatureMunicipalTaxlegalNature
regionalTaxNumberMunicipalTaxregionalTaxNumber
loginNameMunicipalTaxloginName
loginPasswordMunicipalTaxloginPassword
authIssueValueMunicipalTaxauthIssueValue
federalTaxDeterminationMunicipalTaxfederalTaxDetermination
municipalTaxDeterminationMunicipalTaxmunicipalTaxDetermination

Diferenças nas respostas​

Listagem de empresas​

v1: GET /v1/companies

{
  "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

{
  "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:

Aspectov1v2
Paginação"page": 1"hasMore": false + cursor
Dados municipaisCampos inlineReferência por ID em municipalTaxes
Inscrições estaduaisNão existiaArray stateTaxes

Consulta de empresa​

v1: GET /v1/companies/:id

{
  "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

// 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:

Aspectov1v2
Objeto raiz"companies": {...} (singular incorreto)"company": {...}
Dados municipaisInlineRecurso separado
Séries RPSCampo únicoArray 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:

{
  "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/companiesGET /v2/companies
POST /v1/companiesPOST /v2/companies + POST .../municipaltaxes
GET /v1/companies/:idGET /v2/companies/:id
PUT /v1/companies/:idPUT /v2/companies/:id
DELETE /v1/companies/:idDELETE /v2/companies/:id
POST /v1/companies/:id/certificatePOST /v2/companies/:id/certificates

Mudança de domínio​

APIDomí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

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)

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

2. Obtenha o ID da inscrição municipal

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

- 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

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

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:

# 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çãoO que você encontra
Visão GeralExplicação da arquitetura da API e hierarquia de recursos. Exemplo: diagrama mostrando que Company é o "hub" que conecta Certificate, StateTax e MunicipalTax
API de EmpresasDetalhamento 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 MunicipaisExplicaçã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 errosLista 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çãoCada endpoint possui exemplos em cURL e PowerShell prontos para copiar e executar
Boas práticasRecomendações como: enviar CNPJ sem pontuação, usar códigos IBGE de 7 dígitos, inicializar numeração RPS corretamente

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​

FaseEndpoints v1Ação recomendada
AgoraFuncionam normalmente (via adaptador)Iniciar planejamento da migração
Período de transiçãoFuncionam, mas com avisos de depreciaçãoExecutar a migração
Após descontinuaçãoSerão desligadosUsar 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?​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.