Hướng dẫn API Thiết kế Con người: xây dựng ứng dụng HD trên 12 endpoint

🕓 Bản ghi từ 2026-04-14, cập nhật 2026-05-09. Giờ đây, SDK TS / Python / PHP đã có trên các kho công khai — @astroway/sdk (npm), astroway (PyPI), astroway/sdk (Packagist). Chi tiết xem trong changelog.

Human Design đã phát triển từ một hệ thống bí truyền của những năm 1990 thành một khuôn khổ phát triển cá nhân phổ biến. Các ứng dụng có hàng triệu người dùng đã khiến nó trở nên bình thường — và giờ đây các nhà phát triển đặt ra câu hỏi: làm thế nào để tính toán biểu đồ Human Design theo chương trình?

Trong bài viết này, chúng ta sẽ đi sâu vào khía cạnh kỹ thuật: Human Design được tính toán như thế nào, những API nào hỗ trợ nó và cách tích hợp tính năng Human Design vào ứng dụng của bạn.

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

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

Tính toán sử dụng dữ liệu sinh và trả về bodygraph — một biểu đồ trực quan với:

• Kiểu (Manifestor, Generator, Manifesting Generator, Projector, Reflector) — chữ ký năng lượng
• Chiến lược — cách đưa ra quyết định
• Thẩm quyền — trung tâm nào nên được tin tưởng khi đưa ra quyết định (Sacral, Emotional, Splenic, v.v.)
• Cá tính — sự kết hợp của các dòng (1/3, 4/6, v.v.)
• Kênh — kết nối giữa các trung tâm, hình thành nên tính cách
• Thập tự Hóa thân — sứ mệnh cuộc đời, bắt nguồn từ bốn vị trí quan trọng

Bên dưới, mỗi trong số 64 cánh cổng tương ứng với một phạm vi kinh độ hoàng đạo. Kinh độ của các hành tinh vào thời điểm sinh được ánh xạ tới các cánh cổng cụ thể (và các dòng bên trong chúng). Tính toán “Design” — dịch chuyển Mặt Trời 88° trước thời điểm sinh — tương đương khoảng 3 tháng sớm hơn.

Human Design sử dụng hai thời điểm sinh:

1. Personality — thời điểm sinh thực tế. Đây là khía cạnh “có ý thức”.
2. Design — khi Mặt Trời ở vị trí 88° trước thời điểm sinh. Đây là khía cạnh “vô thức”.

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

Chính điều này khiến việc tính toán Human Design trở nên phức tạp hơn so với biểu đồ chiêm tinh tiêu chuẩn — bạn thực sự đang tính toán hai biểu đồ.

Hầu hết các API chiêm tinh không hỗ trợ Human Design hoặc chỉ hỗ trợ ở mức độ sơ sài (chỉ kiểu + chiến lược). Để triển khai đầy đủ Human Design, bạn cần:

• Bảng tra cứu 64 cánh cổng
• 6 dòng cho mỗi cánh cổng (384 ô)
• 9 trung tâm với logic defined/open
• 36 kênh (mỗi kênh kết nối hai trung tâm)
• Tính toán Thập tự Hóa thân
• Trả về Cá tính từ dòng cánh cổng Mặt Trời + dòng cánh cổng Trái Đất (Personality và Design)

Những API có thể làm tất cả điều này rất hiếm. AstroWay API cung cấp 12 endpoints Human Design — mức độ bao phủ sâu nhất mà chúng tôi từng thấy trong một API thương mại.

Hãy tưởng tượng bạn đang thêm Human Design vào một ứng dụng chiêm tinh hiện có. 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({
  date: '1990-07-14',
  time: '14:30:00',
  timezoneOffset: 3,
  latitude: 50.4501,
  longitude: 30.5234,
});

console.log(`Kiểu: ${hd.type}`);         // ví dụ: "Generator"
console.log(`Chiến lược: ${hd.strategy}`); // ví dụ: "To Respond"
console.log(`Thẩm quyền: ${hd.authority}`); // ví dụ: "Sacral"
console.log(`Cá tính: ${hd.profile}`);   // ví dụ: "1/3"
console.log(`Kênh xác định: ${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à một kỹ thuật hiểu động lực nhóm trong các nhóm 3–5 người. Đây là điều hiếm có — hầu hết các công cụ tính Human Design đều không cung cấp nó. Nhưng đây là “vàng” cho các nền tảng HR-tech, coaching và team-building.

const penta = await client.hdPenta({
  members: [
    { 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(`Kiểu Penta: ${penta.type}`);
console.log(`Kênh xác định trong nhóm: ${penta.definedChannels.length}`);

Bản đồ Human Design rất nhạy cảm với thời gian sinh. Sai lệch 10 phút có thể thay đổi Cá tính (ví dụ: 1/3 → 1/4). Đối với người dùng không nhớ chính xác thời gian sinh, hãy chạy phân tích sensitivity:

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

// sensitivity sẽ cho thấy những trường nào thay đổi khi dịch chuyển thời gian ±5/15/30 phút

Hãy sử dụng điều này để cảnh báo người dùng: “Với độ chính xác này, cá tính của bạn có thể thay đổi. Hãy cân nhắc việc hiệu chỉnh lại thời gian sinh.”

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

• Người dùng cơ bản: 1 bản đồ Human Design khi đăng ký, được lưu vào cache vĩnh viễn = 50 credit một lần
• Người dùng tích cực: chuyển động định kỳ + tương thích = ~200 credit/tháng
• 100 DAU với mức sử dụng Human Design vừa phải: ~110.000 credit/tháng → Starter ($19/tháng) dễ dàng đáp ứng
• 1.000 DAU: ~150.000 credit/tháng → Pro ($59/tháng)

Các yêu cầu tương thích là tốn kém nhất (100 credit). Hãy lưu kết quả vào cache cho mỗi cặp người dùng vĩnh viễn (chúng không thay đổi).

Việc render bodygraph thường được thực hiện thông qua SVG. API trả về dữ liệu về các trung tâm và kênh; bạn sẽ render hình ảnh. 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>
  );
}

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

• Human Design API — trang sản phẩm với danh sách đầy đủ các endpoints
• Ví dụ: Human Design — hướng dẫn chi tiết về /v1/human-design
• Khởi đầu nhanh chóng — nhận API key miễn phí (lên tới 200 bản đồ Human Design/tháng ở gói Free)