Índice

Visão Geral Política de Versionamento Compatibilidade com Versões Anteriores Migração de V1 para V2 Alterações nos Endpoints Atualizações no Formato de Resposta Cronograma de Descontinuação Alterações Incompatíveis Migração Passo a Passo Suporte e Recursos

Documentação da API

Guia de Migração da API — Atualização entre Versões

Planeje e execute atualizações suaves de versão da API. Entenda alterações incompatíveis, cronogramas de descontinuação e melhores práticas para migrar entre versões da Smart Money API.

Publicado em 21 de março de 2026 • 16 min de leitura • Avançado

Visão Geral da Migração

A Smart Money API está em desenvolvimento ativo com atualizações regulares. Este guia aborda gerenciamento de versões, alterações incompatíveis e como migrar sua integração sem tempo de inatividade.

Princípios-chave da migração:

Versionamento Semântico — Formato MAJOR.MINOR.PATCH estritamente seguido
Suporte de Longo Prazo — Versão principal anterior suportada por 24+ meses
Avisos de Descontinuação — Aviso prévio de 6 meses para todas as alterações incompatíveis
Versões Paralelas — Execute v1 e v2 simultaneamente durante a migração
Testes Automatizados — Ferramentas de compatibilidade de suite de testes fornecidas

Status Atual: v1 (atual), v2 (beta, disponibilidade geral Q2 2026). v1 suportada até Q1 2028.

Política de Versionamento

Versionamento Semântico

Formato de Versão
Versão da API: MAJOR.MINOR.PATCH
Exemplo: 2.1.3
MAJOR (2) - Alterações incompatíveis, nova arquitetura
MINOR (1) - Recursos compatíveis com versões anteriores
PATCH (3) - Correções de bugs, atualizações de segurança

Ciclo de Lançamento de Versão

Fase	Duração	Características
Alpha	2-4 semanas	Alterações incompatíveis frequentes, apenas para testes
Beta	4-8 semanas	Principalmente estável, feedback da comunidade
Release Candidate	2-4 semanas	Pronto para produção, ajustes finais
Disponibilidade Geral	24+ meses	Suporte total em produção

Obtenha sua chave de API em 30 segundos

Pronto para desenvolver? Obtenha uma chave de API gratuita (200 chamadas/dia, sem cartão) e comece a acessar dados em tempo real de baleias, financiamento e on-chain.

Obtenha sua chave de API →

Compatibilidade com Versões Anteriores

Compatibilidade de Versão

Dentro de uma versão principal, você sempre pode atualizar para versões menores/de patch com segurança:

URLs de Endpoint — Permanecem inalterados
Campos Obrigatórios — Nunca removidos (apenas novos campos opcionais adicionados)
Códigos de Status HTTP — Preservados para cenários existentes
Estrutura de Resposta — Campos principais permanecem idênticos
Autenticação — Nenhuma alteração nos mecanismos de autenticação

Descontinuação Gradual

Cronograma de Descontinuação
// Mês 1: Anúncio de descontinuação
// Recurso marcado com cabeçalho de descontinuação
Deprecation: version="2.2", sunset="2026-09-01"
// Mês 3-6: Período ativo de descontinuação
// API retorna avisos, mas ainda funciona
X-Deprecation-Warning: Este endpoint será removido em 2026-09-01
// Mês 6: Remoção final
// Endpoint retorna 410 Gone
HTTP/1.1 410 Gone

Migração de V1 para V2

Principais Alterações

Redesign da API REST — Endpoints de recursos mais limpos
Formato de Resposta — Empacotamento consistente, melhor tratamento de erros
Autenticação — Suporte a OAuth 2.0 adicionado (chaves de API ainda funcionam)
Limitação de Taxa — Granularidade e clareza aprimoradas
Webhooks — Formato de evento e assinatura redesenhados

Mapeamento de Endpoints

Endpoint V1	Endpoint V2	Alterações
GET /whales	GET /v2/whales/tracking	Reorganizado, filtros adicionados
GET /funding	GET /v2/derivatives/funding-heatmap	Parâmetro de exchange obrigatório
GET /positions	GET /v2/derivatives/positions	Novas opções de agregação

Alterações nos Endpoints

Alterações nos Parâmetros de Solicitação

Solicitação V1
// V1: Taxas de financiamento
GET /v1/funding?symbol=BTCUSDT&exchange=binance

Solicitação V2
// V2: Mesmos dados, estrutura mais clara
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Atualizações no Formato de Resposta

Estrutura de Resposta V1

Formato V1
{
 "status": "success",
 "data": {
 "symbol": "BTCUSDT",
 "funding": 0.0001
  }
}

Estrutura de Resposta V2

Formato V2
{
 "data": {
 "symbol": "BTCUSDT",
 "funding_rate": 0.0001
  },
 "_meta": {
 "request_id": "req_abc123",
 "timestamp": 1709980800000
  }
}

Principais Diferenças: Sem wrapper de status, nomes de campos mais claros, metadados padronizados.

Cronograma de Descontinuação

Descontinuações Planejadas

Recurso	Anunciado	Data de Desativação	Substituição
/v1/whales	Jan 2026	Jan 2028	/v2/whales/tracking
/v1/funding	Jan 2026	Jan 2028	/v2/derivatives/funding-heatmap
Autenticação apenas por chave de API	Mar 2026	Mar 2027	OAuth 2.0 (chaves ainda funcionam)
Formato Webhook v1	Q2 2026	Q2 2027	Formato Webhook v2

Detalhes das Mudanças Quebradas

Endpoints Removidos

/v1/stats — Substituído por /v2/metrics
/v1/historical — Substituído por /v2/historical com novos parâmetros
/v1/alerts/create — Substituído por POST /v2/alerts

Mudanças de Parâmetros

limit — Padrão alterado de 100 para 20 (seja explícito!)
timeframe — Agora obrigatório em consultas históricas
sort — Formato alterado de "field asc" para "field:asc"

Mudanças nos Campos de Resposta

funding → funding_rate
price → mark_price
vol → volume_quote

Migração Passo a Passo

Fase 1: Planejamento (Semana 1-2)

Auditar integração existente para recursos descontinuados
Mapear endpoints V1 para equivalentes V2
Identificar mudanças quebradas que afetam seu código
Planejar estratégia e cronograma de testes

Fase 2: Desenvolvimento (Semana 3-4)

Criar branch V2 no controle de versão
Atualizar todos os endpoints da API para URLs V2
Atualizar manipulação de requisições/respostas
Executar testes unitários no sandbox

Fase 3: Testes (Semana 5-6)

Executar suíte completa de testes de integração
Testar cenários de erro e casos extremos
Teste de carga com endpoints V2
Auditoria de segurança do código atualizado

Fase 4: Homologação (Semana 7)

Implantar código V2 em ambiente de homologação
Executar testes de aceitação completos
Obter aprovação das partes interessadas
Preparar plano de rollback

Fase 5: Produção (Semana 8)

Deploy blue-green em produção
Monitorar métricas e taxas de erro
Ficar de plantão para problemas de suporte
Desativar gradualmente o código V1

Suporte e Recursos

Ferramentas Disponíveis

Validador de Migração — Verificar código por uso descontinuado
Verificador de Atualização de API — Comparar compatibilidade entre V1 e V2
Lista de Verificação de Migração — PDF com tarefas e cronograma
Exemplos de Código — Amostras antes/depois da migração

Obtendo Ajuda

Email: [email protected]
Documentação: Veja changelog-versioning.html
Discord: Canal de suporte da comunidade
Enterprise: Engenheiro de migração dedicado

Comece Sua Migração Hoje

Atualize para a API V2 com ferramentas de migração abrangentes, documentação e suporte. Construído para suportar migração sem tempo de inatividade.

Explore V2

V1 suportado até Jan 2028. Planeje sua migração hoje.