2014
Gerar um XML de Envio passo-a-passo
27 de março de 2014Seguranç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 “<”, “>” e “"” 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.
Devido ao tamanho da mensagem, há um limite de 200 RPS por requisição, sendo que, ao enviar mais de 1 documento na mesma requisição eles serão processados de forma assíncrona.