Criptografia da senha do certificado ao cadastrar empresa via WS

Última atualização em: 16 de abril, 2021

Para garantir maior tranquilidade e segurança ao usuário Parceiro a Plataforma InvoiCy faz uso de comunicação via HTTPS, e além disso permite que o Parceiro envie a senha do seu certificado digital de forma criptografada, no momento de efetuar o cadastro de uma empresa via Web Service.

Para isso basta enviar o cadastro da empresa, seguindo o layout padrão do InvoiCy disponível no artigo Cadastrar empresa via Web Service, porém sem enviar os dados do certificado digital.

Para maiores informações visualize a estrutura do layout de integração para cadastro de empresa clicando aqui.

A empresa será cadastrada com sucesso, e no retorno do Web Service o usuário receberá na tag <ChaveCriptografia> uma chave de 32 caracteres, única por empresa. Esta é a chave que deverá ser utilizada pelo Parceiro para efetuar a criptografia da senha do seu certificado digital, usando o método AES.

O método AES trata-se de um Padrão de Criptografia Avançada. Para obter mais informações sobre esse método de criptografia acesse o link https://pt.wikipedia.org/wiki/Advanced_Encryption_Standard.

O próximo passo é criptografar a senha do seu certificado digital, fazendo uso da chave de criptografia obtida no retorno do cadastro da empresa, por meio do método AES, e efetuar a atualização do cadastro da empresa enviando as informações do certificado, juntamente com a senha criptografada.

Ao efetuar a atualização do cadastro da empresa, não é necessário informar todos os dados novamente, basta enviar o CNPJ da empresa juntamente com os dados do certificado, e a nova tag <MetodoCriptografiaSenha>, que deverá ser preenchida com o método utilizado para criptografia da senha, neste caso o método AES. A imagem abaixo demonstra a estrutura que deverá ser enviada para cadastrar o certificado com a senha criptografada.

É importante destacar que esta opção está disponível apenas para o cadastro de empresas via WS, e que enviar o certificado com a senha criptografada é uma escolha do usuário Parceiro, não é uma obrigatoriedade. O cadastro da empresa continuará sendo executado normalmente caso o usuário Parceiro decida enviar o certificado sem criptografar a senha do mesmo, lembrando que mesmo sem criptografar a senha o cadastro será executado com segurança, devido a utilização de comunicação via HTTPS.

Consultar quantidade de documentos emitidos via Web Service

Última atualização em: 16 de abril, 2021

Olá! Neste artigo vamos lhe auxiliar a realizar a integração do seu ERP com o novo Web Service disponibilizado para consultar a quantidade de documentos emitidos pela sua empresa no InvoiCy. Pronto para iniciar? Então vamos lá!

A Plataforma InvoiCy disponibiliza de um novo Web Service para efetuar a consulta da quantidade de documentos emitidos pela sua empresa, dentro de um determinado período. Essa funcionalidade pode ser utilizada sem a necessidade de interação com a interface da Plataforma InvoiCy, pois todo o processo funciona via Web Service.

O seu ERP deve realizar a integração com o novo Web Service disponibilizado pelo InvoiCy. Trata-se do WS aconsultabilhetagem.aspx. Este Web Service é único e deve ser utilizado apenas para efetuar a consulta da quantidade de documentos emitidos por sua empresa no InvoiCy, independente do tipo de documento que se deseja consultar. Abaixo, detalhamos o processo de integração com esse Web Service.

Para realizar a integração siga os seguintes passos:

1. Visualize a estrutura WSDL do Web Service

Para visualizar a estrutura WSDL do Web Service basta copiar e colar o link do Web Service em seu navegador de internet, por exemplo, https://homolog.invoicy.com.br/aconsultabilhetagem.aspx?wsdl. Assim podemos visualizar toda a estrutura do WSDL, conforme demonstra a imagem abaixo:

2. Realize o consumo do Web Service

Você deverá realizar o consumo do Web Service para efetuar a integração. Ao consumir o WS você deverá informar os seguintes parâmetros:

EmpPK: Chave de Parceiro disponibilizada pela Migrate para cada cliente.

Exemplo: PYcEsFuKroDBojfiFEl+Ms==

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.

EmpCK: Código HASH gerado em formato MD5 de acordo com os dados enviados.

Exemplo: 213f3b55d679e790258fd811cc86d309

Utilizado para validar a comunicação e proporcionar segurança à comunicação. Consulte o artigo “Como gerar o código Hash MD5?” para mais informações.

Por questões de segurança, ao invés de utilizar a chave de acesso para gerar a chave de comunicação deverá ser utilizada a Chave de acesso do parceiro, que estará disponível na tela de Parceiros, apenas para usuários Administrador ou Parceiro. A imagem a seguir demonstra a localização dessa nova chave.

EmpCO: Identificador do PDV.

Texto: Uso interno do InvoiCy. Não é necessário o preenchimento.

Documento: Conteúdo do XML com os parâmetros da consulta a ser enviada para o InvoiCy.

Parâmetros: Neste campo podem ser informados alguns parâmetros, como por exemplo, quais dados deseja que retorne ao executar uma consulta de documentos. Seu preenchimento é obrigatório para efetuar uma consulta, mas especificamente para esse tipo de consulta da quantidade de documentos não é obrigatório.

Dentro da TAG <inv:Documento>, você deverá informar o conteúdo XML da consulta. O conteúdo das tags “Documento” e “Parametros” deve ser convertido para texto, como demonstra a imagem abaixo:

Clique aqui para fazer download do exemplo SOAP exibido na imagem.

3. Gere a estrutura do arquivo XML de consulta

Para efetuar a consulta da quantidade de documentos emitidos pela empresa, deve-se informar os seguintes parâmetros na estrutura do XML:

– Modelo do documento: NF-e, NFC-e, CT-e, MDF-e, CF-e SAT, NFS-e

– Tipo do ambiente: 1 – Produção; 2 – Homologação

– Tipo da consulta: 1 – Acumulado: ao informar esse tipo de consulta será necessário definir se deseja obter os documentos acumulados apenas do dia anterior ou os documentos acumulados do mês, até o dia anterior; 2 – Período: será necessário informar o período desejado para a consulta, respeitando o limite de 3 meses.

– Acumulado: Ao optar pelo tipo de consulta 1 – Acumulado, deverá escolher a forma da consulta, 1 – Do dia anterior: a consulta irá retornar apenas os documentos acumulados do dia anterior; 2 – Do mês: a consulta irá retornar os documentos acumulados do mês, até o dia anterior.

É importante destacar que ao realizar uma consulta acumulada do mês (até o dia anterior) no dia 01/11, por exemplo, irá retornar os documentos do mês anterior, ou seja, do mês de outubro.

Se a consulta for acumulada do dia anterior, no dia 01/12, por exemplo, irá retornar apenas os documentos do dia 30/11.

Já ao executar uma consulta acumulada do dia anterior, ou acumulada do mês (até o dia anterior) no dia 02/12, irá retornar apenas os documentos do dia 01/12.

Data de Inclusão Inicial: quando o tipo de consulta for por Período deverá informar a data inicial da consulta.

Data de Inclusão Final: quando o tipo de consulta for por Período deverá informar a data final da consulta, que deverá ser menor que a data atual e o período não poderá ultrapassar o limite de 3 meses.

CNPJ do Emissor: ao efetuar a consulta o usuário poderá obter o retorno dos documentos de uma empresa específica, então deverá informar o CNPJ dessa empresa. É possível também efetuar a consulta para mais de uma empresa ao mesmo tempo, basta informar os CNPJ correspondentes a cada empresa. Caso nenhum CNPJ seja informado a consulta será realizada para todas as empresas do Parceiro, que possuem licença ativa para o módulo consultado.

A imagem a seguir demonstra a estrutura do layout XML de envio para consulta.

Clique aqui para visualizar um exemplo do XML com os parâmetros para consulta.

Para facilitar seu entendimento disponibilizamos um exemplo do layout de envio em Excel, clique aqui para fazer o download.

4. Realize a leitura do retorno do envio

Após o envio da consulta de quantidade dos documentos, precisamos realizar a leitura do retorno do processamento dessa requisição. O retorno recebido segue a seguinte estrutura SOAP.

Para fazer download do arquivo SOAP exibido na imagem clique aqui. A estrutura SOAP acima demonstra o retorno da consulta de documentos de apenas uma única empresa.

Abaixo demonstramos a estrutura do XML de retorno da consulta.

OBSERVAÇÃO: O InvoiCy conta com um controle das requisições recebidas, onde ao receber várias vezes a mesma requisição de consulta, dentro de um determinado período de tempo, irá bloquear essa requisição para prevenir que o ERP do cliente não entre em loop e cause lentidão no sistema.

Diferença entre o WS arecepcao.aspx e o WS aexportardocumentos.aspx

Última atualização em: 25 de março, 2021

Para facilitar seu entendimento sobre quando usar o WS arecepcao.aspx ou o WS aexportardocumentos.aspx para efetuar a consulta de seus documentos elaboramos uma tabela comparativa, que lista as principais características e diferenças entre estes dois Web Services, como a forma de retorno, os filtros permitidos na consulta, os retornos obtidos e a quantidade de documentos retornados.

As possíveis combinações de filtros para as consultas em cada Web Service são as seguintes:

– Faixa de numeração: Deve informar o número inicial e final, juntamente com a série do documento.

– Chave de acesso: Informar apenas a chave de acesso do documento, obrigatório caso ocorra a consulta de um documento que não esteja na base de dados do InvoiCy. Neste caso o sistema irá consultar seu status junto a SEFAZ.

– Intervalo de datas de emissão: A data inicial e a data final de emissão deverão ser preenchidas, juntamente com o horário, caso desejar. Ao optar por essa forma de consulta, as tags de numeração e série deverão ser preenchidas com zero, ou removidas da estrutura do layout enviado, e as tags de datas de inclusão também deverão ser removidas.

2016-06-01T00:00:01
2016-06-30T23:59:00

– Intervalo de datas de inclusão: A data inicial e a data final de inclusão deverão ser preenchidas, juntamente com o horário, caso desejar. Ao optar por essa forma de consulta, as tags de numeração e série deverão ser preenchidas com zero, ou removidas da estrutura do layout enviado, e as tags de datas de emissão também deverão ser removidas.

– Por série: Informar apenas a série utilizada pela empresa, onde será retornada a numeração do último documento emitido para a respectiva série.

Vale ressaltar que deve-se optar por apenas uma destas opções de consulta por requisição ao Web Service, caso seja informada mais de uma o sistema irá buscar os documentos pela primeira forma de consulta encontrada, seguindo a ordem descrita acima.

– Status do documento: Juntamente com as formas de consulta listadas acima, é possível ainda filtrar pelo status específico do documento, informando na tag os possíveis status listados a seguir:

1 – Pendente; 2 – Autorizado; 3 – Rejeitado; 4 – Necessita interação; 5 – Cancelado; 6 – Inutilizado; 7 – Aguardando Consulta; 8 – Encerrado; 9 – Em Conflito; 10 – EPEC; 11 – Contingência off-line; 12 – Denegado; 13 – Contingência FS-DA.

Na tabela a seguir são destacados quais os filtros aceitos para cada WS em específico.

Particularidades	WS arecepcao.aspx	WS aexportardocumentos.aspx
Layout XML	Download	Download
Forma de retorno	Síncrono, retornando os arquivos XML em formato Base64.	Assíncrono, retornando os arquivos XML compactados em formato .zip, convertido para Base64.
Limite de documentos retornados	100 documentos, mas este valor pode ser alterado para menos, sempre em escala de 50 em 50. Salientando que não será retornado nenhum documento quando o limite for excedido.	Os lotes serão compostos por no máximo 50 arquivos, e ao consultar uma quantidade maior os documentos serão retornados mesmo assim. Por exemplo, se a exportação for de 100 arquivos serão gerados 2 protocolos contendo 50 arquivos cada.
Consulta pelo status específico de um documento	Sim	Sim
Consulta por faixa de numeração e série	Sim. É possível consultar informando apenas a série utilizada pela empresa.	Sim
Consulta informando a chave de acesso de um documento	Sim	Não, pois o objetivo desse WS é retornar lotes de arquivo, por isso não se aplica a consulta por uma chave de acesso específica.
Consulta por intervalo de datas de emissão	Sim. Não possui um limite de dias.	Sim. Destacando que o período de datas informado não pode ultrapassar 31 dias.
Consulta por intervalo de datas de inclusão	Sim. Não possui um limite de dias.	Sim. Destacando que o período de datas informado não pode ultrapassar 31 dias.
Consulta de um resumo do documento	Sim	Sim
Retorno do XML completo na consulta	Sim	Sim
Retorno do link do XML na consulta	Sim	Apenas será retornado o link para download do arquivo XML quando consultado o resumo do documento, e o conteúdo não será compactado e nem convertido para base64.
Retorno do PDF em Base64 na consulta	Sim	Não
Retorno do link do PDF na consulta	Sim	Apenas será retornado o link para download do arquivo PDF quando consultado o resumo do documento, e o conteúdo não será compactado e nem convertido para base64.
Retorno dos Eventos na consulta	Sim	Sim
Sugestão de uso	Indicado para efetuar a consulta de poucos documentos, devido a limitação de retorno de apenas 50 documentos.	Indicado para efetuar a exportação de um grande volume de documentos, devido a possibilidade de exportar vários lotes.

Consultar pulos de numeração

Última atualização em: 15 de abril, 2021

Buscando facilitar para os usuários efetuarem o controle dos documentos emitidos por suas empresas, disponibilizou-se no InvoiCy um novo layout de integração para consulta dos pulos de numeração, onde será possível identificar falhas no sequencial da numeração de documentos emitidos para todos os módulos.

Os principais motivos que podem ocasionar falhas no sequencial de envio dos documentos são:

– Documentos emitidos que ainda não estão com status: Autorizado, Cancelado, Inutilizado ou Denegado;

– Pulo de numeração no aplicativo emissor;

– Falha do aplicativo emissor no envio do documento;

– Documentos emitidos que permanecem com status: Pendente, Rejeitado, Contingência Offline, Em conflito, EPEC ou Necessita interação.

O seu primeiro passo é enviar via Web Service o novo layout de integração para efetuar a consulta dos pulos de numeração. A imagem abaixo demonstra a estrutura do layout, onde deve-se informar o CNPJ do emitente, CNPJ da empresa, modelo do documento, tipo de ambiente, série e data de emissão inicial e final, não podendo ultrapassar o período de 31 dias. Clique aqui para efetuar download de um exemplo desse layout.

Após efetuar o envio do layout para consulta dos pulos de numeração, deverá retornar o código 100 – Pulos de numeração processados, se o processo foi executado com sucesso. O retorno da consulta segue a seguinte estrutura SOAP.

Para fazer download do XML exibido na imagem clique aqui.

No retorno da consulta irá conter o CNPJ do emissor, modelo e série do documento consultado, Quantidade de pulos de numeração, juntamente com a especificação da sequência dos números que estão faltando, e ainda o código e descrição do retorno.

Caso não encontre pulos de numeração para o período informado, irá retornar a mensagem: 100 – Nenhum pulo de numeração encontrado.

Para facilitar seu entendimento, disponibilizamos também um documento que especifica o layout dos XMLs que devem ser gerados, clique aqui para fazer o download.

Cancelando uma NF-e ou NFC-e

Última atualização em: 23 de março, 2021

Agora iremos descrever como é realizado o cancelamento de uma NF-e ou NFC-e através do InvoiCy.

A partir deste momento, assumimos que você já leu o artigo “Enviando uma NF-e ou NFC-e”. Caso ainda não tenha lido este artigo, recomendamos a sua leitura para facilitar o entendimento deste artigo.

Proceda com os seguintes passos para realizar o cancelamento de um documento:

1.      Autorize um documento
O cancelamento só pode ser feito para documentos que receberam a autorização de uso pela SEFAZ. Atente-se para o prazo de cancelamento da NF-e que pode variar para cada UF. Em caso de dúvidas, consulte a SEFAZ de seu estado para maiores informações.

2.      Gere a estrutura do arquivo XML de cancelamento
Você deverá gerar a estrutura do XML de cancelamento de uma NF-e, de acordo com o Layout de eventos da NF-e. Para visualizá-lo, consulte o artigo “Envio de Eventos”.

Nós disponibilizamos para você um exemplo da estrutura do arquivo de cancelamento para facilitar seu entendimento. Clique aqui, para realizar o download.

3.      Consuma o Web Service de envio de documentos do InvoiCy
Após gerar o layout de cancelamento da NF-e que você deseja cancelar, basta realizar o consumo do WS de integração do InvoiCy, conforme já descrito no artigo “Integrando com o InvoiCy”.

Para facilitar o seu entendimento, anexamos a este artigo um exemplo completo de cancelamento de uma NF-e através do WS de integração do InvoiCy. Clique aqui, e realize o download do documento.

4.      Obtenha o retorno do cancelamento
Ao realizar o consumo do Web Service do InvoiCy, no retorno será possível identificar se a operação foi realizada com sucesso e qual o status do documento.

O layout de retorno do Web Service para o cancelamento, assim como qualquer outro evento, é o mesmo retornado no momento da emissão da NF-e ou da NFC-e. Para os eventos, estarão preenchidas as tags específicas no retorno, como o EveTp e EveId, como mostra a imagem abaixo.

Se a empresa está emitindo em contingência e necessita realizar o cancelamento de uma NF-e ou NFC-e , o InvoiCy irá armazenar o evento do cancelamento e enviá-lo após a empresa sair da contingência e o documento ser efetivado.

O próximo passo é: Consultando uma NF-e ou NFC-e, para isso acesse o artigo e confira.

Artigos Relacionados:

• Integrando com o módulo NF-e
• Envio de eventos

Enviando uma NF-e ou NFC-e

Última atualização em: 23 de março, 2021

Neste momento iremos explicar como realizar a emissão de uma NF-e ou NFC-e integrando com o InvoiCy.

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

O envio de um documento é muito simples. Para que isso se torne possível siga os seguintes passos:

1.      Consumindo o Web Service
Primeiramente, você deve realizar o consumo do Web Service de envio de documentos do InvoiCy, conforme o artigo “Integrando com o módulo NF-e”.

2.      Gerando o documento na estrutura correta
O InvoiCy permite o envio de documentos no layout 4.00 da NF-e e também da NFC-e. Para obter esse Layout consulte o artigo “Layout 4.00”. Nele você encontra a estrutura completa do arquivo XML 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 um exemplo de arquivo XML no layout da NF-e.

Clique aqui, para realizar o download do exemplo de Envio de NF-e.

Para facilitar a geração do XML de integração, disponibilizamos um arquivo de esquema XSD que poderá servir como base. É recomendável que após a geração do arquivo XML e antes do consumo do Web Service, o mesmo seja validado contra o arquivo de esquema. OBS: O arquivo de esquema corresponde a versão 4.00.

Clique aqui, para realizar o download do arquivo de esquema XSD.

3.      Realize a leitura do retorno do envio
Após o envio da NF-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á inserido em uma tag “CDATA” e retornará dentro da TAG <Documento> do SOAP de retorno.

Para facilitar seu entendimento, anexamos um exemplo do XML do retorno. Clique aqui, e realize o download.

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

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

Seu próximo passo é:  Cancelando uma NF-e ou NFC-e

Artigos Relacionados:

• Integrando com o módulo NF-e
• Layout 4.00