> For the complete documentation index, see [llms.txt](https://desenvolvedores.skyhub.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://desenvolvedores.skyhub.com.br/etiquetas-americanas-entrega/integracao-etiqueta.md). # > Integração Etiqueta {% hint style="danger" %} **Todo recurso desenvolvido deve ser** [**homologado**](https://desenvolvedores.skyhub.com.br/processo-de-homologacao) **pelo time responsável pela API da Americanas.** {% endhint %} ## 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](/etiquetas-americanas-entrega/etiqueta-de-frete-direct.md#agrupar-pedidos-em-uma-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](/etiquetas-americanas-entrega/etiqueta-de-frete-direct.md#imprimir-plp-pdf): 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](/etiquetas-americanas-entrega/etiqueta-de-frete-direct.md#solicitar-coleta): 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](/etiquetas-americanas-entrega/etiqueta-de-frete-direct.md#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 {% hint style="warning" %} 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**. {% endhint %} #### 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](/produtos/criacao-de-produto.md). 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](https://desenvolvedores.skyhub.com.br/etiquetas-americanas-entrega/etiqueta-de-frete-direct#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,
            "shipping": "BY DIRECT",
            "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
}
{% hint style="success" %} 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. {% endhint %} {% hint style="info" %} 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. {% endhint %} #### 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](https://desenvolvedores.skyhub.com.br/pedidos/criacao-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](#2o-consulta-das-etiquetas-disponiveis). 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",
        "remote_code": "270000000201",
        "items": [
            {
                "id": "2023001",
                "qty": 1,
                "original_price": 39.90,
                "special_price": 39.90
            }
        ],
        "customer": {
            "name": "João dos Santos",
            "email": "comprador@exemplo.com.br",
            "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
    }
}'
{% hint style="info" %} **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. {% endhint %} 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: {% content-ref url="/pages/-LXzMzHo16GXCIhJMjx7" %} [Etiqueta de Frete - Direct](/etiquetas-americanas-entrega/etiqueta-de-frete-direct.md) {% endcontent-ref %} {% content-ref url="/pages/-LXyvcysWixNHuY34IVN" %} [Etiqueta de Frete - Correios](/etiquetas-americanas-entrega/etiqueta-de-frete-correios.md) {% endcontent-ref %} [^1]: Etiquetas com o **shipping** ***By Direct*** poderão ser utilizadas para testes de homologação da plataforma/ERP [^2]: Campo inserido e preenchido com o **code** de uma das etiquetas listadas na consulta ao endpoint /shipments/b2w/to\_group.