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.