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:
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:
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:
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:
Response esperado:
200 [Success] - OK: Como resposta haverá um body contendo todos os pedidos com etiquetas aptas ao agrupamento:
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:
Request body:
Há um limite de 25 pedidos que podem ser agrupados em uma PLP.
Example request:
Response esperado:
201 [Success] - Created: A requisição trará como resposta o ID da PLP gerada:
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:
A consulta ao /shipments/b2w
trará o ID da PLP e os pedidos inseridos em cada agrupamento.
Example request:
Response esperado:
200 [Success] - OK: Como resposta haverá um body contendo todas as PLPs agrupadas:
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:
O code visualizado no parâmetro trata-se do código numérico do pedido a ser consultado.
Example request:
Response esperado:
200 [Success] - OK: Como resposta haverá um body contendo as informações da PLP na qual o pedido consultado foi agrupado:
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:
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:
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:
Response esperado:
200 [Success] - OK: Como resposta haverá o JSON da PLP cujo ID foi selecionado, conforme visualizado a seguir:
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:
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:
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:
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:
Request body:
O order_code corresponde ao código numérico do pedido, visualizado na consulta de pedidos aptos à coleta.
Example request:
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:
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:
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":
Example request:
Response esperado:
200 [Success] - OK: O retorno trará a mensagem de confirmação de que a PLP foi desagrupada:
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:
Example request:
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:
Last updated