Guide Intégration API

L'API REST Synastra permet d'intégrer les calculs astrologiques dans vos applications tierces. Ce guide couvre l'authentification, les principaux endpoints, et des exemples de code.

Authentification

L'API utilise JWT Bearer tokens. Obtenez votre clé API depuis le Dashboard > Paramètres > API.

// Headers requis
const headers = {
  'Authorization': Bearer ${API_KEY},
  'Content-Type': 'application/json'
};

Rate Limiting

Endpoints principaux

POST /api/natal-chart

Calcule un thème natal complet à partir des données de naissance.

// Requête
const response = await fetch('https://api.synastra.com/api/natal-chart', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Test',
    birthDate: '1990-06-15',
    birthTime: '14:30',
    timezone: 'Europe/Paris',
    latitude: 48.8566,
    longitude: 2.3522,
    birthPlace: 'Paris, France'
  })
});

// Réponse (extrait)
{
  "planets": {
    "sun": { "longitude": 84.234, "sign": "Gémeaux", "degree": 24.234 },
    "moon": { "longitude": 312.876, "sign": "Verseau", "degree": 12.876 },
    // ... 10 planètes
  },
  "houses": [0, 30.5, 58.2, ...], // 12 cuspides
  "aspects": [
    { "planet1": "sun", "planet2": "moon", "type": "sextile", "orb": 2.34 }
  ]
}

POST /api/synastry

Compare deux thèmes natals et retourne les inter-aspects.

const response = await fetch('https://api.synastra.com/api/synastry', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    chart1: { / birthData personne 1 / },
    chart2: { / birthData personne 2 / }
  })
});

GET /api/transits

Retourne les transits actifs pour un thème natal donné.

const response = await fetch(
  'https://api.synastra.com/api/transits?chartId=abc123&date=2026-01-20',
  { headers }
);

Gestion des erreurs

L'API retourne des codes HTTP standard :

// Pattern de retry recommandé
async function apiCall(url: string, options: RequestInit, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || '60';
      await new Promise(r => setTimeout(r, parseInt(retryAfter) * 1000));
      continue;
    }
    return response;
  }
  throw new Error('Max retries exceeded');
}

Webhooks (Plan Pro+)

Configurez des webhooks pour recevoir des notifications :

• chart.created - Thème natal calculé
• synastry.completed - Synastrie terminée
• payment.succeeded - Paiement réussi (Stripe)

// Vérification signature webhook
import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

SDKs et bibliothèques

Ressources

• Swiss Ephemeris : la précision des calculs
• Support technique - Assistance API
• Analyse Avancée Backend V8 - Guide avancé