Guia de Migração da API Mais Retorno

Autenticação: Token → API Key

O fluxo OAuth (POST /auth com email/senha → access_token JWT) foi substituído por uma api_key estática, gerada em maisretorno.com/app/meu-perfil/api. A chave (formato mr_xxx_xxxxxxxx...) é vinculada a uma subscription ativa de algum plano (Free / Basic / Starter / Growth / Enterprise) e é exibida em texto plano apenas uma vez.

Como gerar sua api_key (vídeo ~30s)

Resumo das mudanças

Código — Antes

import requests

# 1. Obter access_token via POST /auth (válido por 60min)
auth_response = requests.post(
    "https://data.maisretorno.com/auth",
    data={
        "grant_type": "password",
        "username": "seu-email@exemplo.com",
        "password": "sua-senha",
        "client_id": "mrdata",
    },
)
token = auth_response.json()["access_token"]

# 2. Usar token nas requisições
response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/asset-info/petr4:b3",
    headers={"Authorization": f"Bearer {token}"},
)
print(response.json())

// 1. Obter access_token via POST /auth (válido por 60min)
const authRes = await fetch("https://data.maisretorno.com/auth", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "password",
    username: "seu-email@exemplo.com",
    password: "sua-senha",
    client_id: "mrdata",
  }),
});
const { access_token: token } = await authRes.json();

// 2. Usar token nas requisições
const response = await fetch(
  "https://data.maisretorno.com/mr-data/v4/api/asset-info/petr4:b3",
  { headers: { Authorization: `Bearer ${token}` } }
);
console.log(await response.json());

Código — Depois

import requests

# 1. Gere a api_key uma única vez no portal e guarde com segurança
#    (formato: mr_xxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxx)
api_key = "SUA_API_KEY"

# 2. Use direto nas requisições — sem POST /auth, sem expiração de 60min
#    Server-side: prefira X-Api-Key (recomendado pelo spec)
response = requests.get(
    "https://data.maisretorno.com/mr-data/v4/api/asset-info/petr4:b3",
    headers={"X-Api-Key": api_key},
)
print(response.json())

// 1. Gere a api_key uma única vez no portal e guarde com segurança
//    (formato: mr_xxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxx)
const apiKey = "SUA_API_KEY";

// 2. Use direto nas requisições — sem POST /auth, sem expiração de 60min
//    Server-side: prefira X-Api-Key (recomendado pelo spec)
const response = await fetch(
  "https://data.maisretorno.com/mr-data/v4/api/asset-info/petr4:b3",
  { headers: { "X-Api-Key": apiKey } }
);
console.log(await response.json());

Breaking Changes

Mudanças que quebram parsing/paths

• Formato de datas no response: Epoch (int) → ISO date string (YYYY-MM-DD) em quotes e available-wallets
• Estrutura do asset-info: Campos aninhados sob chave do mercado → Campos flat no root
• Search response: name → nicename, asset_type → type em search
• Wallet available-months: Objetos com date em epoch → Objetos com date em YYYY-MM-DD em available-wallets
• Path params de wallet: CNPJ puro → identifier com formato cnpj:fi em available-wallets e wallet-detail
• Parâmetro adjusted: Removido do stats. No quotes, é hardcoded true (não é parâmetro)
• Rota de quotes: Nome mudou de historical-quotes para quotes

Campos reorganizados

• Campos de fundos reorganizados: cvm_property, class_lvl_*, networth, quota_holders movidos para o novo endpoint /fund-class-subclass
• Campo meta removido: Os endpoints de wallet não são mais retornados como metadata do header do fundo
• Novo campo trading_currency: Adicionado no response de stats e em vários DTOs de asset-info

1. Search

Parâmetros de Input

Campos do Response (array de objetos)

2. Stats

Parâmetros de Input

Campos do Response

3. Quotes (Historical Quotes)

Parâmetros de Input

Campos do Response

4. Asset Info (Header)

Campos Comuns (todos os tipos)

Asset Info por Tipo de Ativo

5. Available Wallets

Campos do Response

6. Wallet Detail

Principais mudanças:

7. Fund Class/Subclass Novo

Campos do Response (FundClassSubclassDto)