Está disponível em nossa plataforma a integração Order Checker. Ela permitirá que todos os usuários dos planos Business e Enterprise vejam uma mensagem de erro todas as vezes que adicionarem ou editarem itens no carrinho que estejam indisponíveis em estoque.
Na prática, isso se dará através de um hooks que será enviado para uma API externa a cada alteração feita na ordem.
Quer saber como realizar esta integração? Confira o artigo para descobrir!
Configurações
A estrutura da configuração se dará da seguinte forma:
endpoint: endereço que deverá ser chamado para efetuar as validações.
headers: array reservado para adicionar headers na request remota, será utilizado principalmente para adicionar tokens de autenticação.
onError: aceita os valores “CONTINUE“ ou “FAIL“, e define o comportamento caso haja alguma falha de resposta pelo backend remoto (definido aqui com a propriedade endpoint).
{
"endpoint": "https://some.end.point.com/endpoint",
"headers": [
{
"Authorization": "Bearer asd654f6a5s4df654asd6f5"
}
],
"onError": "CONTINUE"
}
Possíveis erros
timeout da request (5s).
retorno com código de HTTP não mapeado.
retorno com payload não correspondente - json em formato incorreto ou em outro formato que não json.
A seguir fica descrita a estrutura que será enviada para a API remota.
Importante ressaltar que a API remota irá receber as informações atuais da ordem, ou seja, caso a ordem tenha acabado de ser criada, ela só vai conter o ID e o Status da ordem. A cada edição a API remota recebe o status novo da ordem.
{
"objectId": "ORDER_ID",
"eventType": "ORDER_UPDATE", //pode ser também "ITEM_UPDATE" e apenas a lista de itens será enviada
"retailerOrderId":"SEQUENCE_ORDER_ID",
"isInternational": false,
"canAcceptBoleto":true,
"canAcceptCreditCard":true,
"discount": 10,
"discountMode": "ABSOLUTE", //ABSOLUTE/PERCENTAGE
"deliveryTime": "1 dia útil",
"shippingMethod": "SEDEX",
"freightCost": 10,
"freeShipping":false,
"paymentAccountSelected": "ID_CONTA_SELECIONADA",//id mundipagg,moip,adyen, etc
"orderAccountSelected": "ID_CONTA_SELECIONADA",//id vtex,ciashop,etc
"customer": {
"objectId": "ID_CUSTOMER",
"name": "João",
"lastName": "Medeiros",
"gender": "Male",
"businessAccount": false,
"taxDocumentnumber": "00055544465",
"email": "joao@gmail.com",
"phoneNumber": "999999999",
"phoneAreaCode": "41",
"phoneCountryCode":"55"
},
"shippingAddress": {
"addressLine1": "STREET",
"addressLine2": "COMPLEMENT",
"zip": "CEP",
"recipient": "RECIPIENT_NAME",
"addressState": "STATE",
"city": "CITY",
"country": "COUNTRY",
},
"items": [
{
"objectId": "ID_ITEM",
"quantity": 5,
"price": 10,
"productReference": "654987321",
"weight": 5,
"height": 5,
"length": 5,
"width": 5,
"variantId": "ID_VARIANTE"
}
]
}
E aqui, a estrutura que deverá ser retornada pela API remota.
[
{
"action": "ERROR",
"component": "ITEM",
"componentId": "ID_ITEM",
"message": "Item não disponível"
}
]
Códigos de erro e ações
Para cada envio os seguintes códigos http serão aceitos e serão descritos abaixo os comportamentos deles com seus payloads.
http code | payload | behaviour |
200 | array vazio | deixará passar as informações sem problemas. |
200 | array com ações de erro | marcará os erros, caso for finalização da ordem, deixará passar a requisição. |
403 | array com ações de erro | marcará os erros e irá impedir de prosseguir com a finalização da ordem. |
As ações servem para discriminar qual ação devemos adotar na ordem em resposta ao processamento remoto.
campo | valor |
|
action | ERROR | siginica que houve um error |
component | ITEM | específica que o erro se refere à um item dentro da ordem |
componentId | FgkrtE50fGr5 | especifica qual dos itens falhou |
message | falta de estoque | explica o que houve com o componente afetado |
Passo a passo para a integração.
Veja agora o passo a passo para realizar a integração.
Acesse a plataforma da Omnichat.
No menu de Configurações, selecione a opção Integração >> Outros >> Order Checker.
Insira o EndPoint API.
Para adicionar tokens de autenticação, insira as informações nos campos de Cabeçalho seguido do Valor. Utilize o botão "+" para quantos forem necessários.
Se quiser permitir a venda mesmo com erro na integração, habilite o campo "Permite vendas mesmo se houver erros na API" .
6. Caso queira permitir uma venda mesmo que não tenha produto em estoque, habilite o campo "Permite vendas mesmo se houver erros nos itens" .
7. Clique em Salvar e pronto.
Obs.: utilize a aba Log de Integração para acompanhar o status da requisição.
A mensagem de erro será exibida ao inserir um produto no carrinho.
Exemplos das notificações
É possível enviar diversas notificações, como alterar o valor do frete no pedido, métodos de entrega nos itens, desconto no pedido, adicionar brindes, entre outros.
Alterando o valor do frete no pedido
[
{
"action": "INFO",
"component": "FREIGHT",
"message": "Valor do frete alterado",
"freightCost": 10 // valor do frete
}
]
Alterando o valor do desconto no pedido
[
{
"action": "INFO",
"component": "ORDER",
"message": "Valor do desconto alterado",
"discount": 10 // valor do desconto,
"discountMode": "ABSOLUTE"
}
]
Exibindo os métodos de entrega nos itens
[
{
"action": "INFO",
"component": "ITEM",
"componentId": "ID_DO_ITEM",
"shippingMethod": "PAC" // método de entrega selecionado,
"shippingOptions": [
{
"id": "PAC",
"name": "PAC",
"price": 5,
"listPrice": 5,
"tax": 0,
"deliveryChannel": "delivery",
"shippingEstimate": "3bd",
"productLockedTime": null
},
{
"id": "Expresso",
"name": "Expresso",
"price": 10,
"listPrice": 10,
"tax": 0,
"deliveryChannel": "delivery",
"shippingEstimate": "0bd",
"productLockedTime": null
}
]
}
]
Adicionando brinde no pedido
[
{
"action": "INFO",
"component": "ORDER",
"isGift": true,
"item": {
"name": "Kit Brinde Teste",
"externalId": "123", // Id do item da plataforma de origem
"sellerId": "", // Id do seller do item caso possua
"sellerName": "", // Nome do seller caso possua,
"externalImageURL": "", // URL de imagem do item
"unitMultiplier": 1,
"salePrice": 0,
"price": 0
},
"shippingMethod": "PAC",
"shippingOptions": [
{
"id": "PAC",
"name": "PAC",
"price": 5,
"listPrice": 5,
"tax": 0,
"deliveryChannel": "delivery",
"shippingEstimate": "3bd",
"productLockedTime": null
},
{
"id": "Expresso",
"name": "Expresso",
"price": 10,
"listPrice": 10,
"tax": 0,
"deliveryChannel": "delivery",
"shippingEstimate": "0bd",
"productLockedTime": null
}
]
}
]
Exibindo erros no pedido
[
{
"action": "ERROR",
"component": "ORDER",
"message": "O pedido está inválido"
}
]
Exibindo notificação de info no pedido
[
{
"action": "INFO",
"component": "ORDER",
"message": "Este pedido tem um brinde"
}
]
