Dúvidas Frequentes: Configuração de Order Feed e Order Hook

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

4 Likes

ainda não entendi o uso campo queue. O quer dizer quando fala que preciso fazer um commit? Você também mencionou MessageRetentionPeriodInSeconds isso quer dizer que se esse limite for atingido, o status sera removido automaticamente da fila? essas regras e tutorias se aplicam a esse repo de exemplo? GitHub - vtex-apps/orders-feed-example: Boilerplate app for listening to OMS status events