mar
04
2022

WebHooks

4 de março de 2022

Índice

-

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.

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.

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 o documento autorizar via processo assíncrono, via tela de detalhes ou pela opção de reenviar/reconsultar na tela de documentos, a notificação será enviada para a URL informada.

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.