Arquivo mensal: junho 2021

jun 8 2021

accessToken e refreshToken

Última atualização em: 08 de junho, 2021

Antes de iniciar a leitura deste artigo, realize a leitura do artigo Autenticação API Rest.

Entendido o processo de geração do token JWT (JSON Web Token) para a obtenção do accessToken e refreshToken, entenderemos a utilização dos mesmos através de exemplificação na ferramenta Postman, utilizada pela Migrate. Caso não deseje utilizar o Postman, é possível a utilização de outra ferramenta a seu critério.

A utilização do accessToken e do refreshToken pode ser realizada de duas formas pelo sistema parceiro, sendo elas:

Autenticação utilizando apenas o accessToken

Obtidos os accessToken e refreshToken, o accessToken terá validade de 1 hora e o refreshToken terá validade de 24 horas. É necessário o tempo de expiração dos tokens para que apenas usuários em posse da chave de parceiro e chave de acesso da empresa emissora, possam realizar a autenticação com a aplicação, fazendo uso dos serviços e tendo acesso às informações das operações dos emissores. 

Desta forma, o accessToken poderá ser utilizado para autenticação com o Invoicy dentro do período de 1 hora. O mesmo deverá ser enviado na aba “Headers” em “Authorization” em todas as requisições:

Se o accessToken for utilizado com sua validade expirada, o Invoicy retornará a seguinte estrutura:

Com isso, o sistema parceiro deverá possuir um tratamento em que sempre que receber o retorno de status 400 com title “\”Invalid token\”” será necessário gerar um novo JWT a ser enviado na opção Gerar Token do projeto, para receber um novo accessToken a ser utilizado.

Autenticação utilizando o accessToken e refreshToken

Neste caso, ao receber o retorno de status 400 com title “\”Invalid token\”” o sistema parceiro deverá enviar o refreshToken ao Invoicy através da opção Refresh Token do projeto exemplo:

Ao realizar este envio, serão retornados novos accessToken e refreshToken a serem utilizados para a autenticação. Vale ressaltar que a diferença ao utilizar o accessToken e também utilizar o refreshToken é que no momento em que o accessToken expira utiliza-se o refreshToken e não é necessário gerar um novo token JWT.

Importante! Após expiradas as 24 horas de validade do primeiro refreshToken retornado, obrigatoriamente o sistema parceiro deverá gerar um novo token JWT para receber accessToken e refreshToken novos. Ou seja, se optar por utilizar o refreshToken, no mínimo 1 vez ao dia o sistema integrado ao Invoicy terá de gerar um JWT para receber o accessToken e refreshToken e nas próximas 24 horas poderá trabalhar apenas com o refreshToken para receber chaves accessToken válidas.

Situação hipotética 1: por exemplo, a empresa gerou seu primeiro accessToken e refreshToken para autenticação com o Invoicy para envio de documentos e ela emitiu 3 documentos dentro de 1 hora com este accessToken. Após, a empresa realizou o envio do quarto documento, excedendo a 1 hora de validade mas ainda dentro das 24 horas de validade do refreshToken, e o Invoicy retornou status 400 com title “\”Invalid token\””. Neste momento, o sistema parceiro deve enviar o resfreshToken para obter o novo accessToken e refreshToken a serem utilizados na autenticação.

Situação hipotética 2: a empresa gerou seu primeiro accessToken e refreshToken para autenticação com o Invoicy para envio de documentos e ela emitiu 3 documentos dentro de 1 hora com este accessToken. Após, a empresa realizou o envio do quarto documento, excedendo a 1 hora de validade do accessToken, assim, o sistema envia o refreshToken e recebe um novo accessToken e refreshToken. O quinto documento foi emitido após as 24 horas de validade do refreshToken gerado para o primeiro documento emitido, assim, o sistema parceiro gera um novo JWT para enviar na opção Gerar Token do projeto.

Se enviado um refreshToken expirado,  o Invoicy retornará a seguinte estrutura:

Importante observar que title passa a ser message e a descrição do retorno muda para “Invalid refresh token”.

Recebendo este retorno o software da empresa parceira deve gerar um novo JWT para receber novos accessToken e refreshToken a serem utilizados na autenticação.

jun 8 2021

Autenticação API Rest

Última atualização em: 08 de junho, 2021

Antes de iniciar o desenvolvimento da autenticação com o Invoicy na integração através da API Rest, a melhor alternativa para entendimento do processo de autenticação é a geração do token no padrão JWT (JSON Web Token) (RFC – 7519) de forma manual.Para isso, acesse o portal JWT(https://jwt.io/) e configure o painel Decoded ajustando os grupos Payload e Verify Signature.

Entendendo o grupo Payload:

  • “iat”: campo numérico que deve conter a data/hora atual no fuso zero e em formato timestamp;
  • “exp”: campo numérico que deve conter a data/hora atual + 120 segundos no fuso zero e em formato timestamp;
  • “sub”: é uma string com o CNPJ da empresa emissora ou a chave de parceiro. Quando for gerado um token para cadastro/atualização de empresa deverá conter a chave de parceiro, no restante das situações será utilizado o CNPJ da empresa;
  • “partnerKey”: é uma string com a chave de parceiro fornecida pelo InvoiCy. Quando for gerado um token para cadastro de empresa, não envie essa informação.

A geração da data/hora em timestamp pode ser realizada no portal Epoch Converter (https://www.epochconverter.com/) conforme imagem:

Entendendo o grupo Verify Signature:

No campo em que é permitida a edição, informar a chave de acesso da empresa. A chave de acesso é a chave privada fornecida pelo InvoiCy para cada empresa cadastrada. Quando for gerado um token para cadastro de empresa deverá conter a chave de acesso do parceiro. Ambas informações, chave de parceiro e chave de acesso da empresa, podem ser localizadas acessando no Invoicy a tela Painel de controle > Dados da empresa.

Obs: para consulta de empresa utilizar a chave de acesso da empresa e não a chave de parceiro.

Com o preenchimento destas informações será gerado no painel Encoded o JWT a ser enviado ao Invoicy na opção Gerar Token na ferramenta Postman, utilizando-se do projeto exemplo (https://documenter.getpostman.com/view/9193875/SztEanQL?version=latest#6bf035dc-7680-439e-baab-884293b1421e).

Importante! Após a geração do JWT o sistema parceiro terá 120 segundos para envio do código ao Invoicy no campo “token”, tempo de expiração informado no parâmetro “exp”.

Com o envio do JWT serão retornados o accessToken e o refreshToken que serão utilizados para autenticação com o Invoicy no processo de envio dos documentos.

Para mais detalhes da utilização do accessToken e refreshToken confira o artigo accessToken e refreshToken.

jun 8 2021

Integração da MIA com o processo de correção de NFC-e offline

A partir da nova versão, o sistema irá contar com a integração da MIA no processo de correção de NFC-e offline, pela extensão Dashboard ativa. Será apresentada a seguinte mensagem “Clique aqui para corrigir os itens”, caso o mesmo seja identificado ou não pela SEFAZ.

Quando a SEFAZ não identificar o item da NCM, será feito o direcionamento para a nova tela de correção de NCM ao clicar no link, disponibilizando o ícone da MIA para selecionar a NCM a corrigir, como demonstra a imagem abaixo.

Quando a SEFAZ identificar o item da NCM, será feito o direcionamento para a tela de correção do item da NFC-e. Ao lado do campo NCM, caso a MIA tenha sugestões de correção ficará disponível o ícone da mesma, como demonstra na imagem abaixo.

Ao clicar no ícone da MIA, será apresentada a tela das sugestões de NCM para o usuário avaliar qual será aplicada ao item.

Ao passar o mouse sobre o ícone de informações, será apresentada as descrições da NCM em níveis, conforme imagem abaixo.

Ao selecionar a NCM desejada e clicar para seguir, será direcionado para a tela de correção, com a NCM selecionada ajustada no campo do mesmo. Em seguida, será preciso salvar a alteração e realizar o reenvio da nota e consequentemente o sistema irá identificar se existe ou não outras correções do mesmo tipo a serem corrigidas.

jun 2 2021

Release Notes – Versão 2.39.0

Versão 2.39.0 – 02/06/2021 – em homologação

Olá pessoal!

Já está disponível em homologação a versão 2.39.0 do InvoiCy.

Confira as novidades:

– Novo componente para personalização do DANFE:

Olha só que super novidade! Buscando entregar uma melhor experiência para os usuários no momento de personalizar as configurações para impressão do DANFE, liberamos um novo componente Personalizado BETA. 

Como pode ser visto na imagem abaixo, na lateral esquerda da tela existem algumas configurações de tamanhos de fontes, como: ‘Tamanho da Fonte dos produtos/serviços’, ‘Tamanho da fonte da informação adicional do produto’ e ‘Tamanho da fonte das informações complementares’.

Também é possível definir o ‘Modelo da folha’, que no momento disponibilizamos apenas A4, e escolher a ‘Posição da área destacável’.

Pode-se ainda optar pelo ‘Destaque dos produtos perigosos’ e ‘Imprimir duplicatas’ e ‘Imprimir ICMS Desonerado’.

Nessa tela também já é possível observar a logomarca que sairá impressa no DANFE, de acordo com o cadastro da empresa.

As demais configurações são opções que também estão disponíveis no modo personalizado normal de configurações do DANFE, com exceção de algumas opções que serão liberadas apenas para esse componente.

Ao ativar a opção ‘Personalizar tabela de produtos’, será possível posicionar as colunas correspondentes de acordo com as suas necessidades.

Ainda é possível preencher o campo ‘XML Documento’, com o conteúdo do XML da NF-e e efetuar a pré-visualização do DANFE antes de emitir esse documento. No combobox ‘Modelo do documento para pré-visualização’, é possível selecionar dentre os modelos disponíveis para simular diferentes situações de impressão do DANFE.

Ao clicar em ‘Restaurar DANFE’, tudo que foi personalizado pelo usuário será retornado às configurações padrão novamente.

– Novos parâmetros nas configurações de impressão do DANFE:

A partir dessa versão, as configurações de impressão do DANFE contam com três parâmetros novos, são eles: ‘Imprimir informações do bloco emitente centralizadas’, ‘Imprimir textos em negrito’ e ‘Imprimir FCP’.

Por padrão a logomarca e informações do emitente são impressas do lado esquerdo do DANFE, como demonstramos na imagem abaixo.

Ao ativar o novo parâmetro ‘Imprimir informações do bloco emitente centralizadas’ a logomarca e demais informações do emitente serão impressas de forma centralizada no DANFE, como demonstra na imagem a seguir.

Ativando o parâmetro ‘Imprimir textos em negrito’, todas as informações do DANFE serão impressas em negrito, com exceção dos valores referentes aos itens.

Por fim, ao ativar o parâmetro ‘Imprimir FCP’, o valor do FCP será impresso no bloco de impostos do DANFE, como destacado na imagem abaixo.

– Digitação de NF-e com pessoa física:

O InvoiCy já está ajustado de acordo com a NT 2018/001, que permite a emissão de NF-e por pessoas físicas que possuem inscrição estadual, e um certificado digital do tipo e-CPF. Com isso, o InvoiCy passa a atender a demanda de produtores rurais que também precisam emitir uma Nota Fiscal Avulsa (NFAe).

Porém, até agora só era possível realizar a emissão via Web Service. Mas a boa notícia é que a partir dessa versão será possível emitir NF-e também através da tela de digitação.

Mas atenção! Conforme regra da SEFAZ, os documentos emitidos por pessoas físicas devem obedecer a faixa de numeração para série, devendo estar entre 920 e 969.

Também é importante destacar que essa funcionalidade está disponível apenas para empresas que possuem a contratação da licença de digitação via parceiro.

– Download de PDF na tela de Documentos emitidos:

Na tela de documentos emitidos, você vai encontrar uma nova opção de download dos arquivos PDF: ‘Download PDF – Arquivos separados’, como demonstra a imagem abaixo.

Ao selecionar vários documentos na tela e selecionar essa nova opção, os PDFs serão exportados em arquivos separados, compactados em um arquivo .zip.

Porém, caso optar por: ‘Download PDF – Arquivo único’, será feita a exportação de um único arquivo PDF, contendo todos os PDF dos documentos selecionados.

– Inicializar municípios somente para importação de NFS-e:

A partir de agora o InvoiCy permitirá que prestadores de serviço possam importar documentos emitidos ou recebidos mesmo que o município não possua o serviço de emissão de NFS-e via Web Service e independente de o Prestador utilizar o InvoiCy para emissão de documentos ou utilizar outros sistemas.

No retorno da consulta de Municípios Integrados via Web Service, foram incluídos 3 novos campos que informam se o município consultado possui o serviço de Emissão integrado no InvoiCy ou não, e quais as formas de importação disponíveis. Os novos campos são:

  • possuiRecepcao – Retorna “S” (município possui serviço de emissão) ou “N” (município não possui serviço de emissão)
  • importaNotasEmitidas – Retorna a forma de importação de documentos disponível para o município, sendo as opções “Web Service”, “E-mail” ou “Não”.
  • importaNotasRecebidas – Retorna a forma de importação de documentos recebidos, sendo as opções:
    • Web Service = consulta automática liberada para qualquer empresa.
    • Web Service (1) = consulta automática liberada apenas para empresas que também são deste município, pois é obrigatório informar inscrição municipal.
    • Web Service (2) = consulta automática possível apenas se cadastrar previamente os prestadores de quem a empresa contrata os serviços.
    • E-mail = não possui consulta automática na prefeitura, porém é possível baixar as notas do site da prefeitura e importar no InvoiCy ou cadastrar uma caixa de e-mail onde recebe os XMLs das notas (e-mail deve ser enviado pelo prestador ou pela prefeitura).
    • Não = ainda não foi implementada a consulta automática nem cadastrado layout compatível para leitura de e-mail.

A imagem a seguir apresenta um exemplo de retorno de uma consulta contendo os novos campos.

Essas mesmas informações estão disponíveis no InvoiCy na tela de Municípios Integrados, no grupo de informações de NFS-e, que pode ser acessado no Painel de Controle.

Nessa tela também foi adicionada a coluna “Emissão” que informa se o município possui ou não serviço de emissão de documentos. Essa coluna representa o campo possuiRecepcao  no retorno da consulta via Web Service.

– Adequar espelho RPS para Uberlândia – MG:

Foram realizadas algumas alterações visuais no espelho RPS (documentos ainda não convertidos em NFS-e) exclusivamente para Uberlândia/MG, para adequar exigências da fiscalização municipal. Dentre as mudanças estão a alteração do cabeçalho para “Secretaria municipal de finanças” e posicionamento do número do RPS no bloco superior direito.

– Consulta automática de notas recebidas em 2 novos padrões:

A extensão de importação de documentos conta com mais alguns municípios com importação automática de notas recebidas e/ou emitidas. Os padrões incluídos são Smarapd Sil WS2 e Portal Fácil, apenas nos municípios que disponibilizam o serviço.

– Consulta de NFS-e recebidas por prestador

Na versão 2.38.0 do InvoyCy disponibilizamos a opção de consultar documentos recebidos a partir de um cadastro de Prestadores de serviços, que pode ser realizado diretamente via Painel de Controle.

Nessa nova versão do InvoiCy estamos liberando o cadastro de prestadores via Web Service, tanto para integrações via SOAP ou API REST. A partir de agora é possível cadastrar o prestadores no momento do cadastro de uma nova empresa ou por meio da atualização das informações já cadastradas.

Para cadastrar prestadores via integração SOAP, é necessário enviar alumas informações, conforme apresentamos a seguir;

Podem ser enviados vários prestadores no mesmo cadastro, bastando apenas repetir o grupo <Prestador>.

Para integração via API REST, os os campos a serem enviados no JSON são:

É possível alterar o status, o nome, o código do município e a inscrição municipal de um prestador cadastrado, para isso deve-se enviar todas as informações do prestador, alterando o campo desejado, o InvoiCy irá verificar se o prestador já está cadastrado pelo CNPJ e atualizar seus dados.

Importante lembrar que essa funcionalidade atende somente clientes que utilizam o Módulo NFS-e.