Correios - 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 Correios
Fluxo de operação
DISPONIBILIDADE
A disponibilização da etiqueta para uma entrega Americanas Correios depende diretamente da aprovação do pedido: A partir do momento em que o pedido é aprovado o marketplace irá disponibilizar a etiqueta para impressão.
Atenção! Apesar da etiqueta ser disponibilizada assim que o pedido é aprovado, o fluxo correto do pedido não deve ser ignorado, sendo imprescindível o faturamento do mesmo antes do seu envio.
PROCESSO
Após aprovação e faturamento do pedido, é necessário agrupar, imprimir a etiqueta disponibilizada e anexá-la ao pacote que será levado à agência dos Correios, que 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 pontuar que nas contas de teste não é possível simular os processos com etiquetas relacionadas ao serviço Americanas Entrega Correios. Para a homologação de um sistema, todo o fluxo de operação será validado pelos processos relacionados ao serviço Americanas Entrega Direct.
Em ambiente de produção todo o fluxo para o serviço Americanas Entrega Correios 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:
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_groupExample 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/b2wRequest 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 185500593 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 realizar a emissão da etiqueta a ser indexada ao pedido.
É 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/b2wExample 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}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}Imprimir PLP - PDF
Atenção: Endpoint descontinuado. Apenas para o formato PDF
Importante ressaltar que o fluxo para etiquetas Correios não é habilitado para o ambiente de teste.
Em produção a impressão da etiqueta pode ser feita para os formatos (PDF e JSON), conforme orientações a seguir:
Example request:
curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w/view?plp_id=185500593' \
--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.
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.
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 você receberá o JSON da etiqueta e deverá montar o layout para a impressão.
Example request:
curl --location --request GET 'https://api.skyhub.com.br/shipments/b2w/view?plp_id=185500593' \
--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:
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.
{
"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": "PLP", // "PLP" = Correios - "DIRECT" = Direct
"resumoServicos": [
{
"codServico": "XXXXX", // Código do Serviço
"nomeServico": "PAC CONTRATO AG", // Nome do Serviço - "PAC CONTRATO AG"/"SEDEX CONTRATO AG"
"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 - Informação 5 do Layout da Etiqueta
"nomeEmbarcador": "-- -------", // Centro de Distribuição
"telefoneEmbarcador": XXXXXXXX, // Telefone CD
"emailEmbarcador": "", // E-mail CD
"tpServico": "NORMAL", // Tipo de Serviço - "NORMAL" para PAC/"EXPRESSA" para SEDEX - 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 pertinente somente a pedidos DIRECT
"rota": "", // Informação pertinente somente a pedidos DIRECT
"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
}
]
}
]
}
]
}DELETE - Desagrupando PLP
Atenção: Endpoint descontinuado.
Em casos em que o seller agrupa erroneamente um pedido a uma PLP - como, por exemplo, em situações em que um pedido ainda não faturado foi agrupado a entregas já faturadas - é possível reverter esta ação ao efetuar o desagrupamento.
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.
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
Para desagrupar toda a PLP basta executar um DELETE para o endpoint referenciado acima e ressaltado logo a seguir:
https://api.skyhub.com.br/shipments/b2w/Request body:
{
"plp_id": "{id}"
}Example request:
curl --location --request DELETE '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 '{
"plp_id": "185500715"
}'Response esperado:
200 [Success] - OK: O retorno trará a mensagem de confirmação de que a PLP foi desagrupada:
{
"message": "Plp 185500715 desagrupada com sucesso."
}Desagrupar um pedido da PLP
Atenção: Endpoint descontinuado.
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'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 (260000000002) foi desagrupado da PLP (185500567) com sucesso."
}Last updated