Fluxo de Pedidos - CB Entrega

Sobre ambiente de homologação

Como os testes são feitos em ambiente HLG, o integrador/desenvolvedor precisa criar o pedido e aprovar o seu pagamento para simular uma compra real e seguir com os demais status.

URLs

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

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

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

Collection Postman

As collections do Postman já com os endpoints e bodys montados estão disponível nos seguintes links. Insira seu “client_id” e “access_token” para realizar as chamadas.

https://www.getpostman.com/collections/2c0bf3d85aa3c25da073

Consulta de pedidos

Durante os testes de fluxo de pedido, os status e demais informações do pedido poderão ser consultadas no seguinte endpoint:

• Método: GET

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

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}

Tracking – Pedidos CB Entrega (Macro)

O CB Entrega é a plataforma de soluções logísticas da Casas Bahia que auxilia os lojistas, na operação e gestão de suas entregas. Com o CB Entrega, os lojistas cotam com fretes mais competitivos e melhores prazos para o cliente final.

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 CB Entrega" em ambiente de homologação.

Um pedido de CB Entrega possui os seguintes status (macro):

Tracking – Pedidos CB Entrega (Micro)

Em nosso 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“.

Um pedido de CB Entrega possui os seguintes status (micro):

CB ENTREGA - POSTAGEM

Criando Pedidos

Criando Pedidos (1 SKU)

O primeiro passo é criar um pedido informando que ele é CB Entrega. 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

Request:

{
  "envvias": true,
  "serviceType": "POSTAGEM",
  "items": [{
          "skuSellerId": "7577051",
          "name": "Qualquer Descrição de Produto",
          "salePrice": 500
      }
  ],
  "customer": {
      "name": "Cliente Teste CB Entrega",
      "gender": "M",
      "documentNumber": "66304991070",
      "type": "PF",
      "email": "email@provedor.com.br",
      "bornAt": "2010-01-16T18:36:16.452Z",
      "billing": {
          "address": "Rua Mirassol",
          "number": "16",
          "quarter": "BNH",
          "city": "Mesquita",
          "state": "RJ",
          "countryId": "Brasil",
          "zipCode": "26574420"
      },
      "phones": {
          "mobile": "99988776655"
      }
  }
}

Criando Pedidos (2 SKU)

Caso queira criar um pedido com mais de um item, basta informar o Body da request adicionando mais de uma chave “items”. Exemplo de pedido com 2 produtos:

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

{
  "envvias": true,
  "serviceType": "POSTAGEM",
  "items": [{
          "skuSellerId": "7577051",
          "name": "Qualquer Descrição de Produto",
          "salePrice": 500
      },
      {
          "skuSellerId": "7577051",
          "name": "Qualquer Descrição de Produto",
          "salePrice": 500
      }
  ],
  "customer": {
      "name": "Cliente Teste CB Entrega",
      "gender": "M",
      "documentNumber": "66304991070",
      "type": "PF",
      "email": "email@provedor.com.br",
      "bornAt": "2010-01-16T18:36:16.452Z",
      "billing": {
          "address": "Rua Mirassol",
          "number": "16",
          "quarter": "BNH",
          "city": "Mesquita",
          "state": "RJ",
          "countryId": "Brasil",
          "zipCode": "26574420"
      },
      "phones": {
          "mobile": "99988776655"
      }
  }
}

Response

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

Exemplo: Podemos ver na imagem abaixo que este valor é 2404296001:

Consulta de pedidos: GET

Aprovando Pagamento do Pedido

O segundo passo é realizar o pagamento do pedido. Para realizarmos essa ação devemos acionar 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/{id-pedido}

Request: Não possui um body, então é só deixar em branco.

Observação: Seguiremos o fluxo utilizando o pedido 2404296001, gerado anteriormente.

Response

Não possui um body, avaliamos o sucesso pelo HTTP Status Code retornado, que deverá ser: 200

Status após aprovação do pagamento (macro): PAY (Pagamento aprovado

Enviando Dados Fiscais do Pedido

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

• Base URL homologação (HLG)]

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

• Base URL produção (PRD)

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

• Request:

{
   "items": [
       "7577051-1"
   ],
   "occurredAt": "2021-04-09T18:41:06.133-03:00",
   "invoice": {
       "cnpj": "33041260065290",
       "number": "2222",
       "serie": "01",
       "issuedAt": "2021-04-09T18:41:06.133-03:00",
       "accessKey": "33210233041260065290550260006773291668943901",
       "linkXml": "https://www.nfe.fazenda.gov.br/portal/principal.aspx",
       "linkDanfe": "https://www.nfe.fazenda.gov.br/portal/principal.aspx"
   }
}

Response

Além do HTTP Status Code 200 informando o sucesso da chamado, é possível validar pelo body, através dos campos "valido": true e "mensagem": "Tracking NFS criado com sucesso”.

Status após cadastro da nota fiscal (macro): RIN (Pagamento aprovado)

Gerando Etiqueta Unificada (Pacote / Volume Único)

Etiquetas unificadas são aquelas que representam o pedido como um todo. Deverá ser utilizada quando todos os itens forem enviados dentro de um mesmo pacote / volume.

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

• Método: Base URL produção (HLG)

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox/orders/{id-pedido}/generate-label

• Método: Base URL produção (PRD)

https://api-mktplace.viavarejo.com.br/api/v2/orders/{id-pedido}/generate-label

• Request:

 
{
   "labelsNumber": 1,
   "link": true
}
 

Atenção Este POST é síncrono e pode ser utilizado para obter a etiqueta de formas diferentes e quantas vezes desejar.

Importante: preencha o campo "labalsNumber" com a quantidade de etiquetas que a loja deseja gerar. Lembrando que precisa ser respeitado o número de entregas existentes dentro do pedido.

Response

Retornaremos de forma síncrona um body com a etiqueta em link ou base64 (conforme sua escolha), nos formatos PNG, PDF e ZPL. Abaixo o exemplo de quando optamos pelo retorno em link:

{
   "labels": [
       {
           "skuSellerId": "SKU123Lojista",
           "deliveryId": 30000000001,
           "image": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.png",
           "pdf": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.pdf",
           "zpl": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.zpl",
           "validity": {
               "start": "2023-01-01T00:00:00-03:00Z",
               "end": "2023-12-31T00:00:00-03:00Z"
           }
       }
   ]
}
 

Status após gerar a etiqueta (macro):

Gerando Etiqueta Unitária (Pacotes / Volumes Distintos)

Etiquetas unitárias são aquelas que representam os volumes separadamente, ou seja, uma etiqueta por pacote / volume que será enviado.

Método:• 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

• Método: Base URL produção (HLG)

https://api-mktplace-hlg.viavarejo.com.br/api/v2/sandbox/orders/{id-pedido}/generate-label

• Método: Base URL produção (PRD)

https://api-mktplace.viavarejo.com.br/api/v2/orders/{id-pedido}/generate-label

• Request:

{
   "labelsNumber": 2,
   "link": true,
   "concat": false
}

Atenção: Este POST é síncrono e pode ser utilizado para obter a etiqueta de formas diferentes e quantas vezes for necessário.

Nota-se nesse cenário que foi solicitado 2 etiquetas. Muito importante que antes de solicitar a quantidade de etiquetas, devem verificar quantas entregas há dentro do pedido.

Considerando nesse exemplo que o pedido tenham 3 entregas, para o lojista expedir da forma correta ele solicitou duas etiquetas, sendo assim, ele de alguma forma colocará duas entregas dentro de um pacote e utilizará uma das etiquetas e em outro pacote colocara a outra entrega que ficou faltando, utilizando a outra etiqueta solicitada.

Response

Retornaremos de forma síncrona um body com a etiqueta em link ou base64 (conforme sua escolha), nos formatos PNG, PDF e ZPL. Abaixo o exemplo de quando optamos pelo retorno em link:

{
   "labels": [
       {
           "skuSellerId": "SKU123Lojista",
           "deliveryId": 30000000001,
           "image": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.png",
           "pdf": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.pdf",
           "zpl": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.zpl",
           "validity": {
               "start": "2023-01-01T00:00:00-03:00Z",
               "end": "2023-12-31T00:00:00-03:00Z"
           }
       },
       {
           "skuSellerId": "SKU123Lojista",
           "deliveryId": 30000000002,
           "image": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.png",
           "pdf": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.pdf",
           "zpl": "https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.zpl",
           "validity": {
               "start": "2023-01-01T00:00:00-03:00Z",
               "end": "2023-12-31T00:00:00-03:00Z"
           }
       }
   ]
}

Gerando Etiqueta em Lote

Neste endpoint disponibilizamos a geração de etiqueta em lote, dando várias possibilidades de filtros para que o retorno seja da melhor forma esperada.

Glossário

Método:• 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

• Método: Base URL produção (HLG)

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

• Método: Base URL produção (PRD)

https://api-mktplace.viavarejo.com.br/api/v2/orders/batch/generate-labels

Body Request

{
  "concat": true,
  "link": true,
  "group": [
      {
        "orderId": 98537382901,
        "labelsNumber": 2
      },
      {
        "orderId": 92333024401,
        "labelsNumber": 3
      },
      {
        "orderId": 91880587101,
        "labelsNumber": 1
      },
      {
        "orderId": 97104991301,
        "labelsNumber": 1
      },
      {
        "orderId": 9999910101,
        "labelsNumber": 1
      },
      {
        "orderId": 89478862901,
        "labelsNumber": 1
      },
      {
        "orderId": 92513542401,
        "labelsNumber": 1
      },
      {
        "orderId": 99012855901,
        "labelsNumber": 1
      },
      {
        "orderId": 93534575301,
        "labelsNumber": 1
      },
      {
        "orderId": 98198274201,
        "labelsNumber": 1
      },
      {
        "orderId": 89138429401,
        "labelsNumber": 1
      },
      {
        "orderId": 96829268801,
        "labelsNumber": 1
      },
      {
        "orderId": 96400738201,
        "labelsNumber": 3
      },
      {
        "orderId": 94144620001,
        "labelsNumber": 2
      },
      {
        "orderId": 89278686401,
        "labelsNumber": 1
      },
      {
        "orderId": 94937568701,
        "labelsNumber": 1
      },
      {
        "orderId": 89381269701,
        "labelsNumber": 1
      }
  ]
}

Body Response

{
  "labels": [
      {   
"pdf":"https://storagefusion.blob.core.windows.net/etiquetas/63/7906b3725a50e158c39b4366b7b8d851.pdf",            "zpl":"https://storagefusion.blob.core.windows.net/etiquetas/63/7906b3725a50e158c39b4366b7b8d851.zpl"
      }
  ]
}

Boas práticas no download de etiquetas

Para que obtenham sucesso no download de etiquetas do serviço CB Entrega é importante seguir os parâmetros de segurança do protocolo RFC 7232, que descreve as especificações e padrões do protocolo HTTP, com atenção as especificações do cabeçalho, conforme seção 3.2: https://datatracker.ietf.org/doc/html/rfc7230#section-3.2

Exemplo de cabeçalho HTTP

• GET /index.html HTTP/1.1
• Host: www.exemplo.com
• User-Agent: MeuNavegador/1.0
• Accept: text/html, application/xhtml+xml, application/xml;q=0.9, /;q=0.8
• Accept-Language: pt-BR,pt;q=0.9,en-US;q=0.8,en;q=0.7
• Accept-Encoding: gzip, deflate
• Connection: keep-alive
• Cookie: sessionId=abc123; userId=xyz789

Embora na documentação o user-agent conste como opcional, tratamos como obrigatório devido ferrramentas de proteção de bot e segurança para prevenção de bots e simuladores. Então, caso não utilize nenhum simulador de user agent não haverá necessidade de informar.

Exemplo: Método e URI:

• GET https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.png
• GET https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.pdf
• GET https://storagefusion.blob.core.windows.net/etiquetas/63/999999999999.zpl

HEADERS:

User-Agent:Exemplo 
Accept:application/json
Content-Type:application/json

  Caso precise negociar parâmetros específicos e personalizar o acesso do bot, por favor, enviar email para integracao.mktp@casasbahia.com.br