Human Design API: xây dựng ứng dụng HD trên 12 endpoint

🕓 Bài viết ngày 2026-04-14, cập nhật 2026-05-09. SDK TS / Python / PHP hiện đã có trên các registry công khai - @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Chi tiết trong changelog.

Human Design đã phát triển từ một hệ thống huyền học ngách của thập niên 1990 thành một khung phát triển bản thân phổ biến. Các ứng dụng với hàng triệu người dùng đã đưa nó vào dòng chính - và các nhà phát triển bắt đầu hỏi: làm sao tính biểu đồ Human Design bằng lập trình?

Bài viết này nói về khía cạnh kỹ thuật: phép tính HD là gì, API nào hỗ trợ nó và cách tích hợp tính năng HD vào ứng dụng của bạn.

Human Design được xây dựng trên ba hệ thống cổ điển:

• Chiêm tinh phương Tây: vị trí các hành tinh tại thời điểm sinh
• Kinh Dịch (I Ching): 64 quẻ, được ánh xạ vào 64 “cổng” (gate)
• Hệ thống luân xa: chín “trung tâm” (các nút năng lượng)

Phép tính nhận dữ liệu sinh và trả về bodygraph - bản đồ trực quan gồm:

• Type (Manifestor, Generator, Manifesting Generator, Projector, Reflector) - chữ ký năng lượng
• Strategy: cách đưa ra quyết định
• Authority: nên tin vào trung tâm nào khi quyết định (Sacral, Emotional, Splenic, v.v.)
• Profile: tổ hợp các line (1/3, 4/6, v.v.)
• Channels: các kết nối giữa những trung tâm, định hình tính cách
• Incarnation Cross: mục đích sống, suy ra từ bốn vị trí then chốt

Bên dưới, mỗi cổng trong 64 cổng tương ứng với một khoảng kinh độ hoàng đạo. Kinh độ các hành tinh của bạn lúc sinh được ánh xạ vào những cổng cụ thể (và các line bên trong chúng). Phép tính “Design” - thời điểm Mặt Trời lùi 88° so với lúc sinh - rơi vào khoảng 3 tháng trước đó.

Human Design dùng hai thời điểm:

1. Personality: thời điểm sinh thực tế. Đây là phần “ý thức”.
2. Design: khi Mặt Trời ở vị trí lùi 88° so với vị trí lúc sinh. Đây là phần “vô thức”.

Mỗi kích hoạt cổng thuộc về một trong hai. Một biểu đồ đầy đủ có 13 + 13 = 26 kích hoạt.

Chính điều này khiến phép tính HD nặng hơn một lá số chiêm tinh thông thường - thực chất bạn đang tính hai lá số.

Phần lớn API chiêm tinh hoặc không hỗ trợ HD, hoặc chỉ hỗ trợ hời hợt (chỉ type + strategy). Một triển khai HD đầy đủ cần:

• Ánh xạ 64 cổng (bảng tra cứu)
• 6 line cho mỗi cổng (384 ô)
• 9 trung tâm với logic defined/open
• 36 channel (mỗi channel nối hai trung tâm)
• Tính Incarnation Cross
• Suy ra Profile từ line của cổng Mặt Trời + line của cổng Trái Đất (Personality và Design)

API làm được tất cả những điều này rất hiếm. AstroWay API có 12 endpoint HD - mức bao phủ sâu nhất chúng tôi từng thấy ở một API thương mại.

Giả sử bạn thêm HD vào một ứng dụng chiêm tinh sẵn có. Hãy bắt đầu với endpoint chính:

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}`);

Cấu trúc phản hồi:

{
  "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": [...]
}

Penta là kỹ thuật tìm hiểu động lực đội nhóm trong nhóm 3–5 người. Nó hiếm gặp - phần lớn công cụ tính HD không cung cấp. Nhưng đây là mỏ vàng cho HR-tech, nền tảng coaching và ứng dụng 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}`);

Biểu đồ HD nhạy cảm với giờ sinh. Sai 10 phút có thể đổi Profile (ví dụ 1/3 → 1/4). Với người dùng không biết chính xác giờ sinh, hãy chạy phân tích 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

Dùng nó để cảnh báo người dùng: “Với độ chính xác này, profile của bạn có thể bị lệch. Hãy cân nhắc hiệu chỉnh giờ sinh”.

Nếu bạn xây dựng ứng dụng tập trung vào HD:

• Người dùng cơ bản: 1 biểu đồ HD khi đăng ký, cache vĩnh viễn = 50 credit một lần
• Người dùng tích cực: transit định kỳ + compatibility = ~200 credit/tháng
• 100 DAU dùng HD ở mức vừa phải: ~110 000 credit/tháng → Starter ($19/tháng) dư sức đáp ứng
• 1 000 DAU: ~150 000 credit/tháng → Pro ($59/tháng)

Yêu cầu compatibility nặng nhất (100 credit). Hãy cache kết quả cho mỗi cặp người dùng vĩnh viễn (chúng không thay đổi).

Bodygraph thường được vẽ bằng SVG. API trả về dữ liệu về các trung tâm và channel; bạn tự vẽ phần hiển thị. Ví dụ:

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>
  );
}

Tọa độ là một mẫu cố định (mọi bodygraph đều có cùng 9 trung tâm và 64 cổng ở cùng vị trí).

• Human Design API: trang sản phẩm với danh sách endpoint đầy đủ
• Ví dụ: Human Design: hướng dẫn chi tiết /v1/human-design
• Bắt đầu nhanh: nhận API key miễn phí (tối đa 200 biểu đồ HD/tháng trên gói Free)