Thư viện API

Bạn gọi được REST API của Hạ Tầng từ bất kỳ ngôn ngữ nào bằng một HTTP client thông thường. Trang này liệt kê các thư viện chính thức giúp việc đó dễ hơn, và chỉ cách sinh client có kiểu dữ liệu từ bản OpenAPI cho những ngôn ngữ chưa có SDK chính thức.

Node.js: @hatang/sdk

SDK server chính thức bao gồm Email, Hỗ trợ, Sản phẩm, CRM, Thanh toán và hoá đơn điện tử, có kiểu TypeScript cho mọi request và response.

npm install @hatang/sdk

import { Hatang } from "@hatang/sdk";

const hatang = new Hatang(process.env.HATANG_API_KEY, {
  baseUrl: "https://api.hatang.dev",
  // environment: "development", // chỉ cho Thanh toán; gửi dưới dạng Hatang-Environment
});

const { data, error } = await hatang.emails.send({
  from: "Shop <[email protected]>",
  to: "[email protected]",
  subject: "Chào mừng",
  html: "<p>Chào mừng bạn đến với shop!</p>",
});

Cần biết:

• Trả kết quả, không throw. Mọi hàm trả về { data, error } và không throw khi API báo lỗi. error có statusCode, name và message như thường lệ (Lỗi). Lỗi mạng cho statusCode: 0.
• Cấu hình. Truyền key và tuỳ chọn vào constructor, hoặc đặt HATANG_API_KEY, HATANG_BASE_URL và HATANG_ENVIRONMENT. Luôn đặt base URL là https://api.hatang.dev.
• Namespace theo đúng API: emails, batch, domains, templates, contacts, contactProperties, audiences, segments, topics, broadcasts, automations, events, apiKeys, webhooks, logs, usage, chat, payments và einvoices.
• Idempotency. Các hàm tạo mới nhận tuỳ chọn { idempotencyKey } (Idempotency).
• Hàm hỗ trợ webhook. verifyWebhook và constructWebhookEvent kiểm tra chữ ký webhook; verifyIpn và constructIpnEvent kiểm tra lời gọi IPN của Thanh toán (Webhook).
• React Email. Truyền một element react vào emails.send, SDK sẽ render ra HTML và văn bản thuần (cài thêm @react-email/render và react).

Hướng dẫn SDK Node.js đi qua từng namespace kèm ví dụ.

SDK chat cho web và di động

SDK chat chạy trên trình duyệt và ứng dụng của khách. Chúng kết nối tới chat gateway bằng site id công khai (và khoá ứng dụng trên di động), không bao giờ bằng API key.

Nền tảng	Gói
Website	https://chat.hatang.dev/widget.js
React / Next.js	@hatang/chat-react
WordPress	Plugin Hạ Tầng Chat
Flutter	hatang_chat
React Native / Expo	@hatang/chat-react-native
iOS (Swift)	HatangChat
Android (Kotlin)	dev.hatang:chat

Tổng quan SDK dẫn tới hướng dẫn của từng SDK, các phiên bản được hỗ trợ và giao thức realtime chúng dùng chung.

Ngôn ngữ khác

Hiện chưa có SDK server chính thức cho PHP, Python hay Go. Hai lựa chọn tốt:

• Gọi thẳng REST API. Mọi hướng dẫn trong trang tài liệu này đều có mẫu cURL, Python và PHP. API chỉ là JSON qua HTTPS với Bearer token.
• Sinh client từ bản OpenAPI, như bên dưới.

Bản OpenAPI

REST API được mô tả bằng một tài liệu OpenAPI 3.1, sinh ra từ chính code phục vụ API:

Bản mô tả	URL
REST API	https://api.hatang.dev/openapi.json
Chat gateway	https://chat.hatang.dev/openapi.json

Xem trong tham chiếu REST API và tham chiếu chat gateway, hoặc nhập vào một API client như Postman hay Insomnia để gọi thử bằng tay.

Sinh client

Trỏ trình sinh mã vào URL của bản mô tả. Vài ví dụ:

# Kiểu TypeScript (dùng với openapi-fetch hoặc hàm fetch của bạn)
npx openapi-typescript https://api.hatang.dev/openapi.json -o hatang.d.ts

# Python
pipx run openapi-python-client generate --url https://api.hatang.dev/openapi.json

# Nhiều ngôn ngữ, gồm PHP, Java, Kotlin, C# và Ruby
npx @openapitools/openapi-generator-cli generate \
  -i https://api.hatang.dev/openapi.json -g php -o ./hatang-php

ghi chú

Bản mô tả dùng OpenAPI 3.1. Hãy kiểm tra trình sinh mã của bạn hỗ trợ 3.1; một số chỉ hỗ trợ đầy đủ 3.0. Sinh lại client khi nâng cấp, vì endpoint và trường mới được thêm vào bản mô tả ngay khi ra mắt.

Client sinh ra chỉ gửi những gì bạn đưa, nên hãy nhớ các quy tắc chung: header Authorization: Bearer, Idempotency-Key khi gửi email và tạo thanh toán, phân trang bằng after, và thử lại khi gặp 429 (Giới hạn tần suất).

Bước tiếp theo

• SDK Node.js
• Tổng quan SDK
• Tham chiếu REST API