SkyHub PortalApi Explorer

Consumo de Pedidos - Queues

Nesta seção mostraremos como é realizado o consumo de pedidos criados e atualizados pelo marketplace

Quando criado no marketplace, o pedido tem suas informações encaminhadas para a API, cabendo a plataforma/ERP o consumo de seus dados. O mesmo ocorre para atualizações do pedido: A informação será disponibilizada na API para consumo da plataforma/ERP.

Tanto criação quanto atualização serão notificadas pelo marketplace e deverão ser consumidas no recurso /queues/orders.

GET - Baixando pedidos (fila de integração)

Quando um pedido é gerado ou tem o status atualizado pelo o marketplace ele (pedido) é colocado em uma fila de integração e fica disponível para a baixa, que deve ser realizada através de um GET no endpoint visto a seguir:

https://api.skyhub.com.br/queues/orders

Request headers:

Key
Value

X-User-Email

email_de_usuario

X-Api-Key

token_de_integracao de sua conta SkyHub

X-Accountmanager-Key

token_account único de cada Plataforma/ERP

Accept

application/json

Content-Type

application/json

Example request:

curl --location --request GET 'https://api.skyhub.com.br/queues/orders' \
--header 'X-User-Email: email_de_usuario' \
--header 'X-Api-Key: token_de_integracao de sua conta SkyHub' \
--header 'X-Accountmanager-Key: token_account único de cada Plataforma/ERP' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'

Response esperado:

Dois possíveis retornos são esperados para o GET:

204 [Success] - No content: Retorno esperado caso não hajam pedidos novos/atualizados para consumo;

200 [Success] - OK: Caso existam pedidos novos/atualizados, será visualizado status 200 e o response body trará as informações da entrega, conforme exemplo:

Através da queues não é possível consumir um pedido especificamente. A fila deverá ser consumida por completo com as informações disponibilizadas pelo marketplace.

Suponha-se que existam 20 pedidos gerados/atualizados pelo marketplace; as notificações cairão na fila aleatoriamente, porém visando aquelas mais recentes, sendo de responsabilidade da plataforma/ERP o consumo de todas as informações disponibilizadas.

Mantendo a fila de integração "limpa", isto é, consumindo sempre todos os pedidos, garante-se que todos os novos gerados e todas as alterações de status estarão atualizados na plataforma/ERP.

O consumo do pedido sempre trará o campo calculation_type, responsável por identificar o método de cálculo de frete.

Sempre que o calculation_type for preenchido com o valor b2wentregadirect, espera-se para o payload o array pick_ups contendo informações da warehouse (CD) e SKU de venda.

Por padrão, o array pick_ups é incluso apenas para pedidos b2wentregadirect, desta forma, para pedidos cujo calculation_type for b2wentregacorreios não haverá a inclusão do referido array (pick_ups).

Dicas sobre a fila de integração de pedidos

-> Verificar o campo status[code]

Ao recuperar um pedido da fila, a integração deve verificar o campo status[code] para saber qual foi o tipo de evento: pedido novo ou uma atualização (aprovação ou cancelamento).

-> O GET na /queues/orders sempre irá retornar o status atual do pedido

O pedido entra na fila sempre que receber alguma atualização proveniente do marketplace e para a plataforma/ERP será disponibilizada a informação da última alteração sofrida.

Imagine o seguinte cenário:

  1. O pedido é gerado no marketplace (status NEW) e entra na fila (/queues/orders);

  2. A plataforma/ERP não consome o recurso /queues/orders;

  3. O pedido tem o pagamento confirmado no marketplace (status APPROVED) e esta atualização entra novamente na fila /queues/orders;

  4. Nesse momento a integração faz uma chamada GET /queues/orders. O JSON do pedido retornado conterá o status APPROVED (status atual do pedido) ao invés do status NEW (status que o pedido tinha quando entrou na fila pela primeira vez);

  5. Como o pedido entrou duas vezes na fila e não havia sido consumido, ao ser repetida a chamada GET /queues/orders (sem que haja uma nova atualização do marketplace), a integração receberá o mesmo JSON novamente.

-> Estoque Disponível x Estoque Empenhado

É obrigatório consumir todos os pedidos da fila de integração (/queues) com status NEW para que os produtos sejam empenhados em seus estoques.

Esta obrigatoriedade se dá para que sejam evitadas divergências entre o estoque disponível e o estoque empenhado.

O que pode acontecer caso não consuma todos os status do pedido? Ao não consumir o status de NEW não haverá empenho de estoque na plataforma, assim a API receberá a informação de que há estoque disponível para venda, consequentemente, poderão haver vendas sem estoque.

Vale lembrar:

  • As plataformas que não se adequarem a essa regra de negócios podem arcar com prejuízo do seller;

  • Para a API deve ser enviado apenas o estoque disponível para venda.

DELETE - Confirmando o consumo do pedido

Após o GET na /queues/orders o pedido apresentado sairá da fila de integração e ficará aguardando por 5 minutos para que a plataforma/ERP confirme o seu processamento. Esta confirmação é realizada utilizando os headers padrões na API e aplicando um DELETE no endpoint:

O {code} a ser utilizado é o código de identificação do pedido, visualizado após o GET.

No exemplo disponibilizado acima, temos o "code": "Lojas Americanas-1000000000005".

Se em até 5 minutos a API não receber a confirmação de que a integração conseguiu processar o pedido com sucesso, o mesmo voltará para a fila, ou seja, após o GET na /queues/orders a plataforma/ERP tem até 5 minutos para realizar a confirmação do consumo da informação.

Caso o sistema tente confirmar o consumo (DELETE) após os 5 minutos sem que haja um novo GET na /queues/orders será retornado status 404.

Example request:

Response esperado:

204 [Success] - No content

Importante que como boa prática aconselhamos que seja realizado o DELETE logo na sequência do GET, para evitar possíveis furos no consumo de pedidos.

PreviousFaturamento Pedido - Americanas Entrega DirectNextNotificação de Pedidos

Last updated