Você está na página 1de 47

Nota Fiscal Eletrnica de Servios

Manual de Utilizao Web Service

Verso 2.2

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 2

Manual de Utilizao
Web Service
NDICE
1. INTRODUO .................................................................................................................................................... 4 2. INTERFACES DISPONVEIS .................................................................................................................................. 4 2.1. ENVIO DE RPS ..................................................................................................................................................... 4 2.2. ENVIO DE LOTE DE RPS ....................................................................................................................................... 4 2.3. TESTE DE ENVIO DE LOTE DE RPS ........................................................................................................................ 4 2.4. CONSULTA DE NF-E ............................................................................................................................................ 4 2.5. CONSULTA DE NF-E RECEBIDAS .......................................................................................................................... 4 2.6. CONSULTA DE NF-E EMITIDAS ............................................................................................................................ 4 2.7. CONSULTA DE LOTE ............................................................................................................................................ 4 2.8. CONSULTA INFORMAES DO LOTE .................................................................................................................. 5 2.9. CANCELAMENTO DE NF-E .................................................................................................................................. 5 2.10. CONSULTA DE CNPJ .......................................................................................................................................... 5 3. ARQUITETURA DE COMUNICAO .................................................................................................................... 6 3.1. MODELO CONCEITUAL ....................................................................................................................................... 6 3.2. PADRES TCNICOS ........................................................................................................................................... 7 3.2.1. Padro de Comunicao ............................................................................................................................. 7 3.2.2. Padro de Certificado Digital ...................................................................................................................... 7 3.2.3. Padro de Assinatura Digital ...................................................................................................................... 8 3.2.4. Validao de Assinatura Digital pelo Sistema de NF-e ............................................................................... 8 3.2.5. Resumo dos Padres Tcnicos ................................................................................................................... 9 3.3. MODELO OPERACIONAL..................................................................................................................................... 9 3.3.1. Servios..................................................................................................................................................... 10 3.4. PADRO DAS MENSAGENS XML ....................................................................................................................... 10 3.4.1. Validao da estrutura das Mensagens XML............................................................................................ 10 3.4.2. Schemas XML (arquivos XSD) ................................................................................................................... 11 3.4.3. Verso dos Schemas XML ......................................................................................................................... 11 3.4.4. Regras de preenchimento dos campos .................................................................................................... 13 3.4.5. Tratamento de caracteres especiais no texto de XML ............................................................................. 13 4. WEB SERVICE LOTE NFE ....................................................................................................................................14 4.1. WSDL ................................................................................................................................................................ 14 4.2. TIPOS UTILIZADOS ............................................................................................................................................ 15

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 3

4.2.1. Tipos Simples ............................................................................................................................................ 15 4.2.2. Tipos Complexos....................................................................................................................................... 18 4.3. SERVIOS E MTODOS ..................................................................................................................................... 22 4.3.1. Regras Gerais ............................................................................................................................................ 22 4.3.2. Envio de RPS ............................................................................................................................................. 23 4.3.3. Envio de Lote de RPS (EnvioLoteRPS) ....................................................................................................... 26 4.3.4. Teste de Envio de Lote de RPS (TesteEnvioLoteRPS)................................................................................ 29 4.3.5. Pedido de Consulta de NF-e (ConsultaNFe) ............................................................................................. 29 4.3.6. Pedido de Consulta de NF-e Recebidas (ConsultaNFeRecebidas) ............................................................ 31 4.3.7. Pedido de Consulta de NF-e Emitidas (ConsultaNFeEmitidas) ................................................................. 34 4.3.8. Pedido de Consulta de Lote (ConsultaLote) ............................................................................................. 35 4.3.9. Pedido de Informaes do Lote (ConsultaInformacoesLote) ................................................................... 37 4.3.10. Pedido de Cancelamento de NF-e (CancelamentoNFe) ......................................................................... 39 4.3.11. Pedido de Consulta de CNPJ (ConsultaCNPJ) ......................................................................................... 42 4.4. TABELA DE ERROS E ALERTAS ........................................................................................................................... 43 4.4.1. Erros ......................................................................................................................................................... 44 4.4.2. Alertas ...................................................................................................................................................... 46 5. ARQUIVOS DE EXEMPLOS .................................................................................................................................47 ANEXO I................................................................................................................................................................47 TABELA DE MUNICPIOS .......................................................................................................................................... 47

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 4

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 So Paulo para as empresas prestadoras e/ou tomadoras de servios. Por meio do Web Service as empresas podero integrar seus prprios sistemas de informaes com o Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo. Desta forma, consegue-se automatizar o processo de emisso, consulta e cancelamento de NF-e.

2. INTERFACES DISPONVEIS

Atravs do Web Service, o Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo, 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 Eletrnica. Esta interface destinasse aos prestadores que desejam emitir NF-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 Notas Fiscais Eletrnicas. Esta interface destina-se aos prestadores que desejam emitir NF-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 NF-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 NF-E Esta interface permite os prestadores de servios consultarem as NF-e emitidas por ele. 2.5. CONSULTA DE NF-E RECEBIDAS Esta interface possibilita aos tomadores e/ou prestadores de servios consultarem as NF-e que tiverem sido emitidas para ele, possibilitando, por exemplo, a alimentao automtica de seu mdulo de contas a pagar. 2.6. CONSULTA DE NF-E EMITIDAS Esta interface possibilita aos prestadores de servios consultarem as NF-e que tiverem sido emitidas por ele. 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 NF-e geradas neste lote.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 5

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 NF-E Com esta interface, os prestadores de servios podero cancelar as NF-e emitidas por ele, informando apenas os nmeros da NF-e que devero ser cancelados. 2.10. CONSULTA DE CNPJ Esta interface possibilita aos tomadores e/ou prestadores de servios consultarem quais Inscries Municipais (CCM) esto vinculadas a um determinado CNPJ e se estes Contribuintes j emitem NF-e.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 6

3. ARQUITETURA DE COMUNICAO

3.1. MODELO CONCEITUAL O Web Service do Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo 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 NF-e; E. Consulta de NF-e Recebidas; F. Consulta de NF-e Emitidas; G. Consulta de Lote; H. Consulta de Informaes de Lote; I. Cancelamento de NF-e;

J. Consulta de CNPJ.

Existir um nico Web Service com todos os servios apresentados acima. 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 Notas Fiscais Eletrnicas da Prefeitura de So Paulo:

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 7

3.2. PADRES TCNICOS

3.2.1. Padro de Comunicao A comunicao entre os sistemas de informaes dos contribuintes e o Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo ser baseada em um Web Service disponibilizado no Sistema de Notas Fiscais Eletrnicas. 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 Notas Fiscais Eletrnicas da Prefeitura de So Paulo 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 Notas Fiscais Eletrnicas da Prefeitura de So Paulo 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. 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 NF-e Emitidas, NF-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 Notas Fiscais Eletrnicas). 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 So Paulo: 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).

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 8

3.2.3. Padro de Assinatura Digital As mensagens enviadas ao Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo so documentos eletrnicos elaborados no padro XML e devem ser assinados digitalmente utilizando certificado digital, descrito no item 3.2.2. 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: <X509SubjectName> <X509IssuerSerial> <X509IssuerName> <X509SerialNumber> <X509SKI> Analogamente, as TAGs abaixo no devero ser informadas, pois as informaes sero obtidas a partir do Certificado do emitente: <KeyValue> <RSAKeyValue> <Modulus> <Exponent> 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 Notas Fiscais Eletrnicas da Prefeitura de So Paulo. 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 NF-e Para a validao da assinatura digital, seguem as regras que sero adotadas pelo Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo: 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;

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 9

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 Notas Fiscais Eletrnicas da Prefeitura de So Paulo 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.

3.2.5. Resumo dos Padres Tcnicos A tabela a seguir resume os principais padres de tecnologia utilizados:
CARACTERSTICA Web Services Meio lgico de comunicao Meio fsico de comunicao Protocolo Internet Padro de troca de mensagens Padro da mensagem XML DESCRIO Padro definido pelo WS-I Basic Profile 1.1 (http://www.wsi.org/Profiles/BasicProfile-1.1-2004-08-24.html). Web Service, disponibilizados pelo Sistema de NF-e da Prefeitura de So Paulo. Internet SSL verso 3.0, com autenticao mtua atravs de certificados digitais. SOAP verso 1.2. XML no padro Style/Encoding: Document/Literal, wrapped. X.509 verso 3, emitido por Autoridade Certificadora credenciada pela Infraestrutura 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 NF-e (no caso de Consulta de NF-e Recebidas utilizar o certificado digital do tomador). Opcionalmente as Mensagens XML de consulta de NF-e Emitidas, NF-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 Notas Fiscais Eletrnicas). 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. 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 Enveloped e C14N. Ser validado alm da integridade e autoria, a cadeia de confiana com a validao das LCRs. Campos no obrigatrios do Schema que no possuam contedo tero suas tags suprimidas na mensagem XML. Padres de preenchimento 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.

Padro de certificado digital

Padro de assinatura digital

Validao de assinatura digital

3.3. MODELO OPERACIONAL

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 10

Como dito anteriormente, a forma de processamento dos pedidos de servios do Web Service do Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo 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 NFe; 3. O sistema da NF-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; 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.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 11

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.

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 Notas Fiscais Eletrnicas da Prefeitura de So Paulo. Para obter os Schemas XML do Web Service da NF-e acione o navegador Web (Firefox, Internet Explorer, por exemplo) e digite o endereo a seguir: https://nfe.prefeitura.sp.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 NF-e, verso 1).

A maioria dos Schemas XML definidos para a utilizao do Web Service do Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo 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.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 12

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

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 13

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 So Paulo e podero ocorrer sempre que se fizerem necessrias.

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

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 Sinal de maior Sinal de menor E-comercial Aspas Sinal de apstrofe SUBSTITUIR POR &gt; &lt; &amp; &quot; &apos;

> < &

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 14

4. Web Service Lote NFe


O Web Service LoteNFe, do Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo, 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).

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 Notas Fiscais Eletrnicas da Prefeitura de So Paulo. Para obter o WSDL do Web Service da NF-e acione o navegador Web (Firefox, Internet Explorer, por exemplo) e digite o endereo a seguir: https://nfe.prefeitura.sp.gov.br/ws/lotenfe.asmx?WSDL.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 15

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://nfe.prefeitura.sp.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:
DESCRIO NOME DO TIPO (tipo utilizado para informar...) TIPO BASE

TAMANHO

DEC

OBSERVAO O cdigo informado dever pertencer Tabela de Municpios (do IBGE) disponibilizada pela Prefeitura de So Paulo.

tpCidade

Cdigo da cidade de endereo.

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. Tabelas de tipos simples
DESCRIO NOME DO TIPO (tipo utilizado para informar...) TIPO BASE TAMANHO DEC OBSERVAO Exemplo: tpAliquota Valor da alquota do servio N 3-5 4 5% - 0.05 2,5% - 0.025 1,75% - 0.0175 Assinatura digital de NF-e / RPS Base64 Binary Cadeia de caracteres (com informaes do RPS emitido) assinada conforme descrito no item 4.3.2. Cadeia de caracteres (com informaes do RPS emitido) assinada conforme descrito no item 4.3.10. 0-30 7-8 Bairro CEP O cdigo informado dever pertencer Tabela de Municpios (do IBGE) disponibilizada pela Prefeitura de So Paulo.

tpAssinatura

tpAssinaturaCancelamento

Assinatura Digital de Cancelamento de NF-e. Bairro do endereo CEP do endereo

Base64 Binary C N

tpBairro tpCEP

tpCidade

Cdigo da cidade do endereo

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 16

DESCRIO NOME DO TIPO (tipo utilizado para informar...) Nmero no Cadastro Nacional da Pessoa Jurdica

TIPO BASE C

TAMANHO

DEC

OBSERVAO

tpCNPJ

14 O cdigo informado dever pertencer Tabela de Servios disponibilizada pela Prefeitura de So Paulo. O cdigo informado dever pertencer a Tabela de Erros ou a Tabela de Alertas disponibilizada pela Prefeitura de So Paulo.

tpCodigoServico

Cdigos de Servio

4-5

tpCodigoEvento

Cdigo do Evento

3-4

tpCodigoVerificacao tpComplementoEndereco tpCPF tpDescricaoEvento

Cdigo de Verificao da NF-e Complemento do Endereo Nmero no Cadastro de Pessoas Fsicas Descrio do Evento

C C C C

8 0-30 11 0-300

Cdigo de verificao da NF-e gerado pelo Sistema de Notas Fiscais Eletrnicas.

Descrio correspondente ao cdigo do evento ocorrido. 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). Exemplo: Digitado na NF Lavagem de carro com lavagem de motor Preenchimento do arquivo: Lavagem de carro|com lavagem de motor

tpDiscriminacao

Discriminao dos Servios

0-2000

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 24 linhas (altura). permitido (no recomendvel), o uso de mais de 2000 caracteres. Caso seja ultrapassado o limite de 24 linhas, o contedo ser truncado durante a impresso da Nota.

tpEmail tpInscricaoEstadual tpInscricaoMunicipal tpLogradouro

E-mail Inscrio Estadual Inscrio Municipal Endereo

C N N C

0-75 1-19 8 0-50 Tipo utilizado para informar nmero de NF-e, nmero de RPS, nmero de Guia, nmero de Lote, nmero de pgina, ...

tpNumero

Nmero

1-12

tpNumeroEndereco

Nmero do Endereo

0-10

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 17

DESCRIO NOME DO TIPO (tipo utilizado para informar...)

TIPO BASE

TAMANHO

DEC

OBSERVAO Opo pelo Simples: 0 - No-optante pelo Simples Federal nem Municipal; 1 - Optante pelo Simples Federal (Alquota de 1,0%);

tpOpcaoSimples

Opo pelo Simples

2 - Optante pelo Simples Federal (Alquota de 0,5%); 3 - Optante pelo Simples Municipal. 4 - Optante pelo Simples Nacional.

tpQuantidade tpRazaoSocial tpSerieRPS

Tipo Quantidade Tipo Razo Social Tipo Srie do RPS

N C C

1-15 0-75 1-5 Nome / Razo Social Srie do RPS Status da NF-e: N Normal; C Cancelada; E Extraviada.

tpStatusNFe

Status da NF-e

tpSucesso

O contedo deste campo indica se o pedido do servio obteve sucesso ou no (conforme descrito no item (4.3.1). Tempo de processamento (segundos). Tipo de endereo.

tpTempoProcessamento tpTipoLogradouro

N C

1-15 0-3 Rua, Av, ... Tipo do RPS: RPS Recibo Provisrio de Servios;

tpTipoRPS

Tipo do RPS.

RPS-M Recibo Provisrio de Servios proveniente de Nota Fiscal Conjugada (Mista); RPS-C Cupom. Tipo de Tributao: T - Tributao no municpio de So Paulo;

tpTributacaoNFe

Tipo de Tributao

F - Tributao fora do municpio de So Paulo; I Isento; J - ISS Suspenso por Deciso Judicial.

tpUF

Sigla da UF do endereo.

Sigla da UF do endereo. Tipo utilizado para valores com 15 dgitos, sendo 13 de corpo e 2 decimais.

tpValor

Valores

0-15

Exemplo: R$ 500,85 500.85 R$ 826,00 826 O contedo deste campo indica a verso do Schema XML utilizado. Exemplo:

tpVersao

Verso

1-3

Verso 1 1 Verso 10 10 Verso 100 100

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 18

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

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

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 19

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 20

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 21

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 22

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: <Nome do Mtodo>(<Parmetro VersaoSchema>, <Parmetro MensagemXML>). 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 informando o no sucesso da operao (TAG sucesso = false) e as demais Informaes sobre os eventos de erro/alerta ocorridos.

Observaes: Descrio dos nomes e abreviaes utilizadas no cabealho das tabelas que representam estrutura definida nos schemas XML:

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;

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 23

E. Coluna Tipo: Tipos Base: N campo numrico; C campo alfanumrico; D campo data; Tipos Simples e Tipos Complexos: F. 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://nfe.prefeitura.sp.gov.br/ws/schemas.zip

4.3.2. Envio de RPS

I. Descrio: Este mtodo responsvel por atender aos pedidos de Envio Individual de RPS para substituio por NF-e. II. Mtodo: EnvioRPS. III. Mensagem XML: O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela a seguir:

* 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. 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).

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 24

A cadeia de caracteres a ser assinada dever conter 86 posies com as informaes apresentadas na tabela a seguir:

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 25

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

... Com base no trecho da mensagem XML apresentada, montamos a seguinte string de caracteres:
"31000000OL03 00000000000120070103TNN00000000205000000000000050000002658100013167474254"

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. 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. IV. Schema da Mensagem XML do Retorno: RetornoEnvioRPS.xsd

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

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 26

V. Formato das Mensagens SOAP: Pedido:

Retorno:

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 NF-e. II. Mtodo: EnvioLoteRPS. III. O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela a seguir:

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 27

* 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 NF-e.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 28

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

* 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 NF-e.

V. Formato das Mensagens SOAP:

Pedido:

Retorno:

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 29

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 NF-e. Este mtodo no substitui os RPS por NF-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. III.

Mtodo: TesteEnvioLoteRPS O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela apresentada no item V Schema da Mensagem XML do Retorno: RetornoEnvioLoteRPS.xsd (Idntico ao Schema da Mensagem XML do Retorno do item V)

IV.

4.3.5. Pedido de Consulta de NF-e (ConsultaNFe)

I.

Descrio: Este mtodo responsvel por atender aos pedidos de consulta de NF-e / RPS. Seu acesso permitido apenas pela chave de identificao da NF-e ou pela chave de identificao do RPS. Mtodo: ConsultaNFe

II.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 30

III.

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

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

IV.

Schema da Mensagem XML do Retorno: RetornoConsulta.xsd

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

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 31

V. Pedido:

Formato das Mensagens SOAP:

Retorno:

4.3.6. Pedido de Consulta de NF-e Recebidas (ConsultaNFeRecebidas)

I. II. III.

Descrio: Este mtodo responsvel por atender aos pedidos de consulta de NF-e Recebidas. Mtodo: ConsultaNFeRecebidas O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela a seguir:

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 32

PedidoConsultaNFePeriodo.xsd*
# P1 Campo Cabecalho Descrio TAG de grupo das informaes do cabealho. Verso do XML Schema Utilizado. CPF/CNPJ do Remetente autorizado a enviar a mensagem XML. Para consulta de NF-e Recebidas: Informe o CPF/CNPJ do tomador da NF-e. Para consulta de NF-e Emitidas: Informe o CNPJ do emissor da NF-e. Para consulta de NF-e Recebidas: Informe a Inscrio Municipal do Tomador. Inscricao Para consulta de NF-e Emitidas: Informe a Inscrio Municipal do Prestador. Neste tipo de consulta o preenchimento deste campo se torna obrigatrio. dtInicio dtFim NumeroPagina ** Data incio da consulta. Data fim da consulta. Nmero da pgina consultada E E E P1 P1 P1 D D tpNumero 1-1 1-1 1-1 Default = 1 Signature o elemento raiz de uma assinatura XML. Este elemento descrito no arquivo xmldsigcoreschema_v01.xsd E P1 tpInscricaoMunicipal 0-1 ATENO 1: Este campo s dever ser preenchido com a inscrio de contribuintes estabelecidos no municpio de So Paulo (CCM). Ele G Pai Tipo Ocorr. 1-1 Observao

Versao

P1

tpVersao

1-1

CPFCNPJRemet ente

P1

tpCPFCNPJ

1-1

CPFCNPJ

P1

tpCPFCNPJ

1-1

P2

Signature

Assinatura digital da mensagem XML.

SignatureType

1-1

* Representao da estrutura definida no schema XML PedidoConsultaNFePeriodo.xsd. Os mtodos ConsultaNFeRecebidas e ConsultaNFeEmitidasidas 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 NF-e, Consulta de NF-e Recebidas, Consulta de NF-e Emitidas e Consulta de Lote) s sero retornadas at 50 NF-e por consulta. Porem a Consulta de NF-e Recebidas (assim como a Consulta de NF-e Emitidas) pode encontrar uma quantidade maior de NF-e do que o limite especificado. Sendo assim, as NF-e encontradas sero agrupadas em pginas com at 50 NF-e. Para consultar as NF-e de cada uma das pginas o contribuinte dever transmitir uma mensagem XML de pedido de Consulta de NF-e Recebidas indicando qual pgina deseja consultar. Desta forma, caso um pedido de consulta de NF-e Recebidas, para pgina X, retorne 50 NF-e o sistema de informao do Contribuinte deve efetuar novo pedido de Consulta de NF-e Recebidas, para pgina X+1, para verificar se existem mais NF-e Recebidas no perodo consultado.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 33

Quando o sistema de informao do Contribuinte efetuar um pedido de Consulta de NF-e Recebidas para uma determinada pgina e est consulta retornar menos que 50 NF-e o sistema de informao do contribuinte saber que estas so as ltimas NF-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 NF-e por que a pgina consultada no existe.

Exemplo: O sistema de informao de um Contribuinte envia uma mensagem XML de Pedido Consulta de NF-e Recebidas para o perodo de 01/09/2006 30/09/2006 e requerendo a pgina 1. Para este pedido so encontradas 137 NF-e recebidas. As 137 NF-e so agrupadas em trs pginas: Pgina 1 com as primeiras 50 NF-e (1 50); pgina 2 com as prximas 50 NF-e (51 100) e pgina 3 com as 37 NFe 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 NF-e para a pgina 1. O sistema de informao do Contribuinte envia outra mensagem XML de Pedido Consulta de NF-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 NF-e para a pgina 2. O sistema de informao do Contribuinte envia outra mensagem XML de Pedido Consulta de NF-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 NF-e para a pgina 3 e por tanto no existem mais NF-e recebidas para o perodo consultado. Obs.: As NF-e encontradas so ordenadas por data de emisso da nota (ou data do cancelamento, caso a NF-e tenha sido cancelada) e pela inscrio municipal (CCM) do prestador que emitiu a nota. Abaixo, fluxo de funcionamento baseado no exemplo descrito:

IV.

Schema da Mensagem XML do Retorno: RetornoConsulta.xsd (Idntico ao do item 4.3.5)

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 34

V. Pedido:

Formato das Mensagens SOAP:

Retorno:

4.3.7. Pedido de Consulta de NF-e Emitidas (ConsultaNFeEmitidas)

I. II. III.

Descrio: Este mtodo responsvel por atender aos pedidos de consulta de NF-e Emitidas. Mtodo: ConsultaNFeEmitidas O parmetro MensagemXML (idntico ao Schema da Mensagem XML de pedido apresentado no item 4.3.6 III). Schema da Mensagem XML do Retorno: RetornoConsulta.xsd (Idntico ao do item 4.3.5)

IV.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 35

V. Pedido:

Formato das Mensagens SOAP:

Retorno:

4.3.8. Pedido de Consulta de Lote (ConsultaLote)

I.

Descrio: Este mtodo responsvel por atender aos pedidos de Consulta de Lote de NF-e geradas a partir do mtodo EnvioLoteRPS. Mtodo: ConsultaLote O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela a seguir:

II. III.

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 36

PedidoConsultaLote.xsd*
# P1 Campo Cabecalho Descrio TAG de grupo das informaes do cabealho. Verso do XML Schema Utilizado. CNPJ do Remetente autorizado a enviar a mensagem XML. Nmero do Lote a ser consultado. Ele G Pai Tipo Ocorr. 1-1 Observao

Versao

P1

tpVersao

1-1

CNPJRemetente

P1

tpCPFCNPJ

1-1

NumeroLote

P1

tpNumero

1-1 Signature o elemento raiz de uma assinatura XML. Este elemento descrito no arquivo xmldsigcoreschema_v01.xsd

P2

Signature

Assinatura digital da mensagem XML.

SignatureType

1-1

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

IV. V. Pedido:

Schema da Mensagem XML do Retorno: RetornoConsulta.xsd (Idntico ao do item 4.3.5) Formato das Mensagens SOAP:

Retorno:

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 37

4.3.9. Pedido de Informaes do Lote (ConsultaInformacoesLote)

I.

Descrio: Este mtodo responsvel por atender aos pedidos de Consulta de Informaes de Lote de NF-e geradas a partir do mtodo EnvioLoteRPS. Mtodo: ConsultaInformacoesLote O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela a seguir: PedidoInformaesLote.xsd*
# Campo Cabecalho Descrio TAG de grupo das informaes do cabealho. Verso do XML Schema Utilizado. CNPJ do Remetente autorizado a enviar a mensagem XML. Ele G Pai Tipo Ocorr. 1-1 Observao

II. III.

P1

Versao

P1

tpVersao

1-1

CNPJRemetente

P1

tpCPFCNPJ

1-1

NumeroLote

Nmero do Lote a ser consultado.

P1

tpNumero

0-1

Caso no seja informado o nmero do lote, sero retornadas informaes do ltimo lote gerador de NF-e.

InscricaoPrestador

Inscrio municipal do prestador de servios que gerou o lote a ser consultado.

P1

tpInscricaoMunicipal

1-1

P2

Signature

Assinatura digital da mensagem XML.

SignatureType

1-1

Signature o elemento raiz de uma assinatura XML. Este elemento descrito no arquivo xmldsigcoreschema_v01.xsd

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

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 38

IV.

Schema da Mensagem XML do Retorno: RetornoInformacoesLote.xsd RetornoInformaesLote.xsd*

# P1

Campo Cabecalho Versao Sucesso InformacoesLote

Descrio TAG de grupo das informaes do cabealho. Verso do XML Schema Utilizado. Status do Envio de Lote Informaes sobre o Lote Informaes sobre a ocorrncia de eventos geradores de alertas durante o processamento da mensagem XML. Informaes sobre a ocorrncia de eventos geradores de erros durante o processamento da mensagem XML.

Ele G A E G

Pai P1 P1 P1

Tipo tpVersao tpSucesso tpInformacoesLote

Ocorr. 1-1 1-1 1-1 0-1

Observao

P2

Alerta

tpEvento

0-N

P3

Erro

tpEvento

0-N

* Representao da estrutura definida no schema XML RetornoInformacoesLote.xsd. V. Pedido: Formato das Mensagens SOAP:

Retorno:

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 39

4.3.10. Pedido de Cancelamento de NF-e (CancelamentoNFe)

I.

Descrio: Este mtodo responsvel por atender aos pedidos referentes ao cancelamento de NF-e geradas a partir do mtodo EnvioLoteRPS. Mtodo: CancelamentoNFe O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela a seguir: PedidoCancelamentoNFe.xsd*

II. III.

# P1

Campo Cabecalho

Descrio TAG de grupo das informaes do cabealho. Verso do XML Schema Utilizado.

Ele G

Pai -

Tipo -

Ocorr. 1-1

Observao

Versao

P1

tpVersao

1-1

CNPJ do Remetente CNPJRemetent autorizado a enviar a e mensagem XML

P1

tpCPFCNPJ

1-1 True - As NF-e s sero canceladas se no ocorrer nenhum evento de erro durante o processamento de todo o lote.

Transacao

Informe se as NF-e a serem canceladas faro parte de uma mesma transao.

P1

Boolean

0-1

False - As NF-e aptas a serem canceladas sero canceladas, mesmo que ocorram eventos de erro durante processamento do cancelamento de outras NF-e deste lote. Default: true.

P2

Detalhe ChaveNFe

Tag de grupo das informaes de detalhe. Chave da NF-e.

G E E

P2 P2 tpChaveNFe tpAssinaturaCa ncelamento

1-50 1-1 1-1 Signature o elemento raiz de uma assinatura XML. Este elemento descrito no arquivo xmldsigcoreschema_v01.xsd

Assinatura de AssinaturaCanc Cancelamento da elamento NF-e.

P3

Signature

Assinatura digital da mensagem XML.

SignatureType

1-1

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

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 40

Observao 1: Transao Se ocorrerem eventos de erro de validao dos dados do cabealho do pedido de cancelamento de NFe, independente da opo informada no campo Transao, nenhuma NF-e ser cancelada. Observao 2: Assinatura Adicional Cada NF-e a ser cancelada (representada pela TAG ChaveNFe) dever ter sua respectiva assinatura de cancelamento. 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. Para criar a assinatura dever ser gerado um Hash (utilizando SHA1) de uma cadeia de caracteres (ASCII) com informaes da NF-e a ser cancelada. Este Hash dever ser assinado utilizando RSA. A assinatura do Hash ser informada na TAG AssinaturaCancelamento. A cadeia de caracteres a ser assinada dever conter 20 posies com as informaes apresentadas na tabela a seguir:
# 1 2 Informao Inscrio Municipal do Prestador Nmero da NF-e Contedo Inscrio Municipal do Prestador com 8 posies (dgitos). Completar com zeros esquerda caso seja necessrio. Nmero da NF-e com 12 posies (dgitos). Completar com zeros esquerda caso seja necessrio.

Passos bsicos para assinatura de cancelamento de uma NF-e: 1 - Monte a string de caracteres conforme a tabela a apresentada anteriormente. A seguir apresentamos o exemplo de um trecho de uma mensagem XML de pedido de cancelamento de NF-e (os campos utilizados na montagem da cadeia de caracteres esto em negrito).

Com base no trecho da mensagem XML apresentada, montamos a seguinte String de caracteres: "31000000000000000009" 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. IV. Schema da Mensagem XML do Retorno: RetornoCancelamentoNFe.xsd RetornoCancelamentoNFe.xsd*
# P1 Campo Cabecalho Versao Sucesso Descrio TAG de grupo das informaes do cabealho. Verso do XML Schema Utilizado. Status do cancelamento. Ele G A E Pai P1 P1 Tipo tpVersao tpSucesso Ocorr. 1-1 1-1 1-1 Observao

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 41

RetornoCancelamentoNFe.xsd*
# Campo Descrio Informaes sobre a ocorrncia de eventos geradores de alertas durante o processamento da mensagem XML. Informaes sobre a ocorrncia de eventos geradores de erros durante o processamento da mensagem XML. Ele Pai Tipo Ocorr. Observao

P2

Alerta

tpEvento

0-N

P3

Erro

tpEvento

0-N

* Representao da estrutura definida no schema XML RetornoCancelamentoNFe.xsd. O Sistema da NF-e verificar se a NF-e existe e se no h nenhum impedimento para o cancelamento. O cancelamento poder ser realizado para vrias notas numa mesma mensagem XML (Obedecendo ao limite de 50). V. Pedido: Formato das Mensagens SOAP:

Retorno:

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 42

4.3.11. Pedido de Consulta de CNPJ (ConsultaCNPJ)

I.

Descrio: Este mtodo responsvel por atender aos pedidos de consulta de CNPJ. Este mtodo possibilita aos tomadores e/ou prestadores de servios consultarem quais Inscries Municipais (CCM) esto vinculadas a um determinado CNPJ e se estes CCM emitem NF-e ou no. Mtodo: ConsultaCNPJ O parmetro MensagemXML (ver item 4.3.1) dever ser preenchido conforme tabela a seguir: PedidoConsultaCNPJ.xsd*

II. III.

# P1

Campo Cabecalho

Descrio TAG de grupo das informaes do cabealho. Verso do XML Schema Utilizado. CNPJ do Remetente autorizado a enviar a mensagem XML CNPJ do contribuinte que se deseja consultar.

Ele G

Pai -

Tipo -

Ocorr. 1-1

Observao

Versao

P1

tpVersao

1-1

CNPJRemetente

P1

tpCPFCNPJ

1-1

P2

CNPJContribuinte

tpCPFCNPJ

1-1 Signature o elemento raiz de uma assinatura XML. Este elemento descrito no arquivo xmldsigcoreschema_v01.xsd

P3

Signature

Assinatura digital da mensagem XML.

SignatureType

1-1

*Representao da estrutura definida no schema XML PedidoConsultaCNPJ.xsd. IV. Schema da Mensagem XML do Retorno: RetornoConsultaCNPJ.xsd RetornoConsultaCNPJ.xsd*
# P1 Campo Cabecalho Versao Descrio TAG de grupo das informaes do cabealho. Verso do XML Schema Utilizado. Ele G A Pai P1 Tipo tpVersao Ocorr. 1-1 1-1 Observao

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 43

RetornoConsultaCNPJ.xsd*
# Campo Sucesso Descrio Status do cancelamento. Informaes sobre a ocorrncia de eventos geradores de alertas durante o processamento da mensagem XML. Informaes sobre a ocorrncia de eventos geradores de erros durante o processamento da mensagem XML. TAG de grupo das informaes do detalhe. Ele E Pai P1 Tipo tpSucesso Ocorr. 1-1 Observao

P2

Alerta

tpEvento

0-N

P3

Erro

tpEvento

0-N

P4

Detalhe

G E E

P4 P4 tpInscricaoMuni cipal Boolean

0-N 1-1 1-1

InscricaoMunici Inscrio Municipal vinculada pal ao CNPJ consultado. EmiteNFe Campo que indica se o contribuinte emite NF-e.

* Representao da estrutura definida no schema XML RetornoConsultaCNPJ.xsd. V. Pedido: Formato das Mensagens SOAP:

Retorno:

4.4. TABELA DE ERROS E ALERTAS

As tabelas a seguir, apresentam os erros e alertas relacionados ao Web Service do Sistema de Notas Fiscais Eletrnicas da Prefeitura de So Paulo. Legenda da coluna Onde Ocorre: A. VALIDAO DO SCHEMA; B. VERIFICAO DO CERTIFICADO/ASSINATURA; C. Envio de RPS;

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 44

D. E. F. G. H. I. J. K. L.

Envio de Lote de RPS; Teste de Envio de Lote de RPS; Consulta de NF-e; Consulta de NF-e Recebidas; Consulta de NF-e Emitidas; Consulta de Lote; Consulta de Informaes de Lote; Cancelamento de NF-e; Consulta de CNPJ.

4.4.1. Erros

Tabela de Erros de Schema


Cdigo 1001 1002 1050 1051 1052 1053 1054 1055 1056 1057 XML no compatvel com Schema. Verso do Schema XML Incorreto. Rejeio: Certificado Assinatura Invlido. Rejeio: Certificado Assinatura Data Validade. Rejeio: Certificado Assinatura sem CNPJ. Rejeio: Certificado Assinatura Erro Cadeia de Certificao. Rejeio: Certificado Assinatura revogado. Rejeio: Certificado Assinatura difere ICP-Brasil. Rejeio: Assinatura Digest difere do calculado. Rejeio: Assinatura difere do calculado. Descrio Onde Ocorre A A B B B B B B B B

Tabela de Erros de Pedido de Servio


Cdigo 104 106 107 108 207 209 215 218 219 220 301 Descrio A Data Inicial de emisso das Notas Fiscais enviadas no pode ser inferior a 01/06/2006. A Data Final de emisso das Notas Fiscais enviadas no pode ser inferior a 01/06/2006. A Data Final de emisso das Notas Fiscais enviadas no pode ser Superior a <data atual>. A Data Final de emisso das Notas Fiscais enviadas dever ser superior a Data Inicial. Data de Emisso do RPS no est compreendida entre <data inicio de emisso do lote> e <data fim de emisso do lote> conforme especificado no cabealho da mensagem XML. O cdigo de servio prestado no permite reteno de ISS. RPS em duplicidade na mensagem XML enviada. RPS: <Nmero do RPS> Srie: <Srie do RPS>. RPS no poder ser enviado novamente, pois est includo em Guia de Recolhimento. O campo Inscrio Municipal do Tomador (<Inscrio Municipal Tomador>) s dever ser preenchido para tomadores estabelecidos no municpio de So Paulo. CPF/CNPJ do Tomador (<CPF/CNPJ do Tomador>) possui mais de uma inscrio municipal, sendo obrigatrio o preenchimento do campo Inscrio Municipal do Tomador. O tomador de servios informado o prprio prestador. Onde Ocorre D,E D,E D,E D,E D,E C,D,E D,E C,D,E C,D,E C,D,E C,D,E

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 45

Cdigo 302 303 304 305 306 308 309 310 311 312 313 314 315 317 318 320 321 322 323 324 1100 1101 1102 1105 1106 1107 1108 1109 1201 1202 1203 1204 1205 1206 1207

Descrio CNPJ do Tomador de Servios invlido (dgitos verificadores no conferem). O Valor dos servios dever ser superior a R$ 0,00 (zero). O Valor das dedues dever ser inferior ao valor dos servios. O Valor das dedues dever ser superior ou igual a R$ 0,00 (zero). Cdigo do Servio Prestado <cdigo enviado> do RPS inexistente. Cdigo do Servio Prestado <cdigo enviado> do RPS no permite deduo na base de clculo. Cdigo do Servio Prestado <cdigo enviado> do RPS no permite tributao fora do municpio. Cdigo do Servio Prestado <cdigo enviado> no Informado. Apenas empresas tomadoras de servios inscritas no municpio ou rgos Pblicos podem efetuar reteno de ISS (CPF/CNPJ = <CPF/CNPJ do Tomador>). A data da emisso do RPS no foi preenchida Corretamente. A data da emisso do RPS no poder ser superior a data de hoje. A data da emisso do RPS no poder ser inferior a 01/06/2006. Nmero do RPS no informado. Campo Endereo no preenchido (obrigatrio para tomador com CNPJ). Campo Cidade/UF no preenchido (obrigatrio para tomador com CNPJ). Inscrio Municipal do Tomador de Servios consta como cancelada. Apenas Notas com tributao no municpio ou fora do municpio podem sofrer reteno de ISS. O campo discriminao dos servios no foi Preenchido. Nota no pode ser cancelada. Ver detalhes no Manual. Operao no autorizada por meio eletrnico em razo de ultrapassado o prazo permitido. O CNPJ do usurio autorizado a enviar a mensagem XML no confere com o CNPJ usado na comunicao. Tamanho da mensagem XML ultrapassou o limite mximo permitido de 500 Kbytes. Mensagem XML de Pedido do servio sem contedo. Lote no encontrado. NF-e no encontrada. O CPF/CNPJ da assinatura da mensagem XML no corresponde ao CPF/CNPJ do Prestador de Servios. O CPF/CNPJ vinculado ao Inscricao do Tomador no corresponde ao CPF/CNPJ informado no campo CPFCNPJTomador. CPF/CNPJ invlido. S permitido o envio de RPS emitidos por um nico Prestador de Servios (mesma inscrio municipal). Prestador de Servios no encontrado no Cadastro Municipal (CCM). Total de RPS no confere com o enviado (<total de RPS enviados no arquivo>). Valor Total de Servios no confere com o enviado (<somatrio do valor dos servios presentes no arquivo>). Valor Total de Deduo no confere com o enviado (<somatrio do valor das dedues presentes no arquivo>). Assinatura Digital do RPS incorreta. Prestador de Servios no autorizado a emitir NF-e.

Onde Ocorre C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E C,D,E,F,G,H,I,J,K,L C,D,E,F,G,H,I,J,K,L C,D,E,F,G,H,I,J,K,L I,J F C,D,E,H,I,J C,D,E C,D,E,G,H,L D,E D,E D,E D,E D,E C,D,E C,D,E

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 46

Cdigo 1303 1304 1305 1306 1401 1402 1403 1404

Descrio S permitido o cancelamento de NF-e emitidas por um nico Prestador de Servios (mesma inscrio municipal). Erro ao cancelar NF-e. Assinatura de cancelamento da NF-e incorreta. A NF-e que se deseja cancelar no foi gerada via Web Service. S permitido consultar NF-e emitidas por um nico Prestador de Servios (mesma inscrio municipal). O CPF/CNPJ da assinatura da mensagem XML no tem acesso ao Tomador de Servios informado. As datas informadas compreendem um perodo maior que o permitido. O perodo no pode abranger mais que 31 dias. A Inscrio Municipal do Prestador de Servios no consta na base de dados.

Onde Ocorre J J J J F G,H G,H J

4.4.2. Alertas

Tabela de Alertas
Cdigo 208 Descrio Alquota informada (<valor da alquota>) difere da alquota vigente (<valor da alquota vigente>) para o cdigo de servio informado (<cdigo de atividade>). O sistema ir adotar a alquota vigente. A inscrio municipal do tomador (<Inscrio Municipal do Tomador>) no foi encontrada na base de dados de CCM. Cidade/UF informada (<cidade do Tomador>)/(<UF do Tomador>) no foi encontrada na base de dados. RPS j foi convertido individualmente em NF-e atravs do site e no ser processado novamente. RPS reenviado. A NF-e (<nmero da NF-e>) referente ao RPS (Nmero: <nmero do RPS >, Srie: <sria do RPS >) foi cancelada e uma nova NF-e foi emitida. O CNPJ informado (<CNPJ>) possui inscrio municipal em So Paulo, porm foi informado endereo de fora do municpio (<cidade/UF>). NF-e j cancelada em <data de cancelamento>. NF-e em duplicidade na mensagem XML enviada. No h nenhuma Inscrio Municipal vinculada ao CPF/CNPJ informado. Onde Ocorre C,D,E

211 214 216 217 221 1301 1302 1405

C,D,E C,D,E C,D,E C,D,E C,D,E K K L

Manual de Utilizao Web Service

Verso do Manual: 2.2

pg. 47

5. Arquivos de Exemplos

Para obter exemplos das mensagens XML para todos os pedidos e retornos, acesse: https://nfe.prefeitura.sp.gov.br/ws/exemplos.zip

Anexo I

TABELA DE MUNICPIOS Os campos de cdigos de municpios devem ser informados com a utilizao da Tabela de Municpios mantida pelo IBGE.