Pular para o conteúdo principal

API de Inscrições Estaduais (StateTax)

Gerencie inscrições estaduais para emissão de NF-e e NFC-e

Navegação


Visão Geral

O recurso StateTax (Inscrição Estadual) representa o cadastro da empresa junto à SEFAZ estadual, necessário para emissão de:

  • NF-e - Nota Fiscal Eletrônica
  • NFC-e - Nota Fiscal de Consumidor Eletrônica
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.

O cadastro junto à SEFAZ, obtenção da Inscrição Estadual e habilitação para emissão de documentos fiscais devem ser feitos diretamente por você junto ao órgão estadual competente.


Anatomia de uma Inscrição Estadual

Conceitos Fundamentais

Ao criar uma inscrição estadual, você define os dados necessários para emissão de documentos fiscais na SEFAZ:

ConceitoCampos na APIDescrição
LocalizaçãoCodeCódigo do Estado (UF)
Identificação EstadualTaxNumberNúmero da Inscrição Estadual
Tipo de EmissãoTypeNF-e ou NFC-e
NumeraçãoSerie, NumberSérie e número atual da numeração
AmbienteEnvironmentTypeProdução ou Homologação
ProcessamentoProcessingDetailsDetalhes de autorização e contingência

Campos Gerenciados pelo Sistema

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

CampoTipoQuando é definido
IdstringGerado na criação
CompanyIdstringVinculado à empresa da URL
AccountIdstringVinculado à sua conta/tenant
StatusenumInicia como Active
SeriesarrayLista de séries utilizadas, atualizada automaticamente
ProcessingDetails.AuthorityStatusenumStatus da SEFAZ em tempo real
ProcessingDetails.StatusOndatetimeData/hora da última atualização do status
CreatedOndatetimeData/hora da criação
ModifiedOndatetimeAtualizado a cada alteração

Referência Completa de Propriedades

📋 Expandir tabela completa
PropriedadeTipoObrigatórioDescrição
IdstringIdentificador único (gerado)
CompanyIdstringID da empresa proprietária
AccountIdstringConta/tenant proprietária
StatusenumStatus operacional
CodeenumCódigo do Estado (UF)
TaxNumberstringNúmero da Inscrição Estadual
EnvironmentTypeenumAmbiente de processamento (Production ou Test)
SpecialTaxRegimeenumRegime especial de tributação
TypeenumTipo de emissão (NFe ou NFCe)
SerieintSérie atual
NumberlongPróximo número da série
SeriesarrayLista de séries utilizadas (gerado)
SecurityCredentialobjectCredenciais de segurança (obrigatório para NFC-e)
SecurityCredential.IdintID do CSC
SecurityCredential.CodestringCódigo CSC
ProcessingDetailsobjectDetalhes de processamento
ProcessingDetails.SwitchAuthorizerStrategyenumEstratégia de troca de autorizador
ProcessingDetails.AuthorityStatusenumStatus da SEFAZ
ProcessingDetails.StatusOndatetimeData do status
ProcessingDetails.LastSwitchAuthorizerDetailsobjectÚltima troca de autorizador
CreatedOndatetimeData de criação
ModifiedOndatetimeÚltima modificação

Endpoints

MétodoEndpointDescrição
POST/v2/companies/{company_id}/statetaxesCriar inscrição
GET/v2/companies/{company_id}/statetaxesListar inscrições
GET/v2/companies/{company_id}/statetaxes/{state_tax_id}Consultar inscrição
PUT/v2/companies/{company_id}/statetaxes/{state_tax_id}Alterar inscrição
DELETE/v2/companies/{company_id}/statetaxes/{state_tax_id}Excluir inscrição
POST/v2/companies/{company_id}/statetaxes/{state_tax_id}/switch-authorizerTrocar autorizador
Autenticação

Todos os endpoints exigem autenticação via API Key: Authorization: <sua_api_key>

Saiba como obter sua API Key


Criar uma Inscrição Estadual

Cria uma nova inscrição estadual para a empresa.

POST /v2/companies/{company_id}/statetaxes

Parâmetros de Rota

ParâmetroTipoDescrição
company_idstringID da empresa

Headers

HeaderValor
Content-Typeapplication/json
Authorization<sua_api_key>

Corpo da Requisição

{
"StateTax": {
"Code": "SP",
"TaxNumber": "123456789",
"EnvironmentType": "Production",
"SpecialTaxRegime": "Nenhum",
"Type": "NFe",
"Serie": 1,
"Number": 1,
"ProcessingDetails": {
"SwitchAuthorizerStrategy": "Manual"
}
}
}

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
CodeenumCódigo do Estado (UF)
TaxNumberstringNúmero da Inscrição Estadual
TypeenumTipo de emissão (NFe ou NFCe)
EnvironmentTypeenumProduction ou Test (padrão: Test)
SpecialTaxRegimeenumRegime especial de tributação
SerieintSérie inicial (padrão: 1)
NumberlongNúmero inicial da série
SecurityCredentialobjectObrigatório para NFC-e
ProcessingDetailsobjectConfigurações de processamento

Objeto SecurityCredential (obrigatório para NFC-e)

CampoTipoObrigatórioDescrição
IdintID do CSC (Código de Segurança do Contribuinte)
CodestringCódigo CSC

Objeto ProcessingDetails

CampoTipoDescrição
SwitchAuthorizerStrategyenumManual ou StateTaxAuthorityStatusUnavailable

Resposta de Sucesso

Status: 200 OK

{
"StateTax": {
"Id": "stx_001",
"CompanyId": "company_abc123",
"AccountId": "acct_12345",
"Status": "Active",
"Code": "SP",
"TaxNumber": "123456789",
"EnvironmentType": "Production",
"SpecialTaxRegime": "Nenhum",
"Type": "NFe",
"Serie": 1,
"Number": 1,
"Series": [1],
"SecurityCredential": null,
"ProcessingDetails": {
"SwitchAuthorizerStrategy": "Manual",
"AuthorityStatus": "Unknown",
"StatusOn": "2024-01-15T10:30:00Z",
"LastSwitchAuthorizerDetails": null
},
"CreatedOn": "2024-01-15T10:30:00Z",
"ModifiedOn": null
}
}

Respostas de Erro

StatusDescrição
400 Bad RequestDados inválidos
404 Not FoundEmpresa não encontrada
{
"Errors": [
{
"Code": 40041,
"Message": "company not found"
}
]
}

Exemplo cURL

curl -X POST https://api.nfse.io/v2/companies/company_abc123/statetaxes \
-H "Authorization: sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"StateTax": {
"Code": "SP",
"TaxNumber": "123456789",
"EnvironmentType": "Production",
"Type": "NFe",
"Serie": 1,
"Number": 1
}
}'

Exemplo PowerShell

$headers = @{ Authorization = "sk_live_xxx" }
$body = @{
StateTax = @{
Code = "SP"
TaxNumber = "123456789"
EnvironmentType = "Production"
Type = "NFe"
Serie = 1
Number = 1
}
} | ConvertTo-Json -Depth 5

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

Listar Inscrições Estaduais

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

GET /v2/companies/{company_id}/statetaxes

Parâmetros de Rota

ParâmetroTipoDescrição
company_idstringID da empresa

Headers

HeaderValor
Acceptapplication/json
Authorization<sua_api_key>

Parâmetros de Query

ParâmetroTipoPadrãoDescrição
limitint10Limite de resultados (1-50)
startingAfterstringID do cursor para próxima página
endingBeforestringID 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

{
"hasMore": false,
"stateTaxes": [
{
"Id": "stx_001",
"CompanyId": "company_abc123",
"AccountId": "acct_12345",
"Status": "Active",
"Code": "SP",
"TaxNumber": "123456789",
"EnvironmentType": "Production",
"SpecialTaxRegime": "Nenhum",
"Type": "NFe",
"Serie": 1,
"Number": 1500,
"Series": [1],
"CreatedOn": "2024-01-15T10:30:00Z",
"ModifiedOn": "2024-02-20T14:45:00Z"
},
{
"Id": "stx_002",
"CompanyId": "company_abc123",
"AccountId": "acct_12345",
"Status": "Active",
"Code": "RJ",
"TaxNumber": "987654321",
"EnvironmentType": "Production",
"SpecialTaxRegime": "Nenhum",
"Type": "NFCe",
"Serie": 1,
"Number": 200,
"Series": [1],
"SecurityCredential": {
"Id": 1,
"Code": "ABC123..."
},
"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:

GET /v2/companies/{company_id}/statetaxes?limit=20&startingAfter=stx_002

Respostas de Erro

StatusDescrição
400 Bad RequestParâmetros inválidos
404 Not FoundEmpresa ou cursor não encontrado

Exemplo cURL

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

Consultar Inscrição Estadual por ID

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

GET /v2/companies/{company_id}/statetaxes/{state_tax_id}

Parâmetros de Rota

ParâmetroTipoDescrição
company_idstringID da empresa
state_tax_idstringID da inscrição estadual

Headers

HeaderValor
Acceptapplication/json
Authorization<sua_api_key>

Resposta de Sucesso

Status: 200 OK

{
"StateTax": {
"Id": "stx_001",
"CompanyId": "company_abc123",
"AccountId": "acct_12345",
"Status": "Active",
"Code": "SP",
"TaxNumber": "123456789",
"EnvironmentType": "Production",
"SpecialTaxRegime": "Nenhum",
"Type": "NFe",
"Serie": 1,
"Number": 1500,
"Series": [1, 2],
"SecurityCredential": null,
"ProcessingDetails": {
"SwitchAuthorizerStrategy": "Manual",
"AuthorityStatus": "Available",
"StatusOn": "2024-02-20T14:45:00Z",
"LastSwitchAuthorizerDetails": {
"FromAuthorizer": "EPEC",
"ToAuthorizer": "Normal",
"Reason": "Retorno à operação normal",
"ModifiedOn": "2024-02-20T14:45:00Z"
}
},
"CreatedOn": "2024-01-15T10:30:00Z",
"ModifiedOn": "2024-02-20T14:45:00Z"
}
}

Respostas de Erro

StatusDescrição
400 Bad RequestID inválido
404 Not FoundInscrição não encontrada
{
"Errors": [
{
"Code": 40041,
"Message": "state tax not found"
}
]
}

Exemplo cURL

curl -X GET https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001 \
-H "Authorization: sk_live_xxx"

Alterar Inscrição Estadual

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

PUT /v2/companies/{company_id}/statetaxes/{state_tax_id}

Parâmetros de Rota

ParâmetroTipoDescrição
company_idstringID da empresa
state_tax_idstringID da inscrição estadual

Headers

HeaderValor
Content-Typeapplication/json
Authorization<sua_api_key>

Corpo da Requisição

{
"StateTax": {
"TaxNumber": "123456789",
"EnvironmentType": "Production",
"Serie": 2,
"Number": 1
}
}

Campos Atualizáveis

CampoTipoDescrição
CodeenumCódigo do Estado (UF)
TaxNumberstringNúmero da Inscrição Estadual
EnvironmentTypeenumAmbiente de processamento
SpecialTaxRegimeenumRegime especial de tributação
TypeenumTipo de emissão
SerieintSérie atual
NumberlongPróximo número da série
SecurityCredentialobjectCredenciais de segurança (NFC-e)
ProcessingDetails.SwitchAuthorizerStrategyenumEstratégia de troca de autorizador

Resposta de Sucesso

Status: 200 OK

{
"StateTax": {
"Id": "stx_001",
"CompanyId": "company_abc123",
"AccountId": "acct_12345",
"Status": "Active",
"Code": "SP",
"TaxNumber": "123456789",
"EnvironmentType": "Production",
"SpecialTaxRegime": "Nenhum",
"Type": "NFe",
"Serie": 2,
"Number": 1,
"Series": [1, 2],
"SecurityCredential": null,
"ProcessingDetails": {
"SwitchAuthorizerStrategy": "Manual",
"AuthorityStatus": "Available",
"StatusOn": "2024-02-20T14:45:00Z",
"LastSwitchAuthorizerDetails": null
},
"CreatedOn": "2024-01-15T10:30:00Z",
"ModifiedOn": "2024-03-10T16:20:00Z"
}
}

Respostas de Erro

StatusDescrição
400 Bad RequestDados inválidos
404 Not FoundInscrição não encontrada

Exemplo cURL

curl -X PUT https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001 \
-H "Authorization: sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"StateTax": {
"Serie": 2,
"Number": 1
}
}'

Excluir Inscrição Estadual

Exclui uma inscrição estadual da empresa.

Atenção

Este processo é irreversível. Histórico de numeração será perdido.

DELETE /v2/companies/{company_id}/statetaxes/{state_tax_id}

Parâmetros de Rota

ParâmetroTipoDescrição
company_idstringID da empresa
state_tax_idstringID da inscrição estadual

Headers

HeaderValor
Authorization<sua_api_key>

Resposta de Sucesso

Status: 204 No Content

(Sem corpo na resposta)

Respostas de Erro

StatusDescrição
400 Bad RequestID inválido
404 Not FoundInscrição não encontrada

Exemplo cURL

curl -X DELETE https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001 \
-H "Authorization: sk_live_xxx"

Trocar Autorizador (Switch Authorizer)

Altera o autorizador da inscrição estadual, útil para operações de contingência.

POST /v2/companies/{company_id}/statetaxes/{state_tax_id}/switch-authorizer

Parâmetros de Rota

ParâmetroTipoDescrição
company_idstringID da empresa
state_tax_idstringID da inscrição estadual

Headers

HeaderValor
Content-Typeapplication/json
Authorization<sua_api_key>

Corpo da Requisição

{
"Authorizer": "EPEC",
"Reason": "SEFAZ indisponível - ativando contingência EPEC"
}

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
AuthorizerenumNovo autorizador (Normal ou EPEC)
Reasonstring✅*Motivo da troca (obrigatório para EPEC, 15-256 caracteres)
nota

O campo Reason é obrigatório quando Authorizer = EPEC e deve ter entre 15 e 256 caracteres.

Resposta de Sucesso

Status: 200 OK

{
"FromAuthorizer": "Normal",
"ToAuthorizer": "EPEC",
"Reason": "SEFAZ indisponível - ativando contingência EPEC",
"ModifiedOn": "2024-01-20T15:30:00Z"
}

Respostas de Erro

StatusDescrição
400 Bad RequestDados inválidos
404 Not FoundInscrição não encontrada

Exemplo cURL

curl -X POST https://api.nfse.io/v2/companies/company_abc123/statetaxes/stx_001/switch-authorizer \
-H "Authorization: sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"Authorizer": "EPEC",
"Reason": "SEFAZ indisponível - ativando contingência EPEC"
}'

Exemplo PowerShell

$headers = @{ Authorization = "sk_live_xxx" }
$body = @{
Authorizer = "EPEC"
Reason = "SEFAZ indisponível - ativando contingência EPEC"
} | ConvertTo-Json

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

Fluxo de Contingência

Ativar Contingência EPEC

Quando a SEFAZ está indisponível:

1. Detectar indisponibilidade da SEFAZ

2. POST /switch-authorizer com Authorizer="EPEC"

3. Emitir NF-e em contingência EPEC

4. Quando SEFAZ voltar: POST /switch-authorizer com Authorizer="Normal"

Consultar Histórico de Trocas

O histórico da última troca está disponível em ProcessingDetails.LastSwitchAuthorizerDetails:

{
"ProcessingDetails": {
"SwitchAuthorizerStrategy": "Manual",
"AuthorityStatus": "Available",
"StatusOn": "2024-02-20T14:45:00Z",
"LastSwitchAuthorizerDetails": {
"FromAuthorizer": "EPEC",
"ToAuthorizer": "Normal",
"Reason": "Retorno à operação normal",
"ModifiedOn": "2024-01-20T08:00:00Z"
}
}
}

Estratégia Automática

Configure ProcessingDetails.SwitchAuthorizerStrategy como StateTaxAuthorityStatusUnavailable para que o sistema troque automaticamente para contingência quando a SEFAZ estiver indisponível.


Regras de Validação

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

Dados da Inscrição Estadual

CampoRegraMensagem de Erro
StatusInscrição deve estar ativa para alteraçõesstate tax is not active
CodeObrigatório, deve ser UF válida (exceto EX e NA)state code is not valid
TaxNumberObrigatório, deve ser IE válida para o estadotax number is not valid
SerieDeve ser entre 1 e 999serie is not valid

Validação de NFC-e

CampoRegraMensagem de Erro
SecurityCredentialObrigatório quando Type = NFCeSecurity credential is not valid
SecurityCredential.IdDeve ser maior que 0Security credential is not valid
SecurityCredential.CodeNão pode ser vazioSecurity credential is not valid

Validação de Contingência

CampoRegraMensagem de Erro
ReasonObrigatório para EPEC, 15-256 caracteresreason must be between 15 and 256 characters for contingency authorizer

Códigos de Erro

Validação de Dados

CódigoMensagemDescrição
40002state tax is not activeInscrição inativa não permite alterações
40003tax number is not validInscrição Estadual inválida para o estado

Validação de Empresa

CódigoMensagemDescrição
40035account id is null or emptyAccountId não informado
40037company id is null or emptyCompanyId não informado
40040request state is nullPayload da inscrição estadual nulo
40041company not foundEmpresa não encontrada
40042company is not available to issueEmpresa inativa
40043account id is not valid to this companyAccountId não corresponde à empresa

Validação de Inscrição Estadual

MensagemDescrição
state tax id is null or emptyStateTaxId não informado
state tax not foundInscrição estadual não encontrada
account id is not valid to this state taxAccountId não corresponde à inscrição
company id is not valid to this state taxCompanyId não corresponde à inscrição
state code is not validCódigo do estado inválido
serie is not validSérie fora do intervalo permitido
Security credential is not validCredencial de segurança inválida

Enums

StateCode (Código do Estado)

NomeDescrição
ACAcre
ALAlagoas
APAmapá
AMAmazonas
BABahia
CECeará
DFDistrito Federal
ESEspírito Santo
GOGoiás
MAMaranhão
MTMato Grosso
MSMato Grosso do Sul
MGMinas Gerais
PAPará
PBParaíba
PRParaná
PEPernambuco
PIPiauí
RJRio de Janeiro
RNRio Grande do Norte
RSRio Grande do Sul
RORondônia
RRRoraima
SCSanta Catarina
SPSão Paulo
SESergipe
TOTocantins

EnvironmentType (Ambiente)

NomeValorDescrição
Test0Homologação (padrão)
Production1Produção (emissão real)

Status

NomeValorDescrição
Inactive-1Inativa (excluída/desativada)
None0Não definido
Active1Ativa (permite operações)

StateTaxType (Tipo de Emissão)

NomeValorDescrição
Default0Padrão
NFe1NF-e - Nota Fiscal Eletrônica
NFCe2NFC-e - Nota Fiscal de Consumidor Eletrônica

SpecialTaxRegime (Regime Especial de Tributação)

NomeValorDescrição
Automatico-1Automático
Nenhum0Sem regime especial
MicroempresaMunicipal1Microempresa municipal
Estimativa2Regime de estimativa
SociedadeDeProfissionais3Sociedade de profissionais
Cooperativa4Cooperativa
MicroempreendedorIndividual5MEI
MicroempresarioEmpresaPequenoPorte6ME/EPP

StateTaxProcessingAuthorizer (Autorizador)

NomeValorDescrição
Normal1SEFAZ normal
EPEC4Contingência EPEC (Evento Prévio de Emissão em Contingência)

StateTaxProcessingSwitchAuthorizerStrategy (Estratégia de Troca)

NomeValorDescrição
Manual0Troca manual
StateTaxAuthorityStatusUnavailable1Troca automática quando SEFAZ indisponível

StateTaxAuthorityStatus (Status da SEFAZ)

NomeValorDescrição
Paused-2Pausada
Unavailable-1Indisponível
Unknown0Desconhecido
Available1Disponível

Boas Práticas

Numeração de Séries

  • Use séries sequenciais simples (1, 2, 3)
  • Mantenha controle do último número usado
  • Não reutilize números dentro da mesma série
  • Ao mudar de série, inicie a numeração em 1

Validação de Inscrição Estadual

  • Valide o formato da IE antes de enviar
  • O sistema valida automaticamente a IE para a maioria dos estados
  • Alguns estados (GO, PA) têm validação simplificada

Contingência

  • Monitore a disponibilidade da SEFAZ
  • Tenha um plano de contingência documentado
  • O motivo da contingência deve ter entre 15 e 256 caracteres
  • Registre o motivo de cada troca de autorizador
  • Retorne ao modo normal assim que possível

Múltiplas Inscrições

  • Uma empresa pode ter inscrições em diferentes estados
  • Cada inscrição possui séries independentes
  • Gerencie a numeração de cada estado separadamente

NFC-e

  • O CSC (Código de Segurança do Contribuinte) é obrigatório
  • Obtenha o CSC junto à SEFAZ do estado
  • Mantenha o CSC seguro e não compartilhe

Próximos Passos

Após criar a inscrição estadual:

  1. Configure o certificado digital correspondente ao CNPJ → Ver documentação
  2. Inicialize a numeração da série conforme necessário
  3. Configure a estratégia de contingência se desejar troca automática
  4. Comece a emitir NF-e ou NFC-e

Para emissão de NFS-e, crie uma Inscrição Municipal.


Veja também:

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.