Webhooks

Webhooks

Webhook é um recurso que permite que sua aplicação receba do Mercos informações em tempo real. Através do webhook você pode otimizar sua integração, recebendo notificações automáticas sobre novos pedidos gerados, sobre cancelamentos e faturamentos de pedidos e também notificações sobre atualizações de pagamentos (via Mercos Pay). 

Veja como configurar o Webhook

Para configurar o seu webhook dentro do Mercos, os seguintes passos precisam ser realizados:

  1. Acesse Minha conta -> Sistema -> Webhooks

  2. Clique no botão Configurar webhook

  3. Dentro das configurações, você encontrará os seguintes campos para preenchimento:
    • URL do endpoint: informe a URL da sua aplicação que será responsável pelo recebimento das notificações enviadas pelo Mercos. Esta URL deve ser obtida com o responsável pela integração entre o Mercos e seu ERP. O conteúdo enviado pelo Mercos será em formato JSON dentro de um método do tipo POST. 
    • Situação: opção para manter o webhook como ativo ou inativo. Caso o webhook esteja inativo, nenhuma notificação será enviada para a URL informada. 
    • Tipos de eventos que podem receber notificações através do webhook:
      • ✔️ pedido.gerado: selecione esta opção quando desejar que a sua aplicação seja notificada que um novo pedido foi gerado no Mercos (através do sistema Online, pela API, pelo e-commerce B2B ou pelo aplicativo).
      • ✔️ pedido.faturado: selecione esta opção quando desejar que a sua aplicação seja notificada que um pedido foi faturado no Mercos (através do sistema Online ou pela API).
      • ✔️ pedido.cancelado: selecione esta opção quando desejar que a sua aplicação seja notificada que um pedido foi cancelado no Mercos (através do sistema Online ou pela API).
      • ✔️ pagamento.atualizado: selecione esta opção quando desejar que a sua aplicação seja notificada que um link de pagamento (via Mercos Pay) foi criado ou excluído e/ou que o status de algum pagamento (também via Mercos Pay) foi atualizado

  4. Salve a configuração 

Quando ocorrer algum dos eventos selecionados na configuração do webhook (pedido gerado, cancelado e/ou faturado ou pagamento atualizado), uma notificação será disparada na URL informada. 

Somente os usuários responsáveis pela conta possuem permissão para configurar webhook.

Importante! 
• É permitido configurar até 5 webhooks.
• A URL informada deve ser uma URL válida. Se identificarmos que a URL não é válida, não será possível configurar o webhook. Além disso, não é permitido configurar a mesma URL para diferentes webhooks.
• Pelo menos um tipo de evento precisa ser selecionado ao configurar um webhook.

Visualize as notificações enviadas

Você pode visualizar as notificações que foram enviadas pelo Mercos para a sua integração. Essa visualização auxilia a identificar se a integração conseguiu processar todas as informações que foram sinalizadas pelo Mercos. Para visualizar as notificações já enviadas ou em processo de envio, os seguintes passos precisam ser realizados:

  1. Acessar  Minha conta -> Sistema -> Webhooks
  2. Clicar na opção Consultar informações enviadas dentro das opções de algum dos webhooks já configurados

  3. Uma listagem será exibida em tela com informações sobre as notificações
    • Para cada notificação da listagem existem 4 opções de status:
      • ✔️ Envio não iniciado: a notificação está na fila para ser enviada, mas o envio ainda não foi iniciado.  
      • ✔️ Em processo de envio: o envio da notificação já foi iniciado, mas ainda não foi finalizado.
      • ✔️ Sucesso: a notificação foi enviada com sucesso.
      • ✔️ Falha: ocorreu algum erro durante o envio ou recebimento da notificação.
    • As notificações com status de Sucesso ou Falha possuem o botão Detalhar disponível. Ao clicar neste botão é possível verificar as informações da notificação (mesmas informações que aparecem na listagem) e também o conteúdo enviado na notificação (requisição) e o retorno obtido (resposta). 
    • São realizadas três tentativas de envio para cada notificação e os dados (requisição e resposta) referentes a cada tentativa podem ser visualizados dentro dos detalhes da notificação. A segunda tentativa só ocorre se a primeira não for realizada com sucesso. Da mesma forma, a terceira tentativa só ocorre quando as duas primeiras não obtiverem sucesso.  




 

Importante! São armazenadas apenas as notificações dos últimos 60 dias.

Confira a documentação técnica para obter mais informações sobre a estrutura de dados retornados pelo webhook.

Este recurso está disponível para indústrias e distribuidoras, nos planos bronze, prata e ouro.