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

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

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

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

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.

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