# Tài liệu cho lập trình viên Hạ Tầng

> Hạ Tầng (Ha Tang) là nền tảng chăm sóc khách hàng cho doanh nghiệp Việt Nam: một hộp thư chung cho chat website, ứng dụng di động, Zalo, Messenger, Instagram, TikTok Shop, WhatsApp và email, có trợ lý AI, cùng API gửi email giao dịch, thanh toán VietQR và hóa đơn điện tử. Đây là hướng dẫn và tài liệu tham chiếu API.

- Địa chỉ REST API: https://api.hatang.dev, xác thực bằng `Authorization: Bearer ht_...`; Thanh toán có hai môi trường development và production tách biệt, chọn bằng header `Hatang-Environment`.
- SDK: @hatang/sdk (Node.js), hatang (Python), @hatang/chat-react, @hatang/chat-react-native, hatang_chat (Flutter), HatangChat (iOS), dev.hatang:chat (Android).
- MCP server cho coding agent: `npx -y @hatang/mcp` (xem guides/sdks/mcp).

## Bắt đầu

- [Giới thiệu](https://hatang.dev/vi/docs/guides/getting-started/introduction.md): Hạ Tầng là gì, gồm những module nào, và cách tìm đường trong trang tài liệu cho lập trình viên này.
- [Bắt đầu nhanh: gửi email đầu tiên](https://hatang.dev/vi/docs/guides/getting-started/quickstart-email.md): Tạo API key, xác minh tên miền gửi và gửi email đầu tiên bằng cURL, Node.js, Python hoặc PHP.
- [Bắt đầu nhanh: gắn chat lên website](https://hatang.dev/vi/docs/guides/getting-started/quickstart-chat.md): Gắn widget chat Hạ Tầng lên website bằng hai dòng mã, nhận diện người dùng đã đăng nhập, trả lời từ hộp thư và thêm chat vào ứng dụng di động.
- [Dùng Hạ Tầng với AI coding agent](https://hatang.dev/vi/docs/guides/getting-started/ai-agents.md): Cho Claude Code, Cursor, GitHub Copilot, Codex hay Windsurf tài liệu và quy tắc mới nhất của Hạ Tầng, qua MCP server, skill, Cursor rule hoặc một mục trong AGENTS.md, để agent viết tích hợp đúng.
- [Xác thực API](https://hatang.dev/vi/docs/guides/getting-started/authentication.md): Tạo API key, chọn scope, giới hạn key theo tên miền gửi hoặc origin trình duyệt, chọn môi trường Thanh toán, và xoay hoặc thu hồi key an toàn.
- [Giới hạn tần suất](https://hatang.dev/vi/docs/guides/getting-started/rate-limits.md): Giới hạn số request mỗi giây của từng module, các header báo giới hạn, hạn mức email hằng ngày và cách chờ rồi thử lại.
- [Lỗi](https://hatang.dev/vi/docs/guides/getting-started/errors.md): Định dạng lỗi mà mọi API của Hạ Tầng dùng, các lỗi hay gặp nhất và cách xử lý chúng trong code.
- [Phân trang](https://hatang.dev/vi/docs/guides/getting-started/pagination.md): Duyệt các endpoint danh sách của Hạ Tầng bằng con trỏ after, tham số limit, has_more và next_cursor.
- [Idempotency](https://hatang.dev/vi/docs/guides/getting-started/idempotency.md): Thử lại an toàn lệnh gửi email, tạo thanh toán và gửi tin nhắn chat bằng header Idempotency-Key, và xử lý xung đột idempotency.
- [Webhook](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md): Nhận HTTP callback có chữ ký cho sự kiện của mọi module, xác minh chữ ký, xử lý thử lại và gửi lại, và thử trên máy của bạn.
- [Thư viện API](https://hatang.dev/vi/docs/guides/getting-started/api-libraries.md): SDK Node.js chính thức, các SDK chat cho web và di động, và cách sinh client cho mọi ngôn ngữ từ bản OpenAPI.
- [Bảo mật](https://hatang.dev/vi/docs/guides/getting-started/security.md): Bảo vệ tích hợp Hạ Tầng bằng cách giữ an toàn API key và các secret, giới hạn và xoay key, xác minh webhook và xác minh danh tính trong chat.

## Email

- [Hạ Tầng Email](https://hatang.dev/vi/docs/guides/email/overview.md): Gửi email giao dịch và email marketing từ tên miền của bạn qua API tương thích Resend và SMTP relay, chạy trên Amazon SES.
- [Tên miền](https://hatang.dev/vi/docs/guides/email/domains.md): Thêm tên miền gửi, khai báo bản ghi DKIM, SPF, return path và DMARC, rồi xác minh để gửi được email từ tên miền đó.
- [Gửi email](https://hatang.dev/vi/docs/guides/email/sending.md): Gửi email bằng POST /emails và POST /emails/batch, kèm tệp đính kèm, tag, header, hẹn giờ và idempotency, rồi theo dõi trạng thái và sự kiện của email.
- [SMTP relay](https://hatang.dev/vi/docs/guides/email/smtp.md): Gửi email qua smtp.hatang.dev cổng 5870 với STARTTLS, kèm cấu hình mẫu cho Nodemailer, Laravel, Django, Rails, Spring Boot, WordPress, PHPMailer và Postfix.
- [Templates](https://hatang.dev/vi/docs/guides/email/templates.md): Soạn mẫu email có biến, publish, rồi gửi bằng id hoặc alias từ API, chiến dịch email và automations.
- [Theo dõi mở và nhấp](https://hatang.dev/vi/docs/guides/email/tracking.md): Bật theo dõi lượt mở và lượt nhấp theo từng tên miền, phục vụ link theo dõi từ tên miền phụ của bạn, và hiểu theo dõi ghi lại những gì.
- [Nhận email](https://hatang.dev/vi/docs/guides/email/receiving.md): Nhận thư gửi tới tên miền của bạn dưới dạng webhook email.received, rồi đọc nội dung và tệp đính kèm qua API.
- [Nhóm email](https://hatang.dev/vi/docs/guides/email/groups.md): Chuyển thư gửi tới một địa chỉ trên tên miền của bạn, như team@congty.vn, cho nhiều người, giống nhóm của Google Workspace.
- [Contacts, segments và topics](https://hatang.dev/vi/docs/guides/email/audiences.md): Sắp xếp người nhận chiến dịch email bằng contact, thuộc tính tuỳ chỉnh, segment và topic, qua dashboard hoặc API.
- [Chiến dịch email](https://hatang.dev/vi/docs/guides/email/broadcasts.md): Soạn một email marketing và gửi tới mọi contact đang nhận trong một segment, gửi ngay hoặc hẹn giờ, kèm thẻ trộn và huỷ đăng ký một chạm.
- [Automations](https://hatang.dev/vi/docs/guides/email/automations.md): Dựng chuỗi email cho từng contact, khởi động khi ứng dụng của bạn gửi sự kiện, với bước chờ, chờ sự kiện khác, điều kiện và cập nhật contact.
- [Danh sách chặn và thư trả lại](https://hatang.dev/vi/docs/guides/email/suppressions-and-bounces.md): Thư trả lại cứng, báo spam và huỷ đăng ký đưa địa chỉ vào danh sách chặn ra sao, điều gì xảy ra khi bạn gửi tới địa chỉ đó, và cách gỡ ra.
- [Khả năng vào hộp thư](https://hatang.dev/vi/docs/guides/email/deliverability.md): Đưa email vào hộp thư chính với SPF, DKIM và DMARC căn chỉnh đúng, làm nóng tên miền cẩn thận, danh sách sạch và các tín hiệu Hạ Tầng cung cấp.
- [Số liệu và logs](https://hatang.dev/vi/docs/guides/email/metrics-and-logs.md): Xem số thư tới hộp thư, mở, nhấp, bị trả lại và bị báo spam trong dashboard hoặc qua GET /emails/metrics, và gỡ lỗi tích hợp bằng log các lệnh gọi API.
- [Chuyển từ Resend](https://hatang.dev/vi/docs/guides/email/migrate-from-resend.md): Chuyển từ Resend sang Hạ Tầng Email, những gì giữ nguyên, những gì khác, và cách các trường của SendGrid, Postmark ánh xạ sang API của Hạ Tầng.

## Hỗ trợ khách hàng

- [Tổng quan](https://hatang.dev/vi/docs/guides/support/overview.md): Hạ Tầng Hỗ trợ là hộp thư đa kênh; tìm hiểu các khái niệm (site, hội thoại, khách hàng, kênh, nhân viên) và đường đi của một tin nhắn.
- [Cài đặt widget](https://hatang.dev/vi/docs/guides/support/web-widget/install.md): Tạo kênh website, dán đoạn mã hai thẻ vào mọi trang và kiểm tra widget chat đã tải trên tên miền của bạn.
- [Cấu hình widget](https://hatang.dev/vi/docs/guides/support/web-widget/configuration.md): Đặt giao diện, nút mở chat, lời chào, form trước khi chat, giờ làm việc và nơi hiện widget trong dashboard, và ghi đè theo từng trang bằng window.HATANG_CONFIG.
- [JavaScript API](https://hatang.dev/vi/docs/guides/support/web-widget/javascript-api.md): Điều khiển widget từ trang web bằng lệnh $hatang.push, nghe sự kiện, gửi lead từ form của bạn và theo dõi chuyển đổi từ chat.
- [Ứng dụng di động](https://hatang.dev/vi/docs/guides/support/mobile-apps.md): Đưa chat vào ứng dụng iOS, Android, Flutter hoặc React Native bằng khoá ứng dụng gắn với một website của bạn.
- [Nhận diện khách](https://hatang.dev/vi/docs/guides/support/web-widget/identity-verification.md): Ký các lời gọi identify bằng mã bí mật định danh của site để hộp thư tin user ID, nối mọi phiên của người dùng đã đăng nhập và không cho khách giả mạo nhau.
- [Mua trong ứng dụng và gói thuê bao](https://hatang.dev/vi/docs/guides/support/in-app-purchases.md): Hiện gói và giao dịch mua trên App Store, Google Play và website của từng khách trên hồ sơ, cho nhân viên và trợ lý AI. Hai cách gửi, từ app có kết nối cửa hàng hoặc từ backend của bạn, kèm cấu hình, code, nhập lịch sử và thử nghiệm.
- [Tự động hoá](https://hatang.dev/vi/docs/guides/support/automation.md): Phân phối hội thoại, chạy bot kịch bản, phản ứng theo sự kiện bằng chu trình, hiện chiến dịch chủ động và theo dõi SLA trong Hạ Tầng Hỗ trợ.
- [Trợ lý AI](https://hatang.dev/vi/docs/guides/support/ai-assistant.md): Thiết lập trợ lý AI của Hạ Tầng để trả lời khách từ kho kiến thức, gợi ý câu trả lời cho nhân viên và chuyển cho người khi cần.
- [Knowledge API](https://hatang.dev/vi/docs/guides/support/knowledge-api.md): Đẩy trung tâm trợ giúp, CMS hoặc tài liệu sản phẩm của bạn vào kiến thức của trợ lý AI theo mã của chính bạn, đồng bộ sau mỗi lần deploy và tìm kiếm trong đó.
- [Zalo ZNS](https://hatang.dev/vi/docs/guides/support/zns.md): Gửi tin nhắn mẫu Zalo ZNS đã được duyệt, như xác nhận đơn hàng hay nhắc thanh toán, tới số điện thoại của khách qua Zalo Official Account.
- [Realtime](https://hatang.dev/vi/docs/guides/support/realtime.md): Widget, SDK di động và ứng dụng của nhân viên nói chuyện với chat gateway thế nào, và nên dùng giao diện nào cho client hay tích hợp của riêng bạn.
- [REST API Hỗ trợ](https://hatang.dev/vi/docs/guides/support/rest-api.md): Đọc hội thoại, trả lời thay đội, đổi trạng thái và tag, nhận webhook của hộp thư từ server của bạn.

## SDKs

- [SDK Hạ Tầng: chat, email và thanh toán](https://hatang.dev/vi/docs/guides/sdks/overview.md): Các SDK của Hạ Tầng cho website, ứng dụng di động và server, mỗi SDK làm gì và phiên bản nào đang được hỗ trợ.
- [SDK Node.js cho email, chat và thanh toán](https://hatang.dev/vi/docs/guides/sdks/node.md): Cài @hatang/sdk và gọi mọi phần của API Hạ Tầng từ Node.js, Bun hoặc edge runtime, với kết quả có kiểu và hàm xác minh webhook, IPN.
- [SDK Python cho API Hạ Tầng](https://hatang.dev/vi/docs/guides/sdks/python.md): Cài hatang từ PyPI và gọi API Hạ Tầng từ Python (Django, FastAPI, Flask, worker), đồng bộ hoặc asyncio, với kiểu dữ liệu cho request và hàm xác minh webhook, IPN, identity.
- [MCP server cho AI coding agent](https://hatang.dev/vi/docs/guides/sdks/mcp.md): Kết nối Claude Code, Cursor, VS Code hoặc Windsurf với Hạ Tầng bằng @hatang/mcp, để agent đọc tài liệu mới nhất và có thể gửi email, tạo thanh toán VietQR, xử lý hộp thư hỗ trợ.
- [Widget chat cho React và Next.js](https://hatang.dev/vi/docs/guides/sdks/react.md): Nạp widget chat Hạ Tầng trong ứng dụng React hoặc Next.js bằng một component, và điều khiển widget từ code bằng một hook có kiểu.
- [SDK chat cho Flutter](https://hatang.dev/vi/docs/guides/sdks/flutter.md): Đưa chat hỗ trợ Hạ Tầng vào ứng dụng Flutter với hatang_chat, màn hình chat native kèm thông báo đẩy, deep link và hook in-app purchase.
- [SDK chat cho React Native](https://hatang.dev/vi/docs/guides/sdks/react-native.md): Đưa chat hỗ trợ Hạ Tầng vào ứng dụng React Native hoặc Expo với @hatang/chat-react-native, không cần mã native riêng.
- [SDK chat cho iOS (Swift)](https://hatang.dev/vi/docs/guides/sdks/ios.md): Đưa chat hỗ trợ Hạ Tầng dạng native vào ứng dụng iOS bằng Swift package HatangChat, từ cài đặt tới thông báo đẩy, deep link và tuỳ biến giao diện.
- [SDK chat cho Android (Kotlin)](https://hatang.dev/vi/docs/guides/sdks/android.md): Đưa chat hỗ trợ Hạ Tầng dạng native vào ứng dụng Android bằng dev.hatang:chat, từ cài đặt tới thông báo đẩy, deep link và tuỳ biến giao diện.
- [Thông báo đẩy](https://hatang.dev/vi/docs/guides/sdks/push-notifications.md): Gửi trả lời của bộ phận hỗ trợ tới điện thoại của khách bằng thông báo đẩy qua dự án Firebase của bạn, và hiểu khi nào Hạ Tầng gửi.
- [Tương thích](https://hatang.dev/vi/docs/guides/sdks/compatibility.md): Phiên bản SDK nào đang được hỗ trợ, mỗi SDK nói phiên bản giao thức chat nào, gateway tối thiểu, và cách Hạ Tầng đánh số phiên bản SDK.

## Thanh toán

- [Tổng quan](https://hatang.dev/vi/docs/guides/payments/overview.md): Nhận chuyển khoản VietQR thẳng vào tài khoản ngân hàng của bạn, tự động khớp với đơn hàng và phát hành hóa đơn điện tử.
- [Bắt đầu nhanh](https://hatang.dev/vi/docs/guides/payments/quickstart.md): Nhận khoản thanh toán VietQR đầu tiên ở môi trường development, không cần tài khoản ngân hàng thật.
- [Môi trường và sandbox](https://hatang.dev/vi/docs/guides/payments/environments.md): Môi trường development và production của Hạ Tầng Thanh toán khác nhau thế nào, cách chọn môi trường cho từng request và cách giả lập chuyển khoản.
- [SDK JavaScript](https://hatang.dev/vi/docs/guides/payments/sdk-javascript.md): Tạo payment, xác nhận thanh toán, xác minh IPN và webhook với @hatang/sdk.
- [Liên kết ngân hàng](https://hatang.dev/vi/docs/guides/payments/bank-connections.md): Liên kết tài khoản ngân hàng khách hàng chuyển tiền vào, cấu hình cách khớp giao dịch, hủy liên kết và khôi phục giao dịch bị sót bằng sao kê.
- [Nhận giao dịch không cần tạo đơn](https://hatang.dev/vi/docs/guides/payments/transactions.md): Nhận thông báo cho mọi giao dịch vào tài khoản, kèm mã đơn của bạn tìm được trong nội dung, mà không phải tạo payment cho từng đơn.
- [Tạo thanh toán](https://hatang.dev/vi/docs/guides/payments/create-payment.md): Tạo payment cho đơn hàng, để người mua thanh toán bằng VietQR, và theo dõi payment qua từng trạng thái.
- [Hóa đơn điện tử](https://hatang.dev/vi/docs/guides/payments/einvoices.md): Phát hành hóa đơn điện tử qua tài khoản Mắt Bão của bạn, tự động khi đơn đã thanh toán hoặc theo yêu cầu, và đối soát tiền vào với hóa đơn.
- [Cách người mua thanh toán](https://hatang.dev/vi/docs/guides/payments/buyer-flow.md): Các cách người mua trả một payment của Hạ Tầng (VietQR, trang checkout có sẵn, chuyển khoản thủ công) và cách tự xây trang thanh toán.
- [Nhận kết quả](https://hatang.dev/vi/docs/guides/payments/payment-results.md): Cách server của bạn biết payment đã thay đổi, qua IPN, webhook hoặc polling, và cách xử lý an toàn.
- [Xác minh IPN](https://hatang.dev/vi/docs/guides/payments/verify-ipn.md): Kiểm tra chữ ký HMAC-SHA256 của mọi lời gọi IPN trước khi tin, kèm ví dụ bằng Node.js, Python, PHP và C#.
- [Webhook](https://hatang.dev/vi/docs/guides/payments/webhooks.md): Nhận mọi sự kiện payment, giao dịch, tài khoản ngân hàng và hóa đơn điện tử của doanh nghiệp, xác minh chữ ký Svix và xử lý thử lại.
- [Lên production](https://hatang.dev/vi/docs/guides/payments/go-live.md): Chuyển tích hợp Hạ Tầng Thanh toán từ development sang production, test bằng tiền thật, và giữ hệ thống ổn định sau khi chạy thật.

## Công thức theo tác vụ

- [Gửi email giao dịch từ Node.js và Next.js](https://hatang.dev/vi/docs/guides/recipes/send-email-nodejs.md): Gửi email xác nhận đơn hàng, đặt lại mật khẩu, biên nhận từ Node.js, Next.js hoặc Bun bằng @hatang/sdk, từ tên miền đã xác minh của bạn, gửi lại an toàn với idempotency key.
- [Nhận thanh toán chuyển khoản VietQR trong ứng dụng](https://hatang.dev/vi/docs/guides/recipes/vietqr-payments.md): Nhận thanh toán chuyển khoản bằng mã VietQR trong Node.js hoặc Next.js: tạo thanh toán, đưa người mua tới trang thanh toán, xác minh IPN có chữ ký, và kiểm tra trước khi giao hàng.
- [Gửi tin Zalo ZNS từ backend](https://hatang.dev/vi/docs/guides/recipes/zalo-zns.md): Gửi tin mẫu Zalo ZNS đã duyệt (xác nhận đơn hàng, nhắc thanh toán, cập nhật giao hàng) tới số điện thoại Việt Nam từ Node.js hoặc bất kỳ ngôn ngữ nào qua API Hạ Tầng.
- [Thêm chat trực tuyến vào website Next.js hoặc React](https://hatang.dev/vi/docs/guides/recipes/live-chat-nextjs.md): Gắn widget chat trực tuyến vào website Next.js, React hoặc HTML thường bằng vài dòng, định danh người dùng đã đăng nhập, và trả lời từ một hộp thư chung với Zalo, Messenger, Instagram và email.
- [Xuất hoá đơn điện tử qua API](https://hatang.dev/vi/docs/guides/recipes/einvoice-api.md): Xuất hoá đơn điện tử theo mã số thuế của bạn từ code, tự động khi thanh toán VietQR hoàn tất hoặc xuất riêng, qua chính tài khoản nhà cung cấp hoá đơn của bạn.

## Tích hợp

- [WordPress](https://hatang.dev/vi/docs/guides/integrations/wordpress.md): Thêm widget chat Hạ Tầng vào website WordPress bằng plugin Hạ Tầng Chat, chọn vị trí và ngôn ngữ, và nhận diện người dùng đã đăng nhập.

## Tham chiếu

- [Các endpoint REST API](https://hatang.dev/vi/docs/reference/api.md): Đặc tả OpenAPI 3.1 https://hatang.dev/docs/openapi.json
- [Các endpoint chat gateway](https://hatang.dev/vi/docs/reference/chat-gateway.md): Đặc tả OpenAPI 3.1 https://hatang.dev/docs/chat-gateway-openapi.json
- [Tài liệu tham chiếu](https://hatang.dev/vi/docs/reference/overview.md): Mọi API, sự kiện, giao thức, mã lỗi và giới hạn của Hạ Tầng, sinh tự động từ mã nguồn.
- [Sự kiện webhook](https://hatang.dev/vi/docs/reference/webhooks.md): Mọi sự kiện Hạ Tầng gửi tới webhook của bạn, kèm liên kết tới payload của từng sự kiện.
- [Mã lỗi](https://hatang.dev/vi/docs/reference/errors.md): Mọi mã lỗi của API, giao thức realtime và SMTP relay, kèm cách xử lý.
- [Giới hạn](https://hatang.dev/vi/docs/reference/limits.md): Giới hạn tốc độ và kích thước của các API Hạ Tầng.
- [Giao thức realtime](https://hatang.dev/vi/docs/reference/realtime-protocol.md): Giao thức WebSocket và HTTP (v1) mà widget chat và các SDK di động nói với gateway chat của Hạ Tầng, cho ai muốn tự viết client.

## Optional

- [Nhật ký thay đổi](https://hatang.dev/vi/docs/changelog): https://hatang.dev/vi/docs/changelog/rss.xml
- [Hạ Tầng cho AI coding agent](https://hatang.dev/vi/docs/changelog/2026/11/03/ai-coding-agents.md)
- [Trang SDK trên npm, pub.dev, PyPI, Maven Central và wordpress.org](https://hatang.dev/vi/docs/changelog/2026/11/03/sdk-listings.md)
- [Nhóm email](https://hatang.dev/vi/docs/changelog/2026/11/02/email-groups.md)
- [Email hỗ trợ không cần chuyển tiếp](https://hatang.dev/vi/docs/changelog/2026/11/02/support-email-receiving.md)
- [API Email kiểm tra scope của API key](https://hatang.dev/vi/docs/changelog/2026/10/24/email-scopes.md)
- [Trung tâm trợ giúp tại hatang.dev/vi/help](https://hatang.dev/vi/docs/changelog/2026/10/24/help-center.md)
- [@hatang/sdk 0.4.0: mặc định gọi production, template, liên hệ dùng chung, automation](https://hatang.dev/vi/docs/changelog/2026/10/24/node-sdk-0-4-0.md)
- [Kênh WhatsApp, Telegram, X và LINE](https://hatang.dev/vi/docs/changelog/2026/10/24/whatsapp-telegram-x-line.md)
- [Tài liệu cho lập trình viên chuyển về hatang.dev/docs](https://hatang.dev/vi/docs/changelog/2026/10/23/developer-hub.md)
- [API: payload webhook trong bản đặc tả OpenAPI](https://hatang.dev/vi/docs/changelog/2026/10/23/openapi-webhooks.md)
- [llms-full.txt](https://hatang.dev/vi/docs/llms-full.txt)