SkyHub PortalApi Explorer

Direct - Processos via API

Esta seção consiste em fornecer orientações para as ações a serem realizadas via API para a tratativa de etiquetas emitidas para pedidos Americanas Entrega Direct

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

Recomendamos que durante a homologação sempre consulte quais etiquetas estão disponíveis para as tratativas.

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:

KeyValue

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 padronizados na API, através de um GET para o endpoint a seguir: 

https://api.skyhub.com.br/shipments/b2w/to_group

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

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:

200 [Success] - OK: Como resposta haverá um body contendo todos os pedidos com etiquetas aptas ao agrupamento:

{
    "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 padronizados na API, para o endpoint:

https://api.skyhub.com.br/shipments/b2w

Request body:

{
    "order_remote_codes": [
        "{remote_code}",
        "{remote_code}",
        "{remote_code}"
    ]
}

Há um limite de 25 pedidos que podem ser agrupados em uma PLP.

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:

201 [Success] - Created: A requisição trará como resposta o ID da PLP gerada:

{
    "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 padronizados na API para o endpoint:

https://api.skyhub.com.br/shipments/b2w

A consulta ao /shipments/b2w trará o ID da PLP e os pedidos inseridos em cada agrupamento.

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:

200 [Success] - OK: Como resposta haverá um body contendo todas as PLPs agrupadas:

{
    "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 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}

O code visualizado no parâmetro trata-se do código numérico do pedido a ser consultado.

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:

200 [Success] - OK: Como resposta haverá um body contendo as informações da PLP na qual o pedido consultado foi agrupado:

{
    "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

Apenas após realizar o agrupamento de uma PLP será possível seguir para a impressão da etiqueta.

A impressão da etiqueta (também chamada de "recuperação" ou emissão) é realizada ao executar um GET, utilizando os 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}

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.

Imprimir PLP - PDF

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

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:

200 [Success] - OK: Como resposta haverá o PDF da PLP cujo ID foi selecionado.

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.

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:

200 [Success] - OK: Como resposta haverá o JSON da PLP cujo ID foi selecionado, conforme visualizado a seguir:

{
  "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
            }
          ]
        }
      ]
    }
  ]
}

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 para a correta montagem das etiquetas.

Como emitir múltiplas etiquetas?

Existem situações em que o seller precisa separar a entrega em múltiplos volumes para que a transportadora possa encaminhar o pedido ao destinatário. Neste caso, será necessário informar no momento do faturamento a quantidade de etiquetas necessárias para aquela entrega.

Ao atualizar o pedido para faturado (INVOICED) é possível incluir no campo volume_qty o número de etiquetas necessárias.

Uma vez que não for informada a quantidade de etiquetas, será assumido o valor 1 e não será possível alterar a operação ou solicitar mais etiquetas.

Caso necessário consultar informações sobre o faturamento de pedidos, acesse a guia Atualização de Pedidos.

Solicitação de coleta

Para um pedido emitido via Direct é obrigatória a solicitação de coleta após a emissão da etiqueta.

Caso não haja a solicitação, a Direct não irá efetuar a coleta do pedido.

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

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.

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'

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

Response esperado:

200 [Success] - OK: Como resposta haverá um body contendo todos os pedidos aptos à solicitação de coleta:

{
    "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

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 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}"
    ]
}

O order_code corresponde ao código numérico do pedido, visualizado na consulta de pedidos aptos à coleta.

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"
    ]
}'

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.

Response esperado:

201 [Success] - Created: O retorno trará a mensagem de confirmação da coleta:

{
    "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

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 padronizados na API para executar um DELETE no endpoint base:

https://api.skyhub.com.br/shipments/b2w/

Desagrupar toda a PLP

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.

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:

200 [Success] - OK: O retorno trará a mensagem de confirmação de que a PLP foi desagrupada:

{
    "message": "Plp 185500609 desagrupada com sucesso."
}

Desagrupar um pedido da PLP

É possível desagrupar um único pedido de uma PLP, sem a necessidade de excluir todo o agrupamento prévio.

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'

O parâmetro delivery_id refere o código numérico do pedido a ser removido da PLP previamente agrupada.

Response esperado:

200 [Success] - OK: O retorno trará a mensagem de confirmação de que o pedido selecionado foi desagrupado da PLP:

{
    "message": "O Documento externo (408000655) foi desagrupado da PLP (185500022) com sucesso."
}
PreviousPadrão da Etiqueta DirectNextEtiqueta Clique e Retire - Direct

Last updated