WebHook NFS-e

Essa novidade já está disponível nas configurações de emissão da NFS-e.

WebHook é uma forma de recebimento de informações, que são passadas assim que uma determinada ação acontece, criando um tipo de conexão entre dois sistemas.

Com isso, implementamos a utilização deste método para o módulo NFS-e.

Parametrização do WebHook via Tela

Na tela de “Configurações para a emissão de NFS-e”, foram incluídos novos campos para salvar as informações referentes ao WebHook.

Status: O campo Status define se a API do parceiro está preparada para receber mensagens ou não, os valores aceitos são: A – Ativo, I – Inativo.

URL: O campo URL é a URL com a qual o InvoiCy irá realizar a requisição POST para enviar a notificação da troca de status do documento. Nesse campo deve informar uma URL válida e segura (https).

Tipo de Autenticação: O campo Tipo de Autenticação é a forma como o InvoiCy irá se autenticar para realizar a conexão com a URL informada. Nesse campo deve-se informar os seguintes valores:

0 – Sem autenticação: Parametrizado dessa forma, ao realizar a requisição para a URL informada nenhum tipo de Authorization Request Header será enviado na conexão;

1 – Basic Auth: Ao usar esse tipo de autenticação, quando o InvoiCy se comunicar com o sistema do parceiro, será adicionado ao cabeçalho da requisição o seguinte entity header: Authorization: Basic {Valor informado no campo TokenAutenticacao}.

O Basic Authentication é o sistema de autenticação mais comum do protocolo HTTP. Ele é incluído no header da requisição HTTP dessa maneira: Authorization: Basic {credenciais em base 64 no formato usuário:senha}.

Para autorizar como nome de usuário/senha o cliente enviaria:

Authorization: Basic AXXxxxxxxXXX0xxXxXX==

2 – Bearer Token: Optando por esse tipo de autenticação, no cabeçalho da requisição ao sistema do parceiro será adicionado o seguinte entity header: Authorization: Bearer {Valor informado no campo TokenAutenticacao}.

Bearer: Bearer authentication (também conhecido como token authentication) é um Schema para autenticação HTTP que envolve tokens de segurança.

O Bearer Token é uma string enigmática, geralmente gerada pelo servidor em resposta a uma solicitação de login.

O cliente deve enviar este token no cabeçalho Authorization ao solicitar recursos protegidos:

Authorization: Bearer <token>

Token de Autenticação: Neste campo é parametrizado o Token pelo qual o InvoiCy irá se autorizar/autenticar na API do parceiro em cada requisição.

O Token de autenticação será definido para cada empresa, podendo ser configurado o mesmo token para todas as empresas. Será o parceiro quem irá definir a informação que deseja colocar neste campo, e posteriormente validar na API que o InvoiCy enviou o token informado.

Parametrização do WebHook via Web Service

A parametrização do WebHook poderá ser realizada também via Web Service. No XML de cadastro de empresa existe o Grupo de Campos <Parametros>, onde os parâmetros são divididos por módulos.

Dentro do Grupo de Campos <NFSE> foi criado um Grupo chamado <WebHook>, onde constam os campos de parametrização do processo de notificação via WebHook. Pode-se verificar o exemplo na imagem abaixo.

Na parametrização do WebHook via Web Service junto ao cadastro da empresa, será retornado o código 119 – Falha na parametrização do WebHook caso o campo TipoAutenticacao seja preenchido com um valor diferente de 0, 1 ou 2, solicitando um valor válido.

Com o WebHook parametrizado, sempre que um documento emitido autorizar via processo assíncrono, via tela de detalhes ou pela opção de reenviar/reconsultar na tela de documentos, ou quando uma nota recebida for importada, a notificação será enviada para URL informada.

Notificação via WebHook para alteração de status de NFS-e emitida

No fluxo síncrono, o RPS é recebido do ERP no InvoiCy e já transmitido imediatamente para a Prefeitura, devolvendo o retorno ao ERP na mesma conexão. O retorno pode ser autorizado, rejeitado ou até mesmo pendente e em processamento, pois nem todas as prefeituras processam o RPS de forma síncrona também. Caso o RPS não retorne um status definitivo, como autorizado ou rejeitado por exemplo, o ERP precisa efetuar consultas para obter o status do processamento do documento.

Já no fluxo assíncrono, o InvoiCy recebe o RPS do ERP e apenas devolve o código 105 – pendente. Neste caso, o InvoiCy armazena o RPS em uma fila para transmitir posteriormente à prefeitura, restando ao ERP realizar consultas para obter o status deste processamento.

Desta forma, qualquer alteração de status do documento diferente de 105, será enviado uma notificação via WebHook para o ERP atualizar o documento.

A notificação via WebHook será enviada também quando houver alteração de um Status final para outros Status Final, como por exemplo Rejeitado para Autorizado, Autorizado para Cancelado ou Rejeitado para Inutilizado. Além disso, será enviada notificação quando ocorrer emissão de vento.

No conteúdo da notificação enviada pelo InvoiCy, há o campo “TipoNotificacaoWebHook”, que poderá ser utilizado para identificar o tipo de ação que ocorreu no documento. Os tipos possíveis são:

1 – Documento Emitido
2 – Atualização de status
3 – Evento
4 – Documento Recebido
5 – Documento Atualizado(Atualização de informações que podem incluir também a atualização de status)
6 – Documento Inutilizado

No corpo da requisição será enviado o documento em formato JSON, contendo PDF, Status, Tipo e Número.

Clique aqui para visualizar um exemplo da estrutura que será enviada para o WebHook. A estrutura segue o mesmo padrão do retorno da consulta de NFS-e.

Em caso de dificuldades para receber as mensagens, o cliente poderá acessar a ferramenta https://webhook.site/ e consequentemente criar uma URL válida que será apontada neste parâmetro.

Notificação via WebHook para NFS-e recebida

Quando uma nota for importada no InvoiCy via tela, via Web Service – leia o artigo Importação de documentos via Web Service, via leitura de caixa de e-mail, via InvoiCy Conector ou através da consulta automática, será enviada a notificação no formato padrão para o WebHook configurado nas Configurações de Emissão de NFS-e.

Na notificação de NFS-e recebida, será enviado também o XML do documento no campo “DocCompleto”, o formato do XML enviado neste campo será conforme a opção parametrizada no parâmetro “XML InvoiCy no retorno da requisição” na tela de Configurações para emissão de NFS-e.

Caso o parâmetro “XML InvoiCy no retorno da requisição” estiver parametrizado como “Nao”, o campo “DocCompleto” será alimentado com o Layout InvoiCy.

Clique aqui para visualizar um exemplo da estrutura que será enviada para o WebHook, constando o retorno do XML no campo DocCompleto.

Lembrando que para realizar a importação de documentos no InvoiCy, é necessário ativar a Extensão Importação de Documentos.