Rapports psychologiques (occidental)

Générer des rapports premium complets

POST https://api.freeastroapi.com/api/v1/natal/calculate

En-tête d'authentification: x-api-key

Utilisez l'endpoint natal avec psychological_report.enabled=true. En production, privilégiez le mode asynchrone et l'interrogation selon la cadence serveur, ou recevez les rapports terminés via callback webhook.

La generation d'un rapport complet prend generalement 3-4 minutes. C'est attendu: le rapport est produit via une chaîne multi-passe (synthese, redaction des chapitres, revision et validation).

Retenter sans risque avec Idempotency-Key

Les requetes POST astrologiques authentifiees et facturables acceptent l'en-tete optionnel Idempotency-Key: <cle d'operation unique generee cote client>. Reutilisez la meme cle uniquement pour retenter exactement la meme methode, le meme path, la meme query string et le meme corps JSON apres un timeout ou une erreur reseau.

Une relecture terminee renvoie la premiere reponse avec Idempotency-Replayed: true, ne relance pas le calcul et ne consomme pas de quota supplementaire. Les cles sont conservees environ 24 heures.

Reutiliser une cle avec une requete modifiee renvoie 409 idempotency_key_reused. Un doublon pendant que la premiere requete est encore en cours renvoie 409 request_in_progress avec Retry-After.

Thème de test sans crédit

Utilisez ce payload synthétique exact pour tester la génération de rapports sans dépenser de crédits de rapport. Ce contournement s'applique uniquement à cette signature de naissance précise.

{
  "name": "Synthetic Demo Candidate",
  "year": 1992,
  "month": 11,
  "day": 23,
  "hour": 14,
  "minute": 17,
  "city": "Lisbon",
  "tz_str": "Auto",
  "psychological_report": {
    "enabled": true,
    "mode": "async",
    "style": "standard",
    "markdown": false
  }
}

Pour demander une sortie Markdown, envoyez le même payload avec psychological_report.markdown=true:

{
  "name": "Synthetic Demo Candidate",
  "year": 1992,
  "month": 11,
  "day": 23,
  "hour": 14,
  "minute": 17,
  "city": "Lisbon",
  "tz_str": "Auto",
  "psychological_report": {
    "enabled": true,
    "mode": "async",
    "style": "standard",
    "markdown": true
  }
}

Toute autre donnée de naissance suit la facturation normale en crédits de rapport.

Télécharger les sorties d'exemple complètes

Ces fichiers sont des sorties completes generees depuis le meme theme de demonstration synthetique, fournies comme instantanes fixes pour previsualiser l'integration.

Télécharger l'exemple JSON Télécharger l'exemple Markdown

Paramètres de requête

Paramètre	Type	Req	Description
psychological_report.enabled	boolean	Oui	Active la génération du rapport. Par défaut: false.
psychological_report.mode	string	Non	Mode de livraison du rapport: async ou sync. Par défaut: async.
psychological_report.style	string	Non	Style du rapport: standard ou jungian_parental. Par défaut: standard.
psychological_report.markdown	boolean	Non	Inclut report_markdown dans les réponses terminées. Par défaut: false.
psychological_report.include_natal_chart_in_response	boolean	Non	Inclut le payload du theme natal dans la reponse d'interrogation du rapport. Par defaut: false.
psychological_report.debug	boolean	Non	Inclut les métriques internes de validation debug dans la réponse. Par défaut: false.

Requête de démarrage rapide

curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "name": "Synthetic Demo Candidate",
    "year": 1992,
    "month": 11,
    "day": 23,
    "hour": 14,
    "minute": 17,
    "city": "Lisbon",
    "tz_str": "Auto",
    "psychological_report": {
      "enabled": true,
      "mode": "async"
    }
 }'

Flux asynchrone (intégration minimale viable)

Créez la demande de rapport avec mode: "async" en utilisant le thème de test sans crédit ci-dessus.
Lisez job_id et next_poll_after_seconds.
Interrogez GET /api/v1/natal/report/{job_id} en respectant la cadence serveur.
Pour le thème de test, vérifiez credits_used: 0.
Quand le statut est completed, lisez report_metadata, puis utilisez soit report_content, soit report_markdown selon l'option demandée.

{
  "subject": { "...": "normal natal chart payload..." },
  "credits_used": 0,
  "psychological_report": {
    "status": "pending",
    "mode": "async", 
    "style": "standard",
    "job_id": "7a7f3f9f-...",
    "fetch_url": "/api/v1/natal/report/7a7f3f9f-...",
    "credits_used": 0,
    "next_poll_after_seconds": 15
  }
}

{
  "job_id": "7a7f3f9f-...",
  "status": "completed",
  "credits_used": 0,
  "report_metadata": {
    "report_id": "e5efe6ea-...",
    "title": "Jane Example Natal Psychological Report",
    "generated_at": "2026-03-21T11:44:09.531Z",
    "provider": "openai-compatible",
    "model": "gpt-5.3-chat-latest",
    "summary": "Core report summary...",
    "word_count": 7350
  },
  "report_markdown": "## Introduction ... (full markdown report)"
}

Crédits et cache

Ce flux utilise des crédits de rapport spéciaux, pas le quota normal de requêtes.
Le thème de test synthétique publié est exempté et retourne credits_used: 0 pour tester l'endpoint.
Une génération fraîche de rapport consomme 1 crédit de rapport (credits_used: 1).
Une réponse servie depuis le cache pour les mêmes données de naissance réutilise le rapport stocké et ne consomme pas de crédit supplémentaire.
Utilisez directement report_content.chapters[].sections[].paragraphs[] pour construire votre interface PDF.

Format de sortie

Les réponses terminées incluent toujours report_metadata. Le corps de sortie est exclusif: avec psychological_report.markdown=false (par défaut), vous recevez report_content; avec psychological_report.markdown=true vous recevez report_markdown.

Erreurs fréquentes

En-tête x-api-key manquant.
Interrogation trop rapide au lieu de respecter next_poll_after_seconds / Retry-After.
callback_url fourni sans callback_signing_secret.
Oublier que Markdown doit être activé explicitement. Définissez psychological_report.markdown=true si vous voulez report_markdown.

Avancé : callback webhook (optionnel)

Cette option est avancée et facultative. Si vous envoyez callback_url et callback_signing_secret, l'API envoie un callback signé quand le job est completed ou failed.

Paramètre	Type	Req	Description
psychological_report.callback_url	string	Non	Endpoint HTTPS de callback pour les événements de rapport completed/failed. Par défaut: null.
psychological_report.callback_signing_secret	string	Non	Secret de signature webhook. Requis quand callback_url est défini. Par défaut: null.

{
  "event": "psychological_report.completed",
  "job_id": "7a7f3f9f-...",
  "status": "completed",
  "credits_used": 1,
  "report_metadata": { "...": "same metadata object as polling response" },
  "report_markdown": "## Introduction ...",
  "created_at": "2026-03-21T11:44:09.531Z"
} 

Headers:
X-FreeAstro-Event: psychological_report.completed
X-FreeAstro-Timestamp: 1711025109
X-FreeAstro-Signature: <HMAC_SHA256_HEX>

import crypto from "node:crypto";
import express from "express";

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/freeastro/report", (req, res) => {
  const rawBody = req.body.toString("utf8");
  const timestamp = req.header("X-FreeAstro-Timestamp") || "";
  const signature = req.header("X-FreeAstro-Signature") || "";
  const secret = process.env.FREE_ASTRO_CALLBACK_SECRET || "";

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(rawBody);
  // Save report by event.job_id, then ack
  return res.status(200).json({ ok: true });
});