2024
Cadastro de WebHook via tela
12 de agosto de 2024Índice
-A tecnologia do WebHook vem ganhando espaço significativo no meio tecnológico, por ser uma importante e eficaz forma de recebimento de informações 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 na plataforma do InvoiCy que a partir de agora conta com uma tela exclusiva para realizar o cadastro de WebHooks para diferentes módulos e notificações.
Cadastro do WebHook para empresa via Tela
Para realizar o cadastro de WebHook para uma empresa específica, basta acessar o InvoiCy, selecionar a empresa em questão e na aba “Painel de controle” selecionar a opção “WebHooks” de empresa.
Na tela que abrir serão listados os WebHooks cadastrados para a empresa, os mesmos também poderão ser localizados utilizando os filtros de:
Descrição – No qual, basta informar a descrição que foi informada para o WebHook no momento do cadastro ou uma palavra que conste nela;
Status – Ativo ou Inativo;
Módulo – NFS-e, NF-e, NFC-e, Certificado Digital ou GNRe;
Tipo Notificação – No combo de seleção são disponibilizados todos os tipos de notificações, basta escolher um dos que foi cadastrado no WebHook que pretende filtrar e selecionar, como por exemplo: “Emissão de documento”. Esse campo permite selecionar apenas uma notificação por vez.
Após adicionar os filtros desejados, basta selecionar a opção “Pesquisar” para que eles sejam listados na tela.
Já no campo inferior direito da mesma tela acima, temos a opção de cadastro de um novo WebHook, ao selecionar o botão “Novo”, será direcionado a uma tela de cadastro.
Código – Este campo é de preenchimento automático do InvoiCy, ou seja, estará disponível visualmente apenas para usuários “Administradores”.
Descrição – Neste campo de texto vai a descrição/título que desejarem informar ao WebHook que está sendo cadastrado.
Status – Define se a API do parceiro está preparada para receber mensagens ou não, os valores aceitos são: A – Ativo, I – Inativo.
Tipo 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 base64 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 – 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.
URL – No campo URL é informada a URL com a qual o InvoiCy irá realizar a requisição POST para enviar a notificação da troca de status do documento. Lembrando que a URL deve ser válida e segura (https).
Uso – Esse campo é composto por dois elementos fundamentais, é nessa etapa que será escolhido o módulo e o tipo de notificação que será vinculado ao WebHook em questão.
Primeiramente deve ser escolhido o módulo, entre eles temos os seguintes valores: NFS-e, NF-e, NFC-e, Certificado Digital ou GNRE, ao selecionar o módulo, um novo combo irá aparece para selecionar o tipo de notificação, lembrando que cada módulo tem as suas características então as opções que aparecerem nesse campo vão variar de acordo com o módulo selecionado.
Após inserir o módulo e o tipo de notificação, basta selecionar o botão de “Aplicar” que o registro ficará salvo na tela. Esse processo pode ser realizado várias vezes nessa mesma tela e para módulos diferentes, só não será possível repetir o mesmo uso (Módulo e Tipo de notificação). conforme exemplo:
Caso queiram remover algum registro, esse pode ser feito através do ícone de exclusão que aparece na linha antes da informação do módulo cadastrado, conforme imagem acima.
Após realizar as configurações, basta Salvar e as informações ficarão salvas na tela de WebHook da empresa. Esse também pode ser editado ou excluído por completo.
Cadastro do WebHook de parceiro via Tela
A você parceiro que deseja cadastrar o mesmo WebHook para mais de uma empresa da sua base, temos uma opção exclusiva para realizar o cadastro visando facilitar o processo. Basta acessar o InvoiCy com o usuário do tipo “Parceiro” e na aba “Painel de controle” selecionar a opção “WebHooks” nas configurações do parceiro.
Na tela que abrir, assim como no cadastro do WebHook feito direto para empresas, como vimos anteriormente, serão listados os WebHooks já cadastrados e vinculados ao parceiro, bem como os filtros de “Descrição”, “Status”, “Módulo”, “Tipo Notificação” e “Chave de Parceiro” que é exclusivo dessa tela para o parceiro, aqui poderá filtrar também pela chave.
Após preencher os filtros desejados, basta selecionar a opção “Pesquisar” para que eles sejam listados na tela.
No campo inferior direito da mesma tela acima, temos a opção de cadastro de um novo WebHook, ao selecionar o botão “Novo”, será direcionado a uma tela de cadastro.
Nesta tela existem duas opções diferentes das já vistas, são elas:
Chave de parceiro – Aqui ao cadastrar um novo WebHook deverá informar a chave de parceiro desejada.
Replicar para empresas – Essa opção irá aparecer apenas depois que preencher todos os campos anteriores e clicar em “Salvar”, feito isso a opção de “Replicar para empresas” será exibido no canto inferior esquerdo da tela, essa opção irá permitir que replique as configurações do WebHook que acabou de configurar para mais empresas vinculadas a chave de parceiro inserida no campo “Chave de parceiro”.
Para replicar as configurações a outras empresas da base do parceiro basta selecioná-las na tela que abrir ao clicar sobre o botão de “Replicar para empresas”. Pode localizá-las utilizando alguns filtros disponíveis na tela, como, por exemplo, filtrar pelo CPF, CNPJ ou CNPJ Raiz, pelo nome ou apelido da empresa, pela UF e município ou até mesmo pelo Grupo de empresas.
Após a aplicação dos filtros, selecione o botão de “Pesquisar” e as empresas correspondentes serão listadas na tela. Para aplicar as configurações, as mesmas, basta marcar o combo que aparece antes do CNPJ filtrado e clicar no botão “Aplicar Seleção”.
Ao concluir esses passos, será direcionado à tela anterior, para finalizar com sucesso o processo, deve clicar ainda sobre o botão de “Salvar”.
Para as empresas selecionadas no processo de replicação, as configurações do WebHook também irão aparecer na tela de lista de WebHooks cadastrados para empresas, porém, as informações do mesmo não serão editáveis, será apenas disponível a visualização, ao contrário das configurações do WebHook que for criado exclusivamente pelas configurações da empresa que podem ser modificadas quando necessário.
Atenção!
Para ter mais detalhes sobre o comportamento e configurações do WebHook para cada módulo especificamente, acesse os seguintes manuais: