Human Design API: constrói apps de HD com 12 endpoints

🕓 Publicado a 2026-04-14, atualizado a 2026-05-09. Os SDK de TS / Python / PHP estão agora nos registries públicos: @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Detalhes no changelog.

O Human Design passou de um sistema esotérico de nicho dos anos 1990 a um referencial de desenvolvimento pessoal mainstream. Apps com milhões de utilizadores normalizaram-no, e os programadores perguntam-se: como calcular um mapa de Human Design por código?

Neste post vemos o lado técnico: o que é o cálculo de HD, que APIs o suportam e como integrar uma funcionalidade de HD na tua app.

O Human Design assenta em três sistemas clássicos:

• Astrologia ocidental: as posições dos planetas no momento do nascimento
• I Ching: 64 hexagramas mapeados em 64 “portas”
• Sistema de chakras: nove “centros” (nós energéticos)

O cálculo recebe os dados de nascimento e produz um bodygraph, um mapa visual com:

• Type (Manifestor, Generator, Manifesting Generator, Projector, Reflector): a assinatura energética
• Strategy: como tomar decisões
• Authority: em que centro confiar nas decisões (Sacral, Emotional, Splenic, etc.)
• Profile: a combinação de linhas (1/3, 4/6, etc.)
• Channels: as ligações entre centros que formam a personalidade
• Incarnation Cross: o propósito de vida, derivado de quatro posições-chave

Por baixo, cada uma das 64 portas corresponde a um intervalo de longitude eclíptica. A longitude dos teus planetas no nascimento é mapeada numa porta concreta (e nas linhas dentro dela). O cálculo “Design” é feito para o momento em que o Sol estava 88° antes da posição natal, cerca de 3 meses antes do nascimento.

O Human Design usa dois momentos de nascimento:

1. Personality: a hora real de nascimento. É o lado “consciente”.
2. Design: quando o Sol estava 88° antes da posição natal. É o lado “inconsciente”.

Cada ativação de porta pertence a um deles. Um mapa completo tem 13 + 13 = 26 ativações.

É isto que torna o cálculo de HD mais pesado do que um mapa astrológico normal: na prática estás a calcular dois mapas.

A maioria das APIs de astrologia ou não suporta HD de todo, ou tem um suporte superficial (só type + strategy). Uma implementação completa de HD precisa de:

• Mapeamento das 64 portas (lookup table)
• 6 linhas por porta (384 células)
• 9 centros com a lógica defined/open
• 36 canais (cada um liga dois centros)
• Cálculo da Incarnation Cross
• Derivação do Profile a partir da linha da porta do Sol + linha da porta da Terra (Personality e Design)

APIs que fazem tudo isto são muito raras. A API AstroWay tem 12 endpoints de HD, a cobertura mais profunda que vimos numa API comercial.

Imagina que estás a adicionar HD a uma app de astrologia que já existe. Começa pelo endpoint principal:

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

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

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

console.log(`Type: ${hd.type}`);         // e.g. "Generator"
console.log(`Strategy: ${hd.strategy}`); // e.g. "To Respond"
console.log(`Authority: ${hd.authority}`); // e.g. "Sacral"
console.log(`Profile: ${hd.profile.profile}`);   // e.g. "1/3"
console.log(`Defined channels: ${hd.channels.length}`);

Forma da resposta:

{
  "type": "Generator",
  "strategy": "To Respond",
  "notSelfTheme": "Frustration",
  "authority": "Sacral",
  "profile": "1/3",
  "definition": "single",
  "cross": {
    "name": "Right Angle Cross of the Sphinx",
    "quarter": "Civilization",
    "gates": [1, 2, 7, 13]
  },
  "centers": [
    { "name": "Sacral", "defined": true },
    ...
  ],
  "channels": [
    { "gate1": 34, "gate2": 20, "name": "Channel of Charisma", "type": "Generated" }
  ],
  "personalityActivations": [...],
  "designActivations": [...]
}

O Penta é uma técnica para perceber a dinâmica de equipa em grupos de 3 a 5 pessoas. É raro: a maioria das calculadoras de HD não o oferece. Mas é ouro para HR-tech, plataformas de coaching e apps de team building.

const penta = await client.hd.penta({
  inputs: [
    { 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(`Members: ${penta.memberCount}`);
console.log(`Channels in the group: ${penta.channels.length}`);

Os mapas HD são sensíveis à hora de nascimento. Um erro de 10 minutos pode mudar o Profile (por exemplo, 1/3 → 1/4). Para utilizadores que não sabem a hora exata, corre a análise de sensitivity:

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

// sensitivity tells you which fields change if time shifts ±5/15/30 min

Usa isto para avisar o utilizador: “Com esta precisão o teu profile pode mudar. Considera uma retificação”.

Se estás a construir uma app focada em HD:

• Utilizador básico: 1 mapa HD no registo, guardado em cache para sempre = 50 créditos uma única vez
• Utilizador ativo: trânsitos periódicos + compatibility = ~200 créditos/mês
• 100 DAU com uso moderado de HD: ~110 000 créditos/mês → o Starter ($19/mês) cobre à vontade
• 1 000 DAU: ~150 000 créditos/mês → Pro ($59/mês)

Os pedidos de compatibility são os mais pesados (100 créditos). Guarda em cache o resultado de cada par de utilizadores para sempre (não muda).

O bodygraph costuma ser desenhado em SVG. A API devolve os dados dos centros e canais; tu desenhas o visual. Exemplo:

function Bodygraph({ hd }: { hd: HDChart }) {
  return (
    <svg viewBox="0 0 400 600">
      {hd.centers.map(c => (
        <polygon
          key={c.name}
          points={CENTER_COORDS[c.name]}
          fill={c.defined ? CENTER_COLORS[c.name] : 'white'}
          stroke="black"
        />
      ))}
      {hd.channels.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>
  );
}

As coordenadas são um modelo fixo (todos os bodygraphs têm os mesmos 9 centros e 64 portas nas mesmas posições).

• Human Design API: a página do produto com a lista completa de endpoints
• Exemplo: Human Design: walkthrough detalhado de /v1/human-design
• Início rápido: obtém uma chave de API gratuita (até 200 mapas HD/mês no Free)