Cuprins

Prezentare generală Politica de versionare Compatibilitate inversă Migrare de la V1 la V2 Modificări ale endpoint-urilor Actualizări ale formatului de răspuns Cronologia deprecierii Modificări disruptive Migrare pas cu pas Suport și resurse

Documentația API

Ghid de migrare API — Actualizare între versiuni

Planificați și executați actualizări fluide ale versiunilor API. Înțelegeți modificările disruptive, cronologiile de depreciere și cele mai bune practici pentru migrarea între versiunile Smart Money API.

Publicat pe 21 martie 2026 • 16 min de citit • Avansat

Prezentare generală a migrării

Smart Money API este în continuă dezvoltare cu actualizări regulate. Acest ghid acoperă gestionarea versiunilor, modificările disruptive și cum să vă migrați integrarea fără timpi morti.

Principii cheie ale migrării:

Versionare semantică — Formatul MAJOR.MINOR.PATCH este respectat strict
Suport pe termen lung — Versiunea majoră anterioară este suportată pentru 24+ luni
Avertismente de depreciere — Notificare prealabilă de 6 luni pentru toate modificările disruptive
Versiuni paralele — Rulați v1 și v2 simultan în timpul migrării
Testare automată — Sunt furnizate instrumente de compatibilitate pentru suitele de testare

Stare curentă: v1 (curent), v2 (beta, disponibilitate generală Q2 2026). v1 suportat până în Q1 2028.

Politica de versionare

Versionare semantică

Formatul versiunii
Versiunea API: MAJOR.MINOR.PATCH
Exemplu: 2.1.3
MAJOR (2) - Modificări disruptive, arhitectură nouă
MINOR (1) - Funcționalități compatibile invers
PATCH (3) - Remedieri de erori, actualizări de securitate

Ciclul de lansare a versiunilor

Fază	Durată	Caracteristici
Alpha	2-4 săptămâni	Modificări disruptive majore, doar testare
Beta	4-8 săptămâni	Majoritatea stabilă, feedback din comunitate
Release Candidate	2-4 săptămâni	Gata pentru producție, finisaje finale
Disponibilitate generală	24+ luni	Suport complet pentru producție

Obțineți cheia dvs. API în 30 de secunde

Sunteți gata să construiți? Obțineți o cheie API gratuită (50 de apeluri/zi, fără card) și începeți să extrageți date live despre balene, finanțare și on-chain.

Obțineți cheia dvs. API →

Compatibilitate inversă

Compatibilitatea versiunilor

În cadrul unei versiuni majore, puteți actualiza întotdeauna la versiuni minore/patch în siguranță:

URL-uri endpoint — Rămân neschimbate
Câmpuri obligatorii — Niciodată eliminate (doar câmpuri noi opționale adăugate)
Coduri de stare HTTP — Păstrate pentru scenariile existente
Structura răspunsului — Câmpurile de bază rămân identice
Autentificare — Nicio modificare la mecanismele de autentificare

Depreciere grațioasă

Cronologia deprecierii
// Luna 1: Anunțarea deprecierii
// Funcționalitate marcată cu antetul Deprecation
Deprecation: version="2.2", sunset="2026-09-01"
// Luna 3-6: Perioada activă de depreciere
// API returnează avertismente dar încă funcționează
X-Deprecation-Warning: Acest endpoint va fi eliminat pe 2026-09-01
// Luna 6: Eliminare finală
// Endpoint returnează 410 Gone
HTTP/1.1 410 Gone

Migrare de la V1 la V2

Modificări majore

Redesign REST API — Endpoint-uri de resurse mai curate
Formatul răspunsului — Înveliș consistent, gestionare mai bună a erorilor
Autentificare — Suport OAuth 2.0 adăugat (cheile API încă funcționează)
Limitarea ratei — Granularitate și claritate îmbunătățite
Webhooks — Format și semnătură a evenimentelor reproiectate

Maparea endpoint-urilor

Endpoint V1	Endpoint V2	Modificări
GET /whales	GET /v2/whales/tracking	Reorganizat, adăugată filtrare
GET /funding	GET /v2/derivatives/funding-heatmap	Parametrul exchange obligatoriu
GET /positions	GET /v2/derivatives/positions	Opțiuni noi de agregare

Modificări ale endpoint-urilor

Modificări ale parametrilor de cerere

Cerere V1
// V1: Rate de finanțare
GET /v1/funding?symbol=BTCUSDT&exchange=binance

Cerere V2
// V2: Aceleași date, structură mai clară
GET /v2/derivatives/funding-heatmap?
  symbol=BTCUSDT&
  exchange=binance

Actualizări ale formatului de răspuns

Structura răspuns V1

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

Structura răspuns V2

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

Diferențe cheie: Fără înveliș de status, nume de câmp mai clare, metadate standardizate.

Cronologia deprecierii

Deprecieri planificate

Funcționalitate	Anunțată	Data de retragere	Înlocuitor
/v1/whales	Ian 2026	Ian 2028	/v2/whales/tracking
/v1/funding	Ian 2026	Ian 2028	/v2/derivatives/funding-heatmap
Autentificare doar cu cheie API	Mar 2026	Mar 2027	OAuth 2.0 (cheile funcționează în continuare)
Format Webhook v1	Q2 2026	Q2 2027	Format Webhook v2

Detalii schimbări disruptive

Endpoints eliminate

/v1/stats — Înlocuit de /v2/metrics
/v1/historical — Înlocuit de /v2/historical cu parametri noi
/v1/alerts/create — Înlocuit de POST /v2/alerts

Modificări de parametri

limit — Valoarea implicită schimbată de la 100 la 20 (specificați explicit!)
timeframe — Acum este obligatoriu pentru interogările istorice
sort — Format schimbat de la "field asc" la "field:asc"

Modificări ale câmpurilor din răspuns

funding → funding_rate
price → mark_price
vol → volume_quote

Migrare pas cu pas

Faza 1: Planificare (Săptămâna 1-2)

Auditarea integrării existente pentru funcționalități depreciate
Maparea endpoint-urilor v1 la echivalentele v2
Identificarea schimbărilor disruptive care afectează codul
Planificarea strategiei de testare și a cronologiei

Faza 2: Dezvoltare (Săptămâna 3-4)

Crearea unei ramuri v2 în controlul versiunilor
Actualizarea tuturor endpoint-urilor API la URL-uri v2
Actualizarea gestionării cererilor/răspunsurilor
Rularea testelor unitare în mediul sandbox

Faza 3: Testare (Săptămâna 5-6)

Rularea suitei complete de teste de integrare
Testarea scenariilor de eroare și a cazurilor limită
Testare de încărcare cu endpoint-uri v2
Audit de securitate al codului actualizat

Faza 4: Staging (Săptămâna 7)

Implementarea codului v2 în mediul de staging
Rularea testelor complete de acceptare
Obținerea aprobării de la părțile interesate
Pregătirea planului de revenire

Faza 5: Producție (Săptămâna 8)

Implementare blue-green în producție
Monitorizarea metricilor și ratelor de eroare
Permanență în standby pentru probleme de suport
Dezafectarea treptată a codului v1

Suport & Resurse

Instrumente disponibile

Validator de migrare — Verifică codul pentru utilizări depreciate
Verificator de actualizare API — Compară compatibilitatea între v1 și v2
Listă de verificare pentru migrare — PDF cu sarcini și cronologie
Exemple de cod — Mostre înainte/după migrare

Obțineți ajutor

Email: [email protected]
Documentație: Vezi changelog-versioning.html
Discord: Canal de suport comunitar
Enterprise: Inginer de migrare dedicat

Începeți migrarea astăzi

Actualizați la API v2 cu instrumente de migrare cuprinzătoare, documentație și suport. Construit pentru a sprijini migrarea fără întreruperi.

Explorați V2

V1 suportat până în Ian 2028. Planificați-vă migrarea astăzi.