Gerar um XML de Envio passo-a-passo – Antigo

Última atualização em: 01 de agosto, 2014

 

Segurança dos Web Services

O InvoiCy NFS-e trabalha com um sistema de segurança em cada web service, trata-se de uma chave de segurança de 128 bits.

Cada nova empresa cadastrada no sistema recebe uma chave de acesso que, no momento de envio de algum XML será concatenada com o conteúdo do XML e criptografada em MD5, gerando a CK (chave de comunicação) que será enviada dentro da tag “<EmpCK>”. Para mais informações sobre a chave de acesso consulte o artigo Verificando a chave de acesso da empresa.

Cada cliente do InvoiCy NFS-e recebe uma PK (chave de parceiro) que deve ser enviada em todos os XML dentro da tag “<EmpPK>” , essa chave é a mesma usada para solicitar licenças e fará parte do processo de segurança do InvoiCy NFS-e.
A chave de parceiro é gerada por nosso Sistema de Gestão no momento que a sua empresa é cadastrada como nosso parceiro. A mesma será enviada por e-mail e utilizada para controlar as empresas de clientes finais que utilizarão licenças adquiridas pela sua empresa.

Exemplo do cabeçalho de um XML contendo a chave de comunicação e a chave de parceiro.

cabecalho_xmlCabeçalho com CK e PK

Para gerar a CK concatena-se a chave de acesso com o XML linearizado (remover quebras de linhas e espaços entre as tags). Nesse processo o cabeçalho do XML não é usado, apenas o conteúdo após a tag “</Cabecalho>”. Segue o exemplo para cada web service:

  • Recepção RPS é chave de acesso + <Lista>… </Lista> (sempre com todo o conteúdo da tag)
  • Consulta, Cancelamento e Download Espelho RPS é chave de acesso + <ListaRPS>…</ListaRPS>
  • Download XML é chave de acesso + <FaixaConsulta>… </FaixaConsulta>
  • Cadastro do prestador não utiliza a CK.

Após calcular o hash MD5 dessa string e o resultado será a CK. No caso de dúvidas ver o artigo Como gerar o código Hash MD5.

Gerar um XML passo-a-passo

De uma forma simplificada, a empresa precisa seguir os passos abaixo para criar um XML válido:

1. Gerar o XML a ser comunicado (sem o cabeçalho);

2. Linearizar o XML (remover quebras de linhas e espaços entre as tags);

3. Gerar a CK;

4. Montar o cabeçalho e inserir após o mesmo o XML gerado nos passos 1 e 2.

5. Todo esse XML deve ser convertido para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp. Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática.

6. Substituir os caracteres especiais/símbolos pela Entity number correspondente, por exemplo: “ç = ç”, “Ç = Ç”. Para mais informações consultar o artigo Entity number.

7. Incluir esse XML dentro da tag “EntradaXML” do SOAP.
Exemplo prático

Para facilitar o entendimento, segue um exemplo prático da criação de um XML:

1. Chave de acesso: JnL6wcTDt+hT42gROCYho6F4VTMCx0

2. XML de Recepção linearizado:

3. Chave de acesso e XML concatenado para geração da CK:

4. CK (Hash MD5) gerado sobre a string concatenada no passo 3: dd247a15c1e4fb3241f7e6f9de9cc38a

5. Cabeçalho gerado e concatenado com o XML:

Observe que a CK gerada foi incluída na tag <EmpCK>.

6. XML convertido para texto:

7. XML com os caracteres especiais/símbolos substituídos pela Entity number:

Observe a substituição destacada em vermelho na imagem e abaixo:
exemplo

 

8. XML inserido no pacote SOAP e pronto para envio ao InvoiCy NFS-e:

LAYOUT XML 1.0

Última atualização em: 27 de fevereiro, 2015

 

Olá! Este artigo tem por objetivo disponibilizar o layout 1.0 do XML do MDF-e. Aqui você irá encontrar a estrutura completa de campos para realizar a integração de seu ERP com o InvoiCy.

A tabela abaixo deve ser utilizada como legenda para interpretação dos campos do arquivo do envio e retorno do XML.

Coluna

Nome do Campo

Tipo

(tamanho)

N – campo numérico C – campo alfanumérico D – campo data H – campo hora

Ele

G – Grupo E – Elemento CG – Elemento de Grupo que deriva de uma escolha (choice) CE – Elemento que deriva de uma escolha (choice)

Pai

TAG raiz do XML de integração

Ocorrência

x-y, onde x indica a ocorrência mínima e y, a ocorrência máxima:

1-1  = campo obrigatório, com uma possibilidade,

1-N = campo obrigatório, com uma ou várias possibilidades,

0-1  = campo opcional, com uma possibilidade,

0-N = campo opcional, com uma ou várias possibilidades.

O layout 1.0 do XML está disponível para download em arquivo XLS. Para visualizá-lo, certifique-se de que você possui o Microsoft Excel instalado em seu computador.

DOWNLOAD:

LAYOUT XML 1.0 (MDF-e)

LAYOUT Evento MDF-e

LAYOUT Consultas MDF-e

Acesse também a Central de Downloads Migrate, onde você poderá encontrar diversos exemplos reais de MDF-e para download.

Enviando um MDF-e

Última atualização em: 21 de fevereiro, 2017

 

Olá! Neste artigo iremos demonstrar como realizar o envio de um MDF-e através do InvoiCy.

A partir de agora, assumimos que você já leu o artigo “Integrando com o InvoiCy”. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento deste artigo.

Os seguintes passos são necessários para enviar um MDF-e:

1. Consumindo o Web Service arecepcao.aspx.
Primeiramente, você deve realizar o consumo do Web Service de envio de documentos do InvoiCy, conforme o artigo “Integrando com InvoiCy”.

2. Gerando o documento no layout do MDF-e.
Para obter o layout atualizados do MDF-e, consulte o artigo “Layout 3.0 MDF-e”. Neles você encontra a estrutura completa do arquivo XML da para gerar o documento a ser enviado ao InvoiCy.

O XML do documento deve ser convertido para texto, e inserido entre as TAGS <inv:Documento> </inv:Documento> do SOAP de envio. Veja abaixo um exemplo:

Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática. Para os casos em que o desenvolvedor preferir codificar toda a comunicação sem utilizar componentes, além de ser necessário escrever todo o XML do SOAP, também deverá ser feita a conversão do XML do documento para texto, substituindo os caracteres “<” e “>” por “&lt;” e “&gt;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp.

Para facilitar o seu entendimento, anexamos a este artigo alguns exemplos de arquivo XML no layout do MDF-e.

Clique aqui, e realize o download do arquivo zip contendo exemplos de arquivos XML do MDF-e.

3. Realize a leitura do retorno do envio do MDF-e.
Após o envio do MDF-e, precisamos realizar a leitura do retorno do processamento do documento. O retorno recebido segue a seguinte estrutura SOAP:

A estrutura SOAP acima demonstra o retorno do envio de apenas um único documento.

Note que na TAG <Documento> é retornado o conteúdo XML do retorno, codificado em “CDATA”. Este conteúdo pode ser lido pelo ERP para atualização do Status do documento.

Abaixo demonstramos a estrutura do XML de retorno:

Todo o conteúdo acima estará dentro da tag “CDATA” que, por sua vez, estará dentro da TAG <Documento> do SOAP de retorno.

Existe ainda uma tabela de códigos e descrições dos retornos da SEFAZ, que você pode consultar no artigo “Códigos de Retorno do MDF-e”.

Agora que você já está familiarizado com a integração, podemos prosseguir ao próximo passo.

Seu próximo passo é: Cancelando um MDF-e

Entity Number

Última atualização em: 07 de janeiro, 2015

Olá, como mencionado em outros artigos disponível no Portal, o XML de sua NFS-e precisa ser convertido para texto, sendo assim abaixo possuímos a forma como você pode fazer a conversão e poder utilizar determinados caracteres. Veja abaixo:

      Reserved Characters in HTML

tabela_1
      ISO 8859-1 Symbols


      ISO 8859-1 Characters


      Math Symbols Supported by HTML


      Greek Letters Supported by HTML

Fonte: http://www.w3schools.com/charsets/ref_html_entities_4.asp

Validação de Arquivos XML

Última atualização em: 10 de julho, 2014

Para realizar a validação de um arquivo XML precisaremos dos seguintes itens:

  • O arquivo XML a ser validado;
  • O Schema XSD que descreve como o arquivo XML deve estar estruturado;
  • Notepad++ com o plugin XML Tools ou outra ferramenta como o XML SPY.

Os arquivos XSD podem ser obtidos no artigo de cada serviço.
Neste artigo estaremos demonstrando como executar a validação utilizando o Notepad++. Caso o seu Notepad++ não possua o plugin XML Tools, basta ir ao menu Plugins > Show Plugin Manager > Selecione XML Tools e clique em Install.

      1. Validando o XML
Para validar o XML, é necessário ir até a opção Plugins > XML Tools > Validate Now. Você pode também usar o atalho Ctrl+Alt+Shift+M .

validacao_xml_notepad

Ao clicar em Validate Now irá aparecer a seguinte janela:

validacao_xml_notepad2

Selecione o arquivo XSD correspondente ao XML que você quer validar e clique em OK. Caso ocorra algum erro de validação, a seguinte janela irá aparecer:

validacao_xml_notepad3

Corrija as informações e repita o processo até aparecer a seguinte janela:

validacao_xml_notepad4

Gerar um XML de Envio passo-a-passo

Última atualização em: 25 de setembro, 2015

Segurança dos Web Services

O InvoiCy trabalha com um sistema de segurança em cada web service, trata-se de uma chave de segurança de 128 bits.

Cada nova empresa cadastrada no sistema recebe uma chave de acesso que, no momento de envio de algum XML será concatenada com o conteúdo do XML e criptografada em MD5, gerando a CK (chave de comunicação) que será enviada dentro da tag “<Inv:EmpCK>”.

Cada cliente do InvoiCy recebe uma PK (chave de parceiro) que deve ser enviada em todos os XML dentro da tag “<Inv:EmpPK>” , essa chave é a mesma usada para solicitar licenças e fará parte do processo de segurança do InvoiCy.

Exemplo do cabeçalho de um XML contendo a chave de comunicação e a chave de parceiro.

Cabeçalho com CK e PK

Para gerar a CK concatena-se a chave de acesso com o XML linearizado (remover quebras de linhas e espaços entre as tags). Nesse processo o cabeçalho do XML não é usado, apenas o conteúdo após a tag “<inv:Documento>”. Segue o exemplo para cada web service:

  • Recepção RPS é chave de acesso + < Envio>… </ Envio> (sempre com todo o conteúdo da tag)
  • Consulta, Cancelamento e Download Espelho RPS é chave de acesso + <Documento>…</Documento>

Após calcular o hash MD5 dessa string e o resultado será a CK. Em caso de dúvidas, veja  o exemplo prático abaixo.

Gerar um XML passo-a-passo

De uma forma simplificada, a empresa precisa seguir os passos abaixo para criar um XML válido:

1. Gerar o XML a ser comunicado (sem o cabeçalho);

2. Linearizar o XML (remover quebras de linhas e espaços entre as tags);

3. Gerar a CK;

4. Todo esse XML deve ser convertido para texto, substituindo os caracteres “<”, “>” e “ “ ” (aspas) por “&lt;”, “&gt;” e “&quot;” respectivamente, de acordo com a tabela da W3C: http://www.w3schools.com/html/html_entities.asp. Nos casos em que for usada uma ferramenta RAD para consumo do Web Service através de componente nativo, por exemplo Visual Studio utilizando Web Reference, a conversão do XML para texto irá ocorrer de forma automática.

5. Substituir os caracteres especiais/símbolos pela Entity number correspondente, por exemplo: “ç = Ç”, “Ç = ç”. Para mais informações consultar o artigo Entity number.

6. Incluir esse XML dentro da tag “inv:Documento” do SOAP.

Exemplo prático

Para facilitar o entendimento, segue um exemplo prático da criação de um XML:

1. Chave de acesso: R8CC40EC614E64108965517G90GDEYB6

2. XML de Recepção linearizado:

3. Chave de acesso e XML concatenado para geração da CK:

4. CK (Hash MD5) gerado sobre a string concatenada no passo 3: 193f2eb31f12098f98b330ef193e18c0

5. XML convertido para texto:

6. XML com os caracteres especiais/símbolos substituídos pela Entity number:

Observe a substituição destacada em vermelho na imagem e abaixo:

7. XML inserido no pacote SOAP e pronto para envio ao InvoiCy:

Observe que a CK gerada foi incluída na tag <Inv:EmpCK>.

Envio de mais de uma NFS-e.

O InvoiCy permite o envio de mais de um documento  via Web Service, podendo realizar, por exemplo,  a consulta, cancelamento  e envio de um documento, todos esses documentos em um único Envio. Conforme imagem abaixo, a tag que deve ser repetida é <inv:DadosItem>.

Para enviar mais de um documento a geração da chave de comunicação (tag <inv:EmpCK>) é obtida usando a chave de acesso (tag  <inv:EmpPK>) e apenas o primeiro documento que será enviado.

LAYOUT XML 4.00

Última atualização em: 12 de setembro, 2017

 

Olá! Este artigo tem por objetivo disponibilizar o layout 4.00 do XML da NF-e e da NFC-e. Aqui você irá encontrar a estrutura completa de campos para realizar a integração de seu ERP com o InvoiCy.

A tabela abaixo deve ser utilizada como legenda para interpretação dos campos do arquivo do envio e retorno do XML.

Coluna

Nome do Campo

Tipo

(tamanho)

N – campo numérico C – campo alfanumérico D – campo data H – campo hora

Ele

G – Grupo E – Elemento CG – Elemento de Grupo que deriva de uma escolha (choice) CE – Elemento que deriva de uma escolha (choice)

Pai

TAG raiz do XML de integração entre ERP e GNF-e

Ocorrência

x-y, onde x indica a ocorrência mínima e y, a ocorrência máxima:

1-1  = campo obrigatório, com uma possibilidade,

1-N = campo obrigatório, com uma ou várias possibilidades,

0-1  = campo opcional, com uma possibilidade,

0-N = campo opcional, com uma ou várias possibilidades.

Este layout encontra-se adequado com a Nota Técnica NT2016.002, disponibilizado pela SEFAZ (Secretaria da Fazenda). A íntegra desta NT pode ser consultada clicando aqui.

O layout 4.00 do XML está disponível para download em arquivo XLS. Para visualizá-lo, certifique-se de que você possui o Microsoft Excel instalado em seu computador.

DOWNLOAD:

LAYOUT XML 4.00 (NF-e e NFC-e)

Acesse também a Central de Downloads Migrate, onde você poderá encontrar diversos exemplos reais de NF-e e NFC-e para download.