# Magalu Devs

> Portal de APIs públicas da plataforma Magalu para integração de sellers e parceiros. As especificações OpenAPI 3 abaixo descrevem cada API e podem ser consumidas diretamente por agentes, IDEs e geradores de cliente.

Base URL das APIs: `https://api.magalu.com` (algumas APIs logísticas utilizam `https://services.magalu.com` — consulte o campo `servers` do spec correspondente).

Um índice em JSON com a mesma lista está disponível em [https://developers.magalu.com/apis/index.json](https://developers.magalu.com/apis/index.json). Quando há um link `overview`, ele aponta para um guia em markdown explicando o propósito e o uso da API (9 de 22 APIs possuem overview).

## APIs

- [Agendamento de Estoque](https://developers.magalu.com/apis/stockscheduling.openapi.yaml): agendamento de estoque.
- [Análise Financeira](https://developers.magalu.com/apis/financial-analysis.openapi.yaml) — [overview](https://developers.magalu.com/apis/financial-analysis/overview.md): análise financeira de pedidos e sellers.
- [Atendimento ao Consumidor (SAC)](https://developers.magalu.com/apis/sac.yaml) — [overview](https://developers.magalu.com/apis/sac/overview.md): atendimento ao consumidor (SAC).
- [Automotivo](https://developers.magalu.com/apis/cardan.openapi.yaml): catálogo automotivo (Cardan).
- [Categorias](https://developers.magalu.com/apis/categories.openapi.yaml) — [overview](https://developers.magalu.com/apis/categories/overview.md): categorias do catálogo.
- [Centros de Distribuição](https://developers.magalu.com/apis/warehouses.openapi.yaml) — [overview](https://developers.magalu.com/apis/warehouses/overview.md): consulta e gestão de centros de distribuição.
- [Conversas](https://developers.magalu.com/apis/conversations.openapi.yaml): conversas entre seller e cliente.
- [Documentos Fiscais (NF-e e CT-e)](https://developers.magalu.com/apis/fiscaldocument.openapi.yaml): emissão e consulta de NF-e e CT-e do fulfillment.
- [Estoque](https://developers.magalu.com/apis/stock.openapi.yaml): consulta e conciliação unificada de estoque, transferências entre CDs e movimentações logísticas.
- [Filas](https://developers.magalu.com/apis/queues.openapi.yaml): filas de eventos da plataforma.
- [Fiscal do Fulfillment (Impostos e Departamentos)](https://developers.magalu.com/apis/taxesdepartments.openapi.yaml): integração com entidades fiscais do fulfillment.
- [Pedidos](https://developers.magalu.com/apis/orders.openapi.yaml) — [overview](https://developers.magalu.com/apis/orders/overview.md): ciclo de vida de pedidos do seller.
- [Perguntas & Respostas](https://developers.magalu.com/apis/questions.openapi.yaml): perguntas de clientes nos anúncios.
- [Produtos](https://developers.magalu.com/apis/products.openapi.yaml) — [overview](https://developers.magalu.com/apis/products/overview.md): catálogo de produtos do seller.
- [promo3p-api](https://developers.magalu.com/apis/promotions.openapi.yaml)
- [Rastreamento de Remessas](https://developers.magalu.com/apis/tracking.openapi.yaml): rastreamento de remessas.
- [Regras de Precificação Automática](https://developers.magalu.com/apis/pricingrules.openapi.yaml) — [overview](https://developers.magalu.com/apis/pricingrules/overview.md): criação, atualização e consulta de regras de precificação automática.
- [Remessa](https://developers.magalu.com/apis/shippings.openapi.yaml): remessa de transporte (carrier).
- [Scores](https://developers.magalu.com/apis/scores.openapi.yaml): scores do seller.
- [Smart Label](https://developers.magalu.com/apis/smartlabel.openapi.yaml) — [overview](https://developers.magalu.com/apis/smartlabel/overview.md): geração de etiqueta logística para pedidos.
- [Traces](https://developers.magalu.com/apis/traces.yaml): rastreamento e auditoria.
- [Webhooks](https://developers.magalu.com/apis/webhooks.openapi.yaml) — [overview](https://developers.magalu.com/apis/webhooks/overview.md): inscrição e entrega de eventos via webhook.

## Authentication

Todas as APIs usam **OAuth 2.0 Authorization Code** via ID Magalu (`https://id.magalu.com`). O fluxo é interativo: o seller (pessoa jurídica) precisa autorizar a aplicação cliente. A documentação completa, com o passo a passo, está em [https://developers.magalu.com/docs/first-steps/create-an-application/authentication-authorization](https://developers.magalu.com/docs/first-steps/create-an-application/authentication-authorization).

Resumo do fluxo:

1. Redirecione o seller para a URL de consentimento:
   ```
   https://id.magalu.com/login?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&scope=<SCOPES>&response_type=code&choose_tenants=true
   ```
2. Após o login + consentimento, o ID Magalu redireciona para `<REDIRECT_URI>?code=<CODE>&state=<STATE>`. O `code` tem validade de 10 minutos e é de uso único.
3. Troque o `code` por um `access_token`:
   ```bash
   curl -X POST 'https://id.magalu.com/oauth/token' \
     -H 'Content-Type: application/json' \
     -d '{
       "client_id": "<CLIENT_ID>",
       "client_secret": "<CLIENT_SECRET>",
       "redirect_uri": "<REDIRECT_URI>",
       "code": "<CODE>",
       "grant_type": "authorization_code"
     }'
   ```
   A resposta inclui `access_token` (Bearer JWT, expira em ~7200s), `refresh_token` e `scope`.
4. Use o token nas APIs:
   ```
   Authorization: Bearer <ACCESS_TOKEN>
   ```
5. Renove o token antes da expiração:
   ```bash
   curl -X POST 'https://id.magalu.com/oauth/token' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -d 'grant_type=refresh_token' \
     -d 'client_id=<CLIENT_ID>' \
     -d 'client_secret=<CLIENT_SECRET>' \
     -d 'refresh_token=<REFRESH_TOKEN>'
   ```

Os escopos necessários variam por API e são declarados no campo `security` / `securitySchemes` de cada spec OpenAPI. Para criar um cliente OAuth e obter `client_id`/`client_secret`, consulte [https://developers.magalu.com/docs/first-steps/create-an-application/create-application](https://developers.magalu.com/docs/first-steps/create-an-application/create-application).

## Optional

- [Documentação completa de autenticação OAuth 2.0](https://developers.magalu.com/docs/first-steps/create-an-application/authentication-authorization)
- [Como criar e configurar um cliente OAuth](https://developers.magalu.com/docs/first-steps/create-an-application/create-application)
- [Documentação humana das APIs](https://developers.magalu.com/docs)
- [Roadmap](https://developers.magalu.com/docs/apis/roadmap)
- [Release Notes](https://developers.magalu.com/docs/apis/release-notes)