API de integração via Webhook
A Uoou Solutions oferece um grupo de integrações que são responsáveis por enviar mensagens de aviso de acordo com as ações executadas na página da sua plataforma de e-commerce.
Estas integrações funcionam via Webhook, um serviço que recebe requisições enviadas pela plataforma e respondem automaticamente com as informações e ações desejadas.
Neste artigo será explicado o que é uma requisição, como um Webhook funciona, como você pode integrá-lo e um detalhamento sobre a carga enviada.
O que é uma requisição?
Uma requisição pode ser definida como uma troca de informações entre dois sistemas/servidores. No contexto das integrações via Webhook a troca ocorre da seguinte forma:
A plataforma integradora envia as informações para a "fila" de troca de informações da integração escolhida. O sistema da integração irá analisar as informações - e se enviadas corretamente - irá responder com o serviço desejado, como por exemplo enviar uma notificação para o usuário.
O que é um Webhook?
Um Webhook é um sistema customizado de envio de requisições e devolução de respostas. Através de um Webhook é possível tornar o processamento de informações mais performático por se tratar de uma cooperação entre dois sistemas.
A requisição enviada para um Webhook deve conter, no mínimo, uma seleção de informações, especificadas pela empresa, que são necessária para que o sistema da integração consiga trabalhar com a carga enviada com a requisição, e, subsequentemente, devolver as informações tratadas.
Funcionamento das integrações
O formulário das integrações com Webhook possui dois campos para duas URL's, podendo ativar apenas um se desejado, um para notificação de pedidos criados e outro para notificação de status de pedido alterado. Ao preencher estes campos com as respectivas URL's suas funções serão adicionadas à plataforma, sendo respectivamente:
Envio de notificações quando um pedido for criado: quando um pedido for criado dentro da plataforma será enviada uma notificação para a integração, e as suas ferramentas irão enviar um notificação via WhatsApp para o cliente.
Envio de notificações quando um pedido tiver seu status alterado: quando um pedido alterar seu status uma notificação será enviada para a integração, e as suas ferramentas irão enviar um notificação via WhatsApp para o cliente.
Como integrar em sua plataforma
1ºPasso: Na área administrativa, no menu "CONFIGURAÇÃO", acesse a opção "Integrações".
2ºPasso: Na listagem de integrações, procure por uma integração que utilize Webhook e a selecione.
3ºPasso: No formulário da integração há dois campos, ambos requisitando uma URL para serem ativados, esta URL é personalizada e fornecida pela integração em questão. Por exemplo, ao selecionar a integração SellFlux, os campos do formulário da integração devem ser preenchidos com as URL's fornecidas pela SellFlux. No exemplo abaixo estão sendo utilizados duas URL's de teste, não condizentes com URL's reais para o funcionamento da integração. Após preencher com as URL's, clique no botão de salvar modificações.
Como visualizar as notificações enviadas:
1ºPasso: Na área administrativa, no menu "PEDIDOS", acesse a opção "Pedidos".
2ºPasso: Na listagem de pedidos, clique em um pedido realizado após a integração.
3ºPasso: Na tela de visualização do pedido, desça até o final da página e selecione a aba de "Mensagens de E-mail e WhatsApp".
Esta aba exibe todas as notificações relacionadas ao pedido que foram enviadas. Nela será possível visualizar todas as notificações geradas por Webhook. As notificações de Webhook contém o seguinte padrão:
Assunto: o nome da integração responsável pelo envio da notificação sempre consta no início do assunto, seguido do número do pedido e uma breve descrição do gatilho para a notificação.
Tipo: seu tipo é Webhook
Mensagem transacional: é personalizada de acordo com o campo preenchido no formulário da integração, sendo "Pedido - Notificação de Criação" para a notificação enviada quando o pedido é criado, e "Pedido - Notificação de Atualização" para a notificação enviada quando o pedido tem seu status atualizado.
Destinatário: é preenchido com a URL inserida no respectivo campo no formulário da integração.
Na imagem abaixo duas integrações de Webhook foram ativadas, logo, ambas irão enviar suas notificações de acordo com os gatilhos.
4ºPasso: na aba de mensagens enviadas, clique na notificação que deseja visualizar para exibir seus detalhes.
A mensagem presente dentro da notificação selecionada é o conjunto da payload enviada pela plataforma com a resposta enviada pela integração em formato JSON.
JSON da notificação
Para o funcionamento do Webhook, a plataforma realiza uma requisição do tipo POST enviando uma payload contendo o JSON do pedido. Esta requisição é recebida e o JSON é tratado pela integração, que responde com a notificação.
Ao selecionar uma notificação de pedido é possível visualizar no campo de texto três informações essenciais: o endpoint para qual o POST foi endereçado (sendo a URL inserida no campo do formulário da integração), a payload enviada pela plataforma contendo todas as informações do pedido, e por último, a resposta do servidor da integração.
Exemplo de payload:
Request to URL: https://api.webhookinbox.com/i/Q9ZaNqwX/in/ - Data: "
{
"id": "ABCDEabcFGHi",
"number": "123456789",
"origin": "1",
"state": "delivered",
"payment_state": "completed",
"shipping_state": "delivered",
"completed_at": "2023-01-19T15:38:48-0200",
"payment_confirmed_at": "2023-01-19T15:41:04-0200",
"shipment_shipped_at": "2023-01-24T10:57:59-0200",
"total_quantity": 1,
"total": 1786,
"items_total": 6880,
"adjustments_tax_total": 0,
"adjustments_shipping_total": 0,
"adjustments_promotion_total": -5000,
"adjustments_payment_total": -94,
"adjustments_total": -5094,
"channel": {
"id": "zyxwvUQrST",
"code": "rhodes_varejo",
"name": "Rhodes Varejo"
},
"items": [
{
"id": "ABCDEabcFGHi",
"unit_price": 6880,
"quantity": 1,
"total": 6880,
"virtualized": false,
"order_item_kit_parent_id": "",
"variant": {
"id": "zyxwvUQrST",
"product_id": "ABCDEabcFGHi",
"sku": "01.10.0290.AB34.GG",
"name": "Cropped sem Manga - Tamanho PP - Cor Verde",
"product_name": "Cropped sem Manga",
"product_sku": "01.10.0290",
"release_on": null,
"image": "https:\/\/adaptive-images.uooucdn.com.br\/tr:w-1100,h-1594,c-at_max,pr-true,q-88\/a22254-ogxythkyrt0\/pv\/2d\/a8\/8e\/ABCDEabcFGHi.jpg"
}
}
],
"customer": {
"id": "ABCDEabcFGHi",
"email": "johnmarston@blackwater.com.br",
"first_name": "John",
"last_name": "Marston",
"birthday": "1873-02-19T00:00:00-0300",
"gender": "m",
"groups": [],
"created_at": "2023-01-19T14:52:49-0200",
"updated_at": "2023-01-19T15:31:04-0200",
"last_login": "2023-05-17T12:52:39-0300",
"identity": "999.888.777-66",
"telephone": "(47) 99955-3322",
"cellphone": "(47) 99955-3322",
"situation": "none",
"receive_notification_email": false,
"receive_notification_s_m_s": true,
"agreed_terms_and_conditions": true,
"indicator_i_e_recipient": "tax_payer",
"origin": "1",
"qtd_paid_orders": 1,
"qtd_orders": 1,
"total_paid_orders": 1786,
"total_orders": 1786
},
"adjustments": [
{
"id": "ABCDEabcFGHi",
"type": "shipping",
"description": "Retirada na Loja",
"amount": 0,
"created_at": "2023-01-19T15:36:33-0200",
"updated_at": "2023-01-19T15:36:33-0200"
},
{
"id": "zyxwvUQrST",
"custom_origin": {
"id": "ABCDEabcFGHi",
"code": null,
"name": "PROMO\u00c7\u00c3O TESTE CLIENTE"
},
"type": "promotion",
"description": "PROMO\u00c7\u00c3O TESTE CLIENTE",
"amount": -5000,
"created_at": "2023-01-19T15:38:46-0200",
"updated_at": "2023-01-19T15:38:46-0200"
},
{
"id": "ABCDEabcFGHi",
"type": "payment",
"description": "PIX",
"amount": -94,
"created_at": "2023-01-19T15:38:46-0200",
"updated_at": "2023-01-19T15:38:48-0200"
}
],
"shipping_address": {
"country_id": "ABCDEabcFGHi",
"country_iso": "US",
"country_name": "Estados Unidos",
"province_id": "123abc",
"province_iso": "LE",
"province_name": "Lemoyne",
"name": "Condomínio Itália",
"street": "Rua das Flores",
"city": "St. Denis",
"postcode": "99999-888",
"created_at": "2023-01-19T15:31:04-0200",
"updated_at": "2023-01-19T15:31:04-0200",
"number": "02",
"complement": "Ap 555",
"neighborhood": "Distrito Ribeiro",
"id": "zyxwvUQrST"
},
"billing_address": {
"country_id": "ABCDEabcFGHi",
"country_iso": "US",
"country_name": "Estados Unidos",
"province_id": "123abc",
"province_iso": "LE",
"province_name": "Lemoyne",
"name": "Condomínio Itália",
"street": "Rua das Flores",
"city": "St. Denis",
"postcode": "99999-888",
"created_at": "2023-01-19T15:31:04-0200",
"updated_at": "2023-01-19T15:31:04-0200",
"number": "02",
"complement": "Ap 555",
"neighborhood": "Distrito Ribeiro",
"id": "zyxwvUQrST"
},
"payments": [
{
"id": "ABCDEabcFGHi",
"payment_method_id": "zyxwvUQrST",
"method_type": "credit-card",
"order_id": "ABCDEabcFGHi",
"order_number": "090633333",
"amount": 168368,
"currency": "BRL",
"state": "completed",
"installment": 10,
"gateway": "belluno_cartao_credito",
"credit_card": {
"brand": "master",
"cardholder_name": "JOHN MARSTON",
"first_six_numbers": 123456,
"last_four_numbers": 7890,
"id": "zyxwvUQrST"
},
"acquirer_name": "Belluno",
"transaction_code": "444555",
"tid": "777888",
"nsu": "12345678912345",
"customer_ip": "45.46.47.48",
"completed_at": "2024-03-04T15:28:47-0300",
"created_at": "2024-03-04T12:07:01-0300",
"updated_at": "2024-03-04T15:28:47-0300"
}
],
"shipments": [
{
"id": "zyxwvUQrST",
"shipping_method_id": "ABCDEabcFGHi",
"state": "delivered",
"tracking_link": "",
"delivery_time": 2,
"expected_delivery_at": "2023-01-26T23:59:59-0200",
"manufacturing_delivery_time": 0,
"shipping_price": 0,
"original_amount_with_additional": 0,
"created_at": "2023-01-19T15:36:33-0200",
"updated_at": "2023-01-31T14:23:24-0200",
"method_calculator": "fixed_address",
"method_internal_name": "RETIRADA NA LOJA",
"delivered_at": "2023-01-31T14:23:24-0200"
}
],
"fiscal_documents": [
{
"id": "ABCDEabcFGHi",
"code": "3",
"chave_nfe": "11111112222222333333333334444444444"
}
],
"promotion_coupons": [
{
"id": "zyxwvUQrST",
"code": "CUPOMTESTE",
"promotion_id": "ABCDEabcFGHi"
}
],
"created_at": "2023-01-19T15:11:50-0200",
"updated_at": "2023-01-31T14:23:24-0200",
"review_link": "https:\/\/review.uooucommerce.com.br\/MTM0MQ==\/Nzk3Mzc0MQ==\/MzM5NzU5Mg==?token=d2700e2d498236acb54e0ada3c0a7fb8&utm_source=site"
}"
Response from request {"http_code":200,"response":"Ok "}Como localizar as principais informações no JSON da payload
O endpoint para qual a payload foi enviada está presente no começo da mensagem após "Resquest to URL:". No exemplo acima foi utilizado uma URL de teste.
A resposta do sistema da integração está presente no final da mensagem, contendo o código http e a resposta customizada da integração após "Response from request".
As informações essencias para o funcionamento do Webhook estão espalhadas pelo JSON, presentes em diferentes seções da payload. Os campos essenciais são:
| Campo | Tipo | Exemplo | Descrição |
| name | String | "John Marston" | Nome do lead. |
| email | String | "exemplo@email.com" | Email do lead. |
| phone | String | "(99) 99999-9999" | Telefone do lead. |
| gateway | String | "blackwater_cartao_credito" | Nome da plataforma de origem. |
| transaction_id | String | "123456" | Identificador único da transação. |
| offer_id | String | "123" | Identificador da oferta. |
| status | String | "cancelado" | Status da transação (veja tabela de status abaixo). |
| payment_date | DateTime(String) | "2023-01-25T09:06:50.641815-03" | Data e hora do pagamento. |
| url | String | "https://www.exemplo.com" | URL para pagamento (boleto, pix). |
| payment_method | String | "cartao-credito" | Método de pagamento utilizado (veja tabela de tipos abaixo). |
| expiration_date | DateTime(String) | "2023-01-25T09:06:50.641815-03" | Data de vencimento do pagamento. |
| product_id | String | "12345" | Identificador do produto vendido. |
| product_name | String | "Exemplo de produto" | Nome do produto vendido. |
| transaction_value | String | "299" | Valor da transação. |
| ip | String | "111.111.11.111" | IP do lead. |
| tags | Array(String) | ["gerou-boleto", "comprou-produto"] | Tags que devem ser adicionadas ao lead. |
| remove_tags | Array(String) | ["pagamento-expirado", "sair"] | Tags que devem ser removidas do lead. |
name, email, phone: presentes na entidade "customer" na payload:
payment_method, gateway, url, transaction_value, transaction_id, ip, payment_date, expiration_date: presentes na entidade "payments" na payload:
product_id, product_name: presentes na entidade "items" no campo "variant":
status: presente no início da payload, ou seja, na entidade "order" que engloba todas as outras:
offer_id: presente na entidade "adjustments":
Importante: os campos que não forem preenchidos ou que estiverem vazios não serão exibidos no JSON.
Configurar Webhooks 2.0
Com a grande demanda de parceiros que utilizam a nossa API e visando escalabilidade nos serviços de Webhooks a Uoou criou uma nova versão da funcionalidade, agora é possível criar Webhooks individuais possibilitando múltiplas configurações.
Para configurar um webhook você deve clicar em Webhooks no menu principal.
Ao clicar você será direcionado para a tela de gerenciamento de Webhooks.
Note que na imagem acima não há webhooks criados, para criar um clique no botão "Criar webhook" no canto superior direito da tela.
Ao clicar será exibido abaixo do botão um menu para você selecionar para qual recurso será o webhook:
Neste exemplo vamos criar um webhook de pedido. Clique em pedido.
Insira uma descrição clara informando oque o webhook fará.
Logo abaixo você deve colocar o endereço que será chamado quando o Webhook ser disparado.
No campo situação do pedido você consegue informa em quais status os webhook notificará. Selecione pendente para disparar o e-mail só quando o pedido estiver com o webhook pendente.
Abaixo existe a seção de cabeçalhos da requisição HTTP.
Aqui voce pode configurar quais cabeçalhos a Uoou enviará na requisição, é util para alguma forma de autenticação ou identificação.
Para adicionar, clique no botão adicionar dentro da seção:
Coloque o nome do campo e o valor do cabeçalho que você deseja enviar. Como exemplo podemos colocar um cabeçalho de autorização.
O próximo passo é entender e configurar a seção de agendamento.
Nesta seção você pode definir horários e dias que a Uoou irá disparar os Webhooks, isso permite que você acumule os disparos para dispara em uma hora especifica dos dia.
Observe que com esta configuração a Uoou durante a semana identificará todos os pedido que ouveram alteração e segunda-feira e às 12 horas disparará o as notificações de todos eles.
No próximo passo vamos otimizar o disparo do webhook conforme a nossa necessidade.
Como sabemos estamos criando um webhook para ser disparado quando um pedido é criado, com o que temos configurado até agora a Uoou enviará o webhook sempre que houver uma alteração de um pedido com a situação pendente, que é é o status inicial de todo pedido que ainda não foi pago.
Observe que eu falei anteriormente "sempre que houver alteração" isso significa que o pedido quando entrar na situação de pendente ou tiver qualquer alteração nela será enviado. O novo webhook foi construído de forma a verificar as regras configuradas sempre que houver qualquer tipo de alteração no pedido.
Na imagem acima podemos ver de uma forma melhor qual é o fluxo que o webhook segue, entendendo esse fluxo podemos seguir configurando o nosso webhook.
Em Campos monitorados, temos a opção de informar quais os campos que são relevantes para o noss webhook, aqui podemos configurar quais campos precisam ser atualizados para a Uoou notificar, colocarmos o endereço de envio a uoou so vai notificar se houve alteração no endereço de envio do pedido, se colocarmos valor total a uoou só vai notificar caso aja alteração no valor total do pedido, e assim por diante.
Vamos seguir com a nossa configuração de webhook selecionando o campo ID do pedido, isso porque o ID do pedido é um campo fixo e não será alterado, fazendo com que possamos criar um webhook que só enviará uma notificação para aquele pedido, fazendo isso agora nós chegamos na nossa proposta original, que era cria um webhook para pedidos novos.