Ao realizar a integração de uma loja VTEX com um serviço externo, como um ERP, é necessário configurar um método para que o serviço obtenha detalhes e atualizações de pedidos. Para tal cenário, a VTEX disponibiliza as ferramentas de Order Feed e Order Hook, e este tutorial se destina a auxiliar em sua configuração de forma geral.
Fluxo de Pedido
Antes de tudo, é importante entendermos qual o processo de evolução de um pedido dentro do OMS da VTEX. Cada pedido, desde sua criação até sua conclusão ou cancelamento, tem definido um status que é alterado conforme diferentes passos são seguidos, como por exemplo a criação do pedido (order-created) o início da janela de cancelamento (window-to-cancel) ou o início do processo de entrega (ready-for-handling). Diferentes módulos VTEX utilizam este status para iniciar processos relacionados a pedidos (como pagamento ou logística) e o Order Feed e Order Hook são uma forma de visualizar e utilizar estes status diretamente. Uma lista completa de status e um resumo sobre fluxo de pedidos pode ser encontrado em nossa documentação aqui.
O que é o Order Feed?
O Order Feed é, em resumo, um histórico de todos os status/mudanças pelos quais um pedido passou desde sua criação. Conforme um pedido é alterado/atualizado, o Feed salva esta informação para que o serviço externo a utilize até que ele seja limpo através do envio de um request de commit.
O que é o Order Hook?
Se o Order Feed é um histórico completo de status, o Order Hook por outro lado é uma notificação enviada diretamente para um dado endpoint quando uma condição é atingida. Por exemplo, um Order Hook pode ser configurado para que, toda vez que o pagamento de um pedido seja aprovado (status payment-approved) o ERP seja notificado para prosseguir com o pedido.
Qual dos dois devo utilizar?
A escolha de qual método utilizar em sua integração deve ser tomada junto do serviço que será integrado, levando em conta sua própria arquitetura e capacidade de operação. De forma geral, a VTEX recomenda o uso do Order Hook quando a prioridade maior é a velocidade de atualizações de status. Isso porque o Order Hook, devido a sua natureza como notificação, é reativo e pode enviar múltiplos requests em um curto período de tempo, acompanhando as mudanças do pedido. Porém, muitos serviços podem não ter a infra-estrutura para escalar seu processamento em cenários com pico de notificações (ex: vendas durante a Black Friday) ou priorizam uma visão mais ampla do histórico de status de cada pedido. Neste caso, o Order Feed seria uma opção preferível.
Como configurar o Order Feed?
O processo de configuração do Order Feed é feito via API, com o request POST Create or update feed configuration. O corpo do request deve ter um campo filter e um campo queue e pode ser configurado de duas formas: com o tipo FromWorkflow e o FromOrders.
FromWorkflow
O exemplo abaixo demonstra uma configuração de Feed do tipo FromWorkflow:
{
"filter": {
"type": "FromWorkflow",
"status": [
"order-completed",
"ready-for-handling",
"start-handling",
"handling",
"waiting-ffmt-authorization",
"cancel"
]
},
"queue": {
"visibilityTimeoutInSeconds": 250,
"MessageRetentionPeriodInSeconds": 345600
}
}
Um feed do tipo FromWorkflow utiliza o Fluxo de Pedidos descrito acima, permitindo que pedidos sejam filtrados baseado nos status pelos quais o pedido passou.
FromOrders
Por outro lado, o exemplo abaixo demonstra uma configuração de Feed do tipo FromOrders:
{
"filter": {
"type": "FromOrders",
"expression": "status = \"payment-pending\""
},
"queue": {
"visibilityTimeoutInSeconds": 250,
"MessageRetentionPeriodInSeconds": 345600
}
}
Um feed do tipo FromOrders leva em conta não o status do pedido, mas todo o JSON do mesmo. Sempre que há uma atualização em qualquer dado do pedido o Feed é atualizado levando em conta a configuração do campo expression.
Em ambos os casos, conforme os exemplos, é necessário definir as configurações de tempo do Feed dentro do campo queue. O campo visibilityTimeoutInSeconds é usado para garantir que não ocorram múltiplos commits para um dado Feed. Quando o serviço externo obter atualizações no Feed, ele não ficará visível para outros requests durante o tempo configurado. O campo MessageRetentionPeriodInSeconds, por outro lado, define o tempo total que um item pode ficar no feed sem ter um commit. É importante que itens no Feed tenham um commit ou sejam limpos, para que o Feed não fique poluído com informações antigas.
Após a configuração do Order Feed, cabe ao serviço externo buscar informações dentro dele periodicamente e realizar commits após sua utilização. Este processo poder feito com os seguintes APIs:
Retrieve feed items
Commit feed items
Como configurar o Order Hook?
De forma similar, o Order Hook precisa ser configurado via API com o request Create or update hook configuration. O corpo do request dever utilizar o mesmo tipo de informação para o campo filter descrito acima, mas no lugar do campo queue é necessário utilizar o campo hook:
{
"filter": {
"type": "FromOrders",
"expression": "value > 100",
"disableSingleFire": false
},
"hook": {
"url": "https://endpoint.example/path",
"headers": {
"key": "value"
}
}
Dentro dele, o campo url define o endpoint que será notificado e o campo headers define qualquer informação de header necessária para este end-point. Como o Hook é uma notificação, não é necessária a utilização de outros APIs por parte do serviço externo após sua configuração.
Em nossa documentação completa sobre Feed e Hook, encontrada aqui, você pode obter mais detalhes sobre possíveis valores para cada um dos campos descritos acima, exemplos de configurações possíveis e também mais detalhes sobre em que cenários o Feed e Hook são recomendados.
Eduardo Luciano
Field Software Engineer | VTEX