2024
Cadastro de WebHook via API’s
12 de agosto de 2024Índice
-Neste artigo iremos explicar como realizar o cadastro, a consulta e a atualização de um WebHook integrando com o InvoiCy.
A partir de agora assumimos que você já leu o artigo “Integrando com o WebHook”. Caso ainda não tenha lido o artigo, recomendamos que realize a leitura do mesmo, para facilitar o entendimento deste artigo.
Confira a seguir os detalhes das novas APIs, que estão disponíveis em SOAP e REST.
Cadastro de WebHook via SOAP
Há duas possibilidades para cadastro de WebHook: para a empresa e para parceiros. Existem algumas diferenças na hora de realizar o cadastro de uma ou outra opção, que serão esclarecidas logo em seguida.
- Cadastro de WebHook para Empresa: trata-se de um WebHook exclusivo para a sua empresa, que enviará notificações para o link configurado. Para realizar esse cadastro, é essencial que a informação <inv:EmpCNPJ> seja preenchida no momento do envio da requisição.
Clique aqui para realizar o download da estrutura SOAP.
O XML de envio contém os seguintes campos que devem ser preenchidos:
Descrição – Neste campo de texto vai a descrição/título que desejarem informar ao WebHook que está sendo cadastrado.
Status – Define se o WebHook configurado está preparado para receber mensagens ou não, os valores aceitos são:
A – Ativo
I – Inativo
Tipo Autenticação – O campo Tipo de Autenticação é 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 – 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).
Módulo – É nessa etapa que será escolhido o módulo que será vinculado ao WebHook em questão. Nesse campo temos os seguintes valores:
1 – NF-e
2 – NFC-e
4 – NFS-e
12 – GNRE
14 – Certificado Digital
Tipo Notificação: Deve ser escolhido o tipo de notificação a ser enviado. Nesse campo temos os seguintes valores:
1 – Emissão do documento
2 – Atualização de status
3 – Evento
4 – Documento recebido
5 – Atualização de dados
6 – Documento inutilizado
7 – Documento autorizado na SEFAZ
8 – Vencimento do certificado
9 – Inclusão na fila para consulta
10 – Novo documento não encontrado
11 – Novo documento encontrado
Vale ressaltar que cada módulo tem suas características, então os tipos de notificações variam conforme o módulo em questão. Para estabelecer essa relação, disponibilizamos a seguinte tabela:
Para realizar o download de um xml de exemplo, clique aqui.
- Cadastro de WebHook para Parceiro: trata-se de um cadastro para utilizar o mesmo WebHook para mais de uma empresa da sua base, visando facilitar o processo.
Para realizar esse cadastro, é necessário remover a informação do campo <inv:EmpCNPJ>. Além disso, o Hash MD5 precisa ser gerado no seguinte formato: chave de parceiro + xml da requisição.
No xml de envio, existe apenas um grupo diferente do que já foi visto anteriormente, que contempla o CNPJ das empresas que terão o WebHook replicado:
Clique aqui para fazer o download do XML acima.
Consulta de WebHook via SOAP
A estrutura para a consulta de WebHook é simples, veja em seguida como realizar:
Como já estabelecido anteriormente, quando a ação é relacionada a empresa, é necessário informar o campo <inv:EmpCNPJ> na estrutura SOAP. Já quando for realizada a consulta de um WebHook de parceiros, remova a informação do campo em questão.
O xml de envio conta com o seguinte campo:
Identificador – trata-se de um campo gerado automaticamente pelo InvoiCy no momento do cadastro do WebHook.
Se o campo não for preenchido, a consulta irá retornar todos os WebHooks disponíveis para aquela empresa ou chave de parceiro. Caso seja preenchido, o retorno trará apenas o WebHook identificado.
O que define se a consulta será realizada para empresa ou parceiro é o preenchimento, ou não da tag <inv:EmpCNPJ> e como o Hash MD5 foi gerado. Para empresa, deve ser gerado com base na chave de acesso da empresa + XML da requisição. Para consultar um WebHook de parceiros, o Hash deve ser gerado no seguinte formato: chave de parceiro + XML da requisição.
Para fazer o download do XML de consulta, clique aqui.
Atualização de WebHook via SOAP
Para atualizar dados em um WebHook já existente, é preciso enviar o xml de cadastro juntamente com o campo identificador, para que os dados sejam sobrescritos.
Novamente, nesse caso também existe a regra que contempla o campo <inv:EmpCNPJ> e a forma de geração do Hash MD5, já comentados acima. É isso que irá definir se a solicitação é para empresa ou parceiro.
Para obter o campo “Identificador” e a estrutura completa para atualização, basta consultar os WebHooks disponíveis.
No exemplo acima, é possível identificar que a alteração será feita para um WebHook de parceiros, por conter o grupo <Empresas>. Logo, o código Hash MD5 deve ser gerado com base na chave de parceiro e o campo <inv:EmpCNPJ> não deve ser preenchido na estrutura SOAP.
Também existe a opção de excluir o WebHook através da atualização de cadastro, basta informar o texto “DELETAR” no campo <Modo>.
Ações de WebHook via Rest
Para realizar ações como cadastro, consulta, alteração e exclusão de WebHook é necessário utilizar os métodos POST, GET, PUT e DEL, respectivamente. Acesse aqui a documentação e exemplos de integração REST.
No caso de API REST, o que define se o cadastro é para empresa ou parceiro é a forma de autenticação da requisição. Para cadastro de WebHook parceiro é necessário gerar o token de parceiro. Já para empresa, é necessário gerar o token de empresa.
Atenção!
Para ter um melhor entendimento sobre os tipos de notificações, acesse os seguintes artigos: