Pedidos de Logística própria (/orders)

Como os testes são feitos em ambiente HLG, o integrador precisa criar o pedido e aprovar o seu pagamento para simular uma compra real e seguir com os demais status (em PRD isso não é necessário, pois o pedido vem do FRONT e o gateway de pagamento é da Via, então a atualização de aprovação de pagamento também é nossa).

URLs

Disponibilizamos um ambiente de homologação para a realização dos testes em nossas APIs. O Fluxo a seguir tem como base as seguintes URLs:

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox

https://api-mktplace.viavarejo.com.br/api/v2/

Collection Postman

A collection do Postman já com os endpoints e bodys montados está disponível no link abaixo.

Link (HLG / PRD):https://www.getpostman.com/collections/22d97d8c0db2868db1ba)

Consulta de pedidos

Em HLG, os status e demais informações do pedido poderão ser consultadas no seguinte endpoint:

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox/orders/{orderId}

Já em PRD, é possível obter status de pedido através da consulta (endpoint abaixo) ou por evento de notificação (callback). Clique aqui e veja a documentação do serviço de notificação de pedidos.

https://api-mktplace.viavarejo.com.br/api/v2/orders/{orderId}

Fluxo de pedidos (Status Macro)

Pedidos logística própria ocorrem quando o lojista opta por utilizar seu próprio fluxo de distribuição, onde ele será responsável por realizar a cotação de frete, definir o transportador e também por acompanhar e atualizar o tracking até a entrega.

A proposta desta documentação é fornecer um passo a passo dos endpoints e payloads que sellers e integradores deverão executar para criação de um "pedido logística própria" em ambiente de homologação.

Os status macro podem ser identificados no GET /orders através do campo “status“.

• Pedidos de logística própria possuem os seguintes status (macro):

Fluxo de pedidos (Status Micro)

Na Via Marketplace, dividimos os SKUs por entregas individuais (split), no qual cada uma segue seu respectivo tracking, o que chamamos de status “micro”, pois eles seguem siglas e descrições diferentes dos status “macro”.

Os status micro podem ser identificados no GET /orders através da chave “trackings“.

• Pedidos de logística própria possuem os seguintes status (micro):

Criando pedido contendo 1 SKU ou 2 SKUs (Apenas HLG)

O primeiro passo é criar um pedido informando que ele é logística própria (não Envvias). Para realizarmos essa ação devemos acionar o seguinte endpoint:

Método: POST

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox/orders

Body da chamada contendo 1 SKU

Body da chamada contendo 2 SKUs

Response (independente da quantidade de SKUs)

Nos "Headers" do response, teremos um atributo chamado "content-location", e no seu valor encontraremos o "orderId (número do pedido)" que foi criado, o qual iremos utilizar nos demais endpoints.

Clique aqui e veja o endpoint completo!

Aprovando pagamento de pedido (Apenas HLG)

O segundo passo é realizar o pagamento do pedido. Para realizar essa ação adicione o seguinte endpoint:

Método: PUT

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox/orders/status/approved/{orderId}

Body da chamada

Esta chamada não possui body, basta inserir um número de pedido válido e que esteja no status "PEN".

Response

O sucesso da chamada é avaliado pelo HTTP Status Code retornado, que deverá ser 200

Clique aqui e veja o endpoint completo!

Emitindo nota fiscal de pedido (HLG e PRD)

O terceiro passo é enviar os dados da nota fiscal do pedido. Para realizarmos essa ação devemos acionar o seguinte endpoint:

Método: POST

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox/orders/{orderId}/trackings/invoice

Endpoint (PRD):

https://api-mktplace.viavarejo.com.br/api/v2/orders/{orderId}/trackings/invoice

Body da chamada

Response

Possui um body, informando o sucesso ou não da chamada, que pode ser verificado pelos campos "valido": true e "mensagem": "Tracking NFS criado com sucesso" para sucesso. Além do body podemos validar também pelo HTTP Status Code que deverá ser 200

Clique Aqui e veja o endpoint completo de HLG!

Clique aqui e veja o endpoint completo de PRD!

Marcando pedido como enviado (HLG e PRD)

O quarto passo é enviar os dados de envio do pedido. Para fazermos isso devemos chamar o endpoint a seguir:

Método: :POST

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox/orders/{orderId}/trackings/sent

Endpoint (PRD):

https://api-mktplace.viavarejo.com.br/api/v2/orders/{orderId}/trackings/sent

Body da chamada

Response

Não possui body, avaliamos o sucesso pelo HTTP Status Code que deverá ser :201 - Created

Marcando pedido como entregue (HLG e PRD)

O quinto e último passo, é marcar o pedido como entregue. Fazemos isso o endpoint a seguir:

Método: POST

Composição do Header:

• access_token: Chave de acesso da loja
• client_id: Chave de acesso da integradora
• Accept: application/json
• Content-Type: application/json

Endpoint (HLG):

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox/orders/{orderId}/trackings/delivered

Endpoint (PRD):

https://api-mktplace.viavarejo.com.br/api/v2/orders/{orderId}/trackings/delivered

Body da chamada

Response

Não possui body, avaliamos o sucesso pelo HTTP Status Code que deverá ser :201 - Created