APIs Magalog

A Magalog é a plataforma de serviços logísticos do Magalu para clientes embarcadores. Esta seção reúne, em um único lugar, todas as rotas públicas expostas pela plataforma.

Todas as APIs seguem o mesmo padrão: especificação OpenAPI, autenticação via ID Magalu (OAuth2 / OIDC), autorização por escopos e um formato único de erro.

Disponibilidade em fases

Esta documentação descreve o escopo completo das APIs Magalog. As funcionalidades serão liberadas em fases. Atualmente, estão disponíveis:

• Geração de etiquetas logísticas
• Consulta de rastreio de pedidos
• Consulta de novos prazos de entrega
• Relatórios de remessas

Novas capacidades serão adicionadas progressivamente.

Rotas disponíveis

Rota	O que faz	Escopo
POST /logistic/smart-label/v1/labels/generate	Gera a etiqueta logística de um pedido	open:smart-label:write
GET /logistic/tracking/v1/shipment	Consulta o rastreio de uma remessa	open:tracking:read
GET /logistics/shipments/v1/delivery-date-changes	Consulta novos prazos de entrega	open:logistic-shipmentdeadline-shipper:read
GET /logistic/shipments-reports/v1/shipments	Lista as remessas de um período	open:logistic-shipment-report-shipper:read
GET /logistic/shipments-reports/v1/shipments/status-summaries	Consulta o resumo de status das remessas	open:logistic-shipment-report-shipper:read

Gerar etiqueta

POST /logistic/smart-label/v1/labels/generate

Recebe os dados do pedido — remetente, destinatário, pacotes e documentos fiscais — e devolve a etiqueta de transporte. É a rota que abre a jornada: sem etiqueta gerada, o pacote não circula.

Base: https://services.magalu.com/logistic

Referência completa

Consultar o rastreio de pedidos

GET /logistic/tracking/v1/shipment

Base: https://api.magalog.com.br

Devolve o status atual da remessa e o histórico completo de movimentações.

Informe exatamente um dos parâmetros de busca:

Parâmetro	O que é	Exemplo
reference	Identificador do pedido que o cliente integra conosco (ex: 8 dígitos CNPJ - ID do pedido)	12345678-987654321
code_id	Identificador da remessa na Magalog	MGL0000123456

Enviar os dois, ou nenhum, resulta em 400.

Referência completa

Consultar novos prazos de entrega

GET /logistics/shipments/v1/delivery-date-changes

Base: https://api.magalog.com.br

Devolve, de forma paginada, as remessas que tiveram o prazo de entrega replanejado. Cada registro informa a remessa, o pacote, o pedido relacionado e a mudança de data: o prazo original (old_delivery_date) e o replanejado (new_delivery_date).

Além da consulta, é possível receber a mudança de prazo de forma reativa por webhook — o tópico logistic_shipmentdeadline_updated notifica quando uma remessa tem a data de entrega atualizada.

Referência completa

Consultar relatórios de remessas

GET /logistic/shipments-reports/v1/shipments

Base: https://api.magalog.com.br

Devolve as remessas do embarcador de um período, de forma paginada, filtrando por intervalo de created_at. Cada remessa traz os identificadores, o cliente, o serviço utilizado, os eventos registrados e a janela de entrega esperada e, se houver, a replanejada.

GET /logistic/shipments-reports/v1/shipments/status-summaries

Devolve as contagens agregadas por status das remessas na janela móvel configurada, com o total geral do período — ideal para responder quantas remessas estão em cada etapa da entrega sem percorrer a lista completa.

Referência completa — Listar remessas

Referência completa — Consultar resumo de status

Autenticação

As rotas usam OAuth2 com fluxo authorization code do ID Magalu:

Authorization URL	https://id.magalu.com/login
Token URL	https://id.magalu.com/oauth/token

Para gerar o token de acesso, siga os passos de primeiros passos na Plataforma Magalu.

Envie o token no header Authorization:

Authorization: Bearer <access_token>

O token identifica o cliente. Não existe nenhum identificador de conta ou tenant a ser enviado na requisição — cada consulta enxerga apenas os dados do dono do token.

Escopos

Valor	Descrição
open:smart-label:write	Gerar etiquetas logísticas.
open:tracking:read	Consultar o rastreio de pedidos do cliente autenticado. Somente leitura.
open:logistic-shipmentdeadline-shipper:read	Consultar novos prazos de entrega das remessas.
open:logistic-shipment-report-shipper:read	Consultar os relatórios de remessas e o resumo de status.

Um token sem o escopo exigido pela rota recebe 403, não 401.

Formato de erro

Todas as rotas respondem erro com o mesmo corpo:

{
  "slug": "shipment_not_found",
  "message": "Nenhuma remessa encontrada para o identificador informado.",
  "details": []
}

Campo	Descrição
slug	Identificador estável do erro. É o campo para programar em cima.
message	Texto legível, sujeito a mudança de redação.
details	Lista de problemas específicos, cada um com field, location, slug e message. Pode vir vazia.

Status usados:

Status	Quando acontece
400	A requisição não passou na validação de parâmetros ou de corpo.
401	Token ausente, expirado ou inválido.
403	O token não carrega o escopo exigido pela rota.
404	O recurso não existe, ou não pertence ao dono do token.
422	Os parâmetros obrigatórios foram enviados com valor inválido.
500	Erro interno.
503	Dependência temporariamente indisponível. Vale repetir a chamada.

Rastreabilidade

Envie X-Correlation-Id na requisição para correlacionar a chamada nos logs. As respostas trazem X-Request-Id, que é o identificador a informar ao abrir um chamado de suporte.