Sistema Terra

Módulo NFS-e

Criciúma, junho de 2024

1
Controle de Versão

Versão Data Alteração Responsável Observações

1.0.0.0 17/03/2021 Enoque Criação do documento
1.0.0.1 06/04/2021 Edison Efetuada alteração na estrutura de dados dos serviços Gerar, Cancelar,
Substituir e Consultar
1.0.0.2 28/04/2021 Edison Disponibilizado informações para Homologação
1.0.0.3 29/06/2021 Edison Disponibilizados exemplos da formatação do arquivo JSON
1.0.0.4 21/07/2021 Edison Ajustado o tamanho da Observação no serviço de Geração da NFS-e
1.0.0.5 09/08/2021 Edison - Incluído o campo “Codigo de Validação” no JSON de retorno da
consulta da NFS-e
- Removido o campo ValorTotalTributos do layout de Geração da NFS-e.
- Removido o campo ValorLiquidoNota do layout de Geração da NFS-e.
1.0.0.6 08/09/2021 Edison Adicionado novo parâmetro no serviço de Consulta: NumeroRps
1.0.0.7 04/01/2022 Edison Ajuste no tamanho da descrição do serviço
1.0.0.8 22/03/2022 Edison - Disponibilizado novo serviço para recuperar o número do último rps
enviado
- Incluído o campo “LinkNfse” no JSON de retorno da consulta da NFS-e
- Incluído hora, minutos e segundos no campo “DataEmissao” no JSON
de retorno da consulta da NFS-e
- Efetuado ajuste na hierarquia da descrição dos campos
1.0.0.9 20/04/2022 Edison Efetuado ajuste nos códigos de retorno HTTP (Status Code)
1.0.1.0 20/04/2022 Edison Alterado o número de casas decimais no campo 1.10.13 - Alíquota do
serviço prestado de 2 dígitos para 4 dígitos.
1.0.1.1 21/06/2022 Edison Removida a obrigatoriedade do campo 1.10.15 – Valor do Crédito.
1.0.1.2 01/07/2022 Edison Nova validação. O valor total dos itens deve ser compatível com o
campo Valores » ValorServicos.
1.0.1.3 06/07/2022 Edison Incluído novo campo 1.5.3 chamado “CodigoLc116” no layout de
geração da NFS-e.
1.0.1.4 27/12/2022 Edison Incluídos dois novos campos no layout de geração da NFS-e:
1.7.6 – “InscricaoEstadual” - Inscrição estadual do tomador
1.7.7 – “InscricaoMunicipal” – Inscrição municipal do tomador
1.0.1.5 22/04/2023 Edison Adicionadas informações a respeito da atividade no JSON de consulta da
NFS-e.
1.0.1.6 13/06/2023 Edison Tornado o campo 1.7.4.1 – “Logradouro” obrigatório.
1.0.1.7 02/04/2024 Edison Aumentando o tamanho do campo 1.7.4.1 – “Logradouro” para 125.
1.0.1.8 07/06/2024 Edison - Disponibilizado novo serviço para retornar o XML das notas fiscais de
serviço em lote.
- Incluído um novo campo chamado “XmlCompactado” no JSON de
retorno da consulta da NFS-e.

2
Sumário
1 - Introdução....................................................................................................................................................... 5
2 - Considerações Iniciais ...................................................................................................................................... 6
2.1 - Nota Fiscal de Serviços Eletrônica (NFS-e) ................................................................................................... 6
2.2 - Recibo Provisório de Serviço (RPS).............................................................................................................. 6
3 - Arquitetura da Solução..................................................................................................................................... 7
3.1 – Ambiente de Homologação ....................................................................................................................... 7
3.2 – Ambiente de Produção ............................................................................................................................. 8
4 - Serviços Disponibilizados .................................................................................................................................. 9
4.1 - Gerar NFS-e .............................................................................................................................................10
4.1.1. Request: Exemplo da formatação do arquivo JSON ...................................................................................13
4.1.2. Response com sucesso ............................................................................................................................15
4.1.3. Response com erros................................................................................................................................15
4.2 - Cancelar NFS-e .........................................................................................................................................16
4.2.1. Request: Exemplo da formatação do arquivo JSON ..................................................................................16
4.2.2. Response com sucesso ...........................................................................................................................17
4.2.3. Response com erros...............................................................................................................................17
4.3 - Substituir NFS-e........................................................................................................................................18
4.3.1. Request: Exemplo da formatação do arquivo JSON ..................................................................................18
4.3.2. Response com sucesso ...........................................................................................................................19
4.3.3. Response com erros...............................................................................................................................19
4.4. Consultar NFS-e ........................................................................................................................................20
4.4.1. Response com sucesso ............................................................................................................................21
4.4.2. Response com erros................................................................................................................................23
4.5. Recuperar número do último RPS enviado ..................................................................................................24
4.5.1. Response com sucesso ............................................................................................................................24
4.5.2. Response com erros................................................................................................................................24
4.6. Consultar XML da NFS-e.............................................................................................................................25
4.6.1. Response com sucesso ............................................................................................................................26
4.6.2. Response com falha................................................................................................................................27

3
1 - Introdução

Este manual tem como objetivo apresentar as especificações e critérios técnicos necessários para
utilização do Web Service disponibilizado pela Administração Tributária Municipal para as empresas
prestadoras e/ou tomadoras de serviços.

Utilizando o Web Service as empresas poderão integrar seus próprios sistemas de informações com o
Sistema de Notas Fiscais de Serviço Eletrônicas da Administração Tributária Municipal. Desta forma,
consegue-se automatizar o processo de geração, consulta e cancelamento de NFS-e.

4
2 - Considerações Iniciais

2.1 - Nota Fiscal de Serviços Eletrônica (NFS-e)

A Nota Fiscal de Serviços Eletrônica (NFS-e) é um documento de existência exclusivamente digital,

gerado e armazenado eletronicamente pela Administração Tributária Municipal ou por outra entidade
conveniada, para documentar as operações de prestação de serviços.

A geração da NFS-e será feita, automaticamente, por meio de serviços informatizados, disponibilizados
aos contribuintes. Para que sua geração seja efetuada, dados que a compõem serão informados,
analisados, processados, validados e, se corretos, gerarão o documento.

A responsabilidade pelo cumprimento da obrigação acessória de emissão da NFS-e e pelo correto

fornecimento dos dados à Administração Tributária Municipal, para a geração da NFS-e, é do contribuinte.

A NFS-e somente será gerada com a utilização dos serviços informatizados disponibilizados pelas
Administrações Tributárias Municipais. Esse tipo de serviço pressupõe riscos inerentes à ininterrupta
disponibilidade, podendo, eventualmente, em alguns momentos tornar-se indisponível.

2.2 - Recibo Provisório de Serviço (RPS)

Visando manter as atividades dos contribuintes ininterruptas, independente de os serviços

informatizados disponibilizados pelas Administrações Tributárias Municipais estarem disponíveis, será
disponibilizado o uso do Recibo Provisório de Serviços (RPS), que é um documento de posse e
responsabilidade do contribuinte, que deverá ser gerado manualmente ou por alguma aplicação local,
possuindo uma numeração sequencial crescente e devendo ser convertido em NFS-e no prazo estipulado
pela legislação tributária municipal.

5
3 - Arquitetura da Solução

Utilizando Web Service, o Sistema de Notas Fiscais de Serviço Eletrônicas da Administração Tributária
Municipal disponibilizará serviços que poderão ser acessados pelos sistemas dos contribuintes.

Para cada serviço oferecido existirá uma chamada específica. O fluxo de comunicação é sempre
iniciado pelo software que está realizando a operação, através do envio de uma mensagem ao servidor da
Administração Tributária Municipal, com a solicitação do serviço desejado. O servidor da Administração
Tributária Municipal devolve uma mensagem de resposta confirmando o recebimento da solicitação do
serviço na mesma conexão, de forma síncrona, juntamente com o resultado da solicitação do serviço.

O servidor da Administração Tributária Municipal adota o padrão REST para a comunicação entre
sistemas, utilizando o modelo JSON como padrão de dados.

Todas as chamadas ao servidor da Administração Tributária Municipal devem obedecer ao padrão

REST, utilizando os métodos HTTP especificados em cada serviço, para realizar as chamadas previstas neste
manual.

Cada chamada realizada ao servidor da Administração Tributária Municipal deverá conter em seu
Header a indicação dos três parâmetros abaixo descritos:

1. Authorization: SecurityKey1
2. Content-Type: application/json
3. Accept: application/json

O servidor da Administração Tributária Municipal será disponibilizado em um endpoint para cada órgão
onde o sistema estiver instalado, conforme especificação dos ambientes a seguir.

1 Chave de segurança disponibilizada pela Administração Tributária Municipal (Token)

6
3.1 – Ambiente de Homologação

O ambiente para homologação pode ser acessado através dos dados abaixo:
Web: https://homologacao.prefeituramoderna.com.br/meuiss_new/nfe/
Usuário: 1223
Senha: 123

Para utilizar os serviços da API no ambiente de homologação, deve-se utilizar os seguintes dados:
EndPoint: https://api-nfse-homologacao.prefeituramoderna.com.br/ws/services/nome_do_servico
SecurityKey: 9f16d93554dc1d93656e23bd4fc9d4566a4d76848517634d7bcabd5731e4948f

3.2 – Ambiente de Produção

O ambiente para produção pode ser acessado através dos dados abaixo:
Web: https://prefeituramoderna.com.br
Usuário: Fornecido pela Administração Tributária Municipal
Senha: Fornecido pela Administração Tributária Municipal

Para utilizar os serviços da API no ambiente de produção, deve-se utilizar os seguintes dados:
EndPoint: https://api-nfse-nomedomunicipio-uf.prefeituramoderna.com.br/ws/services/nome_do_servico
SecurityKey: Fornecido pela Administração Tributária Municipal

O Token API pode ser verificado, acessando o portal do ambiente de produção, na opção de menu
Token API.

7
4 - Serviços Disponibilizados

Nome URL Método Tipo

Geração de NFS-e /gerar POST Síncrono
Cancelamento de NFS-e /cancelar POST Síncrono
Substituição de NFS-e /substituir POST Síncrono
Consulta de NFS-e /consultar GET Síncrono
Retorna o número do último RPS enviado /ultimorpsenviado GET Síncrono
Consulta XML da NFS-e /xmlnfse GET Síncrono

Para cada serviço será apresentado o detalhamento da estrutura dos dados que serão utilizados. A
tabela será apresentada com as colunas abaixo:

• Item: Identifica em qual lugar da estrutura o campo em questão se encontra.

• Campo: Nome do campo.
• Descrição: Descrição detalhada da informação que estará presente no campo.
• Tipo: Identificação do tipo de dados utilizado.
▪ C: Caractere - Será identificado com o tamanho do campo. Ex: C (10).
▪ N: Numérico - Será identificado com o tamanho do campo e, se houver, a quantidade de
casas decimais. Ex: N (9), N (15, 2).
Campos numéricos nunca devem iniciar com 0, pois invalida o JSON, Ex.:
CEP: 04634-042 deverá ser informado como 4634042
▪ D: Data / Hora.
• Oc. : Identificação da quantidade de ocorrências do campo. Esta coluna também será utilizada para
determinar a obrigatoriedade de um campo.
▪ 0-1: Determina que o mínimo de ocorrências para o campo é 0 (zero), ou seja, não
obrigatório, e o máximo de ocorrências para o campo é 1 (um).
▪ 0-N: Determina que o mínimo de ocorrências para o campo é 0 (zero), ou seja, não
obrigatório, e que a quantidade máxima não está definida, sendo aceito quantos itens
forem necessários.

8
 ▪ 1-1: Determina que o mínimo de ocorrências para o campo é 1 (um), ou seja, obrigatório, e
o máximo de ocorrências para o campo é 1 (um).
▪ 1-N: Determina que o mínimo de ocorrências para o campo é 1 (um), ou seja, obrigatório, e
que a quantidade máxima não está definida, sendo aceito quantos itens forem necessários.
• Gerado: Indica quem é o responsável por gerar a informação (Prefeitura, Contribuinte ou Ambos).

4.1 - Gerar NFS-e

Esse serviço compreende a recepção do RPS, realizando as validações necessárias do RPS e a geração
da NFS-e, e retornando uma mensagem com o resultado do processamento do serviço, seja ele com a
estrutura da NFS-e gerada ou com a mensagem de erro.

Estrutura dos Dados da Nota Fiscal Eletrônica

Item Campo Descrição Tipo Oc. Gerado

1 Dados da Nota Fiscal DadosNota (1-1)
1.1 MunicipioPrestacao Código do município onde o serviço foi N (7) 1-1 Contr.
prestado (Tabela do IBGE), se exterior
deve-se informar 9999999
1.2 NaturezaOperacao Natureza da operação N(1) 1-1 Contr.

1-Tributação no município
2-Tributação fora do município
3-Isento; Enquadrado no MEI; Paga ISS
Fixo
4-Imune
5-Exigibilidade suspensa por decisão
judicial
6-Exigibilidade suspensa por decisão
administrativo.
1.3 IssRetido ISS Retido na fonte C (1) 1-1 Contr.

S - Sim
N - Não
1.4 Observacoes Observações da NFSe C (255) 0-1 Contr.
1.5 Atividade do Serviço Prestado Atividade (1-1)
1.5.1 Codigo Identificação da atividade envolvida (A N (15) 1-1 Contr.
empresa cadastrada no Município deverá
retirar os códigos de suas atividades
junto a Prefeitura, setor de ISS, e
repassá-los a empresa produtora do

9
 software).
1.5.2 CodigoCnae Código CNAE 2.0. Informar somente C(7) 1-1 Contr.
números.
Ex.: CNAE: 0220-9/01 informar 0220901
1.5.3 CodigoLc116 Código da LC-116. Informar somente N(4) 0-1 Contr.
números, omitindo zeros a esquerda.
Ex.: LC “07.02” informar 702
LC “14.01” informar 1401
1.6 Prestador do Serviço Prestador (1-1)
1.6.1 InscricaoMunicipal Inscrição municipal do prestador N(15) 1-1 Contr.
1.7 Tomador do Serviço Tomador (1-1)
1.7.1 TipoPessoa Tipo de pessoa do tomador C (1) 1-1 Contr.

F - Física
J- Jurídica
E - Exterior
1.7.2 NrDocumento Número do documento de identificação C (14) 1-1 Contr.
do tomador

Física – CPF
Jurídica - CNPJ
Exterior - NIF
1.7.3 RazaoSocial Razão social do tomador C (100) 1-1 Contr.
1.7.4 Endereço do Tomador do Serviço Endereco (1-1)
1.7.4.1 Logradouro Tipo e nome do logradouro do tomador C (125) 1-1 Contr.
1.7.4.2 Numero Número do imóvel do tomador C (10) 0-1 Contr.
1.7.4.3 Complemento Complemento do endereço do tomador C (60) 0-1 Contr.
1.7.4.4 Bairro Bairro do endereço do tomador C (60) 0-1 Contr.
1.7.4.5 Municipio Código do município do tomador (Tabela N (7) 1-1 Contr.
do IBGE) , se exterior deve-se informar
9999999
1.7.4.6 Cep Número do CEP do tomador N (8) 0-1 Contr.
1.7.5 Contato do Tomador do Serviço Contato (0-1)
1.7.5.1 Telefone Número do telefone do tomador C (20) 0-1 Contr.
1.7.5.2 Email E-Mail do tomador C (100) 0-1 Contr.
1.7.6 InscricaoEstadual Inscrição estadual do tomador C (20) 0-1 Contr.
1.7.7 InscricaoMunicipal Inscrição municipal do tomador C (20) 0-1 Contr.
1.8 Dados do RPS Rps (1-1)
1.8.1 Numero Número sequencial do RPS N (15) 1-1 Contr.
1.8.2 Serie Série do RPS N (5) 1-1 Contr.
1.8.3 Tipo Tipo do RPS N (1) 1-1 Contr.

1 - Recibo Provisório de Serviços

2 - RPS Nota Fiscal Conjugada (Mista)
3 - Cupom

10
1.8.4 DataEmissao Data da emissão do RPS. Formato AAAA- D 1-1 Contr.
MM-DD
1.9 Serviços Prestados Servicos (1-N)
1.9.1 Unidade Unidade de medida do serviço prestado C (3) 1- Contr.
N
1.9.2 Quantidade Quantidade de serviços prestados N (15, 4) 1- Contr.
N
1.9.3 Descricao Descrição do serviço prestado C (**) 1- Contr.
N
1.9.4 ValorUnitario Valor unitário do serviço prestado N (15, 4) 1- Contr.
N
1.10 Valores da Nota Valores (1-1)
1.10.1 ValorServicos Valor total dos serviços prestados N (15, 2) 1-1 Contr.
1.10.2 ValorDeducoes Valor das deduções pra redução da base N (15, 2) 1-1 Contr.
de cálculo
1.10.3 ValorOutrasDeducoes Valor de outras deduções da nota N(15,2) 1-1 Contr.
1.10.4 ValorPis Valor da retenção do PIS N (15, 2) 1-1 Contr.
1.10.5 ValorCofins Valor da retenção do COFINS N (15, 2) 1-1 Contr.
1.10.6 ValorInss Valor da retenção do INSS N (15, 2) 1-1 Contr.
1.10.7 ValorIr Valor da retenção do IR N (15, 2) 1-1 Contr.
1.10.8 ValorCsll Valor da retenção do CSLL N (15, 2) 1-1 Contr.
1.10.9 OutrasRetencoes Outras retenções na fonte N (15, 2) 1-1 Contr.
1.10.10 DescontoIncondicionado Valor do desconto incondicionado N (15, 2) 1-1 Contr.
1.10.11 DescontoCondicionado Valor do desconto condicionado N (15, 2) 1-1 Contr.
1.10.12 BaseCalculo Valor da base de cálculo N (15, 2) 1-1 Ambos
1.10.13 Aliquota Alíquota do serviço prestado N (15, 4) 1-1 Ambos
1.10.14 ValorIss Valor do ISS devido N (15, 2) 1-1 Ambos
1.10.15 ValorCredito Valor do crédito gerado N (15, 2) 0-1 Pref.
1.10.16 ValorTotalNota Valor total da nota N (15,2) 0-1 Contr.

** O tamanho do campo será limitado pelo tamanho da discriminação dos serviços. O campo da discriminação dos
serviços possui 2000 caracteres é composto por todas as informações relacionadas a cada serviço (Descrição,
Unidade, Quantidade, Valor unitário, Valor total) e pela observação da NFS-e.

11
4.1.1. Request: Exemplo da formatação do arquivo JSON

12
13
14
4.1.2. Response com sucesso

4.1.3. Response com erros

15
4.2 - Cancelar NFS-e

Este serviço é responsável por cancelar uma NFSe já emitida. Caso a NFSe não tenha sido gerada ou já
tenha sido cancelada, uma mensagem de retorno será enviada ao requisitante informando o fato.

Esta funcionalidade cancela apenas uma NFSe de cada vez, e não vincula este cancelamento a
nenhum RPS, assim como a nenhuma NFSe substituta.

Estrutura dos Dados do Cancelamento da Nota Fiscal Eletrônica

Item Campo Descrição Tipo Oc. Gerado

1 Dados da Nota Fiscal DadosNota (1-1)
1.1 Numero Número da NFSe a ser cancelada N (15) 1-1 Contr.
1.2 Dados do Cancelamento Cancelamento (1-1)
1.2.1 Motivo Motivo do Cancelamento da NFSe C (200) 1-1 Contr.
1.3 Prestador do Serviço Prestador (1-1)
1.3.1 InscricaoMunicipal Inscrição municipal do prestador N(15) 1-1 Contr.

4.2.1. Request: Exemplo da formatação do arquivo JSON

16
4.2.2. Response com sucesso

4.2.3. Response com erros

17
4.3 - Substituir NFS-e

Esta funcionalidade cancela apenas uma NFSe de cada vez, vinculando o número da nota substituta,
na nota cancelada.

Estrutura dos Dados da Substituição da Nota Fiscal Eletrônica

Item Campo Descrição Tipo Oc. Gerado

1 Dados da Nota Fiscal DadosNota (1-1)
1.1 Numero Número da NFSe a ser cancelada N (15) 1-1 Contr.
1.2 Substituta Número da NFSe emitida em N (15) 1-1 Contr.
substituição da atual
1.3 Dados do Cancelamento Cancelamento (1-1)
1.3.1 Motivo Motivo do Cancelamento da NFSe C (200) 1-1 Contr.
1.4 Prestador do Serviço Prestador (1-1)
1.4.1 InscricaoMunicipal Inscrição municipal do prestador N(15) 1-1 Contr.

4.3.1. Request: Exemplo da formatação do arquivo JSON

18
4.3.2. Response com sucesso

4.3.3. Response com erros

19
 4.4. Consultar NFS-e

Este serviço é responsável por consultar uma NFS-e já emitida. Esta funcionalidade consulta apenas
uma NFSe de cada vez. O usuário poderá consultar uma NFS-e informando o número da NFS-e ou o
número do RPS. O XML disponibilizado no campo “XmlCompactado” estará no padrão ZIP/Base64.

Estrutura dos Dados da Consulta da Nota Fiscal Eletrônica

Item Parâmetro Descrição Tipo Oc. Gerado

1 NumeroNfse Número da NFSe N (15) 0-1 Contr.
2 NumeroRps Número do RPS N(15) 0-1 Contr.

Exemplos:

GET /consultar?NumeroNfse=999

GET /consultar?NumeroRps=999

20
4.4.1. Response com sucesso

21
22
23
4.4.2. Response com erros

24
4.5. Recuperar número do último RPS enviado

Este serviço é responsável por retornar o número do último RPS enviado.

Exemplo:

GET /ultimorpsenviado

4.5.1. Response com sucesso

4.5.2. Response com erros

25
4.6. Consultar XML da NFS-e

Este serviço é responsável por retornar o XML das notas fiscais de serviços emitidas. A funcionalidade
retornará o XML de todas as notas fiscais de serviço encontradas de acordo com os parâmetros enviados.

O XML será disponibilizado no padrão ZIP/Base64.

As requisições serão paginadas e retornarão no máximo 100 registros por página. Quando houver
necessidade de buscar uma nova página, o parâmetro “nr_page” deverá ser informado na requisição.

Parâmetros disponíveis:

Estrutura dos Dados da Consulta da Nota Fiscal Eletrônica

Item Parâmetro Descrição Tipo Oc. Gerado

1 nr_inicial Número inicial da NFSe N (15) 0-1 Contr.
2 nr_final Número final da NFSe N(15) 0-1 Contr.
3 dt_inicial Período de emissão inicial da NFSe no C 0-1 Contr.
formato (YYYY-MM-DD)
4 dt_final Período de emissão final da NFSe no C 0-1 Contr.
formato (YYYY-MM-DD)
5 nr_competencia Competência da NFSe no formato N(6) 0-1 Contr.
YYYYMM
6 nr_page Número da página N(4) 0-1 Contr.

Exemplos:

GET /xmlnfse?nr_inicial=25&nr_final=50

GET /xmlnfse?dt_inicial=2024-01-15& dt_final=2024-01-30

GET /xmlnfse?dt_inicial=2024-01-15& dt_final=2024-01-30&nr_page=2

GET /xmlnfse?nr_competencia=202401

GET /xmlnfse?nr_competencia=202401&nr_page=3

26
4.6.1. Response com sucesso

27
4.6.2. Response com falha

28