Manual de Utilização Do Web Service - NFSe Blumenau

27/6/2013 Pgina 1 de 73

Nota Fiscal de Servios

Eletrnica - NFS-e

Manual de Utilizao do Web Service

Verso: 1.2

Para baixar a verso mais atualizada deste documento, acesse o link:

http://www.blumenau.sc.gov.br/nfse

Prefeitura Municipal de Blumenau Notas Fiscal de Servios Eletrnica (NFS-e) Manual de Utilizao do Web Service

27/6/2013 Pgina 2 de 73

ndice

1 INTRODUO ..................................................................................................................................................... 4

2 INTERFACES DISPONVEIS ............................................................................................................................... 5

2.1 ENVIO DE RPS ............................................................................................................................................... 5

2.2 ENVIO DE LOTE DE RPS .................................................................................................................................. 5

2.3 TESTE DE ENVIO DE LOTE DE RPS .................................................................................................................. 5

2.4 CONSULTA DE NFS-E ...................................................................................................................................... 5

2.5 CONSULTA DE NFS-E RECEBIDAS .................................................................................................................... 5

2.6 CONSULTA DE NFS-E EMITIDAS ....................................................................................................................... 5

2.7 CONSULTA DE LOTE ........................................................................................................................................ 6

2.8 CONSULTA INFORMAES DO LOTE ................................................................................................................. 6

2.9 CANCELAMENTO DE NFS-E ............................................................................................................................. 6

2.10 CONSULTA DE CNPJ ....................................................................................................................................... 6

3 ARQUITETURA DE COMUNICAO ................................................................................................................. 7

3.1 MODELO CONCEITUAL ..................................................................................................................................... 7

3.2 PADRES TCNICOS ....................................................................................................................................... 8

3.2.1 Padro de Comunicao ...................................................................................................................... 8

3.2.2 Padro de Certificado Digital ................................................................................................................ 8

3.2.3 Padro de Assinatura Digital ................................................................................................................ 9

3.2.4 Validao de Assinatura Digital pelo Sistema de NFS-e ................................................................... 11

3.2.5 Resumo dos Padres Tcnicos .......................................................................................................... 12

3.3 MODELO OPERACIONAL ................................................................................................................................. 13

3.3.1 Servios .............................................................................................................................................. 13

3.4 PADRO DAS MENSAGENS XML ..................................................................................................................... 14

3.4.1 Validao da estrutura das Mensagens XML ..................................................................................... 14

3.4.2 Schemas XML (arquivos XSD) ........................................................................................................... 15

3.4.3 Verso dos Schemas XML ................................................................................................................. 15

3.4.4 Regras de preenchimento dos campos .............................................................................................. 18

3.4.5 Tratamento de caracteres especiais no texto de XML ....................................................................... 19

4 WEB SERVICE LOTENFE ................................................................................................................................. 20

4.1 WSDL .......................................................................................................................................................... 21

4.2 TIPOS UTILIZADOS ......................................................................................................................................... 23

4.2.1 Tipos Simples ..................................................................................................................................... 23


27/6/2013 Pgina 3 de 73

4.2.2 Tipos Complexos ................................................................................................................................ 27

4.3 SERVIOS E MTODOS .................................................................................................................................. 33

4.3.1 Regras Gerais ..................................................................................................................................... 33

4.3.2 Envio de RPS...................................................................................................................................... 36

4.3.3 Envio de Lote de RPS (EnvioLoteRPS) ............................................................................................. 42

4.3.4 Teste de Envio de Lote de RPS (TesteEnvioLoteRPS) ..................................................................... 45

4.3.5 Pedido de Consulta de NFS-e (ConsultaNFe) ................................................................................... 46

4.3.6 Pedido de Consulta de NFS-e Recebidas (ConsultaNFeRecebidas) ................................................ 49

4.3.7 Pedido de Consulta de NFS-e Emitidas (ConsultaNFeEmitidas) ....................................................... 54

4.3.8 Pedido de Consulta de Lote (ConsultaLote) ....................................................................................... 56

4.3.9 Pedido de Informaes do Lote (ConsultaInformacoesLote) ............................................................. 58

4.3.10 Pedido de Cancelamento de NFS-e (CancelamentoNFe) ................................................................. 60

4.3.11 Pedido de Consulta de CNPJ (ConsultaCNPJ) .................................................................................. 64

4.4 TABELA DE ERROS E ALERTAS ....................................................................................................................... 66

4.4.1 Erros ................................................................................................................................................... 66

4.4.2 Alertas ................................................................................................................................................. 71

5 ARQUIVOS DE EXEMPLOS.............................................................................................................................. 72

ANEXO I ..................................................................................................................................................................... 73

TABELA DE MUNICPIOS ............................................................................................................................................. 73


27/6/2013 Pgina 4 de 73

1 INTRODUO

Este manual tem como objetivo apresentar a definio das especificaes e critrios tcnicos

necessrios para utilizao do Web Service disponibilizado pela Prefeitura de Blumenau para as

empresas prestadoras e/ou tomadoras de servios.

Atravs do Web Service as empresas podero integrar seus prprios sistemas de informaes com o

Sistema da Nota Fiscal de Servios Eletrnica da Prefeitura de Blumenau. Desta forma, consegue-se

automatizar o processo de emisso, consulta e cancelamento de NFS-e.


27/6/2013 Pgina 5 de 73

2 INTERFACES DISPONVEIS

Atravs do Web Service, o Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de Blumenau,

disponibiliza uma srie de interfaces que podero ser acessadas pelos sistemas dos contribuintes. A

seguir, esto resumidas as interfaces disponveis e suas respectivas funcionalidades bsicas.

2.1 ENVIO DE RPS

Atravs desta interface, os prestadores de servios podero enviar um RPS emitido por seu sistema

para que seja substitudo por uma Nota Fiscal de Servios Eletrnica. Esta interface destina-se aos

prestadores que desejam emitir NFS-e online e individualmente. Para emisses de grandes volumes

recomendamos a utilizao da interface Envio de Lote de RPS.

2.2 ENVIO DE LOTE DE RPS

Atravs desta interface, os prestadores de servios podero enviar lotes de RPS emitidos por seus

sistemas para que sejam substitudos por Nota Fiscal de Servios Eletrnica. Esta interface destina-se

aos prestadores que desejam emitir NFS-e ofline e em grandes volumes.

2.3 TESTE DE ENVIO DE LOTE DE RPS

O uso desta interface opcional. A interface de Envio de Lote de RPS faz exatamente as mesmas

verificaes, entretanto na interface de Teste, nenhuma NFS-e gerada. Esta interface dever ser

usada apenas na fase de adaptao dos sistemas dos contribuintes. Nos casos de sistemas j

adaptados, seu uso resulta em duplicidade de esforos desnecessrios.

2.4 CONSULTA DE NFS-E

Esta interface permite os prestadores de servios consultarem as NFS-e emitidas por ele.

2.5 CONSULTA DE NFS-E RECEBIDAS

Esta interface possibilita aos tomadores e/ou prestadores de servios consultarem as NFS-e que

tiverem sido emitidas para ele, possibilitando, por exemplo, a alimentao automtica de seu mdulo de

contas a pagar.

2.6 CONSULTA DE NFS-E EMITIDAS

Esta interface possibilita aos prestadores de servios consultarem as NFS-e que tiverem sido emitidas

por ele.


27/6/2013 Pgina 6 de 73

2.7 CONSULTA DE LOTE

Aps o envio bem sucedido de um Lote de RPS, o Web Service retorna diversas informaes, entre

elas o nmero do lote processado. Com esta interface, basta informar o nmero do lote desejado para

receber as informaes de todas as NFS-e geradas neste lote.

2.8 CONSULTA INFORMAES DO LOTE

Aps o envio bem sucedido de um Lote de RPS, o Web Service retorna diversas informaes, entre

elas o nmero do lote processado. Com esta interface, basta informar o nmero do lote desejado para

receber informaes resumidas: data/hora de envio do lote, quantidade de notas processadas, tempo

de processamento, etc...

Para ter informaes das notas processadas, deve-se usar a interface de Consulta de Lote.

2.9 CANCELAMENTO DE NFS-E

Com esta interface, os prestadores de servios podero cancelar as NFS-e emitidas por ele, informando

apenas os nmeros da NFS-e que devero ser cancelados.

2.10 CONSULTA DE CNPJ

Esta interface possibilita aos tomadores e/ou prestadores de servios consultarem quais Inscries

Municipais (CMC) esto vinculadas a um determinado CNPJ e se estes Contribuintes j emitem NFS-e.


27/6/2013 Pgina 7 de 73

3 ARQUITETURA DE COMUNICAO

3.1 MODELO CONCEITUAL

O Web Service do Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de Blumenau ir

disponibilizar as seguintes funcionalidades:

A. Envio de RPS;

B. Envio de Lote de RPS;

C. Teste de Envio de Lote de RPS;

D. Consulta de NFS-e;

E. Consulta de NFS-e Recebidas;

F. Consulta de NFS-e Emitidas;

G. Consulta de Lote;

H. Consulta de Informaes de Lote;

I. Cancelamento de NFS-e;

J. Consulta de CNPJ.

Existir um nico Web Service com todos os servios apresentados a cima. O fluxo de comunicao

sempre iniciado pelo sistema do contribuinte atravs do envio de uma mensagem XML ao Web Service

com o pedido do servio desejado.

O pedido de servio ser atendido na mesma conexo (todos os servios sero sncronos). O

processamento do pedido do servio concludo na mesma conexo, com a devoluo de uma

mensagem XML contendo o retorno do processamento do servio pedido;

O diagrama a seguir ilustra o fluxo conceitual de comunicao entre o sistema do contribuinte e o

Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de Blumenau:


27/6/2013 Pgina 8 de 73

3.2 PADRES TCNICOS

3.2.1 Padro de Comunicao

A comunicao entre os sistemas de informaes dos contribuintes e o Sistema de Nota Fiscal de

Servios Eletrnica da Prefeitura de Blumenau ser baseada em um Web Service disponibilizado no

Sistema de Nota Fiscal de Servios Eletrnica. O meio fsico de comunicao utilizado ser a Internet,

com o uso do protocolo SSL, que alm de garantir um duto de comunicao seguro na Internet, permite

a identificao do servidor e do cliente atravs de certificados digitais, eliminando a necessidade de

identificao do usurio atravs de nome ou cdigo de usurio e senha.

O modelo de comunicao segue o padro de Web Services definido pelo WS-I Basic Profile.

A troca de mensagens entre o Web Service do Sistema de Nota Fiscal de Servios Eletrnica da

Prefeitura de Blumenau e o sistema do contribuinte ser realizada no padro SOAP, com troca de

mensagens XML no padro Style/Enconding: Document/Literal, wrapped. A opo wrapped representa

a chamada aos mtodos disponveis com a passagem de mais de um parmetro.

3.2.2 Padro de Certificado Digital

Os certificados digitais utilizados no Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de

Blumenau sero emitidos por Autoridade Certificadora credenciada pela Infra-estrutura de Chaves

Pblicas Brasileira ICP-Brasil, tipo A1, A3 ou A4, devendo conter o CNPJ do proprietrio do certificado

digital.


27/6/2013 Pgina 9 de 73

Os certificados digitais sero exigidos no mnimo* em dois (2) momentos distintos:

A. Assinatura de Mensagens XML:

Quem pode assinar a Mensagem XML:

Todas as Mensagens XML podem ser assinadas pelo prprio contribuinte.

Neste caso o certificado digital utilizado dever conter o CNPJ do contribuinte

que gerou a mensagem XML;

As Mensagens XML de consulta de NFS-e Emitidas, NFS-e Recebidas e

Informaes de lote, podem ser assinadas pelo contador (desde que cadastrado

na tela de Configuraes do Perfil do Contribuinte) ou por um terceiro (ex.:

funcionrio da empresa contribuinte), desde que o contribuinte tenha concedido

a este permisso de acesso a consultas (atravs do menu Gerenciamento de

Usurios do Sistema de Nota Fiscal de Servios Eletrnica). Neste caso o

certificado digital utilizado dever conter o CPF/CNPJ do contador / usurio

autorizado.

Todas as mensagens XML devero conter o CPF/CNPJ de quem estar autorizado a efetuar a

sua transmisso (TAG CPFCNPJRemetente). No caso de as Mensagens XML serem

transmitidas por quem as gerou o CPF/CNPJ informado dever ser o do prprio.

B. Autenticao na transmisso das mensagens entre os servidores do contribuinte e da Prefeitura

de Blumenau: O certificado digital utilizado para identificar essa funo dever conter o

CPF/CNPJ do responsvel pela transmisso das mensagens. Este CPF/CNPJ dever ser o

mesmo que consta na TAG CPFCNPJRemetente da mensagem XML.

* Adicionalmente os certificados digitais tambm podero ser exigidos conforme a necessidade

especfica de cada servio (exemplo: itens 4.3.2 e 4.3.10).

3.2.3 Padro de Assinatura Digital

As mensagens enviadas ao Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de Blumenau

so documentos eletrnicos elaborados no padro XML e devem ser assinados digitalmente utilizando

certificado digital, descrito no item 3.2.2.


27/6/2013 Pgina 10 de 73

Os elementos abaixo esto presentes dentro do Certificado do contribuinte tornando desnecessria a

sua representao individualizada na mensagem XML. Portanto, a mensagem XML no deve conter os

elementos:

Analogamente, as TAGs abaixo no devero ser informadas, pois as informaes sero obtidas a partir

do Certificado do emitente:

Para o processo de assinatura, o contribuinte no deve fornecer a Lista de Certificados Revogados, j

que a mesma ser montada e validada pelo Sistema de Nota Fiscal de Servios Eletrnica da

Prefeitura de Blumenau.


27/6/2013 Pgina 11 de 73

A assinatura digital do documento eletrnico dever atender aos seguintes padres adotados:

A. Padro de assinatura: XML Digital Signature, utilizando o formato Enveloped

(http://www.w3c.org/TR/xmldsig-core/);

B. Certificado digital: Emitido por AC credenciada no ICP-Brasil

(http://www.w3c.org/2000/09/xmldsig#X509Data);

C. Cadeia de Certificao: EndCertOnly (Incluir na assinatura apenas o certificado do usurio final);

D. Tipo do certificado: A1, A3 ou A4 (o uso de HSM recomendado);

E. Tamanho da Chave Criptogrfica: Compatvel com os certificados A1 e A3 (1024bits) ou A4

(2048 bits);

F. Funo criptogrfica assimtrica: RSA (http://www.w3c.org/2000/09/xmldsig#rsa-sha1);

G. Funo de message digest: SHA-1 (http://www.w3c.org/2000/09/xmldsig#sha1);

H. Codificao: Base64 (http://www.w3c.org/2000/09/xmldsig#base64);

I. Transformaes exigidas: til para realizar a canonicalizao do XML enviado para realizar a

validao correta da Assinatura Digital. So elas:

(1) Enveloped (http://www.w3c.org/2000/09/xmldsig#enveloped-signature)

(2) C14N (http://www.w3c.org/TR/2001/REC-xml-c14n-20010315)

3.2.4 Validao de Assinatura Digital pelo Sistema de NFS-e

Para a validao da assinatura digital, seguem as regras que sero adotadas pelo Sistema de Nota

Fiscal de Servios Eletrnica da Prefeitura de Blumenau:

A. Extrair a chave pblica do certificado digital e no utilizar a chave indicada na TAG XML

(ds:KeyValue);

B. Verificar o prazo de validade do certificado utilizado;

C. Montar e validar a cadeia de confiana dos certificados validando tambm a LCR (Lista de

Certificados Revogados) de cada certificado da cadeia;

D. Validar o uso da chave utilizada (Assinatura Digital) de tal forma a aceitar certificados somente

do tipo A (no sero aceitos certificados do tipo S);

E. Garantir que o certificado utilizado de um usurio final e no de uma Autoridade Certificadora;

F. Adotar as regras definidas pelo RFC 3280 para LCRs e cadeia de confiana;

G. Validar a integridade de todas as LCR utilizadas pelo sistema;

H. Prazo de validade de cada LCR utilizada (verificar data inicial e final)

A forma de conferncia da LCR pelo Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de

Blumenau, pode ser feita de 2 (duas) maneiras: On-line ou Download peridico. As assinaturas digitais

das mensagens sero verificadas considerando o horrio fornecido pelo Observatrio Nacional.


27/6/2013 Pgina 12 de 73

3.2.5 Resumo dos Padres Tcnicos

A tabela a seguir resume os principais padres de tecnologia utilizados:

Caracterstica Descrio

Web Services Padro definido pelo WS-I Basic Profile 1.1 (http://www.ws-

i.org/Profiles/BasicProfile-1.1-2004-08-24.html).

Meio lgico de comunicao Web Service, disponibilizados pelo Sistema de NFS-e da

Prefeitura de Blumenau

Meio fsico de comunicao Internet

Protocolo Internet SSL verso 3.0, com autenticao mtua atravs de certificados

digitais.

Padro de troca de mensagens SOAP verso 1.2.

Padro da mensagem XML XML no padro Style/Encoding: Document/Literal, wrapped.

Padro de certificado digital X.509 verso 3, emitido por Autoridade Certificadora credenciada

pela Infra-estrutura de Chaves Pblicas Brasileira ICP-Brasil, do

tipo A1, A3 ou A4, devendo conter o CNPJ do proprietrio do

certificado digital.

Para assinatura de mensagens, utilizar o certificado digital do

estabelecimento emissor da NFS-e (no caso de Consulta de NFS-

e Recebidas utilizar o certificado digital do tomador).

Opcionalmente as Mensagens XML de consulta de NFS-e

Emitidas, NFS-e Recebidas e Informaes de lote, podem ser

assinadas pelo contador (desde que cadastrado na tela de

Configuraes do Perfil do Contribuinte) ou por um terceiro (ex.:

funcionrio da empresa contribuinte), desde que o contribuinte

tenha concedido a este permisso de acesso a consultas (atravs

do menu Gerenciamento de Usurios do Sistema de Nota Fiscal

de Servios Eletrnica). Neste caso o certificado digital utilizado

dever conter o CPF/CNPJ do contador / usurio autorizado.

Para autenticao, utilizar o certificado digital do responsvel pela

transmisso.

Padro de assinatura digital XML Digital Signature, Enveloped, com certificado digital X.509

verso 3, com chave privada de 1024 bits (A1 / A3) ou 2048 bits

(A4), com padres de criptografia assimtrica RSA, algoritmo

message digest SHA-1 e utilizao das transformaes


27/6/2013 Pgina 13 de 73

Enveloped e C14N.

Validao de assinatura digital Ser validado alm da integridade e autoria, a cadeia de

confiana com a validao das LCRs.

Padres de preenchimento XML Campos no obrigatrios do Schema que no possuam contedo tero suas tags suprimidas na mensagem XML.

Mscara de nmeros decimais e datas esto definidas no Schema XML.

Nos campos numricos inteiro, no incluir a vrgula ou ponto decimal.

Nos campos numricos com casas decimais, utilizar o ponto decimal na separao da parte inteira.

3.3 MODELO OPERACIONAL

Como dito anteriormente, a forma de processamento dos pedidos de servios do Web Service do

Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de Blumenau ser sncrona, atendo ao

pedido de servio na mesma conexo.

3.3.1 Servios

Os pedidos de servios so processados imediatamente e o resultado do processamento obtido em

uma nica conexo.

Abaixo, o fluxo simplificado de funcionamento:

Etapas do processo ideal:

1. O sistema do contribuinte inicia a conexo enviando uma mensagem XML de pedido do servio

para o Web Service;

2. O Web Service recebe a mensagem XML de pedido do servio e encaminha ao sistema da

NFS-e;

3. O sistema da NFS-e recebe a mensagem XML de pedido do servio e realiza o processamento*,

devolvendo uma mensagem XML de retorno ao Web Service;

4. O Web Service recebe a mensagem XML de retorno e a encaminha ao sistema do contribuinte;


27/6/2013 Pgina 14 de 73

5. O sistema do contribuinte recebe a mensagem XML de retorno e encerra a conexo.

3.4 PADRO DAS MENSAGENS XML

A especificao adotada para as mensagens XML a recomendao W3C para XML 1.0, disponvel em

www.w3.org/TR/REC-xml e a codificao dos caracteres ser em UTF-8.

3.4.1 Validao da estrutura das Mensagens XML

Para garantir minimamente a integridade das informaes prestadas e a correta formao das

mensagens XML, o contribuinte dever submeter cada uma das mensagens XML de pedido de servio

para validao pelo seu respectivo arquivo XSD (XML Schema Definition, definio de esquemas XML)

antes de seu envio. Neste manual utilizaremos a nomenclatura Schema XML para nos referir a arquivo

XSD.

Um Schema XML define o contedo de uma mensagem XML, descrevendo os seus atributos,

elementos e a sua organizao, alm de estabelecer regras de preenchimento de contedo e de

obrigatoriedade de cada elemento ou grupo de informao.

A validao da estrutura da mensagem XML realizada por um analisador sinttico (parser) que verifica

se a mensagem XML atende as definies e regras de seu respectivo Schema XML.

Qualquer divergncia da estrutura da mensagem XML em relao ao seu respectivo Schema XML,

provoca um erro de validao do Schema XML. Neste caso o contedo da mensagem XML de pedido

do servio no poder ser processado.

A primeira condio para que a mensagem XML seja validada com sucesso que ela seja submetida

ao Schema XML correto.

Assim, os sistemas de informao dos contribuintes devem estar preparados para gerar mensagens

XML em seus respectivos Schemas XML em vigor.


27/6/2013 Pgina 15 de 73

3.4.2 Schemas XML (arquivos XSD)

O Schema XML (arquivo XSD) correspondente a cada uma das mensagens XML de pedido e de retorno

utilizadas pelo Web Service LoteNFe pode ser obtido na internet acessando o Portal do Sistema de

Nota Fiscal de Servios Eletrnica da Prefeitura de Blumenau.

Para obter os Schemas XML do Web Service da NFS-e acione o navegador Web (Firefox, Internet

Explorer, por exemplo) e digite o endereo a seguir:

https://nfse.blumenau.sc.gov.br/ws/schemas.zip

3.4.3 Verso dos Schemas XML

Toda mudana de layout das mensagens XML do Web Service implica na atualizao do seu respectivo

Schema XML.

A identificao da verso dos Schemas XML ser realizada com o acrscimo do nmero da verso no

nome do arquivo XSD precedida da literal _v, como segue:

PedidoEnvioLoteRPS_v02.xsd (Schema XML de Envio de Lote de RPS, verso 2);

RetornoEnvioLoteRPS_v03.xsd (Schema XML do Retorno de Envio de Lote de RPS, verso 3);

TiposNFe_v01.xsd (Schema XML dos tipos bsicos da NFS-e, verso 1).

A maioria dos Schemas XML definidos para a utilizao do Web Service do Sistema de Nota Fiscal de

Servios Eletrnica da Prefeitura de Blumenau utiliza as definies de tipos simples ou tipos

complexos que esto definidos em outros Schemas XML (ex.: TiposNFe.xsd e xmldsig-core-

schema.xsd), nestes casos, a modificao de verso do Schema bsico ser repercutida no Schema

principal.

Por exemplo, o tipo RPS (tpRPS) utilizado no Schema PedidoEnvioLoteRPS_V04.xsd est definido no

Schema TiposNFe_V01.xsd, caso ocorra alguma modificao na definio deste tipo, e um

conseqente incremento da verso do Schema TiposNFe_V01.xsd para TiposNFe_V02.xsd o Schema

PedidoEnvioLoteRPS_V04.xsd (bem como todos os Schemas que utilizam o tipo RPS) deve ter a

declarao import atualizada com o nome do Schema TiposNFe_V02.xsd e a verso atualizada para

PedidoEnvioLoteRPS_V05.xsd


27/6/2013 Pgina 16 de 73

Exemplo de Schema XML de Pedido de Envio de Lote de RPS (arquivo PedidoEnvioLoteRPS_v01.xsd):

Schema utilizado para PEDIDO de envio de lote de RPS. Este Schema XML utilizado pelos prestadores de servios para substituio em lote de RPS por NFS-e. Cabealho do pedido. Informe o CPF/CNPJ do Remetente autorizado a transmitir a mensagem XML. Informe se os RPS a serem substitudos por NFS-e faro parte de uma mesma transao. True - Os RPS s sero substitudos por NFS-e se no ocorrer nenhum evento de erro durante o processamento de todo o lote; False - Os RPS vlidos sero substitudos por NFS-e, mesmo que ocorram eventos de erro durante processamento de outros RPS deste lote. Informe a data de incio do perodo transmitido (AAAA-MM-DD). Informe a data final do perodo transmitido (AAAA-MM-DD). Informe o total de RPS contidos na mensagem XML. Informe o valor total dos servios prestados dos RPS contidos na mensagem XML. Informe o valor total das dedues dos RPS contidos na mensagem XML.


27/6/2013 Pgina 17 de 73

Informe a Verso do Schema XML utilizado. Informe os RPS a serem substituidos por NFS-e. Assinatura digital emissor dos RPS.

As modificaes de layout das mensagens XML do Web Service podem ser causadas por necessidades

tcnicas ou em razo da modificao de alguma legislao. As modificaes decorrentes de alterao

da legislao devero ser implementadas nos prazos previstos no ato normativo que introduziu a

alterao. As modificaes de ordem tcnica sero divulgadas pela Prefeitura de Blumenau e podero

ocorrer sempre que se fizerem necessrias.


27/6/2013 Pgina 18 de 73

3.4.4 Regras de preenchimento dos campos

Campos que representam CPF e CNPJ (respectivamente 11 e 14 caracteres) devem ser

informados com o tamanho fixo previsto, sem formatao e com o preenchimento dos zeros no

significativos;

Campos numricos que representam valores e quantidades so de tamanho varivel,

respeitando o tamanho mximo previsto para o campo e a quantidade de casas decimais

(quando houver). O preenchimento de zeros no significativos causa erro de validao do

Schema XML.

Os campos numricos devem ser informados sem o separador de milhar, com uso do ponto

decimal para indicar a parte fracionria (quando houver) respeitando-se a quantidade de dgitos

prevista no layout;

As datas devem ser informadas no formato AAAA-MM-DD;

Para reduzir o tamanho final das mensagens XML alguns cuidados de programao devero ser

assumidos:

Na gerao das mensagens XML, excetuados os campos identificados como obrigatrios no

respectivo Schema XML, no incluir as TAGs de campos zerados (para campos tipo numrico)

ou vazios (para campos tipo caractere);

No incluir "espaos" no incio e/ou no final de campos alfanumricos;

No incluir comentrios na mensagem XML;

No incluir anotao e documentao na mensagem XML (TAG annotation e TAG

documentation);

No incluir caracteres de formatao na mensagem XML: LF (Line Feed ou salto de linha,

caractere ASCII 10), "CR" (Carriage Return ou retorno do carro, caractere ASCII 13), "tab",

caractere de "espao" entre as TAGs).


27/6/2013 Pgina 19 de 73

3.4.5 Tratamento de caracteres especiais no texto de XML

Todos os textos de uma mensagem XML passam por uma anlise do parser especfico da linguagem.

Alguns caracteres afetam o funcionamento deste parser, no podendo aparecer no texto de uma

forma no controlada. Estes caracteres devem ser substitudos conforme a tabela a seguir:

Caracteres que afetam o parser Descrio Substituir por

> Sinal de maior. >

< Sinal de menor. <

& e-comercial. &

Aspas. "

Sinal de apstrofe. '


27/6/2013 Pgina 20 de 73

4 WEB SERVICE LOTENFE

O Web Service LoteNFe, do Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de

Blumenau, disponibiliza os servios que sero utilizados pelos sistemas de informao dos

contribuintes. O mecanismo de utilizao do Web Service LoteNFe segue as seguintes premissas:

Ser disponibilizado um Web Service (LoteNFe) para todos os servios, existindo um mtodo Web para

cada tipo de servio.

Os servios disponibilizados sero sncronos, por tanto o envio da mensagem XML de pedido do

servio e a obteno da mensagem XML de retorno sero realizados na mesma conexo atravs de um

nico mtodo.

As mensagens XML de pedido de servio que excederem o tamanho limite previsto (500 KB) obtero

como retorno uma mensagem XML de erro. Por tanto os sistemas de informao dos contribuintes no

podero permitir a gerao de mensagens XML com tamanho superior a 500 KB.

Primeiramente cada mensagem XML de pedido de servio ser recebida pelo Web Service LoteNFe

para validao de seu respectivo Schema XML (arquivo XSD). Caso ocorram erros de validao do

Schema XML, o contedo da mensagem XML no ser processado e ser retornada uma mensagem

XML contendo o(s) erro(s) ocorrido(s).


27/6/2013 Pgina 21 de 73

4.1 WSDL

Para que os sistemas de informao dos contribuintes saibam quais parmetros enviar ao Web Service

LoteNFe e quais parmetros sero retornados, os contribuintes devero utilizar o arquivo WSDL (Web

Service Description Language, linguagem de descrio de servio Web). Trata-se de um arquivo XML

que configura como ocorrer a interao entre um Web Service e seus consumidores (sistemas de

informao dos contribuintes).

O WSDL uma linguagem baseada em XML, com a finalidade de documentar as mensagens XML que

o Web service aceita (pedidos de servio) e gera (retornos). Esse mecanismo padro facilita a

interpretao dos contratos pelos desenvolvedores e ferramentas de desenvolvimento.

Para enxergar o valor do WSDL, imagine que um contribuinte quer invocar um dos mtodos que

fornecido pelo Web Service LoteNFe. O contribuinte pode pedir alguns exemplos de mensagens XML

de pedido e de retorno e escrever sua aplicao para produzir e consumir mensagens XML que se

parecem com os exemplos, mas isso pode gerar muitos erros. Por exemplo, o contribuinte pode assumir

que um campo um inteiro, quando de fato uma string. O WSDL especifica o que a mensagem XML

de pedido deve conter e como vai ser a mensagem XML de retorno, em uma notao no ambgua.

A notao que o arquivo WSDL usa para descrever o formato das mensagens baseada no padro

XML, o que significa que uma linguagem de programao neutra e baseada em padres, o que a

torna adequada para descrever as interfaces dos Web services, que so acessveis por uma grande

variedade de plataformas e linguagens de programao. Alm de descrever o contedo das

mensagens, o WSDL define onde o servio est disponvel e quais protocolos de comunicao so

usados para conversar com o servio. Isso significa que o arquivo WSDL define tudo que necessrio

para escrever um programa que utilize o XML Web service. H vrias ferramentas disponveis para ler o

arquivo WSDL e gerar o cdigo para comunicar com o XML Web service.

A documentao do WSDL pode ser obtida na internet acessando o endereo do Web Service do

Sistema de Nota Fiscal de Servios Eletrnica da Prefeitura de Blumenau.

Para obter o WSDL do Web Service da NFS-e acione o navegador Web (Firefox, Internet Explorer, por

exemplo) e digite o endereo a seguir: https://nfse.blumenau.sc.gov.br/ws/lotenfe.asmx?WSDL


27/6/2013 Pgina 22 de 73


27/6/2013 Pgina 23 de 73

4.2 TIPOS UTILIZADOS

A seguir so apresentados os tipos Simples e Complexos utilizados nos Schemas XML de pedido e de

retorno. Estes tipos esto definidos no Schema XML de TiposNF-e (arquivo TiposNFe_V01.xsd).

Para obter a verso mais recente do Schema XML de TiposNF-e (bem como os demais Schemas XML)

acesse o link: https://nfse.blumenau.sc.gov.br/ws/schemas.zip

4.2.1 Tipos Simples

Descrio dos nomes e abreviaes utilizadas nas colunas de cabealho do layout da tabela de Tipos

Simples:

Nome do Tipo Descrio

(Tipo utilizado para informar ...)

Tipo

Base

Tamanho Dec Observao

tpCidade Cdigo da cidade do endereo. N 7 O cdigo informado dever pertencer Tabela de

Municpios (do IBGE) disponibilizada pela


A. Coluna Nome do Tipo: Nome do tipo simples;

B. Coluna Descrio: Descrio do tipo simples;

C. Coluna Tipo Base: tipo base utilizado na criao do tipo simples.

B boolean;

Base64Binary;

C campo alfanumrico;

D campo data;

N campo numrico;

D. Coluna Tamanho: x-y, onde x indica o tamanho mnimo e y o tamanho mximo; a existncia de

um nico valor indica que o campo tem tamanho fixo, devendo-se informar a quantidade de

caracteres exigidos, preenchendo-se os zeros no significativos; tamanhos separados por

vrgula indicam que o campo deve ter um dos tamanhos fixos da lista;

E. Coluna Dec: indica a quantidade mxima de casas decimais do campo;


27/6/2013 Pgina 24 de 73

Tabela de Tipos Simples


(Tipo utilizado para

informar ...)

Tipo

Base


tpAliquota Valor da alquota do

servio.

N 3-5 4 Exemplo:

5% - 0.05

2,5% - 0.025

1,75% - 0.0175

tpAssinatura Assinatura Digital de NFS-

e / RPS

base64Bi

nary

Cadeia de caracteres (com informaes

do RPS emitido) assinada conforme

descrito no item 4.3.2.

tpAssinaturaCancelamento Assinatura Digital de

Cancelamento de NFS-e.

base64Bi

nary

Cadeia de caracteres (com informaes

da NFS-e emitida) assinada conforme

descrito no item 4.3.10.

tpBairro Bairro do endereo. C 0-30 Bairro.

tpCEP CEP do endereo. N 7-8 CEP.

tpCidade Cdigo da cidade do

endereo.

N 7 O cdigo informado dever pertencer

Tabela de Municpios (do IBGE)

disponibilizada pela Prefeitura de

Blumenau.

tpCNPJ Nmero no Cadastro

Nacional da Pessoa

Jurdica.

C 14

tpCodigoServico Cdigos do servio. N 1-8 O cdigo informado dever pertencer

Tabela de Servios disponibilizada pela


tpCodigoEvento Cdigo do evento. N 3-4 O cdigo informado dever pertencer a

Tabela de Erros ou a Tabela de Alertas

disponibilizada pela Prefeitura de

Blumenau.

tpCodigoVerificacao Cdigo de verificao da

NFS-e.

C 8 Cdigo de verificao da NFS-e gerado

pelo Sistema de Nota Fiscal de Servios

Eletrnica.

tpComplementoEndereco Complemento do

endereo.

C 0-30

tpCPF Nmero no Cadastro de

Pessoas Fsicas.

C 11

tpDescricaoEvento Descrio do evento. C 0-300 Descrio correspondente ao cdigo do

evento ocorrido.

tpDiscriminacao Discriminao dos

Servios.

C 0-2000 Texto contnuo descritivo dos servios. O

conjunto de caracteres correspondentes

ao cdigo ASCII 13 e ASCII 10 dever

ser substitudo pelo caracter | (pipe ou

barra

vertical. ASCII 124).


27/6/2013 Pgina 25 de 73



informar ...)

Tipo

Base


Exemplo:

Digitado na NF

Lavagem de carro

com lavagem de motor

Preenchimento do arquivo:

Lavagem de carro|com lavagem de

motor

No devem ser colocados espaos neste

campo para completar seu tamanho

mximo, devendo o campo ser preenchido

apenas com contedo a ser processado /

armazenado.

(*) Este campo impresso num

retngulo com 95 caracteres (largura) e

21 linhas (altura). permitido (no

recomendvel), o uso de mais de 1000

caracteres. Caso seja ultrapassado o

limite de 21 linhas, o contedo ser

truncado durante a impresso da Nota.

tpEmail E-mail. C 0-75

tpInscricaoEstadual Inscrio Estadual. N 1-19

tpInscricaoMunicipal Inscrio Municipal. N 1-15

tpLogradouro Endereo. C 0-50

tpNumero Nmero. N 1-13 Tipo utilizado para informar nmero de

NFS-e, nmero de RPS, nmero de Guia,

nmero de Lote, nmero de pgina, ...

tpNumeroEndereco Nmero do endereo. C 0-10

tpOpcaoSimples Opo pelo Simples. C 1 Opo pelo Simples:

0 - No-optante pelo Simples Federal nem

Municipal;

1 - Optante pelo Simples Federal

(Alquota de 1,0%);

2 - Optante pelo Simples Federal

(Alquota de 0,5%);

3 - Optante pelo Simples Municipal.

4 - Simples Nacional

6 - MEI

tpQuantidade Tipo quantidade. N 1-15

tpRazaoSocial Tipo Razo Social. C 0-75 Nome/Razo Social.

tpSerieRPS Tipo Srie do RPS. C 1-5 Srie do RPS.

tpStatusNFe Status da NFS-e. C 1 Status da NFS-e:

N Normal;

C Cancelada;

E Extraviada.


27/6/2013 Pgina 26 de 73



informar ...)

Tipo

Base


tpSucesso O contedo deste campo

indica se o pedido do

servio obteve sucesso ou

no (conforme descrito no

item (4.3.1).

B

tpTempoProcessamento Tempo de processamento

(em segundos).

N 1-15

tpTipoLogradouro Tipo de endereo. C 0-3 Rua, Av, ...

tpTipoRPS Tipo do RPS. C 1 Tipo do RPS:

RPS Recibo Provisrio de Servios;

RPS-M Recibo Provisrio de Servios

proveniente

de Nota Fiscal Conjugada (Mista);

RPS-C Cupom.

tpTributacaoNFe Tipo de Tributao. C 1 Tipo de Tributao:

T - Tributao no municipio de Blumenau;

F - Tributao fora do municipio de

Blumenau;

I Isento;

J - ISS Suspenso por Deciso Judicial.

tpUF Sigla da UF do endereo. C 2 Sigla da UF do endereo.

tpValor Valores. N 0-15 2 Tipo utilizado para valores com 15 dgitos,

sendo 13 de corpo e 2 decimais.

Exemplo:

R$ 500,85 500.85

R$ 826,00 826

tpVersao Verso. N 1-3 O contedo deste campo indica a verso

do Schema XML utilizado.

Exemplo:

Verso 1 1

Verso 10 10

Verso 100 100


27/6/2013 Pgina 27 de 73

4.2.2 Tipos Complexos

Layout da tabela utilizada para representar a estrutura XML dos Tipos Complexos:

Nome do Elemento Tipo do Elemento Ocorrncia* Descrio

x-y

x-y

Elemento que

deriva de uma

escolha (Choice).

x-y

x-y

* Ocorrncia: x - y, onde x indica a ocorrncia mnima e y a ocorrncia mxima.

tpEvento

Tipo que representa a ocorrncia de eventos de erro/alerta durante o processamento da mensagem XML.

Nome do Elemento Tipo do Elemento Ocorrncia Descrio

Codigo tpCodigoEvento 1-1 Cdigo do evento ocorrido.

Descricao tpDescricaoEvento 0-1 Descrio do evento ocorrido.

(Choice)

Caso o evento tenha sido gerado

durante o processamento de uma

NFS-e (ou RPS), o tpEvento

tambm retorna a chave da NFS-

e (ou RPS) que o gerou.

ChaveNFe tpChaveNFe

0-1

Chave de identificao da NFS-e que

gerou o evento (ver detalhes na tabela

tpChaveNFe).

ChaveRPS tpChaveRPS

Chave de identificao do RPS que gerou

o evento (ver detalhes na tabela

tpChaveRPS).

tpCPFCNPJ

Tipo que representa um CPF/CNPJ


(Choice) CPF tpCPF 1-1

Nmero no Cadastro de

Pessoas Fsicas.

CNPJ tpCNP 1-1 Nmero no Cadastro

Nacional da Pessoa Jurdica.


27/6/2013 Pgina 28 de 73

tpChaveNFeRPS

Tipo que representa a Chave de uma NFS-e e a Chave do RPS que a mesma substitui.


ChaveNFe tpChaveNFe 1-1 Chave de identificao da NFS-e que substitui o RPS (ver

detalhes na tabela tpChaveNFe).

ChaveRPS tpChaveRPS 1-1 Chave de identificao do RPS substitudo (ver detalhes

na tabela tpChaveRPS).

tpChaveNFe

Tipo que representa a chave que um NFS-e


InscricaoPrestador tpInscricaoMunicipal 1-1 Inscrio Municipal do Prestador que emitiu a NFS-e.

Numero tpNumero 1-1 Nmero da NFS-e.

CodigoVerificacao tpCodigoVerificacao 0-1 Cdigo de Verificao da NFS-e.

tpChaveRPS

Tipo que define a chave identificadora de um RPS


InscricaoPrestador tpInscricaoMunicipal 1-1 Inscrio Municipal do Prestador que emitiu o RPS.

SerieRPS tpSerieRPS 0-1 Srie do RPS.

NumeroRPS tpNumero 1-1 Nmero do RPS.

tpEndereco

Tipo que representa um Endereo


TipoLogradouro tpTipoLogradouro 0-1 Tipo do endereo.

Logradouro tpLogradouro 0-1 Endereo.

NumeroEndereco tpNumeroEndereco 0-1 Nmero do endereo.

ComplementoEndereco tpComplementoEndereco 0-1 Complemento do endereo.

Bairro tpBairro 0-1 Bairro do endereo.

Cidade tpCidade 0-1 Cdigo da cidade do endereo.

UF tpUF 0-1 Sigla da UF do endereo.

CEP tpCEP 0-1 CEP do endereo.


27/6/2013 Pgina 29 de 73

tpInformacoesLote

Tipo que representa as informaes do lote processado


NumeroLote tpNumero 0-1 Nmero do lote.

InscricaoPrestador tpInscricaoMunicipal 1-1 Inscrio Municipal do prestador dos RPS contidos no lote.

CPFCNPJRemetente tpCPFCNPJ 1-1 CPF/CNPJ do remetente autorizado a transmitir a mensagem XML.

DataEnvioLote dateTime 1-1 Data/Hora do envio do lote (AAAA-MM-DDThh:mm:ss).

QtdNotas tpQuantidade 1-1 Quantidade de RPS contidos no lote.

TempoProcessamento tpTempoProcessamento 1-1 Tempo de processamento do lote.

ValorTotalServicos tpValor 1-1 Valor total dos servios dos RPS contidos na mensagem XML.

ValorTotalDeducoes tpValor 0-1 Valor total das dedues dos RPS contidos na mensagem XML.


27/6/2013 Pgina 30 de 73

tpNFe

Tipo que representa uma NFS-e


Assinatura tpAssinatura 0-1 Assinatura do RPS que gerou a NFS-e (conforme especificado no Item

4.3.2).

ChaveNFe tpChaveNFe 1-1 Chave de identificao da NFS-e (ver detalhes na tabela

tpChaveNFe).

DataEmissaoNFe dateTime 1-1 Data/Hora da emisso da NFS-e (AAAA-MM-DDThh:mm:ss).

NumeroLote tpNumero 0-1 Nmero do lote que gerou a NFS-e.

ChaveRPS tpChaveRPS 0-1 Chave de identificao do RPS (ver detalhes na tabela tpChaveRPS).

TipoRPS tpTipoRPS 0-1 Tipo do RPS.

DataEmissaoRPS date 0-1 Data da emisso do RPS.

CPFCNPJPrestador tpCPFCNPJ 1-1 CPF/CNPJ do prestador.

RazaoSocialPrestador tpRazaoSocial 1-1 Nome / Razo Social do prestador.

EnderecoPrestador tpEndereco 1-1 Endereo do prestador.

EmailPrestador tpEmail 0-1 E-mail do prestador.

StatusNFe tpStatusNFe 1-1 Status da NFS-e.

DataCancelamento date 0-1 Se a NFS-e tiver sido cancelada, este campo ser preenchido com a

data de cancelamento da NFS-e (AAAA-MM-DDThh:mm:ss).

TributacaoNFe tpTributacaoNFe 1-1 Tipo de tributao da NFS-e.

OpcaoSimples tpOpcaoSimples 1-1 Tipo de opo pelo Simples.

NumeroGuia tpNumero 0-1 Nmero da guia vinculada a NFS-e.

DataQuitacaoGuia Date 0-1 Data de quitao da guia vinculada a NFS-e.

ValorServicos tpValor 1-1 Valor dos servios em R$.

ValorDeducoes tpValor 0-1 Valor das dedues em R$.

ValorPIS tpValor 0-1 Valor da reteno do PIS em R$.

ValorCOFINS tpValor 0-1 Valor da reteno do COFINS em R$.

ValorINSS tpValor 0-1 Valor da reteno do INSS em R$.

ValorIR tpValor 0-1 Valor da reteno do IR em R$.

ValorCSLL tpValor 0-1 Valor da reteno do CSLL em R$.

CodigoServicos tpCodigo 1-1 Cdigo do servio prestado.

AliquotaServicos tpAliquota 1-1 Alquota do servio prestado.

ValorISS tpValor 1-1 Valor do ISS em R$.

ValorCredito tpValor 1-1 Valor do crdito gerado.

ISSRetido Boolean 1-1 Reteno do ISS. Preencher com:

"true" - para NFS-e com ISS Retido;

"false" - para NFS-e sem ISS Retido

CPFCNPJTomador tpCPFCNPJ 0-1 CPF/CNPJ do tomador.

InscricaoMunicipalTomador tpInscricaoMunicipal 0-1 Inscrio Municipal do tomador.

InscricaoEstadualTomador tpInscricaoEstadual 0-1 Inscrio Estadual do tomador.

RazaoSocialTomador tpRazaoSocial 0-1 Nome / Razo Social do tomador.

EnderecoTomador tpEndereco 0-1 Endereo do tomador.

EmailTomador tpEmail 0-1 E-mail do tomador.

Discriminacao tpDiscriminacao 1-1 Discriminao dos servios.


27/6/2013 Pgina 31 de 73


27/6/2013 Pgina 32 de 73

tpRPS

Tipo que representa RPS


Assinatura tpAssinatura 1-1 Assinatura do RPS emitido (conforme especificado no Item 4.3.2).

ChaveRPS tpChaveRPS 1-1 Chave de identificao do RPS (ver detalhes na tabela

tpChaveRPS).

TipoRPS tpTipoRPS 1-1 Tipo do RPS.

DataEmissao date 1-1 Data da emisso do RPS.

StatusRPS tpStatusNFe 1-1 Status do RPS.

TributacaoRPS tpTributacaoNFe 1-1 Tipo de tributao do RPS.

ValorServicos tpValor 1-1 Valor dos servios em R$.

ValorDeducoes tpValor 1-1 Valor das dedues em R$.

ValorPIS tpValor 0-1 Valor da reteno do PIS em R$.

ValorCOFINS tpValor 0-1 Valor da reteno do COFINS em R$.

ValorINSS tpValor 0-1 Valor da reteno do INSS em R$.

ValorIR tpValor 0-1 Valor da reteno do IR em R$.

ValorCSLL tpValor 0-1 Valor da reteno do CSLL em R$.

CodigoServicos tpCodigo 1-1 Cdigo do servio prestado.

AliquotaServicos tpAliquota 1-1 Alquota do servio prestado.

ISSRetido Boolean 1-1 Reteno do ISS. Preencher com:

"true" - para NFS-e com ISS Retido;

"false" - para NFS-e sem ISS Retido

CPFCNPJTomador tpCPFCNPJ 0-1 CPF/CNPJ do tomador do servio.

InscricaoMunicipalTomador tpInscricaoMunicipal 0-1 Inscrio Municipal do tomador.

ATENO 1: Este elemento s dever ser preenchido para

tomadores estabelecidos no municpio de Blumenau(CMC).

ATENO 2: O preenchimento deste elemento implica na

obrigatoriedade do preenchimento do elemento CPFCNPJTomador.

Ser verificado se o CNPJ vinculado ao CMC corresponde ao CNPJ

informado no elemento CPFCNPJTomador.

InscricaoEstadualTomador tpInscricaoEstadual 0-1 Inscrio Estadual do tomador.

RazaoSocialTomador tpRazaoSocial 0-1 Nome / Razo Social do tomador.

EnderecoTomador tpEndereco 0-1 Endereo do tomador.

EmailTomador tpEmail 0-1 E-mail do tomador.

Discriminacao tpDiscriminacao 1-1 Discriminao dos servios.


27/6/2013 Pgina 33 de 73

4.3 SERVIOS E MTODOS

A seguir so descritos cada um dos servios disponibilizados pelo Web Service LoteNFe, bem como

seus respectivos mtodos e schemas XML de pedido e de retorno do servio.

4.3.1 Regras Gerais

Parmetros

Todos os mtodos de pedido de servio disponveis recebem dois parmetros conforme o exemplo:

(, )

Onde,

Parmetro VersaoSchema: Verso do Schema XML utilizado para montar a mensagem XML de pedido

do servio (tipo de dado: Integer);

Parmetro MensagemXML: Mensagem XML de pedido do servio (tipo de dado: String).

Todos os mtodos retornam uma mensagem XML de retorno no respectivo Schema XML de retorno do

servio pedido (string). Todos os Schemas XML de retorno contem uma TAG chamada Sucesso no

cabealho. Esta TAG indica se o pedido foi atendido com sucesso (true) ou no (false) conforme

descrito a seguir:

Sucesso: True

Caso todo o pedido do servio tenha sido processado sem que ocorram eventos de erro.

Sendo assim, o Web Service transmitir uma mensagem XML de retorno do respectivo

servio informando o sucesso da operao (TAG sucesso = true) e as demais informaes

pertinentes ao respectivo Schema de Retorno. Caso ocorram eventos de alerta durante o

processamento, os alertas gerados sero apresentados na mensagem XML de retorno.

Eventos de alerta no impedem que o pedido seja atendido com sucesso.

Sucesso: False

Caso ocorra algum evento de erro durante o processamento do pedido do servio. Sendo

assim, o Web Service transmitir uma mensagem XML de retorno do respectivo servio


27/6/2013 Pgina 34 de 73

informando o no sucesso da operao (TAG sucesso = false) e as demais Informaes

sobre os eventos de erro/alerta ocorridos.


27/6/2013 Pgina 35 de 73

Observaes:

Descrio dos nomes e abreviaes utilizadas no cabealho das tabelas que representam estrutura

definida nos schemas XML:

# Campo Descrio Ele. Pai Tipo Ocorr. Observao

P1 Cabecalho TAG de grupo das informaes do

cabealho

G - - 1-1

Versao Verso do XML Schema Utilizado. A P1 tpVersao 1-1

dtInicio Data de incio do perodo transmitido. E P1 D 1-1 (AAAA-MM-DD)

A. Coluna #: Cdigo de identificao do campo. Este cdigo utilizado por um elemento filho

identificar seu elemento pai na coluna Pai;

B. Coluna Descrio: Descrio do campo;

C. Coluna Ele.:

A - indica que o campo um atributo do Elemento anterior;

E - indica que o campo um Elemento;

CE indica que o campo um Elemento que deriva de uma Escolha (Choice);

G indica que o campo um Elemento de Grupo;

CG - indica que o campo um Elemento de Grupo que deriva de uma Escolha (Choice);

D. Coluna Pai: Indica qual o elemento pai;

E. Coluna Tipo:

Tipos Base:

N campo numrico;

C campo alfanumrico;

D campo data;

Tipos Simples e Tipos Complexos:

Coluna Ocorr.: x - y, onde x indica a ocorrncia mnima e y a ocorrncia mxima;

Para obter a verso mais recente dos Schemas XML acesse o link:

https://nfse.blumenau.sc.gov.br/ws/schemas.zip


27/6/2013 Pgina 36 de 73

4.3.2 Envio de RPS

I. Descrio: Este mtodo responsvel por atender aos pedidos de Envio Individual de RPS para

substituio por NFS-e.

II. Mtodo: EnvioRPS

III. Mensagem XML: O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme

tabela a seguir:

PedidoEnvioRPS.xsd*

# Campo Descrio Ele Pai Tipo Ocorr Observao

P1 Cabecalho TAG de grupo das

informaes do cabealho.

G - - 1-1

Versao Verso do XML Schema

Utilizado.

A P1 tpVersao 1-1

CNPJRemetente CNPJ do Remetente

autorizado a transmitir a

mensagem XML.

E P1 tpCPFCNPJ 1-1

P2 RPS Recibo Provisrio de Servio. G - tpRPS 1-1

P3 Signature Assinatura digital da

mensagem XML.

G - SignatureType 1-1 Signature o elemento raiz de

uma assinatura XML. Este

elemento descrito no arquivo

xmldsig-core-schema_v01.xsd

* Representao da estrutura definida no schema XML PedidoEnvioRPS.xsd.

Observao: Assinatura Adicional

O RPS dever ter uma assinatura digital. Esta assinatura utilizar o mesmo certificado digital usado

na assinatura da mensagem XML (item 3.2.2A), com os mesmos padres de criptografia assimtrica

RSA e algoritmo message digest SHA-1.


27/6/2013 Pgina 37 de 73

Para criar a assinatura dever ser gerado um Hash (utilizando SHA1) de uma cadeia de caracteres

(ASCII) com informaes do RPS emitido. Este Hash dever ser assinado utilizando RSA. A

assinatura do Hash ser informada na TAG Assinatura (tipo RPS apresentado no item 4.2.1).

A cadeia de caracteres a ser assinada dever conter 86 posies com as informaes apresentadas

na tabela a seguir:

# Informao Contedo

1 Inscrio Municipal do

Prestador

Inscrio Municipal do Prestador com 8 posies (dgitos). Completar com zeros

esquerda caso seja necessrio.

2 Srie do RPS Srie do RPS com 5 posies (caracteres). Completar com espaos em branco direita

caso seja necessrio.

Ateno: No utilize espaos esquerda. O contedo dever estar alinhado a esquerda.

3 Nmero do RPS Nmero do RPS com 12 posies (dgitos). Completar com zeros esquerda caso seja

necessrio.

4 Data de Emisso do RPS Data de emisso do RPS no formato AAAAMMDD (caracteres).

5 Tipo de Tributao do RPS Tipo de Tributao do RPS com 1 posio (caractere):

T - Tributao no municipio de Blumenau;

F - Tributao fora do municipio de Blumenau;

I Isento;

J - ISS Suspenso por Deciso Judicial.

6 Status do RPS Status do RPS com 1 posio (caractere):

N Normal;

C Cancelado;

E Extraviado.

7 ISS Retido Valor S (SIM) para ISS Retido (caractere).

Valor N (NO) para Nota Fiscal sem ISS Retido.

8 Valor dos Servios Valor dos Servios do RPS, incluindo os centavos (sem ponto decimal e sem R$), com 15

posies (dgitos).

Exemplo:

R$ 500,85 000000000050085

R$ 500,00 000000000050000

9 Valor das Dedues Valor das Dedues do RPS, incluindo os centavos (sem ponto decimal e sem R$), com

15 posies (dgitos).

Exemplo:

R$ 500,85 000000000050085

R$ 500,00 000000000050000

10 Cdigo do Servio Prestado Cdigo do Servio do RPS com 5 posies (dgitos). Completar com zeros esquerda

caso seja necessrio.

11 Indicador de CPF/CNPJ do

Tomador

Indicador de CPF/CNPJ com 1 posio (dgito).

Valor 1 para CPF.

Valor 2 para CNPJ.

Valor 3 para No-Informado

12 CPF/CNPJ do Tomador CPF/CNPJ do tomador com 14 posies (dgitos). Sem formatao (ponto, trao, barra,

....). Completar com zeros esquerda caso seja necessrio. Se o Indicador do CPF/CNPJ

for 3 (no-informado), preencher com 14 zeros.


27/6/2013 Pgina 38 de 73


27/6/2013 Pgina 39 de 73

Passos bsicos para assinatura de um RPS:

1 - Monte a string de caracteres conforme a tabela a apresentada anteriormente.

A seguir apresentamos o exemplo de parte de uma mensagem XML de pedido de envio de RPS (os

campos utilizados na montagem da cadeia de caracteres esto em negrito).

...

31000 OL03 1 RPS-M 2011-01-03 N T 20500

5000 2658 0.05 false 13167474254

...

Com base no trecho da mensagem XML apresentada, montamos a seguinte string de caracteres:

"00031000OL03 00000000000120110103TNN00000000205000000000000050000002658100013167474254"

Note que o valor dos servios (R$ 20.500,00) foi transformado em 2050000, o valor de

dedues (R$ 5.000,00) foi transformado em 500000. Tambm foi acrescentado srie do RPS

um espao em branco direita para preencher as 5 posies. A srie do RPS deve estar em

maiscula para ser assinada.

2 - Converta a cadeia de caracteres ASCII para bytes.

3 - Gere o HASH (array de bytes) utilizando SHA1.

4 - Assine o HASH (array de bytes) utilizando RSA-SHA1.

ATENO! Na maioria das linguagens de programao, os passos 3 e 4 so feitos atravs de uma

nica funo. Verifique a documentao de sua linguagem para evitar assinar um hash de um hash.


27/6/2013 Pgina 40 de 73

IV. Schema da Mensagem XML do Retorno: RetornoEnvioRPS.xsd

RetornoEnvioRPS.xsd*

# Campo Descrio Ele Pai Tipo Ocorr. Observao


cabealho.

G - - 1-1


Sucesso Status do Pedido de Envio de Lote

de RPS.

E P1 tpSucesso 1-1

P2 Alerta Informaes sobre a ocorrncia de

eventos geradores de alertas

durante o processamento da

mensagem XML.

G - tpEvento 0-N

P3 Erro Informaes sobre a ocorrncia de

eventos geradores de erros


mensagem XML.

G - tpEvento 0-N

P4 ChaveNFeRPS Chave do RPS e Chave da NFS-e

gerada.

G - tpChaveNFeRPS 0-1

* Representao da estrutura definida no schema XML RetornoEnvioRPS.xsd.

V. Formato das Mensagens SOAP:

Pedido:

1 INCLUIR AQUI A MENSAGEM XML CONFORME ITEM III

Retorno:

MENSAGEM XML DE RETORNO CONFORME ITEM IV


27/6/2013 Pgina 41 de 73


27/6/2013 Pgina 42 de 73

4.3.3 Envio de Lote de RPS (EnvioLoteRPS)

I. Descrio: Este mtodo responsvel por atender aos pedidos de Envio de Lote de RPS para

substituio por NFS-e.

II. Mtodo: EnvioLoteRPS

III. O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela a seguir:

PedidoEnvioLoteRPS.xsd*



informaes do cabealho.

G - - 1-1


Utilizado.

A P1 tpVersao 1-1

CNPJRemetente CNPJ do Remetente

autorizado a transmitir a

mensagem XML.

E P1 tpCPFCNPJ 1-1

Transacao Informe se os RPS a serem

substitudos por NFS-e faro

parte de uma mesma

transao.

E P1 boolean 0-1 True - Os RPS s sero

substitudos por NFS-e se no

ocorrer nenhum evento de erro

durante o processamento de

todo o lote.

False - Os RPS vlidos sero

substitudos por NFS-e, mesmo

que ocorram eventos de erro

durante processamento de

outros RPS deste lote.

Default: true.

dtInicio Data de incio do perodo

transmitido.

E P1 D 1-1 (AAAA-MM-DD)

dtFim Data final do perodo E P1 D 1-1 (AAAA-MM-DD)


27/6/2013 Pgina 43 de 73

PedidoEnvioLoteRPS.xsd*


transmitido.

QtdRPS Quantidade de RPS contidos

no lote.

E P1 tpQuantidade 1-1

ValorTotalServicos Valor total dos servios dos

RPS contidos no lote.

E P1 tpValor 1-1

ValorTotalDeducoes Valor total das dedues dos

RPS/Cupom contidos no lote.

E P1 tpValor 1-1

P2 RPS Recibo Provisrio de Servio. G - tpRPS 1-50


mensagem XML.

G - SignatureType 1-1 Signature o elemento raiz de

uma assinatura XML. Este

elemento descrito no arquivo

xmldsig-core-schema_v01.xsd

* Representao da estrutura definida no schema XML PedidoEnvioLoteRPS.xsd.

Observao 1: Assinatura Adicional

Cada RPS enviado no lote dever ser assinado digitalmente conforme especificado no item 4.3.2

(Envio de RPS).

Observao 2: Transao

Se ocorrerem eventos de erro de validao dos dados do cabealho do pedido de envio de lote de

RPS, independente da opo informada no campo Transao, nenhum RPS ser substitudo por

NFS-e.

IV. Schema da Mensagem XML do Retorno: RetornoEnvioLoteRPS.xsd

RetornoEnvioLoteRPS.xsd*



cabealho.

G - - 1-1


Sucesso Status do Pedido de Envio de Lote

de RPS.

E P1 tpSucesso 1-1

InformacoesLote Informaes sobre o Lote. G P1 tpInformacoesLote 0-1


eventos geradores de alertas


mensagem XML.

G - tpEvento 0-N


eventos geradores de erros


mensagem XML.

G - tpEvento 0-N

P4 ChaveRPSNFe Chave do RPS e Chave da NFS-e G - tpChaveNFeRPS 0-50


27/6/2013 Pgina 44 de 73

gerada.

* Representao da estrutura definida no schema XML RetornoEnvioLoteRPS.xsd.

Observao: Transao

Para pedidos de envio de lote de RPS com transao (Transacao = True), o campo

InformacoesLote retornar (dentre outras informaes) o total dos servios, o total das dedues e a

quantidade de RPS enviados na mensagem XML de pedido do servio.

Para pedidos de envio de lote de RPS sem transao (Transacao = False), o campo

InformacoesLote retornar (dentre outras informaes) o total dos servios, o total das dedues e a

quantidade de RPS que efetivamente foram substitudos por NFS-e.


Pedido:


Retorno:



27/6/2013 Pgina 45 de 73

4.3.4 Teste de Envio de Lote de RPS (TesteEnvioLoteRPS)

I. Descrio: Este mtodo responsvel por atender aos pedidos de Teste de Envio de Lote de RPS

para substituio por NFS-e. Este mtodo no substitui os RPS por NFS-e.

Observao:

Conforme informado no item 2.3, este mtodo dever ser usado apenas na fase de adaptao dos

sistemas dos contribuintes. Nos casos de sistemas j adaptados, seu uso resulta em duplicidade de

esforos desnecessrios, pois as verificaes feitas no mtodo TesteEnvioLoteRPS so as mesmas

realizadas pelo mtodo EnvioLoteRPS.

II. Mtodo: TesteEnvioLoteRPS

III. O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela apresentada

no item V

IV. Schema da Mensagem XML do Retorno: RetornoEnvioLoteRPS.xsd

(Idntico ao Schema da Mensagem XML do Retorno do item V)


27/6/2013 Pgina 46 de 73

4.3.5 Pedido de Consulta de NFS-e (ConsultaNFe)

I. Descrio: Este mtodo responsvel por atender aos pedidos de consulta de NFS-e / RPS. Seu

acesso permitido apenas pela chave de identificao da NFS-e ou pela chave de identificao do

RPS.

II. Mtodo: ConsultaNFe


PedidoConsultaNFe.xsd*



cabealho.

G - - 1-1


CNPJRemetente CNPJ do Remetente autorizado a

enviar a mensagem XML.

E P1 tpCPFCNPJ 1-1

P2 Detalhe TAG de grupo das informaes do

detalhe.

G - - 1-50

ChaveRPS Chave do RPS. CE P2 tpChaveRPS 1-1

ChaveNFe Chave da NFS-e. CE P2 tpChaveNFe 1-1

P3 Signature Assinatura digital da mensagem

XML.

G - SignatureType 1-1 Signature o

elemento raiz de

uma assinatura

XML. Este

elemento

descrito no

arquivo xmldsig-

core-

schema_v01.xsd


27/6/2013 Pgina 47 de 73

*Representao da estrutura definida no schema XML PedidoConsultaNFe.xsd.

IV. Schema da Mensagem XML do Retorno: RetornoConsulta.xsd

RetornoConsulta.xsd*



cabealho.

G - - 1-1


Sucesso Status do Envio de Lote. E P1 tpSucesso 1-1


eventos geradores de alertas durante o

processamento da mensagem XML.

G - tpEvento 0-N


eventos geradores de erros durante o

processamento da mensagem XML.

G - tpEvento 0-N

P4 NFe Elemento NFe - pode se repetir quantas

vezes for necessrio (respeitando o limite

de mmimo estabelecido). Cada item ser

um NFS-e.

G - tpNFe 0-50

* Representao da estrutura definida no schema XML RetornoConsulta.xsd.


Pedido:


Retorno:



27/6/2013 Pgina 48 de 73


27/6/2013 Pgina 49 de 73

4.3.6 Pedido de Consulta de NFS-e Recebidas (ConsultaNFeRecebidas)

I. Descrio: Este mtodo responsvel por atender aos pedidos de consulta de NFS-e Recebidas.

II. Mtodo: ConsultaNFeRecebidas


PedidoConsultaNFePeriodo.xsd*



informaes do

cabealho.

G - - 1-1

Versao Verso do XML

Schema Utilizado.

A P1 tpVersao 1-1

CPFCNPJRemeten

te

CPF/CNPJ do

Remetente autorizado

a enviar a mensagem

XML.

E P1 tpCPFCNPJ 1-1

CPFCNPJ Para consulta de

NFS-e Recebidas:

Informe o CPF/CNPJ

do tomador da NFS-e.

Para consulta de

NFS-e Emitidas:

Informe o CNPJ do

emissor da NFS-e.

E P1 tpCPFCNPJ 1-1

Inscricao Para consulta de

NFS-e Recebidas:

Informe a Inscrio

Municipal do

Tomador.

E P1 tpInscricaoMunicipal 0-1 ATENO 1: Este campo

s dever ser preenchido

com a inscrio de

contribuintes estabelecidos

no municpio de Blumenau


27/6/2013 Pgina 50 de 73

Para consulta de

NFS-e Emitidas:

Informe a Inscrio

Municipal do

Prestador. Neste tipo

de consulta o

preenchimento deste

campo se torna

obrigatrio.

(CMC).

dtInicio Data incio da

consulta.

E P1 D 1-1

dtFim Data fim da consulta. E P1 D 1-1

NumeroPagina ** Nmero da pgina

consultada

E P1 tpNumero 1-1 Default = 1


mensagem XML.

G - SignatureType 1-1 Signature o elemento raiz

de uma assinatura XML. Este

elemento descrito no

arquivo xmldsig-core-

schema_v01.xsd

* Representao da estrutura definida no schema XML PedidoConsultaNFePeriodo.xsd. Os mtodos

ConsultaNFeRecebidas e ConsultaNFeEmitidas utilizam o mesmo schema XML para o pedido do

servio.

** Conforme especificado no Schema XML RetornoConsulta.xsd (utilizado no retorno dos pedidos de

Consulta de NFS-e, Consulta de NFS-e Recebidas, Consulta de NFS-e Emitidas e Consulta de Lote) s

sero retornadas at 50 NFS-e por consulta. Porm a Consulta de NFS-e Recebidas (assim como a

Consulta de NFS-e Emitidas) pode encontrar uma quantidade maior de NFS-e do que o limite

especificado.

Sendo assim, as NFS-e encontradas sero agrupadas em pginas com at 50 NFS-e. Para consultar as

NFS-e de cada uma das pginas o contribuinte dever transmitir uma mensagem XML de pedido de

Consulta de NFS-e Recebidas indicando qual pgina deseja consultar. Desta forma, caso um pedido de

consulta de NFS-e Recebidas, para pgina X, retorne 50 NFS-e o sistema de informao do

Contribuinte deve efetuar novo pedido de Consulta de NFS-e Recebidas, para pgina X+1, para verificar

se existem mais NFS-e Recebidas no perodo consultado.

Quando o sistema de informao do Contribuinte efetuar um pedido de Consulta de NFS-e Recebidas

para uma determinada pgina e est consulta retornar menos que 50 NFS-e o sistema de informao

do contribuinte saber que estas so as ltimas NFS-e recebidas para o perodo consultado e que por

tanto est a ltima pgina. Se o Web Service retornar uma mensagem XML informando sucesso (tag

sucesso = true) e sem nenhuma NFS-e por que a pgina consultada no existe.


27/6/2013 Pgina 51 de 73

Exemplo:

O sistema de informao de um Contribuinte envia uma mensagem XML de Pedido Consulta de NFS-e

Recebidas para o perodo de 01/09/2010 30/09/2010 e requerendo a pgina 1. Para este pedido so

encontradas 137 NFS-e recebidas. As 137 NFS-e so agrupadas em trs pginas: Pgina 1 com as

primeiras 50 NFS-e (1 50); pgina 2 com as prximas 50 NFS-e (51 100) e pgina 3 com as 37

NFS-e restantes (101 137). O Web Service retorna uma mensagem XML com a pgina requerida

(pgina 1). Ao receber a mensagem XML de retorno o sistema de informao do Contribuinte verifica

que foram retornadas 50 NFS-e para a pgina 1. O sistema de informao do Contribuinte envia outra

mensagem XML de Pedido Consulta de NFS-e Recebidas para o mesmo perodo, mas desta vez

requerendo a prxima pgina (pgina 2). O Web Service retorna uma mensagem XML com a pgina

requerida (pgina 2). Ao receber a mensagem XML de retorno o sistema de informao do Contribuinte

verifica que foram retornadas 50 NFS-e para a pgina 2. O sistema de informao do Contribuinte envia

outra mensagem XML de Pedido Consulta de NFS-e Recebidas para o mesmo perodo, mas desta vez

requerendo a prxima pgina (pgina 3). O Web Service retorna uma mensagem XML com a pgina

requerida (pgina 3). Ao receber a mensagem XML de retorno o sistema de informao do Contribuinte

verifica que foram retornadas 37 NFS-e para a pgina 3 e por tanto no existem mais NFS-e recebidas

para o perodo consultado.

Obs.: As NFS-e encontradas so ordenadas por data de emisso da NFS-e (ou data do cancelamento,

caso a NFS-e tenha sido cancelada) e pela inscrio municipal (CMC) do prestador que emitiu a NFS-e.

Abaixo, fluxo de funcionamento baseado no exemplo descrito:


27/6/2013 Pgina 52 de 73


(Idntico ao do item 4.3.5)


Pedido:


Retorno:



27/6/2013 Pgina 53 de 73


27/6/2013 Pgina 54 de 73

4.3.7 Pedido de Consulta de NFS-e Emitidas (ConsultaNFeEmitidas)

I. Descrio: Este mtodo responsvel por atender aos pedidos de consulta de NFS-e Emitidas.

II. Mtodo: ConsultaNFeEmitidas

III. O parmetro MensagemXML (idntico ao Schema da Mensagem XML de pedido apresentado no

item 4.3.6 III).

VI. Schema da Mensagem XML do Retorno: RetornoConsulta.xsd


VII. Formato das Mensagens SOAP:

Pedido:


Retorno:


27/6/2013 Pgina 55 de 73



27/6/2013 Pgina 56 de 73

4.3.8 Pedido de Consulta de Lote (ConsultaLote)

I. Descrio: Este mtodo responsvel por atender aos pedidos de Consulta de Lote de NFS-e

geradas a partir do mtodo EnvioLoteRPS.

II. Mtodo: ConsultaLote


PedidoConsultaLote.xsd*


P1 Cabecalho TAG de grupo das informaes

do cabealho.

G - - 1-1


Utilizado.

A P1 tpVersao 1-1

CNPJRemetente CNPJ do Remetente autorizado

a enviar a mensagem XML.

E P1 tpCPFCNPJ 1-1

NumeroLote Nmero do lote a ser

consultado.

E P1 tpNumero 1-1

P2 Signature Assinatura digital da mensagem

XML.

G - SignatureType 1-1 Signature o

elemento raiz de uma

assinatura XML. Este

elemento descrito

no arquivo xmldsig-

core-schema_v01.xsd

* Representao da estrutura definida no schema XML PedidoConsultaLote.xsd.



Prefeitura Municipal de Blumenau Notas Fiscal de Servios Eletrnica (NFS-e

Documents

Manual de Utilização Do Web Service - NFSe Blumenau