Cadastro via Tela

Os Webhooks permitem o recebimento de informações em tempo real na forma de notificações, sempre que uma ação ocorre, conectando sistemas de forma simples e eficiente. O InvoiCy conta com uma tela exclusiva para cadastro de Webhooks, onde é possível configurar diferentes módulos e notificações.

Confira a seguir as opções de cadastro disponíveis para empresas e parceiros.

Para referência visual, consulte o vídeo demonstrativo clicando aqui.

Cadastro para Empresa

Para realizar o cadastro de Webhook para uma empresa específica, acesse o InvoiCy, selecione a empresa em questão, e em "Painel de controle" selecione a opção "Webhooks" do grupo Empresas.

Em seguida, na tela "Lista de Webhooks Cadastrados" serão listados os Webhooks previamente cadastrados para a empresa. Os mesmos também poderão ser localizados utilizando os seguintes filtros:

Descrição: Insira a descrição cadastrada para o Webhook ou qualquer palavra presente nela.

Status: Pode ser definido como "Ativo" ou "Inativo".

Módulo: Selecione "NFS-e", "NF-e", "NFC-e", "Certificado Digital" ou "GNRe".

Tipo Notificação: O combo de seleção exibe todos os tipos de notificações disponíveis. Escolha aquela correspondente ao Webhook que deseja filtrar, como, por exemplo, "Emissão de documento". Além disso, esse campo permite selecionar somente uma notificação por vez.

Após preencher os filtros desejados, selecione a opção "Pesquisar" para que eles sejam listados na tela. No canto direito desta tela, clique em "Novo" para abrir a tela de Webhook e preencha os campos abaixo para realizar o cadastro:

Para cadastrar um novo Webhook, preencha corretamente os seguintes campos: Código: Este campo é preenchido automaticamente pelo InvoiCy, ou seja, estará disponível visualmente apenas para usuários "Administradores".

Descrição: Neste campo de texto insira a descrição/título que deseja informar ao Webhook que está sendo cadastrado.

Status: Define se a API do parceiro está preparada para receber mensagens ou não. Pode ser definido como "Ativo (A)" ou "Inativo (I)".

Tipo Autenticação: Este campo define o modo como o InvoiCy irá se autenticar para realizar a conexão com a URL informada. Nesse campo podem ser informados os seguintes valores:

0 - Sem autenticação: ao realizar a requisição para a URL informada nenhum tipo de Authorization Request Header será enviado na conexão.
1 - Basic Auth: 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}. Sendo 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: Neste campo é 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).

Headers: Nesse campo pode ser inserida uma informação adicional na notificação, com a finalidade de identificar e processar a requisição corretamente.

Uso: Neste campo determine o módulo que será vinculado ao Webhook, dentre eles temos os seguintes valores: NFS-e, NF-e, NFC-e, Certificado Digital ou GNRE. Ao selecionar o módulo, uma nova opção será disponibilizada para selecionar o tipo de notificação, lembrando que cada módulo tem as suas características, ou seja, as opções que aparecem nesse campo variam conforme o módulo selecionado.

Após inserir o módulo e o tipo de notificação, selecione o botão de "Aplicar" e o registro ficará salvo na tela. Esse processo pode ser realizado inúmeras vezes nesta mesma tela para módulos diferentes. No entanto, não é possível repetir o mesmo uso (Módulo e Tipo de notificação).

Caso pretenda remover algum registro, clique no ícone de exclusão, que está localizado na linha da informação do módulo cadastrado, como evidenciado acima.

Clique em "Salvar" para registrar o Webhook. Ele será exibido na "Lista de Webhooks Cadastrados", com as seguintes opções disponíveis:

Excluir: Se localiza na primeira coluna. Através dessa opção é possível excluir o Webhook selecionado.
Editar: Se localiza na segunda coluna. Através dessa opção é possível editar as informações definidas anteriormente neste Webhook.
Testar: se localiza na terceira coluna. Através dessa opção é possível testar a conexão com o Webhook.

Cadastro para Parceiro

Para cadastrar um Webhook para mais de uma empresa da base, acesse o InvoiCy e, no Painel de Controle, selecione Webhooks nas configurações do parceiro.

Em seguida, na tela "Lista de Webhooks Cadastrados" serão listados os Webhooks previamente cadastrados e vinculados ao parceiro. Bem como os filtros de "Descrição", "Status", "Módulo", "Tipo Notificação" e "Chave de Parceiro". Este último campo é exclusivo dessa tela para o parceiro.

Após preencher os filtros desejados, selecione a opção "Pesquisar" para que eles sejam listados na tela.

No lado direito da tela, clique em "Novo" para abrir a tela de Webhook e preencha corretamente os campos abaixo para cadastrar um novo Webhook:

Código: Este campo é preenchido automaticamente pelo InvoiCy, ou seja, estará disponível visualmente apenas para usuários "Administradores".

Chave de Parceiro: Ao cadastrar um novo Webhook deverá informar a chave de parceiro desejada.

Descrição: Neste campo de texto insira 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: Este campo define o modo como o InvoiCy irá se autenticar para realizar a conexão com a URL informada. Nesse campo podem ser informados os seguintes valores:

0 - Sem autenticação: ao realizar a requisição para a URL informada nenhum tipo de Authorization Request Header será enviado na conexão.
1 - Basic Auth: 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}. Sendo 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).

Headers: Neste campo pode ser inserida uma informação adicional na notificação, para identificar e processar a requisição corretamente.

Replicar para empresas: Para replicar, clique em "Replicar para empresas" e selecione as empresas desejadas na tela "Selecionar Empresa(s)". É possível localizá-las utilizando filtros como CPF/CNPJ/CNPJ Raiz, nome/apelido da empresa, UF e município, ou mesmo pelo Grupos 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, 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 o processo com sucesso, clique novamente em "Salvar".

Para as empresas selecionadas no processo de replicação, o Webhook irá aparecer na tela de lista de Webhooks cadastrados para as empresas. No entanto, suas informações não poderão ser editadas; apenas a opção "Testar" estará disponível.