Human Design API: costruire applicazioni HD con 12 endpoint

🕓 Aggiornamento del 2026-04-14, aggiornato il 2026-05-09. Gli SDK TS / Python / PHP ora vivono nei registri pubblici — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). I dettagli sono disponibili in changelog.

Il Design Umano è cresciuto da un sistema esoterico di nicchia degli anni ‘90 a una cornice mainstream di sviluppo personale. Le app con milioni di utenti lo hanno normalizzato — e gli sviluppatori si chiedono: come calcolare la carta del Design Umano in modo programmatico?

In questo post, esploreremo il lato tecnico: cosa sono i calcoli del Design Umano, quali API li supportano e come integrare la funzionalità del Design Umano nella tua app.

Il Design Umano si basa su tre sistemi classici:

• Astrologia occidentale — posizioni dei pianeti al momento della nascita
• I Ching — 64 esagrammi, mappati su 64 “porte”
• Sistema dei chakra — nove “centri” (nodi energetici)

I calcoli prendono i dati di nascita e producono un bodygraph — una mappa visiva con:

• Tipo (Manifestor, Generatore, Generatore Manifestante, Proiettore, Riflettore) — firma energetica
• Strategia — come prendere decisioni
• Autorità — a quale centro affidarsi nelle decisioni (Sacrale, Emotivo, Splenico, ecc.)
• Profilo — combinazione di linee (1/3, 4/6, ecc.)
• Canali — collegamenti tra i centri che formano la personalità
• Incarnazione Cross — scopo della vita, derivato da quattro posizioni chiave

Sotto il cofano, ogni porta corrisponde a un intervallo di longitudine eclittica. La longitudine dei pianeti al momento della nascita viene mappata su porte specifiche (e righe all’interno di esse). Il calcolo del “Design” — per lo spostamento del Sole di 88° prima della nascita — è di circa 3 mesi prima.

Il Design Umano utilizza due punti di nascita:

1. Personalità — il tempo di nascita reale. Questo è il lato “cosciente”.
2. Design — quando il Sole era a 88° prima della posizione di nascita. Questo è il lato “inconscio”.

Ogni attivazione della porta appartiene a uno di essi. La carta completa ha 13 + 13 = 26 attivazioni.

È proprio questo che rende i calcoli del Design Umano più difficili rispetto alla carta astrologica standard — stai effettivamente calcolando due carte.

La maggior parte delle API di astrologia non supporta il Design Umano o ha un supporto superficiale (solo tipo + strategia). Una implementazione completa del Design Umano richiede:

• Mappatura delle 64 porte (tabella di lookup)
• 6 linee per ogni porta (384 celle)
• 9 centri con logica definita/aperta
• 36 canali (ognuno collega due centri)
• Calcolo dell’Incarnazione Cross
• Estrazione del Profilo dalle linee della porta del Sole + linea della porta della Terra (Personalità e Design)

Le API che possono fare tutto ciò sono rare. AstroWay API ha 12 endpoint del Design Umano — la copertura più approfondita che abbiamo visto in un’API commerciale.

Immagina di aggiungere il Design Umano a un’app di astrologia esistente. Inizia con l’endpoint principale:

import { Astroway } from '@astroway/sdk';

const client = new Astroway({ apiKey: process.env.ASTROWAY_API_KEY! });

const hd = await client.humanDesign({
  date: '1990-07-14',
  time: '14:30:00',
  timezoneOffset: 3,
  latitude: 50.4501,
  longitude: 30.5234,
});

console.log(`Tipo: ${hd.type}`);         // ad esempio, "Generatore"
console.log(`Strategia: ${hd.strategy}`); // ad esempio, "Rispondere"
console.log(`Autorità: ${hd.authority}`); // ad esempio, "Sacrale"
console.log(`Profilo: ${hd.profile}`);   // ad esempio, "1/3"
console.log(`Canali definiti: ${hd.channels.length}`);

La forma della risposta:

{
  "type": "Generatore",
  "strategy": "Rispondere",
  "notSelfTheme": "Frustrazione",
  "authority": "Sacrale",
  "profile": "1/3",
  "definition": "singolo",
  "cross": {
    "name": "Croce dell'Angolo Destro della Sfinge",
    "quartiere": "Civiltà",
    "porte": [1, 2, 7, 13]
  },
  "centri": [
    { "name": "Sacrale", "defined": true },
    ...
  ],
  "canali": [
    { "gate1": 34, "gate2": 20, "name": "Canale del Carisma", "type": "Generato" }
  ],
  "attivazioniPersonalità": [...],
  "attivazioniDesign": [...]
}

Penta — tecnica per comprendere la dinamica di squadra in gruppi di 3-5 persone. È una rarità — la maggior parte dei calcolatori del Design Umano non la offre. Ma è oro per le piattaforme HR-tech, di coaching e di team building.

const penta = await client.hdPenta({
  membri: [
    { date: '1990-07-14', time: '14:30:00', timezoneOffset: 3, latitude: 50.45, longitude: 30.52 },
    { date: '1988-03-10', time: '08:15:00', timezoneOffset: 2, latitude: 48.85, longitude: 2.35 },
    { date: '1985-11-22', time: '18:00:00', timezoneOffset: -5, latitude: 40.71, longitude: -74.00 },
  ],
});

console.log(`Tipo Penta: ${penta.type}`);
console.log(`Canali definiti nel gruppo: ${penta.definedChannels.length}`);

Le carte del Design Umano sono sensibili all’ora di nascita. Un errore di 10 minuti può cambiare il Profilo (ad esempio, 1/3 → 1/4). Per gli utenti che non conoscono l’ora esatta, esegui l’analisi della sensibilità:

const sensibilità = await client.hdSensitivity({
  date: '1990-07-14',
  time: '14:30:00',
  timezoneOffset: 3,
  latitude: 50.4501,
  longitude: 30.5234,
});

// sensibilità mostrerà quali campi cambieranno se si sposta l'ora di ±5/15/30 min

Usa questo per avvertire l’utente: “A questa precisione, il tuo profilo potrebbe spostarsi. Considera la rettificazione”.

Se stai costruendo un’app focalizzata sul Design Umano:

• Utente base: 1 carta del Design Umano alla registrazione, memorizzata per sempre = 50 crediti una tantum
• Utente attivo: trasiti periodici + compatibilità = ~200 crediti/mese
• 100 DAU con utilizzo moderato del Design Umano: ~110 000 crediti/mese → Starter ($19/mese) copre facilmente
• 1 000 DAU: ~150 000 crediti/mese → Pro ($59/mese)

Le richieste di compatibilità sono le più pesanti (100 crediti). Memorizza i risultati per ogni coppia di utenti per sempre (non cambiano).

La renderizzazione del bodygraph si esegue tradizionalmente attraverso SVG. L’API restituisce i dati sui centri e i canali; tu renderizzi la visualizzazione. Esempio:

function Bodygraph({ hd }: { hd: HDChart }) {
  return (
    <svg viewBox="0 0 400 600">
      {hd.centri.map(c => (
        <polygon
          key={c.name}
          points={CENTER_COORDS[c.name]}
          fill={c.defined ? CENTER_COLORS[c.name] : 'white'}
          stroke="black"
        />
      ))}
      {hd.canali.map(ch => (
        <line
          key={`${ch.gate1}-${ch.gate2}`}
          x1={GATE_COORDS[ch.gate1].x}
          y1={GATE_COORDS[ch.gate1].y}
          x2={GATE_COORDS[ch.gate2].x}
          y2={GATE_COORDS[ch.gate2].y}
          stroke="#d4a84c"
          strokeWidth="3"
        />
      ))}
    </svg>
  );
}

Le coordinate sono un modello fisso (ogni bodygraph ha gli stessi 9 centri e 64 porte nelle stesse posizioni).

• API del Design Umano — pagina del prodotto con l’elenco completo degli endpoint
• Esempio: Design Umano — walkthrough dettagliato di /v1/human-design
• Guida rapida — ottieni una chiave API gratuita (fino a 200 carte del Design Umano/mese sul piano Free)