> Integração Etiqueta
Nesta seção mostraremos a trilha para realização da integração do recurso de PLP, desde a emissão da etiqueta até a solicitação de coleta de pedidos Americanas Entrega Direct
Todo recurso desenvolvido deve ser homologado pelo time responsável pela API da Americanas.
Passos para integração de etiquetas
Os passos para a integração de etiquetas são:
Compreensão sobre a diferença entre um pedido gerado através do serviço Americanas Entrega Correio e um Direct;
Agrupar/desagrupar uma PLP;
Imprimir uma PLP previamente agrupada;
Confirmar a coleta de um pedido pertencente ao serviço Americanas Entrega Direct.
O que será validado durante o processo de homologação?
Durante o processo de homologação serão validados os aspectos citados acima, que englobam o fluxo de etiquetas para o serviço Americanas Entrega Direct:
Agrupar PLP: O ambiente de teste disponibilizado para a homologação de um sistema conta com etiquetas pré-definidas que deverão ser agrupadas para a validação desta ação, obrigatória para a impressão da etiqueta;
Imprimir etiqueta de pedido: Para a homologação, será validada a emissão da etiqueta. Em ambiente de teste, a impressão limita-se ao formato JSON; em ambiente de produção é possível recuperar (imprimir) a etiqueta nos formatos JSON e PDF;
Solicitar a coleta de um pedido gerado para o serviço Direct: Um passo obrigatório para pedidos Direct é a solicitação de coleta. Para a homologação, será validada a capacidade do sistema/plataforma/ERP de confirmar a coleta de pedidos;
Desagrupar PLP: O ato de desagrupar a PLP é essencial para, principalmente, cancelar a solicitação de coleta já executada. Para a homologação, é necessário que o sistema seja capaz de executar esta ação.
Etiquetas na conta de teste
Os pedidos criados em ambiente de teste não possuirão etiquetas.
Para a execução de requisições referentes ao recurso de PLP e homologação de um sistema serão utilizadas as etiquetas previamente disponibilizadas nas contas de teste.
Como emitir etiquetas a partir de pedidos criados em uma conta de teste?
Como mencionado acima, as etiquetas a serem tratadas são disponibilizadas previamente no ambiente de teste, não sendo possível emitir novas etiquetas a partir de pedidos gerados diretamente através do POST no endpoint /orders.
Neste caso, para que todo o fluxo do marketplace seja seguido - desde o cadastro do produto até a criação do pedido e emissão da etiqueta - é possível gerar um pedido e realizar o seu vínculo com uma etiqueta disponibilizada previamente, processo detalhado logo abaixo:
1º - Cadastro de produto
Caso ainda não hajam produtos na conta de teste é possível realizar o cadastro seguindo as orientações da seção Criação de Produto.
Neste ponto, é imprescindível que o produto criado contenha estoque e status ativo (enabled), conforme exemplo:
curl --location --request POST 'https://api.skyhub.com.br/products' \
--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' \
--data '{
"product": {
"sku": "2023001",
"name": "Camiseta Branca Tam. Único",
"description": "Produto Simples para Exemplificar a Criação de Pedidos",
"status": "enabled",
"qty": 100,
"price": 39.90,
"promotional_price": 39.90,
(...)
}
}'2º - Consulta das etiquetas disponíveis
É necessário consultar a lista de etiquetas disponíveis na conta de teste para criar pedidos com os mesmos códigos. A consulta das etiquetas disponíveis pode ser visualizada a seguir de forma resumida e está detalhada em nossa seção Como obter a minha etiqueta de frete na API SkyHub.
curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w/to_group' \
--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'Ao realizar a listagem das etiquetas disponíveis para agrupamento é importante atentar-se ao campo shipping, pois deverão ser utilizadas apenas as entregas preenchidas como "By Direct", conforme exemplo:
{
"orders": [
(...)
{
"code": "4000000007",
"customer": "João dos Santos",
"value": 52.45,
"shipping": "CORREIOS",
"warehouse_id": ""
},
{
"code": "270000000201",
"customer": "José da Silva",
"value": 167.05,
,
"warehouse_id": ""
},
{
"code": "350000000601",
"customer": "Maria Pereira",
"value": 287.16,
"shipping": "BY DIRECT",
"warehouse_id": ""
},
{
"code": "400000064",
"customer": "Catia Alves",
"value": 179.9,
"shipping": "BY DIRECT",
"warehouse_id": "98"
}
],
"total": 20
}O campo code retornado é o código numérico do pedido. Este valor será utilizado para a realização do vínculo entre o pedido criado no ambiente de teste e a etiqueta previamente disponibilizada.
3º - Criação do pedido vinculado a uma etiqueta disponível
A criação do pedido seguirá o padrão detalhado em nossa seção Criação e Aprovação de Pedido Teste, porém deverá contar com as seguintes especificações:
O campo shipping_calculation_type do pedido, responsável por determinar o método do cálculo de frete, deverá conter o valor b2wentregadirect;
Obrigatoriamente deverá ser incluso no body da requisição o campo remote_code para definição do código do pedido. O código a ser utilizado é o code visualizado na listagem das etiquetas disponíveis.
A seguir temos um exemplo prático da criação do pedido gerado para o serviço Americanas Entrega Direct onde houve a inclusão do código da etiqueta disponível em ambiente de teste:
curl --location --request POST 'https://api.skyhub.com.br/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' \
--data-raw '{
"order": {
"channel": "Lojas Americanas",
,
"items": [
{
"id": "2023001",
"qty": 1,
"original_price": 39.90,
"special_price": 39.90
}
],
"customer": {
"name": "João dos Santos",
"email": "[email protected]",
"date_of_birth": "1989-01-01",
"gender": "male",
"vat_number": "23455567899",
"phones": [
"11 99999-9999"
]
},
"billing_address": {
"street": "Avenida Paulista",
"number": "1234",
"detail": "Próximo ao museu",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"region": "SP",
"country": "BR",
"postcode": "90000000"
},
"shipping_address": {
"street": "Avenida Paulista",
"number": "1000",
"detail": "Ao lado da cafeteria",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"region": "SP",
"country": "BR",
"postcode": "90000000"
},
"payments": [
{
"method": "CREDIT_CARD",
"description": "SkyHub",
"parcels": 1,
"value": 39.90
}
],
"shipping_method": "Courier",
"estimated_delivery": "2023-04-30",
"shipping_calculation_type": "b2wentregadirect",
"shipping_cost": 0,
"interest": 0,
"discount": 0
}
}'Com os produtos e pedidos criados na conta teste é possível seguir com o fluxo da PLP, que consiste em efetuar as requisições para agrupar, imprimir e desagrupar etiquetas conforme orientações disponíveis nas guias abaixo:
Etiqueta de Frete - DirectEtiqueta de Frete - CorreiosLast updated