---
title: "API de Inscrições Municipais - Gestão de IM | NFE.io | Docs"
description: "Documentação da API para cadastro e gerenciamento de inscrições municipais (IM) necessárias para emissão de NFS-e."
source_url: https://nfe.io/docs/documentacao/gerenciamento-empresas/api-inscricoes-municipais
last_updated: 2026-02-06
---

# API de Inscrições Municipais (MunicipalTax)

## Cadastre os dados de inscrição municipal para emissão de NFS-e

> **Navegação**
> - [← Voltar para Visão Geral](./gerenciamento-empresas-resumo.md)
> - [Empresas →](./gerenciamento-empresas.md)
> - [Certificados →](./gerenciamento-certificado.md)
> - [Inscrições Estaduais →](./gerenciamento-inscricao-estadual.md)

---

## Visão Geral

O recurso **MunicipalTax** (Inscrição Municipal) **registra na NFE.io** os dados cadastrais da empresa, necessários para emissão de NFS-e (Nota Fiscal de Serviços Eletrônica).

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

O cadastro junto à prefeitura, obtenção de credenciais (login/senha ou token) e habilitação para emissão de NFS-e devem ser feitos **diretamente por você** no portal da respectiva prefeitura.
:::

---

## Anatomia de uma Inscrição Municipal

### Conceitos Fundamentais

Ao cadastrar uma inscrição municipal, você informa os dados **já obtidos** junto à prefeitura:

| Conceito | Campos na API | Descrição |
|----------|---------------|-----------|
| **Localização** | `City` | Cidade da inscrição (código IBGE, nome, UF) |
| **Identificação Municipal** | `TaxNumber` | Número da Inscrição Municipal obtido na prefeitura |
| **Numeração RPS** | `RpsSerialNumber`, `RpsNumber` | Controle de numeração de RPS |
| **Ambiente** | `Environment` | Produção ou Desenvolvimento para emissão da nota|
| **Credenciais** | `LoginName`, `LoginPassword`, `AuthIssueValue` | Dados de acesso à prefeitura (usados na emissão) |

### Campos Gerenciados pelo Sistema

Além dos dados que você informa, o sistema gera e mantém automaticamente:

| Campo | Tipo | Quando é definido |
|-------|------|-------------------|
| `Id` | string | Gerado na criação |
| `CompanyId` | string | Vinculado à empresa da URL |
| `AccountId` | string | Vinculado à sua conta/tenant |
| `Status` | enum | Inicia como `Active` |
| `LastRpsSent` | long | Último RPS enviado (controle interno de numeração utilizado para emissões em prefeituras onde o RPS é sequencial) |
| `FiscalStatus` | enum | Verificado automaticamente (suporte da NFE.io para a cidade) |
| `RpsSerialNumbers` | array | Lista de séries utilizadas, atualizada automaticamente |
| `City.Country` | string | Definido automaticamente como `"BRA"` |
| `CreatedOn` | datetime | Data/hora da criação |
| `ModifiedOn` | datetime | Atualizado a cada alteração |

### O que o contribuinte faz **fora** do sistema NFE.io

1. Obtém sua Inscrição Municipal diretamente na prefeitura
2. Consegue credenciais de acesso (login/senha ou token) junto à prefeitura (se exigido)
3. Habilita a emissão de NFS-e no portal da prefeitura
4. Verifica com qual série e número de RPS ele deve utilizar na plataforma da NFE.io 
5. Cadastra esses dados no sistema NFE.io através desta API

### Referência Completa de Propriedades

### 📋 Expandir tabela completa

| Propriedade | Tipo | Obrigatório | Descrição |
|-------------|------|:-----------:|-----------|
| `Id` | string | — | Identificador único (gerado) |
| `CompanyId` | string | — | ID da empresa proprietária |
| `AccountId` | string | — | Conta/tenant proprietária |
| `Status` | enum | — | Status operacional |
| `City` | object | ✅ | Cidade da inscrição |
| `City.Code` | string | ✅ | Código IBGE (7 dígitos) |
| `City.Name` | string | ✅ | Nome da cidade |
| `City.State` | string | ✅ | UF (2 letras) |
| `City.Country` | string | — | País (sempre "BRA") |
| `TaxNumber` | string | — | Número da Inscrição Municipal |
| `SpecialTaxRegime` | enum | — | Regime especial de tributação |
| `Email` | string | — | E-mail para notificações |
| `LegalNature` | enum | — | Natureza jurídica |
| `CompanyRegistryNumber` | long | — | Registro na Junta Comercial |
| `RegionalTaxNumber` | long | — | Número do cadastro regional |
| `RpsSerialNumber` | string | ✅ | Série de RPS atual |
| `RpsNumber` | long | ✅ | Próximo número de RPS |
| `LastRpsSent` | long | - | Último RPS enviado |
| `RpsSerialNumbers` | array | — | Lista de séries (gerado) |
| `IssRate` | decimal | — | Alíquota do ISS (%) |
| `Environment` | enum | ✅ | Ambiente de processamento |
| `FiscalStatus` | enum | — | Suporte da NFE.io para a cidade |
| `FederalTaxDetermination` | enum | — | Determinação fiscal federal |
| `MunicipalTaxDetermination` | enum | — | Determinação fiscal municipal |
| `LoginName` | string | — | Usuário para acesso à prefeitura |
| `LoginPassword` | string | — | Senha para acesso à prefeitura |
| `AuthIssueValue` | string | — | Token de autorização |
| `CreatedOn` | datetime | — | Data de criação |
| `ModifiedOn` | datetime | — | Última modificação |

---

## Endpoints

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| `POST` | `/v2/companies/{company_id}/municipaltaxes` | Criar inscrição |
| `GET` | `/v2/companies/{company_id}/municipaltaxes` | Listar inscrições |
| `GET` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}` | Consultar inscrição |
| `PUT` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}` | Alterar inscrição |
| `DELETE` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}` | Excluir inscrição |
| `PATCH` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}/updateprefecture` | Verificar suporte da cidade |
| `GET` | `/v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}/series/{serie}` | Consultar série RPS |

:::info[Autenticação]
Todos os endpoints exigem autenticação via API Key: `Authorization: <sua_api_key>`

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

---

## Criar uma Inscrição Municipal

Cadastra os dados de uma inscrição municipal no sistema NFE.io.

:::note
Este endpoint apenas cadastra os dados no sistema NFE.io. A inscrição municipal deve ter sido previamente obtida junto à prefeitura.
:::

```http
POST /v2/companies/{company_id}/municipaltaxes
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

:::warning Ambiente padrão de criação
Toda Inscrição Municipal é criada no ambiente **`Development`**, independentemente do valor enviado no campo `Environment`. Isso evita emissões acidentais em produção durante a configuração e os testes.

Para emitir notas em **produção**, é necessário **alterar a IM após a criação**, definindo `Environment` como `Production` — veja [Alterar Inscrição Municipal](#alterar-inscrição-municipal).
:::

### Corpo da Requisição

```json
{
  "MunicipalTax": {
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP"
    },
    "TaxNumber": "876543",
    "Environment": "Development",
    "RpsSerialNumber": "IO",
    "RpsNumber": 1000,
    "LastRpsSent": 999
  }
}
```

### Parâmetros do Corpo

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `City` | object | ✅ | Cidade da inscrição |
| `City.Code` | string | ✅ | Código IBGE (7 dígitos) |
| `City.Name` | string | ✅ | Nome da cidade |
| `City.State` | string | ✅ | UF (2 letras) |
| `TaxNumber` | string | | Número da Inscrição Municipal |
| `Environment` | enum |  | Ambiente. **A IM é sempre criada em `Development`**, mesmo que outro valor seja enviado. Para emitir em produção, [altere a IM após a criação](#alterar-inscrição-municipal). Valores: `Development` (padrão), `Production`, `Staging` |
| `RpsSerialNumber` | string | ✅ | Série do RPS |
| `RpsNumber` | long | ✅ | Próximo número de RPS |
| `LastRpsSent` | long | ✅ | Último RPS enviado |

#### Parâmetros Opcionais

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `SpecialTaxRegime` | enum | Regime especial de tributação (padrão: `Nenhum`) |
| `Email` | string | E-mail para notificações |
| `LegalNature` | enum | Natureza jurídica |
| `CompanyRegistryNumber` | long | Número do registro na Junta Comercial |
| `RegionalTaxNumber` | long | Número do cadastro regional |
| `IssRate` | decimal | Alíquota de ISS (%) |
| `FederalTaxDetermination` | enum | Determinação fiscal federal (padrão: `Default`) |
| `MunicipalTaxDetermination` | enum | Determinação fiscal municipal (padrão: `Default`) |
| `LoginName` | string | Usuário para acesso à prefeitura |
| `LoginPassword` | string | Senha para acesso à prefeitura |
| `AuthIssueValue` | string | Token de autorização |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "MunicipalTax": {
    "Id": "mtx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    },
    "TaxNumber": "876543",
    "SpecialTaxRegime": "Nenhum",
    "Email": null,
    "LegalNature": "None",
    "CompanyRegistryNumber": null,
    "RegionalTaxNumber": null,
    "RpsSerialNumber": "IO",
    "RpsNumber": 1000,
    "LastRpsSent": 999,
    "IssRate": null,
    "Environment": "Development",
    "FiscalStatus": "Active",
    "FederalTaxDetermination": "Default",
    "MunicipalTaxDetermination": "Default",
    "LoginName": null,
    "LoginPassword": null,
    "AuthIssueValue": null,
    "RpsSerialNumbers": ["IO"],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": null
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Empresa não encontrada |

```json
{
  "Errors": [
    {
      "Code": 40044,
      "Message": "city is null"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X POST https://api.nfse.io/v2/companies/company_abc123/municipaltaxes \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "MunicipalTax": {
      "City": { "Code": "3550308", "Name": "São Paulo", "State": "SP" },
      "Environment": "Development",
      "RpsSerialNumber": "IO",
      "RpsNumber": 1000,
      "LastRpsSent": 999
    }
  }'
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }
$body = @{
  MunicipalTax = @{
    City = @{ Code = "3550308"; Name = "São Paulo"; State = "SP" }
    TaxNumber = "876543"
    Environment = "Development"
    RpsSerialNumber = "IO"
    RpsNumber = 1000
    LastRpsSent = 999
  }
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies/company_abc123/municipaltaxes" `
  -Method Post -Headers $headers -Body $body -ContentType "application/json"
```

---

## Listar Inscrições Municipais

Lista todas as inscrições municipais de uma empresa com paginação.

```http
GET /v2/companies/{company_id}/municipaltaxes
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Parâmetros de Query

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|--------|-----------|
| `limit` | int | 10 | Limite de resultados (1-50) |
| `startingAfter` | string | | ID do cursor para próxima página |
| `endingBefore` | string | | ID do cursor para página anterior |

### Ordenação

- Primária: `CreatedOn` (descendente - mais recentes primeiro)
- Secundária: `Id` (ascendente)

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "hasMore": true,
  "municipalTaxes": [
    {
      "Id": "mtx_001",
      "CompanyId": "company_abc123",
      "AccountId": "acct_12345",
      "Status": "Active",
      "City": {
        "Code": "3550308",
        "Name": "São Paulo",
        "State": "SP",
        "Country": "BRA"
      },
      "TaxNumber": "876543",
      "SpecialTaxRegime": "Nenhum",
      "Email": "contato@acme.com.br",
      "LegalNature": "SociedadeEmpresariaLimitada",
      "CompanyRegistryNumber": 1234567,
      "RegionalTaxNumber": null,
      "RpsSerialNumber": "IO",
      "RpsNumber": 1000,
      "LastRpsSent": 999,
      "IssRate": 2.0,
      "Environment": "Production",
      "FiscalStatus": "Active",
      "FederalTaxDetermination": "Default",
      "MunicipalTaxDetermination": "Default",
      "LoginName": "pref_user",
      "AuthIssueValue": null,
      "RpsSerialNumbers": ["IO"],
      "CreatedOn": "2024-01-15T10:30:00Z",
      "ModifiedOn": "2024-02-20T14:45:00Z"
    },
    {
      "Id": "mtx_002",
      "CompanyId": "company_abc123",
      "AccountId": "acct_12345",
      "Status": "Active",
      "City": {
        "Code": "3304557",
        "Name": "Rio de Janeiro",
        "State": "RJ",
        "Country": "BRA"
      },
      "TaxNumber": "112233",
      "SpecialTaxRegime": "Nenhum",
      "Email": null,
      "LegalNature": "None",
      "CompanyRegistryNumber": null,
      "RegionalTaxNumber": null,
      "RpsSerialNumber": "A1",
      "RpsNumber": 200,
      "LastRpsSent": 199,
      "IssRate": null,
      "Environment": "Production",
      "FiscalStatus": "Active",
      "FederalTaxDetermination": "Default",
      "MunicipalTaxDetermination": "Default",
      "LoginName": null,
      "AuthIssueValue": null,
      "RpsSerialNumbers": ["A1"],
      "CreatedOn": "2024-01-10T14:00:00Z",
      "ModifiedOn": null
    }
  ]
}
```

### Paginação

Use o `Id` do último item como `startingAfter` para obter a próxima página:

```http
GET /v2/companies/{company_id}/municipaltaxes?limit=20&startingAfter=mtx_002
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Empresa ou cursor não encontrado |

### Exemplo cURL

```bash
curl -X GET "https://api.nfse.io/v2/companies/company_abc123/municipaltaxes?limit=20" \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Inscrição Municipal por ID

Retorna os detalhes de uma inscrição municipal específica.

```http
GET /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "MunicipalTax": {
    "Id": "mtx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    },
    "TaxNumber": "876543",
    "SpecialTaxRegime": "Nenhum",
    "Email": "contato@acme.com.br",
    "LegalNature": "SociedadeEmpresariaLimitada",
    "CompanyRegistryNumber": 1234567,
    "RegionalTaxNumber": 98765,
    "RpsSerialNumber": "IO",
    "RpsNumber": 1000,
    "LastRpsSent": 999,
    "IssRate": 2.0,
    "Environment": "Production",
    "FiscalStatus": "Active",
    "FederalTaxDetermination": "Default",
    "MunicipalTaxDetermination": "Default",
    "LoginName": "pref_user",
    "LoginPassword": null,
    "AuthIssueValue": "ABC-XYZ",
    "RpsSerialNumbers": ["IO", "A1"],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-02-20T14:45:00Z"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Inscrição não encontrada |

```json
{
  "Errors": [
    {
      "Code": 40041,
      "Message": "municipal tax not found"
    }
  ]
}
```

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001 \
  -H "Authorization: sk_live_xxx"
```

---

## Alterar Inscrição Municipal

Atualiza os dados de uma inscrição municipal existente.

```http
PUT /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |

### Headers

| Header | Valor |
|--------|-------|
| `Content-Type` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Corpo da Requisição

:::tip Promover a IM para produção
Como a IM nasce em `Development`, este é o endpoint usado para movê-la para produção: basta enviar `"Environment": "Production"` no corpo da requisição. Confirme que a integração com a prefeitura está validada (`FiscalStatus: Active`) antes de promover.
:::

```json
{
  "MunicipalTax": {
    "TaxNumber": "876544",
    "Email": "novo-email@acme.com.br",
    "IssRate": 3.0,
    "Environment": "Production",
    "LoginName": "novo_usuario",
    "LoginPassword": "nova_senha"
  }
}
```

### Campos Atualizáveis

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `City` | object | Cidade da inscrição |
| `TaxNumber` | string | Número da Inscrição Municipal |
| `Email` | string | E-mail para notificações |
| `SpecialTaxRegime` | enum | Regime especial de tributação |
| `LegalNature` | enum | Natureza jurídica |
| `CompanyRegistryNumber` | long | Número do registro na Junta Comercial |
| `RegionalTaxNumber` | long | Número do cadastro regional |
| `IssRate` | decimal | Alíquota de ISS (%) |
| `RpsSerialNumber` | string | Série do RPS |
| `RpsNumber` | long | Próximo número de RPS |
| `LastRpsSent` | long | Último RPS enviado |
| `Environment` | enum | Ambiente de processamento |
| `LoginName` | string | Usuário da prefeitura |
| `LoginPassword` | string | Senha da prefeitura |
| `AuthIssueValue` | string | Token de autorização |
| `FederalTaxDetermination` | enum | Determinação fiscal federal |
| `MunicipalTaxDetermination` | enum | Determinação fiscal municipal |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "MunicipalTax": {
    "Id": "mtx_001",
    "CompanyId": "company_abc123",
    "AccountId": "acct_12345",
    "Status": "Active",
    "City": {
      "Code": "3550308",
      "Name": "São Paulo",
      "State": "SP",
      "Country": "BRA"
    },
    "TaxNumber": "876544",
    "SpecialTaxRegime": "Nenhum",
    "Email": "novo-email@acme.com.br",
    "LegalNature": "SociedadeEmpresariaLimitada",
    "CompanyRegistryNumber": 1234567,
    "RegionalTaxNumber": null,
    "RpsSerialNumber": "IO",
    "RpsNumber": 1000,
    "LastRpsSent": 999,
    "IssRate": 3.0,
    "Environment": "Production",
    "FiscalStatus": "Active",
    "FederalTaxDetermination": "Default",
    "MunicipalTaxDetermination": "Default",
    "LoginName": "novo_usuario",
    "LoginPassword": null,
    "AuthIssueValue": null,
    "RpsSerialNumbers": ["IO"],
    "CreatedOn": "2024-01-15T10:30:00Z",
    "ModifiedOn": "2024-03-10T16:20:00Z"
  }
}
```

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Dados inválidos |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X PUT https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001 \
  -H "Authorization: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "MunicipalTax": {
      "Email": "novo-email@acme.com.br",
      "IssRate": 3.0
    }
  }'
```

---

## Excluir Inscrição Municipal

Exclui uma inscrição municipal da empresa.

:::warning[Atenção]
Este processo é **irreversível**. Histórico de numeração RPS será perdido.
:::

```http
DELETE /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X DELETE https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001 \
  -H "Authorization: sk_live_xxx"
```

---

## Verificar Suporte da Cidade

Força uma verificação se a NFE.io possui suporte/homologação para emissão de NFS-e na cidade cadastrada.

:::warning[Importante]
Este endpoint **não** verifica o status da prefeitura em si. Ele verifica internamente se o sistema NFE.io tem integração homologada com a prefeitura daquela cidade.
:::

```http
PATCH /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}/updateprefecture
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |

### Headers

| Header | Valor |
|--------|-------|
| `Authorization` | `<sua_api_key>` |

### Uso

Este endpoint é útil quando:
- Você quer verificar se a NFE.io adicionou suporte para uma cidade que antes não era suportada
- Houve atualização na lista de cidades homologadas
- Você quer atualizar o `FiscalStatus` após mudanças internas no sistema

### Resposta de Sucesso

**Status:** `204 No Content`

(Sem corpo na resposta - o FiscalStatus é atualizado internamente)

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | ID inválido |
| `404 Not Found` | Inscrição não encontrada |

### Exemplo cURL

```bash
curl -X PATCH https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001/updateprefecture \
  -H "Authorization: sk_live_xxx"
```

---

## Consultar Série RPS

Consulta informações de numeração de uma série específica de RPS.

```http
GET /v2/companies/{company_id}/municipaltaxes/{municipal_tax_id}/series/{serie}
```

### Parâmetros de Rota

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `company_id` | string | ID da empresa |
| `municipal_tax_id` | string | ID da inscrição municipal |
| `serie` | string | Identificador da série RPS |

### Headers

| Header | Valor |
|--------|-------|
| `Accept` | `application/json` |
| `Authorization` | `<sua_api_key>` |

### Resposta de Sucesso

**Status:** `200 OK`

```json
{
  "Serie": {
    "RpsNumber": 1500,
    "LastRpsSent": 1499
  }
}
```

### Campos da Resposta

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `RpsNumber` | long | Próximo número de RPS disponível |
| `LastRpsSent` | long | Último número de RPS enviado/utilizado |

### Respostas de Erro

| Status | Descrição |
|--------|-----------|
| `400 Bad Request` | Parâmetros inválidos |
| `404 Not Found` | Inscrição ou série não encontrada |

### Exemplo cURL

```bash
curl -X GET https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001/series/IO \
  -H "Authorization: sk_live_xxx"
```

### Exemplo PowerShell

```powershell
$headers = @{ Authorization = "sk_live_xxx" }

Invoke-RestMethod -Uri "https://api.nfse.io/v2/companies/company_abc123/municipaltaxes/mtx_001/series/IO" `
  -Method Get -Headers $headers
```

---

## Regras de Validação

O sistema aplica as seguintes regras de validação ao criar ou alterar uma inscrição municipal:

### Dados da Inscrição Municipal

| Campo | Regra | Mensagem de Erro |
|-------|-------|------------------|
| `Status` | Inscrição deve estar ativa para alterações | municipal tax is not active |
| `City` | Obrigatório | city is null |
| `City.Code` | 7 dígitos, primeiros 2 devem corresponder ao código da UF | city code does not match the state code |
| `City.Name` | Obrigatório | city name is null or empty |
| `City.State` | Obrigatório, deve ser UF válida | state is null or empty / state is not valid |
| `RpsSerialNumber` | Obrigatório | rps serial number is null or empty |
| `Email` | Se informado, não pode ser vazio | email is null or empty |

### Validação de Cidade

O código IBGE da cidade deve corresponder ao estado informado (exemplos):

| UF | Código IBGE (primeiros 2 dígitos) |
|----|-----------------------------------|
| SP | 35 |
| RJ | 33 |
| MG | 31 |
| PR | 41 |
| RS | 43 |

---

## Códigos de Erro

### Validação de Dados

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40035 | account id is null or empty | AccountId não informado |
| 40037 | company id is null or empty | CompanyId não informado |
| 40040 | request municipal tax is null | Payload da inscrição municipal nulo |
| 40044 | city is null | Cidade não informada |
| 40045 | city code is null or empty | Código IBGE não informado |

### Validação de Empresa

| Código | Mensagem | Descrição |
|--------|----------|-----------|
| 40041 | company not found | Empresa não encontrada |
| 40042 | company is not available to issue | Empresa inativa |
| 40043 | account id is not valid to this company | AccountId não corresponde à empresa |

### Validação de Inscrição Municipal

| Mensagem | Descrição |
|----------|-----------|
| municipal tax is not active | Inscrição inativa não permite alterações |
| municipal tax not found | Inscrição municipal não encontrada |
| city name is null or empty | Nome da cidade não informado |
| state is null or empty | UF não informada |
| state is not valid | UF inválida |
| city code does not match the state code | Código IBGE não corresponde à UF |
| rps serial number is null or empty | Série RPS não informada |
| series not found | Série não encontrada |
| serial number not found | Série especificada não existe |
| account id is not valid to this municipal tax | AccountId não corresponde à inscrição |
| company id is not valid to this municipal tax | CompanyId não corresponde à inscrição |

---

## Enums

### ApiEnvironment (Ambiente)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Development` | 0 | Desenvolvimento (padrão) |
| `Production` | 1 | Produção (emissão real) |
| `Staging` | 2 | Homologação |

> **Importante:** ao criar uma IM, o ambiente é sempre `Development`, mesmo que outro valor seja enviado no `POST`. Para mudar para `Production` ou `Staging`, [altere a IM](#alterar-inscrição-municipal) após a criação.

:::note
Nem todas as prefeituras suportam ambiente de teste/homologação.
:::

### Status

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Inactive` | -1 | Inativa (excluída/desativada) |
| `None` | 0 | Não definido |
| `Active` | 1 | Ativa (permite operações) |

### MunicipalTaxFiscalStatus (Suporte da Cidade)

Indica se a NFE.io possui integração homologada com a prefeitura da cidade.

| Nome | Valor | Descrição | NFE.io pode emitir? |
|------|-------|-----------|---------------------|
| `CityNotSupported` | -3 | NFE.io não possui integração com esta cidade | ❌ Não |
| `Pending` | -2 | Integração em desenvolvimento | ❌ Não |
| `Inactive` | -1 | Integração temporariamente indisponível | ❌ Não |
| `None` | 0 | Status não determinado | ❌ Não |
| `Active` | 1 | NFE.io tem integração homologada | ✅ Sim |

### SpecialTaxRegime (Regime Especial de Tributação)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `Automatico` | -1 | Automático (detectado pelo sistema) |
| `Nenhum` | 0 | Sem regime especial |
| `MicroempresaMunicipal` | 1 | Microempresa municipal |
| `Estimativa` | 2 | Regime de estimativa |
| `SociedadeDeProfissionais` | 3 | Sociedade de profissionais |
| `Cooperativa` | 4 | Cooperativa |
| `MicroempreendedorIndividual` | 5 | MEI |
| `MicroempresarioEmpresaPequenoPorte` | 6 | ME/EPP |

### FederalTaxDeterminationBy (Determinação Fiscal Federal)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `NotInformed` | 0 | Não informado |
| `Default` | 2 | Padrão |
| `SimplesNacional` | 4 | Simples Nacional |

### MunicipalTaxDeterminationBy (Determinação Fiscal Municipal)

| Nome | Valor | Descrição |
|------|-------|-----------|
| `NotInformed` | 0 | Não informado |
| `Default` | 2 | Padrão |
| `SimplesNacional` | 4 | Simples Nacional |

### LegalNature (Natureza Jurídica)

Código de acordo com a Tabela de Natureza Jurídica (Resolução Concla). Exemplos mais comuns:

| Nome | Código | Descrição |
|------|--------|-----------|
| `None` | 0 | Não definido |
| `EmpresaPublica` | 2011 | 201-1 Empresa Pública |
| `SociedadeAnonimaAberta` | 2046 | 204-6 S.A. Aberta |
| `SociedadeAnonimaFechada` | 2054 | 205-4 S.A. Fechada |
| `SociedadeEmpresariaLimitada` | 2062 | 206-2 Sociedade Empresária Limitada |
| `SociedadeEmpresariaEmNomeColetivo` | 2070 | 207-0 Sociedade em Nome Coletivo |
| `SociedadeEmpresariaEmComanditaSimples` | 2089 | 208-9 Sociedade em Comandita Simples |
| `Empresario` | 2135 | 213-5 Empresário Individual |
| `Cooperativa` | 2143 | 214-3 Cooperativa |
| `SociedadeSimplesPura` | 2232 | 223-2 Sociedade Simples Pura |
| `SociedadeSimplesLimitada` | 2240 | 224-0 Sociedade Simples Limitada |
| `EireliNaturezaEmpresaria` | 2305 | 230-5 EIRELI (Natureza Empresária) |
| `EireliNaturezaSimples` | 2313 | 231-3 EIRELI (Natureza Simples) |
| `EmpresaSimplesDeInovacao` | 2348 | 234-8 Inova Simples |
| `AssociacaoPrivada` | 3999 | 399-9 Associação Privada |

:::info
Consulte a tabela completa de Natureza Jurídica no [site do IBGE/Concla](http://concla.ibge.gov.br/estrutura/natjur-estrutura/natureza-juridica-2009-1).
:::

---

## Valores Padrão

O sistema aplica os seguintes valores padrão quando não informados:

| Campo | Valor Padrão | Descrição |
|-------|--------------|-----------|
| `RpsSerialNumber` | `"IO"` | Série padrão de RPS |
| `SpecialTaxRegime` | `Nenhum` | Sem regime especial |
| `FederalTaxDetermination` | `Default` | Determinação padrão |
| `MunicipalTaxDetermination` | `Default` | Determinação padrão |
| `LegalNature` | `None` | Não definido |
| `Environment` | `Development` | Ambiente de desenvolvimento |
| `City.Country` | `"BRA"` | Brasil (aplicado automaticamente) |

---

## Boas Práticas

### Numeração RPS

- **Inicie a numeração corretamente**: Defina `RpsNumber` como o próximo número a ser usado
- **Sincronize `LastRpsSent`**: Deve ser `RpsNumber - 1` na criação
- **Use séries simples**: `IO`, `A1`, `1` são exemplos comuns
- **Não reutilize números**: Cada RPS deve ter número único na série

### Códigos IBGE

Use códigos IBGE válidos de 7 dígitos. Exemplos:

| Cidade | Código IBGE |
|--------|-------------|
| São Paulo/SP | 3550308 |
| Rio de Janeiro/RJ | 3304557 |
| Belo Horizonte/MG | 3106200 |
| Curitiba/PR | 4106902 |
| Porto Alegre/RS | 4314902 |

### Credenciais da Prefeitura

As credenciais são **armazenadas** no sistema NFE.io e utilizadas automaticamente **no momento da emissão** de cada NFS-e:

- Algumas prefeituras exigem `LoginName` e `LoginPassword`
- Outras exigem `AuthIssueValue` (token)
- Consulte os requisitos específicos da prefeitura no portal dela
- As credenciais devem ser obtidas **diretamente na prefeitura** pelo contribuinte
- **Nunca** compartilhe credenciais em logs ou mensagens de erro

### Monitoramento

- Verifique `FiscalStatus` para confirmar que a NFE.io tem suporte para a cidade
- Use `updateprefecture` para verificar se houve atualização no suporte da cidade
- Se `FiscalStatus != Active`, a cidade pode não ser suportada pela NFE.io ainda

---

## Próximos Passos

Após cadastrar a inscrição municipal no sistema NFE.io:

1. **Verifique o FiscalStatus** - Confirme que a NFE.io tem suporte para a cidade (`Active`)
2. **Configure o certificado digital** se ainda não tiver → [Ver documentação](./gerenciamento-certificado.md)
3. **Confirme as credenciais** - Se a prefeitura exige login/senha ou token, verifique se foram cadastradas corretamente
4. **Valide a numeração RPS** - Confirme que `RpsNumber` e `LastRpsSent` estão sincronizados com a prefeitura
5. **Teste a emissão** - Se possível, use ambiente de desenvolvimento para validar a configuração

:::tip[Lembre-se]
A NFE.io apenas registra os dados que você já possui. O cadastro na prefeitura (obtenção da Inscrição Municipal, credenciais e habilitação para emissão) deve ser feito diretamente por você no portal da prefeitura.
:::

---

## Veja também:

- [API de Empresas](./gerenciamento-empresas.md) - Gerenciamento de empresas
- [API de Certificados](./gerenciamento-certificado.md) - Gerenciamento de certificados digitais
- [Inscrições Estaduais](./gerenciamento-inscricao-estadual.md) - Configuração para NF-e/NFC-e