Como integrar o HotConnect e o Webhook

A Hotmart, além de oferecer o site com relatórios e uma área de membros, também disponibiliza duas formas de conexão automatizadas: o HotConnect e o Webhook. 

Para essas formas de conexão é necessário o auxílio de um desenvolvedor. Mas, mesmo assim, muitas vezes existem dúvidas sobre qual a melhor maneira de integrar isso.

Por isso, pensamos neste post para te ajudar a escolher a melhor forma de conectar o sistema dos usuários na plataforma e vamos mostrar alguns pontos positivos de cada um.

HotConnect

O HotConnect é a forma que os sistemas dos usuários se conectam na plataforma utilizando as APIs disponibilizadas neste link. 

Como principais funcionalidades dessa ferramenta, temos:

• Credenciais
• Autenticação de usuários
• Autenticação de aplicativos
• API

Credenciais

Antes de começar a utilizar o Hotconnect, é importante criar uma credencial na aba de Credenciais, clicando no botão Nova credencial na parte direita da tela.

Ao clicar, um pop-up vai abrir.

Basta colocar o nome da credencial e salva-lá para que ela apareça nas suas credenciais já criadas.

Ao clicar no ícone de Ações, vão aparecer três ações possíveis:

• Editar: na qual você pode alterar o nome da sua credencial;
• Parâmetros de autenticação: mostra os parâmetros que são necessários para utilizar os recursos do HotConnect;
• Remover: para deletar aquela autenticação. Consequentemente, sistemas que utilizam essa credencial irão parar de funcionar após a remoção.

Ao clicar em Parâmetros de autenticação, aparecerá um novo pop-up com as credenciais para acessar os recursos do HotConnect, como:

• Client ID: chave única de identificação da credencial;
• Client Secret: código para liberação da credencial;
• Basic: código gerado para acesso dos recursos do HotConnect.

É importante dizer que, para maior segurança, os acessos só serão permitidos caso todas informações estiverem corretas.

Agora, com a credencial, já podemos utilizar os recursos do HotConnect. A seguir, vamos mostrar os principais cenários de aplicação.

Autenticação de usuários

Através desse recurso, o usuário faz um login na Hotmart e, com isso, disponibiliza acesso às informações das APIs do HotConnect. 

Esse recurso é muito útil caso o seu software precise de algumas informações do usuário na plataforma. 

Exemplo disso são sistemas que geram notas fiscais através do histórico de vendas. Quando o Produtor aceita o login, o sistema pode gerar as notas necessárias com o token do usuário.

É importante deixar claro que a utilização desse recurso só é possível com a autorização prévia do usuário.

Autenticação de aplicativos

Essa funcionalidade geralmente é a parte mais utilizada do HotConnect.

Com ela, seu aplicativo pode utilizar todas as ferramentas de forma automática mas, antes, é necessário autorizar o seu aplicativo. 

Com as credenciais já geradas, a requisição deve ser feita, ficando da seguinte forma:

Lembrando que deve-se alterar nos locais [CLIENT_ID], [CLIENT_SECRET] e [BASIC] pelos valores que estão na parte de credenciais.

Para facilitar, segue o exemplo de código em Curl:

Em Java:

E em Javascript:

Caso a requisição seja feita corretamente, será retornado um JSON conforme exemplo abaixo:

Com esse access_token em mãos, tudo do HotConnect pode ser executado adicionando a header da requisição no parâmetro “Authorization” -> “Bearer [ACCESS_TOKEN]”.

A chamada deve ficar da seguinte forma:

Segue o exemplo em Curl:

Em Java:

Em Javascript:

APIs

As APIs do HotConnect permitem que o seu sistema obtenha todas as informações do usuário dentro da Hotmart, como:

• Afiliações: Permite que você acesse seus links de divulgação (hotlinks) de produtos já Afiliados e, assim, faça uma divulgação mais automatizada.
• Produtos: Faça o gerenciamento do seu produto podendo criar novas ofertas e recupere todos os possíveis valores pelos quais seu produto é ofertado.
• Reports: Recupere todas as compras e tenha o detalhamento delas em mãos. Lembre-se que os dados das vendas como Afiliados ficam disponíveis apenas com a autorização do Produtor.
• Assinatura: Permite que você tenha informações das assinaturas dos seus clientes.
• Usuário: Retorna informações do usuário que utiliza o HotConnect.

Pontos positivos e negativos do HotConnect

Muitos desenvolvedores pensam que essa é a melhor forma de conexão, porque o controle de buscar informação seria de total responsabilidade do sistema do cliente, mas isso acarreta alguns problemas.

Vamos imaginar que o seu software deve se comportar da seguinte forma: 

Após a aprovação de uma compra, ele envia um email para o seu cliente contendo um bônus. Caso seja um boleto, o sistema deve enviar essa mensagem apenas quando a compra foi aprovada e somente uma vez. Garantir isso deve ser responsabilidade do seu sistema e pode ser bem trabalhoso fazer isso funcionar.

Além disso, existe um trabalho de rotinas que seu software deve fazer de tempos em tempos para verificar se houve alguma alteração no status das entidades que você deseja. 

Fazendo isso várias vezes por minuto, além de ser caro, algumas requisições podem ser bloqueadas pela Hotmart para evitar sobrecarga dos serviços.

Como pontos positivos, temos a possibilidade de revisar o histórico e chamar isso sempre que você desejar. Além disso, você pode ter acesso do seu produto para alterações que podem ser refletidas na sua página.

Webhook

O Webhook é a forma que utilizamos para notificar o sistema de forma passiva. Isso quer dizer que o seu sistema só deve ficar esperando quando tivermos alguma alteração de compra ou assinatura.

Antes de começar, o seu sistema já deve estar pronto com uma API esperando o post das atividades que acontecerão. 

Uma sugestão: a primeira coisa que o seu sistema deve fazer após receber a chamada é salvar o dado para ter toda a informação, caso necessário.

Para começar a utilizar essa funcionalidade é só clicar neste link, onde você vai encontrar a parte de configuração, documentação e histórico de envios. 

Mas fique tranquilo, vamos falar de cada parte mais pra frente.

Configuração

Na parte direita da tela existe um botão + para adicionar um novo webhook.

Depois de clicar, ele abre uma parte para configurar quais tipos de eventos o webhook vai notificar o sistema.

Na parte Minha configuração, basta colocar o nome que você deseja para essa configuração. 

O novo webhook permite que seja feita uma segmentação por status das compras, alterações de assinatura, abandono de carrinhos e produto. 

No lugar da url, deve-se colocar a url da API da sua plataforma que espera o post.

Após o cadastro, vai aparecer uma listagem com todas as APIs já configuradas. 

Agora, na parte da direita, é possível enviar um teste para aquela segmentação, editar ou remover aquele cadastro, além de poder deixar inativa temporariamente.

Teste de segmentação 

Ao utilizar o webhook, você pode fazer disparos para sua API quando quiser com os testes que disponibilizamos. 

Ao clicar em Teste, você pode escolher qual tipo de envio deseja testar. Se quiser, pode testar todos ao mesmo tempo e ver como seu sistema se comporta recebendo múltiplas requisições.

Para os testes de compra será enviado como QUERYSTRING, um formulário com um modelo parecido com esse:

Para os casos de abandono de carrinho e troca de plano, já fizemos uma atualização nas chamadas para um padrão melhor utilizando JSON. O post para esses casos será no seguinte formato.

Abandono de carrinho:

Troca de plano:

Documentação

Na parte de documentação, você pode encontrar tudo que vamos enviar para cada tipo de notificação. 

A seguir, vamos destacar os campos mais importantes para que você verifique no seu sistema.

• Hottok:  Token de verificação. Cada conta da Hotmart possui um Hottok único para que você verifique que essa chamada está realmente sendo feita pelo nosso webhook.
• Prod: Identificador do produto que foi realizada a compra ou cancelamento.
• Off: Identificador de qual oferta  foi adquirida.
• Price: Preço da oferta no momento da compra
• E-mail: E-mail do comprador.
• Doc: Documento informado pelo comprador na compra.
• Transaction: Número de transação gerado pela Hotmart.
• Status: Status da compra. Possíveis valores: approved, canceled, billet_printed, refunded, dispute, completed, blocked, chargeback, delayed, expired.
• Subscriber_code: Enviado em casos de assinatura, é um código para identificação único de cada assinatura.
• Subscription_status: Status da assinatura. Possíveis valores: active, canceled, past_due, expired, started, inactive.
• Full_price: Preço total da venda.
• Currency: Campo utilizado para exibir a moeda de pagamento.

Para o controle de suas compras, esses campos devem bastar. 

É importante saber que não enviamos as informações do comprador para Afiliados que não recebem essa permissão do comprador via liberação na plataforma.

Histórico 

Além de todos os pontos citados, contamos também com uma aba de histórico para que você possa acompanhar as respostas que estamos recebendo da sua API ao enviar os posts. 

Algumas respostas são mais comuns e vamos detalhá-las aqui:

• 200: Resposta positiva para Hotmart falando que recebeu a nossa chamada com sucesso.
• 401: Não autorizado. Quando isso ocorre, o seu sistema tem algum tipo de bloqueio que deve ser removido para que as requisições funcionem normalmente. 
• 404: NOT FOUND. Muitas vezes, quando isso acontece ou o sistema está fora do ar ou a URL informada não está correta.
• 500: Erro interno do servidor. O seu serviço conseguiu receber a nossa requisição, mas houve um problema e não conseguiu processar corretamente.
• –1: TIME_OUT: esperamos pelo nosso tempo limite de resposta e não recebemos nada.

Para todos os erros, fazemos 5 retentativas e é possível visualizar a resposta no detalhe de cada histórico a última resposta. 

Caso tenha algum problema, é possível pedir o reprocessamento de requisição quando já estiver solucionado.

Pontos positivos e negativos do Webhook

O webhook é muito útil para casos em que a sua aplicação tem que tomar uma decisão instantânea logo após algum evento, como o caso de enviar um email depois de uma aprovação de compra.

Nesse caso, seu sistema já recebe um aviso após a mudança de status e o sistema já pode realizar o fluxo desejado.

Além disso, com o ferramental de reprocessamento e histórico de chamadas ficando do lado da Hotmart, isso seria uma preocupação a menos para o seu sistema.

Como pontos negativos, temos que para dados criados antes do seu sistema entrar ao ar não foram feitas as requisições. Com isso, é necessário uma exportação dos dados mais antigos. 

Um outro problema é que, no caso de vendas simultâneas, como um lançamento, se o seu sistema não estiver preparado, ele pode cair e perder alguns posts que, é claro, podem ser reprocessados.

Conclusão

No final de tudo, não existe uma receita simples para qual tipo de integração você deve decidir. 

Para cada caso, deve ser analisado qual a melhor opção, e existe uma infinidade de opções do que pode ser feito e para cada aplicação existe um tipo de conexão que vai ser mais adequado.

Em resumo, caso necessite de um processamento mais instantâneo, uma boa alternativa seria utilizar o webhook, lembrando de escalar o sistema em caso de um comportamento atípico como um lançamento. 

Agora, se a intenção é fazer um sistema que vai rodar de vez em quando para se atualizar através de um histórico, é uma solução que é mais parecida com um caso para o HotConnect.

De qualquer forma, o importante é que você conheça mais essa solução que disponibilizamos no universo da Hotmart.

É claro que pensar em conexões é algo que exige mais conhecimento técnico de desenvolvimento. Mas a Hotmart cria soluções sempre pensando em ajudar nossos Produtores e Afiliados a focarem em uma só coisa: trabalhar com aquilo que amam.

Quer conhecer mais essas soluções?

Conheça 20 ferramentas da Hotmart para te ajudar a vender mais!