# 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." } ```