> 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:

1. Compreensão sobre a diferença entre um pedido gerado através do serviço Americanas Entrega Correio e um Direct;

2. Agrupar/desagrupar uma PLP;

3. Imprimir uma PLP previamente agrupada;

4. 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.

Posso utilizar as etiquetas com o campo shipping preenchido como "Correios"?

Não existem impeditivos para a utilização das etiquetas Correios no ambiente de teste, porém é extremamente importante estar ciente de que há ações - como a solicitação de coleta - que são possíveis apenas para o serviço Direct.

Ao utilizar uma etiqueta Correios para execução do fluxo de um pedido Direct, será retornado erro.

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": "[e-mail]",
            "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
    }
}'

A API atua como um proxy para o serviço de etiquetas do marketplace.

Uma vez que a API não é detentora dos dados fornecidos pelo marketplace, as informações que constam nas etiquetas não serão alteradas e a ação descrita acima é capaz apenas de vincular um pedido a uma etiqueta já disponibilizada no ambiente de teste.

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 - Direct

Etiqueta de Frete - Correios