Agendamento
Este documento descreve o serviço de agendamento de estoque, o qual permite ao vendedor (seller) agendar o envio de seus produtos para os centros de distribuição da Magalu.
Os canais de venda são as plataformas de e-commerce que ofertam e realizam as vendas dos produtos como o Magalu, Netshoes e outros.
Atualmente estará disponível apenas o canal de vendas Magalu - Magazine Luiza. No futuro novos canais de venda poderão ser adicionados.
É necessário o consentimento dos usuários, para isso implemente o processo de autenticação e autorização.
Se você não possui integração com as APIs antigas, basta seguir o processo de solicitação de criação de aplicação.
Escopos necessários
Para a utilização das APIs os seguintes escopos poderão ser necessários:
| Valor | Descrição |
|---|---|
open:logistic-stock-scheduling-seller:read | Permite leitura das informações de agendamento de estoque do seller. |
open:logistic-stock-scheduling-seller:write | Permite realizar operações de logística. |
📄️ Buscar agendamentos
Este endpoint permite a busca paginada e filtrada de agendamentos existentes. O seller pode utilizar query parameters como limit, offset, status e um intervalo de datas (date_start e date_end) para refinar a busca. A finalidade é permitir que o seller monitore e rastreie o status e o histórico de todos os seus agendamentos. Esta operação requer a permissão de leitura (stock-scheduling-seller:read). Em caso de sucesso, retorna o status 200 OK com a lista de agendamentos.
📄️ Criar agendamentos
Este endpoint permite ao seller criar um novo agendamento de entrega de estoque no Centro de Distribuição (CD). O payload deve incluir o identificador do usuário responsável pela criação (created_by) e, opcionalmente, a flag generate_suggested_products nas opções. Quando generate_suggested_products é true, o sistema retorna sugestões de produtos para o agendamento. A API valida as informações do seller antes da criação. Após o sucesso, retorna um novo agendamento com status PENDING e código de resposta 201 Created. Esta operação requer a permissão de escrita (stock-scheduling-seller:write).
📄️ Consulta um agendamento específico pelo ID
Este endpoint permite ao seller recuperar os detalhes completos de um agendamento de entrega de estoque específico usando seu identificador (id). A rota retorna informações como o status atual (PENDING, FINALIZED, CANCELED), a data agendada, o tipo de entrega (DELIVERY, PICKUP, COLLECT) e os itens listados para envio. Esta operação requer a permissão de leitura (stock-scheduling-seller:read). Em caso de sucesso, retorna o status 200 OK com os dados do agendamento.
📄️ Deleta um agendamento existente
Este endpoint permite ao seller excluir permanentemente um agendamento de envio de estoque existente. A funcionalidade é utilizada para remover processos logísticos que não serão mais realizados, eliminando o registro da base de dados. Para a execução, é obrigatório fornecer o identificador do agendamento (id) na URL. Esta operação requer a permissão de escrita (stock-scheduling-seller:write). Em caso de sucesso, retorna o status 204 No Content.
📄️ Gerar etiquetas para um agendamento específico
Este endpoint permite ao seller gerar as etiquetas necessárias para o agendamento. A etiqueta é essencial para a operação logística do Centro de Distribuição (CD), pois contém o código de barras e informações de identificação dos volumes. O endpoint requer o identificador do agendamento (id) e aceita o formato desejado (pdf para impressão A4 ou thermal para impressoras térmicas) no payload. Esta operação requer a permissão de escrita (stock-scheduling-seller:write).Em caso de sucesso, retorna o status 200 OK com o arquivo binário da etiqueta, que deve ser impresso e anexado aos volumes antes da coleta ou envio.
📄️ Excluir um produto de um agendamento
Este endpoint permite ao seller remover um item específico (identificado pelo SKU) de um agendamento que ainda está em processo. A finalidade é permitir ajustes finos no conteúdo da remessa antes do envio ou coleta. Esta operação requer a permissão de escrita (stock-scheduling-seller:write). A rota requer o identificador do agendamento (id) e o SKU do item a ser removido nos path parameters. Em caso de sucesso, retorna o status 204 No Content.
📄️ Atualizar a data de um agendamento específico
Este endpoint permite ao seller atualizar a data agendada de um envio de estoque para o Centro de Distribuição (CD). A funcionalidade é essencial quando há necessidade de remarcar a entrega ou coleta devido a imprevistos logísticos ou operacionais. A rota requer o identificador do agendamento (id) como parâmetro de caminho e a nova data no corpo da requisição. Esta operação requer a permissão de escrita (stock-scheduling-seller:write). Em caso de sucesso, retorna o status 200 OK com os dados completos do agendamento atualizado.
📄️ Atualiza o volume de um agendamento existente
Este endpoint permite ao seller atualizar informações de volume e peso para um agendamento específico, identificado pelo seu id. A funcionalidade é essencial para a operação logística, pois garante que o Centro de Distribuição (CD) ou a transportadora tenha os dados corretos sobre as dimensões e o peso da remessa a ser recebida ou coletada. Esta operação requer a permissão de escrita (stock-scheduling-seller:write). Em caso de sucesso, retorna o status 200 OK com os dados atualizados do agendamento.
📄️ Inclui ou atualiza itens em um agendamento específico
Este endpoint permite ao seller atualizar (upsert) os itens incluídos em um agendamento de estoque já criado, usando o ID do agendamento como referência. A funcionalidade permite ajustes na lista de produtos a serem coletados ou enviados para o Centro de Distribuição (CD), incluindo a possibilidade de adicionar novos SKUs ou modificar a quantidade de itens já existentes. Esta operação requer a permissão de escrita (stock-scheduling-seller:write). Em caso de sucesso, retorna o status 200 OK com o objeto do agendamento contendo os itens atualizados.
📄️ Cancela um agendamento específico
Este endpoint permite ao seller cancelar um agendamento de entrega de estoque previamente criado, informando o motivo do cancelamento. O agendamento é o processo pelo qual o seller gerencia a entrada de seus produtos no Centro de Distribuição (CD). Uma vez cancelado, o agendamento reflete o novo status no sistema, permitindo a gestão adequada do fluxo logístico. Esta operação requer a permissão de escrita (stock-scheduling-seller:write) e o identificador do agendamento na URL, além do motivo do cancelamento no corpo da requisição. Em caso de sucesso, retorna o status 204 No Content.
📄️ Busca as datas disponíveis para um agendamento específico por ID e tipo de entrega
Este endpoint permite consultar as datas e slots de horários disponíveis para agendamento. O seller precisa fornecer o identificador do agendamento (id) e especificar o tipo de entrega desejado (DELIVERY, PICKUP ou COLLECT) como parâmetros de caminho. A finalidade é garantir que a logística tenha capacidade de receber ou coletar o estoque na data escolhida, evitando gargalos operacionais. Esta operação requer a permissão de leitura (stock-scheduling-seller:read). Em caso de sucesso, retorna o status 200 OK com as datas disponíveis.
📄️ Confirma um agendamento específico
Este endpoint permite ao seller marcar um agendamento de entrega de estoque como finalizado, concluindo o fluxo de planejamento logístico. Ao chamar esta rota, o seller indica que todas as etapas de preparação do agendamento (como a atualização de itens e volumes) foram concluídas, e o agendamento está pronto para o recebimento ou coleta no Centro de Distribuição (CD). O sistema executa o fluxo de finalização, atualizando o status do agendamento e preparando o registro para as próximas etapas operacionais. Para realizar esta operação, o seller deve possuir a permissão de escrita (stock-scheduling-seller:write). Em caso de sucesso, o endpoint retorna o status 200 OK com os dados da finalização.