Os tópicos presentes neste Guia Técnico possibilitam o correto desenvolvimento e garante a padronização de todas as etiquetas emitidas para os sellers que utilizam o serviço de frete B2W Entrega via API. Com isso, o fluxo operacional de entrega e identificação visual por parte da operação da transportadora responsável pela entrega das encomendas é assertivo e segue o padrão pré-estabelecido pelos mesmos.
A etiqueta do B2W Entrega tendo como seu transportador a Direct, tem informações vitais e específicas para todo o processo de entrega e todos os campos que serão referenciados abaixo devem ser parte integrante da etiqueta desta modalidade:
Logo da Marca (B2W Entrega)
QR Code
Símbolo de Encaminhamento
Informação de Volumes
Nota Fiscal
Número do Pedido
Número do Packing List
DtPr (informação interna Direct)
Código de Rastreamento
Código de Barras (AWB)
Dados de Recebedor (Recebedor, Assinatura, Documento)
Dados de Destinatário (Nome, Endereço, Bairro, Complemento, CEP, Cidade e UF)
Código de Barras do CEP
Campo Base/Rota (informação interna Direct)
Campo Menu de Frete (informação interna B2W)
Dados do Remetente (Vendedor, Endereço, CEP, Cidade e UF)
As medidas de toda a etiqueta, assim como o devido posicionamento de todos os seus campos e elementos, devem segui exatamente as cotas abaixo:
Todas as fontes, tamanhos e suas aplicações presentes em todos os campos que são parte integrante da etiqueta do B2W Entrega seguem um padrão referenciado pelos transportadores do serviço e sua aplicação deve ser exatamente conforme descrito na tabela abaixo:
O serviço B2W Entrega é identificado por 3 variações de logos conforme ilustração abaixo. Esta identificação visual tem como objetivo principal o selo de garantia da qualidade e reputação do serviço de entrega oferecido ao cliente final, assim como são facilmente identificados dentro da operação dos transportadores com as quais o serviço de entrega é prestado, sendo assim de suma importância a presença destes elementos na etiqueta do serviço:
{"plp": [{"id": 61931,"expiration_date": "2019-09-12","printed": false,"type": null,"orders": [{"code": "158274862","customer": "Rubia","value": 20}, {"code": "158274859","customer": "Rubia","value": 20}]}]}
Atenção: Para cada entrega este logo varia conforme regras acima, e não é desejável aplicar apenas um deles como padrão fixo.
Os símbolos de encaminhamento são ícones que representam o conjunto de serviços de envio de encomendas dos Correios. Tais símbolos tem o objetivo de identificar visualmente a linha da encomenda e são usados para os serviços conforme abaixo:
Atenção: É expressamente proibido a inserção de qualquer logo nesta etiqueta que não seja o das marcas oficiais da B2W reproduzidas através da marca do seu produto B2W Entrega, contidas neste Guia.
GET /shipments/b2w/to_group
Atualmente são disponibilizados 20 pedidos por página via API, mas nós disponibilizamos o recurso de paginação para este Endpoint.
Segue abaixo um exemplo de como realizar a paginação de pedidos aptos para agrupamento:
GET https://api.skyhub.com.br/shipments/b2w/to_group?offset=1
O limite de pedidos para incluir no agrupamento atualmente é de 25.
curl --request GET \--url https://api.skyhub.com.br/shipments/b2w/to_group \--header 'accept: application/pdf' \--header 'x-accountmanager-key: SUAXACCOUNT' \--header 'x-api-key: SuaApiKey' \--header 'x-user-email: seu@email.com'
Request Headers:
Name | Type | Required | Description | Example |
accept | String | Required | O formato que você deseja receber o retorno da requisição | application/pdf |
x-user-email | String | Required | E-mail da loja | seu@email.com |
x-api-key | String | Required | Token da loja | SuaApiKey |
x-accountmanager-key | String | Required | Código identificador da sua Integração | SUAXACCOUNT |
Você também pode utilizar o Header accept como application/json para receber a etiqueta em formato Json.
200 Success - Postagem (PLP) Get - retorno 200 lista de pedidos aptos ao agrupamento
GET /shipments/b2w/
Função que permite verificar na API todas as PLP's agrupadas. No retorno será possível verificar o ID da PLP e os pedidos inseridos em cada agrupamento.
curl --request GET \--url https://api.skyhub.com.br/shipments/b2w/ \--header 'accept: application/json' \--header 'content-type: application/json' \--header 'x-accountmanager-key: SUAXACCOUNT' \--header 'x-api-key: SuaAPIKey' \--header 'x-user-email: seu@email.com'
Request Headers:
Name | Type | Required | Description | Example |
accept | String | Required | O formato que você deseja receber o retorno da requisição | application/json |
Content-type | String | Required | | application/json |
x-user-email | String | Required | E-mail da loja | seu@email.com |
x-api-key | String | Required | Token da loja | SuaApiKey |
x-accountmanager-key | String | Required | Código identificador da sua Integração | SUAXACCOUNT |
200 Success: Postagem (PLP) Get - listar PLP's
POST /shipments/b2w/
Ao efetuar o POST para agrupar a PLP retornará a ID da PLP. Com a ID da PLP será necessário recuperar a PLP.
Example Request:
curl --request POST \--url https://api.skyhub.com.br/shipments/b2w/ \--header 'accept: application/json' \--header 'content-type: application/json' \--header 'x-accountmanager-key: SUAXACCOUNT' \--header 'x-api-key: SuaApiKey' \--header 'x-user-email: seu@email.com' \--data '{"order_remote_codes":["265358194401","265358194401","265358194401"]}'
Request Headers:
Name | Type | Required | Description | Example |
accept | String | Required | O formato que você deseja receber o retorno da requisição | application/json |
Content-type | String | Required | | application/json |
x-user-email | String | Required | E-mail da loja | seu@email.com |
x-api-key | String | Required | Token da loja | SuaApiKey |
x-accountmanager-key | String | Required | Código identificador da sua Integração | SUAXACCOUNT |
Request Body:
{"order_remote_codes": ["265358194401","265358194401","265358194401"]}
Responses:
200 Success: "message": "Plp 14 agrupada com sucesso."
Hoje é possível fazer a consulta ou descobrir qual o ID da PLP através do numero do pedido, para que haja a impressão da etiqueta.
Para descobrir o ID, deve ser utilizado a seguinte requisição.
GET /shipments/b2w?delivery_id={numerodopedido}
Responses:
200 Success
Segue a baixo o body do response:
{"plp": [{"id": 61931,"expiration_date": "2019-09-12","printed": false,"type": null,"orders": [{"code": "158274862","customer": "Rubia","value": 20}, {"code": "158274859","customer": "Rubia","value": 20}]}]}
Neste método mostramos como desagrupar a PLP por completo, ou seja, todos os pedidos do agrupamento. Por exemplo:
Pensando que 3 pedidos foram agrupados, retornará um ID. Ao efetuar o DELETE do ID, todos os pedidos ficarão disponíveis para que sejam agrupados novamente da forma que achar melhor, seja ela unitário ou em grupo.
DELETE /shipments/b2w/
Example Request:
curl --request DELETE \--url https://api.skyhub.com.br/shipments/b2w/ \--header 'accept: application/json' \--header 'content-type: application/json' \--header 'x-accountmanager-key: SUAXACCOUNT' \--header 'x-api-key: SuaApiKey' \--header 'x-user-email: seu@email.com'
Request Headers:
Name | Type | Required | Description | Example |
accept | String | Required | O formato que você deseja receber o retorno da requisição | application/json |
Content-type | String | Required | | application/json |
x-user-email | String | Required | E-mail da loja | seu@email.com |
x-api-key | String | Required | Token da loja | SuaApiKey |
x-accountmanager-key | String | Required | Código identificador da sua Integração | XACCOUNT |
Request Body:
{"plp_id": "14"}
200 - Success: "message": "Plp 14 desagrupada com sucesso."
Diferente da ação apresentado acima, nesta função é possível desagrupar apenas 1 pedido da PLP.
Por exemplo:
Foi agrupado 3 pedidos e por algum motivo você precisa desagrupar 1 pedido, ou seja, tirar um pedido do agrupamento. Neste caso, será necessário utilizar o método a baixo:
DELETE /shipments/b2w/{delivery_id}
Example Request:
curl --request DELETE \--url 'https://api.skyhub.com.br/shipments/b2w/{delivery_id}' \--header 'accept: application/json' \--header 'content-type: application/json' \--header 'x-accountmanager-key: SUAXACCOUNT' \--header 'x-api-key: SuaApiKey' \--header 'x-user-email: seu@email.com'
Em {delivery_id} deve ser informado o numero do pedido a ser excluído do agrupamento.
Request Headers:
Name | Type | Required | Description | Example |
accept | String | Required | O formato que você deseja receber o retorno da requisição | application/json |
Content-type | String | Required | | application/json |
x-user-email | String | Required | E-mail da loja | seu@email.com |
x-api-key | String | Required | Token da loja | SuaApiKey |
x-accountmanager-key | String | Required | Código identificador da sua Integração | XACCOUNT |
GET /shipments/b2w/view?plp_id={CODE}
Para recuperar a PLP é necessário primeiro efetuar o agrupamento da PLP para receber o ID e passar no Endpoint.
Caso queria retornar os dados da etiqueta em formato JSON, deve-se passar o header Accept: application/json.
Example Request:
curl --request GET \--url 'https://api.skyhub.com.br/shipments/b2w/view?plp_id={CODE}' \--header 'accept: application/pdf' \--header 'content-type: application/json' \--header 'x-accountmanager-key: SUAXACCOUNT' \--header 'x-api-key: SuaApiKey' \--header 'x-user-email: seu@email.com'
Request Headers:
Name | Type | Required | Description | Example |
accept | String | Required | O formato que você deseja receber o retorno da requisição | application/json |
Content-type | String | Required | | application/json |
x-user-email | String | Required | E-mail da loja | seu@email.com |
x-api-key | String | Required | Token da loja | SuaApiKey |
x-accountmanager-key | String | Required | Código identificador da sua Integração | XACCOUNT |
Responses:
200 - Success: "Response": PDF ou Json da PLP
Para imprimir a etiqueta na impressora térmica, será necessário baixar o arquivo Json da etiqueta utilizando o parâmetro: Accept: application/json. Através dele você receberá o Json da etiqueta de deverá montar o layout para a impressão
Existem situações que o seller precisa dividir a entrega em múltiplos volumes, para que a transportadora possa recolher e transportar os itens. Nestes caso será necessário informar no momento do faturamento a quantidade de etiquetas necessárias.
Ao atualizar um pedido para faturado (INVOICE) além da chave da NFe, é necessário informar no campo "volume_qty", o número de etiquetas que será necessário.
Uma vez que não é informado o numero, entendemos que será necessário apenas 1 etiqueta e não será possível alterar a operação ou solicitar mais etiquetas.
Será obrigatório após a emissão da etiqueta que haja a solicitação da coleta dos pedidos. Nesta solicitação é importante que seja informado quais pedidos estão aptos para serem coletados.
Atenção: Caso não haja a solicitação, a Direct não irá efetuar a coleta.
Segue a baixo o processo para que seja confirmado a coleta:
Após emitir a etiqueta, será necessário efetuar o GET dos pedidos e verificar quais estão aptos para a coleta.
GET /shipments/b2w/collectables?requested=false&offset=1
Example Request:
curl--request GET\--url 'https://api.skyhub.com.br/shipments/b2w/collectables?requested=false&offset=1' \--header 'accept: application/json'\--header 'content-type: application/json'\--header 'x-accountmanager-key: SUAXACCOUNT'\--header 'x-api-key: SuaApiKey'\--header 'x-user-email: seu@email.com'\
Request Headers:
Name | Type | Required | Description | Example |
accept | String | Required | | application/json |
Content-type | String | Required | | application/json |
x-user-email | String | Required | E-mail da loja | seu@email.com |
x-api-key | String | Required | Token da loja | SuaApiKey |
x-accountmanager-key | String | Required | Código identificador da sua Integração | XACCOUNT |
Query Parameters:
Name | Type | Required | Description | Example |
requested | String | Required | entregas que já tiveram sua coleta solicitada | true ou false |
offset | integer | opcional | paginação, inicia em 1 e hoje por padrão retorna de 20 em 20 registros. | 1 |
200 - Success:
{ "orders": [{ "code": "158258462", "customer": "Rubia", "value": 10 }, { "code": "158260587", "customer": "Rubia", "value": 10 }, { "code": "158260588", "customer": "Rubia", "value": 10 } ] }
Após verificar quais os pedidos aptos a serem coletados, o próximo passo é solicitar a coleta:
POST /shipments/b2w/confirm_collection
Example Request:
curl--request POST\--url https://api.skyhub.com.br/shipments/b2w/confirm_collection \--header 'accept: application/json'\--header 'content-type: application/json'\--header 'x-accountmanager-key: SUAXACCOUNT'\--header 'x-api-key: SuaApiKey'\--header 'x-user-email: seu@email.com'\--data '{"order_codes":["158260592"]}'
Embora não haja limitação de pedidos no array, a B2W possui uma limitação de 500 pedidos.
Request Headers:
Name | Type | Required | Description | Example |
accept | String | Required | | application/json |
Content-type | String | Required | | application/json |
x-user-email | String | Required | E-mail da loja | seu@email.com |
x-api-key | String | Required | Token da loja | SuaApiKey |
x-accountmanager-key | String | Required | Código identificador da sua Integração | XACCOUNT |
200 - Success:
{
"message": "Confirmacao para coleta realizada com sucesso."
}
Existe a duvida se é possível cancelar a coleta após ter solicitado, pois uma vez solicitado a coleta, não era mais possível efetuar nenhuma ação, apenas aguardar a coleta por parte da Direct.
Hoje é possivel cancelar a solicitação.
Para cancelar a coleta basta enviar a requisição de Desagrupar PLP. Uma vez que a PLP é desagrupada, os pedidos voltam para a relação de pedidos aptos ao agrupamento, ou seja, será necessário fazer todo o processo de agrupamento dos pedidos.