Guia de integração de ERPs - Pedidos

Integração

VTEX Team

VTEX Team

Última atualização

A única razão para a existência de uma loja é vender. Isto significa não apenas receber pedidos feitos por clientes, mas também fazer o fulfillment desses pedidos de maneira eficiente.

Quanto maior a operação, maior a necessidade de uma plataforma automatizada para lidar com os pedidos recebidos por diferentes canais.

Neste artigo, você encontrará o principal método para entrada dos pedidos recebidos por sua loja em sua plataforma de fulfillment.

Visão geral

A integração de pedido compreende quatro momentos distintos, cada um deles sendo um pequeno processo por si só.

ERP Orders 1

Passos da integração de pedidos

Vamos olhar detalhadamente cada um dos passos da integração de pedidos.

Download de pedido

A primeira coisa que você precisa para o download de um pedido é saber o momento certo de fazer isso. Para ajudá-lo nessa tarefa, a VTEX oferece o Feed de pedidos. Esse serviço informa mudanças importantes no workflow do pedido, especialmente mudanças no status dos pedidos.

Após decidir que é hora de levar um pedido para sua plataforma de fulfillment, você precisa apenas fazer o download dos detalhes desse pedido e dizer ao feed que ele não precisa enviar aquele evento novamente, uma vez que seu interesse nele terminou.

No fim, para os pedidos processados, você envia ao OMS uma mensagem de "Start Handling".

ERP Orders 2

Chamadas de API

1. Take feed event: https://documenter.getpostman.com/view/487146/oms/6tjSKqi#49ba56c0-0358-4579-b99e-ad330bfc37d0

curl --request GET \
  --url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/feed/orders/status?maxLot={{maxLot}}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
  --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}’

2. Get order detail: https://documenter.getpostman.com/view/487146/oms/6tjSKqi#43524211-bbed-4f80-9a9b-d96b32347f0a

curl --request GET \
  --url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
  --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}'

3. start-handling: https://documenter.getpostman.com/view/487146/oms/6tjSKqi#d1f4d8fb-1173-4a1e-8a55-38ed5521704e

Você também verá essa chamada em outros passos do processo de integração, com a mudança apenas do evento-alvo.

É muito importante chamar a transição "Start-handling", já que essa é a operação que liga o pedido e a contagem de estoque à reserva de estoque, no módulo de logística da VTEX. Nesse etapa o pedido vai ser alterado de "Pronto para o manuseio" para "Iniciar manuseio" e depois para "Preparando Entrega".

curl --request POST \
  --url 'http://{{accountname}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/start-handling' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
  --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}'

4. Ack feed: https://documenter.getpostman.com/view/487146/oms/6tjSKqi#1befe019-2219-40ad-b693-ff16aaf51d84

curl --request POST \
  --url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/feed/orders/status/confirm' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
  --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
  --data '[
    {
        "commitToken": "Marketplace##{\"Receipt\":\"+eXJYhj5rDqHa28+XUcfebDO4pve3TvMpPlW0ivc5STyE/
40J6wxooXgBF8LZ9CdhZkFJnMYBVDwPwQtNEoZQrVtErDB2Yq2zs16QqsJuYxSrQtBfl9rMfmkO5orB9oDHSpvwL6DjDzcuJeQBBNxono/
m4F6BloJEsk9BmuTmPaRI+7xsrN5Oeg8NPUoNSnsT983JPr1B+Y+TbbFjC1R8ZkvFHGVfti1QbhOwmYWTHPG08YMqla+Qwh7kUONLBXPqpo
rF/CcqJo5YVTSu2uBcCuXkUo+OH9uUTn6hHkUROo=\",\"PublisheId\":\"C0111A50CEB244E59C95422870127A4F\",
\"PublisheId_Item\":\"C0111A50CEB244E59C95422870127A4F\",\"EventId\":\"0dc05b6b-48a5-4f03-975aa69fb6550aaa\",\"
LastSendOverwrite\":null}"
    }
]'

Fatura

Agora o pedido está sendo processado por sua plataforma de fulfillment. Durante esse processo, você pode precisar fazer mudanças no pedido original, seja por conta de ruptura de estoque, seja por outra razão qualquer. Você pode desejar remover, adicionar ou alterar itens, causando ou não mudanças no valor do pedido.

Quando você estiver pronto para a entrega do pedido, é hora de informar isso à VTEX. Assim, a autorização de pagamento poderá ser capturada e o consumidor será notificado sobre o progresso.

ERP Orders 3

Chamadas de API

1. Enviar mudanças para a loja: https://documenter.getpostman.com/view/487146/oms/6tjSKqi#4701480a-d95f-4279-9e9d-da256ee8ea5c

curl --request POST \
  --url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/changes' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
  --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
  --data '{
  "reason": "Promotion by phone.",
  "discountValue": 1000,
  "incrementValue": 0,
  "itemsRemoved": [
    {
      "id": "234794",
      "price": 600,
      "quantity": 2
    }
  ],
  "itemsAdded": [
    {
      "id": "234788",
      "price": 200,
      "quantity": 1
    }
  ]
}’

2. Enviar fatura para a loja: https://documenter.getpostman.com/view/487146/oms/6tjSKqi#102391a1-346d-4fa8-91fe-b11706922a77

curl --request POST \
    --url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/invoice' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
    --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
    --data '{
  "type":"Output",
  "issuanceDate":"2010-01-31",
  "invoiceNumber":"9999",
  "invoiceValue":"10000",
  "invoiceKey": null,
  "invoiceUrl": null,
  "courier": null,
  "trackingNumber": null,
  "trackingUrl": null,
  "items": [
    {
      "id": "1234",
      "price": 10000,
      "quantity": 1
    }
  ]
}’

Rastreamento de pedido

A última etapa do seu gerenciamento de pedido é enviar informações de rastreamento do pedido à VTEX.

Embora não seja um passo necessário para que o pedido chegue ao consumidor, esta é uma das funcionalidades mais importantes para uma boa experiência do usuário. Não existe como saber com precisão a localização do produto comprado.

Não há limite para o número de mensagens de rastreamento que podem ser adicionadas a uma fatura. Normalmente, é adicionada uma mensagem para cada evento de rastreamento até que os itens sejam entregues ao comprador. No caso de produtos digitais, este último evento seria a URL para download.

É importante ressaltar que essa informação é, na verdade, um conjunto de atributos de uma fatura. Portanto, pode ser enviada junto à fatura, no momento de envio à loja, caso você tenha essa informação nessa etapa.

ERP Orders 4

Chamadas de API

1. Enviar informação de entrega à loja: https://documenter.getpostman.com/view/487146/oms/6tjSKqi#2bc08480-cc43-4126-8368-6508a4358d28

curl --request PATCH \
  --url 'http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/invoice/
{{invoiceNumber}}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
  --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
  --data '{
  "trackingNumber": "87658",
  "trackingUrl": "https://my.tracking.url/package",
  "courier": "WorldEx"
}’

2. Enviar mensagens de rastreamento à loja: https://documenter.getpostman.com/view/487146/oms/6tjSKqi#97ec170c-076e-4347-870b-143704124e17

curl --request PUT \
  --url http://{{accountName}}.vtexcommercestable.com.br/api/oms/pvt/orders/{{orderId}}/invoice/
{{invoiceNumber}}/tracking \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
  --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}' \
  --data '{
  "isDelivered": true,
  "events": [
    {
      "city": "Rio de Janeiro",
      "state": "RJ",
      "description": "Left the distribution center.",
      "date": "2015-06-23"
    },
    {
      "city": "Sao Paulo",
      "state": "SP",
      "description": "On its way to Curitiba.",
      "date": "2015-06-24"
    }
  ]
}’

Passo extra: Cancelamento de pedido

Quando, por algum motivo operacional, você precisar cancelar o pedido sendo processado, uma mensagem de cancelamento pode ser enviada ao workflow do OMS. Se o pedido estiver em um status que não permite cancelamento, aparecerá um erro.

Atenção: pedidos com fatura não podem ser cancelados.

Chamada de API

https://documenter.getpostman.com/view/487146/oms/6tjSKqi#8e74afca-431d-413e-92ad-017102abdbe2

curl --request POST \
  --url 'http://{{accountName}}.{{environment}}.com.br/api/oms/pvt/orders/{{orderId}}/cancel' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-vtex-api-appkey: {{X-VTEX-API-AppKey}}' \
  --header 'x-vtex-api-apptoken: {{X-VTEX-API-AppToken}}'

Este artigo foi útil?