# Direct - Processos via API ## Fluxo de operação #### DISPONIBILIDADE A disponibilização da etiqueta para uma entrega **Direct** depende diretamente do **faturamento** do pedido: A partir do momento em que o pedido é **faturado**, o marketplace receberá os dados da nota fiscal, processará as informações e só então disponibilizará a etiqueta para impressão, ou seja, não é possível emitir uma etiqueta Direct antes do pedido ser faturado e o marketplace processar as informações do faturamento. #### PROCESSO Uma vez processado o faturamento do pedido, é necessário **agrupar** e **imprimir** a etiqueta disponibilizada, anexá-la ao pacote e **solicitar a coleta** pelo serviço Direct, que irá até ao local de retirada e fará uma validação (as etiquetas contam com registro de dimensões, peso, dentre outras informações importantes para a identificação), onde qualquer não conformidade resultará em recusa. ### Etiqueta/PLP na conta de teste É importante reforçar as orientações fornecidas na seção [Integração Etiqueta](https://desenvolvedores.skyhub.com.br/etiquetas-americanas-entrega/homologacao-para-impressao-de-etiquetas-americanas-entregas): Para o ambiente de teste, todo o fluxo de operações (agrupar/desagrupar, imprimir e solicitar a coleta) será realizado em pedidos **Americanas Entrega Direct** com base nas **etiquetas ****previamente disponibilizadas**, ou seja, os pedidos criados na conta de teste não terão etiquetas. {% hint style="info" %} Recomendamos que durante a homologação sempre consulte quais etiquetas estão disponíveis para as tratativas. {% endhint %} Todo o fluxo, seja para conta de teste ou na de produção, opera conforme as informações disponibilizadas a seguir: ## Etiqueta de frete via API Todo o recurso de etiquetas será tratado através da URI base vista a seguir: ``` https://api.skyhub.com.br/shipments/b2w/ ``` Os headers utilizados são aqueles padronizados na API, com diferenciação apenas para a emissão de etiquetas em PDF (cuja requisição sofrerá uma alteração no *accept*). Os headers padronizados podem ser consultados logo abaixo: #### **Request headers:** | Key | Value | | -------------------- | ------------------------------------------- | | X-User-Email | email\_de\_usuario | | X-Api-Key | token\_de\_integracao de sua conta SkyHub | | X-Accountmanager-Key | token\_account único de cada Plataforma/ERP | | Accept | application/json | | Content-Type | application/json | ## GET - Lista de pedidos aptos ao agrupamento As etiquetas disponíveis podem ser listadas, utilizando os [headers](#request-headers) padronizados na API, através de um GET para o endpoint a seguir: ``` https://api.skyhub.com.br/shipments/b2w/to_group ``` {% hint style="info" %} **A consulta listará 20 pedidos por página**. Caso a conta possua mais pedidos a serem tratados, é possível aplicar a paginação através do parâmetro ***offset*** (`/shipments/b2w/to_group?offset=1`). {% endhint %} #### Example request: ``` curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w/to_group?offset=1' \ --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' ``` #### Response esperado: {% hint style="success" %} 200 \[Success] - OK: Como resposta haverá um body contendo todos os pedidos com etiquetas aptas ao agrupamento: {% endhint %} ``` { "orders": [ { "code": "260000000002", "customer": "Bruno", "value": 68.28, "shipping": "CORREIOS", "warehouse_id": "" }, { "code": "300000000501", "customer": "Oswaldo Filho", "value": 287.16, "shipping": "BY DIRECT", "warehouse_id": "" } (...) ], "total": 19 } ``` ## POST - Agrupando pedidos em uma PLP Em posse dos pedidos aptos ao agrupamento, é possível seguir efetivamente para a ação de agrupar as etiquetas. O agrupamento é realizado através da execução de um POST, utilizando os [headers](#request-headers) padronizados na API, para o endpoint: ``` https://api.skyhub.com.br/shipments/b2w ``` #### Request body: ``` { "order_remote_codes": [ "{remote_code}", "{remote_code}", "{remote_code}" ] } ``` {% hint style="warning" %} Há um limite de **25 pedidos** que podem ser agrupados em uma PLP. {% endhint %} **Example request:** ``` curl --location --request POST 'https://api.skyhub.com.br/shipments/b2w' \ --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 '{ "order_remote_codes": [ "260000000002", "300000000501" ] }' ``` #### Response esperado: {% hint style="success" %} 201 \[Success] - Created: A requisição trará como resposta o ID da PLP gerada: {% endhint %} ``` { "message": "Packing list 185500592 agrupada com sucesso." } ``` ### Consultar PLPs agrupadas Um ID é gerado ao realizar o agrupamento de etiquetas em uma PLP (*packing list*); este código será utilizado para as demais tratativas do `/shipments/b2w`, como a emissão da etiqueta a ser indexada ao pedido e cancelamento da solicitação de coleta. É possível realizar a consulta de todas as PLPs disponíveis ao executar um GET contendo os [headers](#request-headers) padronizados na API para o endpoint: ``` https://api.skyhub.com.br/shipments/b2w ``` {% hint style="info" %} A consulta ao `/shipments/b2w` trará o ID da PLP e os pedidos inseridos em cada agrupamento. {% endhint %} #### Example request: ``` curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w' \ --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' ``` #### Response esperado: {% hint style="success" %} 200 \[Success] - OK: Como resposta haverá um body contendo todas as PLPs agrupadas: {% endhint %} ``` { "plp": [ { "id": 185500609, "expiration_date": "", "printed": false, "type": "DIRECT", "orders": [ { "code": "408000029", "customer": "Nagila Santos", "value": 163.72, "warehouse_id": "98" }, { "code": "408000037", "customer": "Denilson Melo", "value": 729.9, "warehouse_id": "98" } ] }, { "id": 185500571, "expiration_date": "", "printed": true, "type": "DIRECT", "orders": [ { "code": "260000000601", "customer": "Catia Silva", "value": 179.9, "warehouse_id": "98" } ] } ], "total": 2 } ``` ### Consultar o ID da PLP através do número do pedido Para seguir com a impressão da etiqueta também é possível buscar o ID da PLP através do número do pedido agrupado. Para tal consulta serão aplicados os [headers](#request-headers) padronizados na API e o método GET para o endpoint `/shipments/b2w`, que deverá receber o parâmetro **delivery\_id**: ``` https://api.skyhub.com.br/shipments/b2w?delivery_id={code} ``` {% hint style="info" %} O **code** visualizado no parâmetro trata-se do **código numérico do pedido** a ser consultado. {% endhint %} **Example request:** ``` curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w?delivery_id=260000000601' \ --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' ``` #### Response esperado**:** {% hint style="success" %} 200 \[Success] - OK: Como resposta haverá um body contendo as informações da PLP na qual o pedido consultado foi agrupado: {% endhint %} ``` { "plp": [ { "id": 185500571, "expiration_date": "", "printed": true, "type": "DIRECT", "orders": [ { "code": "260000000601", "customer": "Catia Silva", "value": 179.9, "warehouse_id": "98" } ] } ], "total": 1 } ``` ## GET - Imprimindo PLP {% hint style="danger" %} Apenas após realizar o agrupamento de uma PLP será possível seguir para a impressão da etiqueta. {% endhint %} A impressão da etiqueta (também chamada de "recuperação" ou emissão) é realizada ao executar um GET, utilizando os [headers](#request-headers) padronizados na API (com especificações distintas no ***accept***), para o endpoint `/shipments/b2w/view`, indicando como parâmetro a *key* **plp\_id**, que deverá receber o ID da PLP a ser impressa: ``` https://api.skyhub.com.br/shipments/b2w/view?plp_id={ID} ``` {% hint style="info" %} Para a impressão da etiqueta, o header ***accept*** poderá receber dois valores: **PDF** ou **JSON**, sendo: * Para impressão em **PDF**: Será aplicado o ***accept***: **application/pdf**; * Para impressão em **JSON**: Será aplicado o valor **application/json** para o ***accept***. {% endhint %} ### Imprimir PLP - PDF {% hint style="danger" %} **Atenção:**** *****Esta impressão sofreu alterações recentemente.***\ \ ***Agora, o retorno mostra a etiqueta impressa codificada em Base64, devendo a plataforma desenvolver uma solução para decodificá-la.*** {% endhint %} {% hint style="warning" %} **A impressão em PDF está desabilitada exclusivamente para o ****ambiente de teste****.** Em produção é possível seguir com a impressão em ambos os formatos (PDF e JSON). {% endhint %} #### Example request: ``` curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w/view?plp_id=185500592' \ --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/pdf' \ --header 'Content-Type: application/json' ``` #### Response esperado**:** {% hint style="success" %} 200 \[Success] - OK: Como resposta haverá um código Base64 com a etiqueta. {% endhint %} {% hint style="danger" %} 409 \[Error] - As etiquetas desta PLP ainda não estão disponíveis para impressão.\ \ Neste caso, é necessário trabalhar com o Retry para obter a etiqueta quando ela estiver disponível. {% endhint %} ### Imprimir PLP - JSON Para imprimir a etiqueta na impressora térmica, será necessário baixar o arquivo JSON utilizando o parâmetro: **Accept: application/json**. Através dele será retornado o JSON da etiqueta e deverá ser montado o [layout para a impressão](https://desenvolvedores.skyhub.com.br/etiquetas-americanas-entrega/etiqueta-de-frete-direct/padrao-da-etiqueta-direct). #### Example request: ``` curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w/view?plp_id=185500592' \ --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' ``` **Response esperado:** {% hint style="success" %} 200 \[Success] - OK: Como resposta haverá o JSON da PLP cujo ID foi selecionado, conforme visualizado a seguir: {% endhint %} {% hint style="danger" %} 409 \[Error] - As etiquetas desta PLP ainda não estão disponíveis para impressão.\ \ Neste caso, é necessário trabalhar com o Retry para obter a etiqueta quando ela estiver disponível. {% endhint %} ``` { "plp": { "id": XXXXXXXXX, // ID da PLP "codExterno": "XXXXXXXXX", // Número da PLP - Informação 8 do Layout da Etiqueta "dtEnvio": "25/10/2021 15:26:04", // Data e Hora da emissão da etiqueta "tpAgrupamento": "DIRECT", // "PLP" = Correios - "DIRECT" = Direct "resumoServicos": [ { "codServico": "", // Código do Serviço (Vazio para Direct) "nomeServico": "", // Nome do Serviço (Vazio para Direct) "quantidadeAwbs": 1 // Quantidade de Etiquetas } ] }, "docsExternos": [ { "codCliente": XXXXXXXXXXX, // Código do Cliente "docExterno": "XXXXXXXXXXXX", // Número do Pedido - Informação 7 do Layout da Etiqueta "dtPrometida": "XXXXXX", // Data Prometida - Dia(XX) Mês(XX) Ano(XX) "dtLimiteExpedicao": "XXXXXX", // Data Limite Expedição - Dia(XX) Mês(XX) Ano(XX) "dtLimiteExpedicaoCompleta": "XXXXXX", // Data Limite Expedição - Dia(XX) Mês(XX) Ano(XX) "tpEntrega": "Normal", // Tipo de Entrega "pesoTotal": 0.315, // Peso da Embalagem "marca": "ACOM", // Marca da Venda - ACOM/SUBA/SHOP - Informação 1 do Layout da Etiqueta "qtVolumes": 1, // Quantidade de Volumes - Informação 4 do Layout da Etiqueta "numeroContratoTransp": "XXXXXXXXXX", // Número Contrato Transportadora - (Vazio para Direct) "nomeEmbarcador": "CD CENTRO DE DISTRIBUIÇÃO_1", // Centro de Distribuição "telefoneEmbarcador": XXXXXXXX, // Telefone CD "emailEmbarcador": "", // E-mail CD "tpServico": "EXPRESA", // Tipo de Serviço - "EXPRESSA" para pedidos Direct - Informação 3 do Layout da Etiqueta "numNotaFiscal": "", // Número da Nota Fiscal - Informação 6 do Layout da Etiqueta "serieNotaFiscal": "", // Série da Nota Fiscal "megaRota": "", // Informação 15 do Layout da Etiqueta "rota": "", // Informação 14 do Layout da Etiqueta "telefoneContato": "(XX)XXXXXXXX", // Telefone de Contato "vlEntrega": 50.39, // Valor Total Declarado "cartaoPostagem": "XXXXXXXXXX", // Cartão Postagem "servicoAdicional": "XXXXXXXX", // Serviço Adicional "pedInLoja": "N", // Pega na Loja "tpLoja": "", // Tipo da Loja "coletaPudo": "N", "destinatario": { // Informação 12 do Layout da Etiqueta "nome": "José Francisco Silva", // Nome Destinatário "enderecoLogradouro": "Avenida Avenida", // Logradouro "enderecoNumero": "1111", // Número da Residência "enderecoComplemento": "Casa 3 - Condominio Privê", // Complemento "enderecoBairro": "Novo Bairro", // Bairro "enderecoReferencia": "", // Referência "enderecoCidade": "São Paulo", // Cidade "enderecoUf": "SP", // Estado "enderecoCep": "00000000" // CEP }, "remetente": { // Informação 14 do Layout da Etiqueta "nome": "Loja Brasil", // Nome Remetente "enderecoLogradouro": "Rua Rua", // Logradouro "enderecoNumero": "2222", // Número do Remetente "enderecoComplemento": "Loja 06", // Complemento "enderecoBairro": "Centro", // Bairro "enderecoCidade": "Rio de Janeiro", // Cidade "enderecoUf": "RJ", // Estado "enderecoCep": "00000000", // CEP "enderecoReferencia": "" // Referência }, "awbs": [ { "codigoAwb": "XXXXXXXXXXXBR", // Código de Rastreamento - Informação 9 do Layout da Etiqueta "posicaoVolume": 1, "itens": [ { "descricao": "Bone Aba Curva", // Descrição do Item "quantidade": 1, // Quantidade "peso": 0.315 // Peso } ] } ] } ] } ``` {% hint style="danger" %} Importante atentar-se que os campos disponibilizados no *json* seguem o padrão dos Correios e não devem ser realizadas alterações nos valores preenchidos pelo marketplace. Por exemplo, no campo CEP, para geração do código de barras não devem ser adicionados espaços ou pontuações; assim como é preciso validar a quantidade de caracteres, que não deve exceder 8 dígitos numéricos (sem contar o hífen). Caso necessário, sugerimos que seja validado o [**Guia de Endereçamento dos Correios**](https://www.correios.com.br/enviar/encomendas/arquivo/nacional/guia-de-enderecamento.pdf) para a correta montagem das etiquetas. {% endhint %} ## Solicitação de coleta Para um pedido emitido via Direct é obrigatória a solicitação de coleta após a emissão da etiqueta. {% hint style="danger" %} Caso não haja a solicitação, a Direct não irá efetuar a coleta do pedido. {% endhint %} ### GET - Aptos à coleta É possível consultar quais pedidos estão aptos para a coleta, isto é, através da API é possível listar os pedidos que tiveram suas etiquetas agrupadas e impressas. Esta ação é realizada através de um GET - utilizando os [headers](#request-headers) padronizados na API e visualizados no início deste guia - para o endpoint abaixo, onde o parâmetro *requested* é obrigatório: ``` https://api.skyhub.com.br/shipments/b2w/collectables?requested=false ``` {% hint style="info" %} **Por padrão, utiliza-se o parâmetro *****requested = false***** para listagem das entregas que ainda não tiveram sua coleta solicitada.** Os valores para o parâmetro são *true* ou *false*. {% endhint %} #### **Example request:** ``` curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w/collectables?requested=false' \ --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' ``` {% hint style="info" %} Para a listagem de pedidos aptos à coleta também é possível realizar a paginação dos resultados através do parâmetro ***offset*** (`/shipments/b2w/collectables?requested=false&offset=1`). {% endhint %} #### Response esperado: {% hint style="success" %} 200 \[Success] - OK: Como resposta haverá um body contendo todos os pedidos aptos à solicitação de coleta: {% endhint %} ``` { "orders": [ { "code": "408000037", "customer": "Denilson Melo", "value": 729.9, "warehouse_id": "98" }, { "code": "408100094", "customer": "Gabriele Souza", "value": 379.9, "warehouse_id": "98" }, { "code": "260000000601", "customer": "Catia Silva", "value": 179.9, "warehouse_id": "98" }, { "code": "408000029", "customer": "Nagila Santos", "value": 163.72, "warehouse_id": "98" } ], "total": 4 } ``` ### **POST - Solicitando a coleta** {% hint style="danger" %} **Atenção:**** *****Endpoint***** descontinuado.** {% endhint %} Após verificar quais pedidos estão aptos a serem coletados, o próximo passo é efetivamente seguir para a solicitação da coleta, ação executada ao aplicar os [headers](#request-headers) padronizados na API e o método POST para o endpoint: ``` https://api.skyhub.com.br/shipments/b2w/confirm_collection ``` #### Request body: ``` { "order_codes": [ "{order_code}" ] } ``` {% hint style="info" %} O ***order\_code*** corresponde ao **código numérico do pedido**, visualizado na consulta de pedidos [aptos à coleta](#get-aptos-a-coleta). {% endhint %} #### **Example request:** ``` curl --location --request POST 'https://api.skyhub.com.br/shipments/b2w/confirm_collection' \ --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 '{ "order_codes": [ "408000037" ] }' ``` {% hint style="warning" %} Embora não haja limitação de pedidos para o *array **order\_codes***, o marketplace Americanas estabeleceu um limite de 500 entregas para esta ação. {% endhint %} #### **Response esperado:** {% hint style="success" %} 201 \[Success] - Created: O retorno trará a mensagem de confirmação da coleta: {% endhint %} ``` { "message": "Confirmacao para coleta realizada com sucesso." } ``` ## Cancelar o processo de coleta Para cancelar a solicitação de uma coleta basta enviar a requisição responsável por **desagrupar a PLP**. Uma vez que a PLP é desagrupada, os pedidos voltam para a relação de aptos ao agrupamento, ficando disponíveis novamente para a execução de todas as ações relacionadas às etiquetas. ### DELETE - Desagrupando PLP {% hint style="danger" %} **Atenção:**** *****Endpoint***** descontinuado.** {% endhint %} A ação de desagrupar pode ser realizada tanto para toda a PLP quanto para um pedido em específico. Em ambos os cenários, serão utilizados os [headers](#request-headers) padronizados na API para executar um DELETE no endpoint base: ``` https://api.skyhub.com.br/shipments/b2w/ ``` #### Desagrupar toda a PLP {% hint style="info" %} **Ao desagrupar toda a PLP, todos os pedidos do agrupamento serão disponibilizados novamente para as tratativas referentes às etiquetas.** Por exemplo: Todo agrupamento gera um ID. Num cenário em que três (3) pedidos são agrupados e é executado o DELETE no ID gerado, estes 3 pedidos ficarão disponíveis para que sejam agrupados novamente. {% endhint %} Para desagrupar toda a PLP basta executar um DELETE para o endpoint referenciado acima e reforçado logo a seguir, acrescentando como parâmetro o "plp\_id": ``` https://api.skyhub.com.br/shipments/b2w?plp_id={id_da_plp} ``` #### **Example request:** ``` curl --location --request DELETE 'https://api.skyhub.com.br/shipments/b2w?plp_id=185500609' \ --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' \ ``` #### Response esperado**:** {% hint style="success" %} 200 \[Success] - OK: O retorno trará a mensagem de confirmação de que a PLP foi desagrupada: {% endhint %} ``` { "message": "Plp 185500609 desagrupada com sucesso." } ``` #### Desagrupar um pedido da PLP {% hint style="danger" %} **Atenção:**** *****Endpoint***** descontinuado.** {% endhint %} {% hint style="info" %} **É possível desagrupar um único pedido de uma PLP, sem a necessidade de excluir todo o agrupamento prévio.** {% endhint %} Quando se opta por agrupar mais de um pedido em uma mesma PLP e há a necessidade de desagrupar apenas uma entrega deve ser realizado o DELETE para o endpoint base `/shipments/b2w/`, **incluindo o código numérico do pedido**: ``` https://api.skyhub.com.br/shipments/b2w/{delivery_id} ``` #### **Example request:** ``` curl --location --request DELETE 'https://api.skyhub.com.br/shipments/b2w/408000655' \ --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' ``` {% hint style="info" %} O parâmetro **delivery\_id** refere o **código numérico do pedido** a ser removido da PLP previamente agrupada. {% endhint %} #### Response esperado**:** {% hint style="success" %} 200 \[Success] - OK: O retorno trará a mensagem de confirmação de que o pedido selecionado foi desagrupado da PLP: {% endhint %} ``` { "message": "O Documento externo (408000655) foi desagrupado da PLP (185500022) com sucesso." } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://desenvolvedores.skyhub.com.br/etiquetas-americanas-entrega/etiqueta-de-frete-direct/etiqueta-direct-via-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.