SDK, Agent SDK và CLI
Mọi đoạn mã dưới đây sinh ra từ chính đặc tả OpenAPI mà trang này phát hành, nên máy chủ, header xác thực và endpoint làm ví dụ luôn khớp với 455 endpoint bạn đang được phép gọi. Chọn ngôn ngữ, dán vào máy, chạy.
Ngôn ngữ
TypeScript
Ổn địnhNode 20 trở lên. Tệp phải là ESM ("type": "module" trong package.json) thì await ở cấp cao nhất mới hợp lệ. AbortSignal.timeout đặt hạn chờ 15 giây — bỏ nó đi thì một endpoint chậm sẽ treo tiến trình vô hạn.
# Node 20 trở lên đã có fetch trong nhân (undici), không cần thư viện HTTP. npm install --save-dev typescript tsx npx tsx vi-du.ts
// Dùng fetch có sẵn của Node 20+ thay vì axios/got: bớt một phụ thuộc phải
// vá bảo mật, và cùng đoạn mã này chạy nguyên vẹn trên trình duyệt,
// Cloudflare Workers, Deno và Bun.
const khoa = process.env.HITECHCLOUD_API_KEY;
if (!khoa) {
throw new Error('Thiếu biến môi trường HITECHCLOUD_API_KEY.');
}
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
const phanHoi = await fetch('https://api-tools.hitechcloud.vn/api/tax/business/0316954486', {
headers: {
'X-API-Key': khoa,
Accept: 'application/json',
},
signal: AbortSignal.timeout(15_000),
});
if (!phanHoi.ok) {
const loi = await phanHoi.json().catch(() => ({}));
throw new Error(`HTTP ${phanHoi.status}: ${loi.message ?? phanHoi.statusText}`);
}
console.log(await phanHoi.json());
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g typescript-fetch \
-o ./sdk/api-tools-typescript-fetch \
--additional-properties='npmName=@hitechcloud/api-tools,supportsES6=true'
Python
Ổn địnhPython 3.9 trở lên, httpx 0.27 trở lên. raise_for_status() biến 401/403/429 thành ngoại lệ — bỏ dòng đó thì mã lỗi lặng lẽ đi tiếp vào json() và báo sai chỗ.
python -m venv .venv && source .venv/bin/activate pip install "httpx>=0.27" python vi_du.py
# Chọn httpx chứ không phải requests: cùng một API cho đồng bộ và bất đồng bộ,
# có sẵn HTTP/2, và quan trọng nhất là timeout MẶC ĐỊNH khác None — requests
# không đặt hạn chờ nên một endpoint treo sẽ treo luôn tiến trình gọi.
import os
import httpx
khoa = os.environ["HITECHCLOUD_API_KEY"]
with httpx.Client(base_url="https://api-tools.hitechcloud.vn", timeout=15.0) as phien:
# Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
phan_hoi = phien.get(
"/api/tax/business/0316954486",
headers={"X-API-Key": khoa, "Accept": "application/json"},
)
phan_hoi.raise_for_status()
print(phan_hoi.json())
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g python \
-o ./sdk/api-tools-python \
--additional-properties='packageName=hitechcloud_api_tools'
CLI
Ổn địnhcurl 7.76 trở lên cho --fail-with-body; bản cũ hơn dùng -f, nhưng -f nuốt mất thân phản hồi nên bạn sẽ không đọc được thông điệp lỗi tiếng Việt. jq chỉ để in cho dễ đọc, không bắt buộc.
# macOS brew install curl jq # Debian / Ubuntu sudo apt-get install -y curl jq
# curl có sẵn trên mọi hệ điều hành và là thứ duy nhất không cần cài gì để
# kiểm chứng khoá, IP và hạn mức trước khi viết dòng mã đầu tiên. Khi báo lỗi
# cho hỗ trợ kỹ thuật, hãy gửi đúng lệnh này — nó tái hiện được ở mọi máy.
export HITECHCLOUD_API_KEY="khoa-cua-ban"
# Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
curl -sS --fail-with-body --max-time 15 \
-H "X-API-Key: $HITECHCLOUD_API_KEY" \
-H "Accept: application/json" \
"https://api-tools.hitechcloud.vn/api/tax/business/0316954486" | jq .
# Xem đủ header trả về (Retry-After khi vượt hạn mức, mã lỗi thật):
curl -i -sS --max-time 15 \
-H "X-API-Key: $HITECHCLOUD_API_KEY" \
"https://api-tools.hitechcloud.vn/api/tax/business/0316954486"
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g bash \
-o ./sdk/api-tools-bash
Go
Ổn địnhGo 1.21 trở lên (dùng kiểu any). Hạn chờ đặt bằng context chứ không bằng http.Client.Timeout để cùng một ngữ cảnh huỷ được cả chuỗi lời gọi khi người dùng bỏ ngang.
go mod init vi-du go run .
// Dùng net/http của thư viện chuẩn, không thêm phụ thuộc nào: mọi client HTTP
// của Go đều bọc quanh chính gói này, nên thêm thư viện chỉ đổi cú pháp chứ
// không đổi hành vi. Đánh đổi: phải tự đóng Body, quên là rò kết nối.
package main
import (
"context"
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
func main() {
khoa := os.Getenv("HITECHCLOUD_API_KEY")
ctx, huy := context.WithTimeout(context.Background(), 15*time.Second)
defer huy()
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
yeuCau, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api-tools.hitechcloud.vn/api/tax/business/0316954486", nil)
if err != nil {
panic(err)
}
yeuCau.Header.Set("X-API-Key", khoa)
yeuCau.Header.Set("Accept", "application/json")
phanHoi, err := http.DefaultClient.Do(yeuCau)
if err != nil {
panic(err)
}
defer phanHoi.Body.Close()
var ketQua map[string]any
if err := json.NewDecoder(phanHoi.Body).Decode(&ketQua); err != nil {
panic(err)
}
fmt.Printf("%d %v\n", phanHoi.StatusCode, ketQua)
}
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g go \
-o ./sdk/api-tools-go \
--additional-properties='packageName=hitechcloud,moduleName=github.com/hitechcloud/api-tools'
Java
ExperimentalJDK 11 trở lên. connectTimeout chỉ giới hạn lúc bắt tay, HttpRequest.timeout mới giới hạn cả lời gọi — phải đặt cả hai. Phần giải mã JSON tuỳ bạn chọn Jackson hay Gson, ví dụ này in nguyên văn.
# JDK 11 trở lên chạy thẳng tệp nguồn, không cần Maven/Gradle: java ViDu.java
// Dùng java.net.http.HttpClient có sẵn từ JDK 11 thay cho OkHttp hay Apache
// HttpClient: không thêm phụ thuộc nào vào cây build của bạn, mà vẫn có
// HTTP/2 và API bất đồng bộ. Chỉ cần OkHttp khi phải chạy trên Android cũ.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
public class ViDu {
public static void main(String[] args) throws Exception {
String khoa = System.getenv("HITECHCLOUD_API_KEY");
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(15))
.build();
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
HttpRequest yeuCau = HttpRequest.newBuilder()
.uri(URI.create("https://api-tools.hitechcloud.vn/api/tax/business/0316954486"))
.header("X-API-Key", khoa)
.header("Accept", "application/json")
.timeout(Duration.ofSeconds(15))
.GET()
.build();
HttpResponse<String> phanHoi =
client.send(yeuCau, HttpResponse.BodyHandlers.ofString());
if (phanHoi.statusCode() >= 400) {
throw new IllegalStateException("HTTP " + phanHoi.statusCode() + ": " + phanHoi.body());
}
System.out.println(phanHoi.body());
}
}
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g java \
-o ./sdk/api-tools-java \
--additional-properties='library=native,invokerPackage=vn.hitechcloud.api'
C#
Experimental.NET 8 trở lên (dùng câu lệnh cấp cao nhất). Đọc thân phản hồi TRƯỚC khi kiểm tra mã trạng thái, vì EnsureSuccessStatusCode() ném lỗi rồi thì thông điệp tiếng Việt trong thân đã mất.
dotnet new console -o vi-du cd vi-du dotnet run
// HttpClient nằm sẵn trong BCL của .NET nên không cần gói NuGet nào. Tạo MỘT
// thể hiện rồi dùng lại cho toàn ứng dụng (hoặc IHttpClientFactory trong
// ASP.NET Core): tạo mới mỗi lời gọi sẽ cạn cổng do socket ở trạng thái
// TIME_WAIT — lỗi này chỉ lộ ra khi đã lên sản xuất và tải cao.
using System.Text.Json;
var khoa = Environment.GetEnvironmentVariable("HITECHCLOUD_API_KEY")
?? throw new InvalidOperationException("Thiếu biến môi trường HITECHCLOUD_API_KEY.");
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(15) };
client.DefaultRequestHeaders.Add("X-API-Key", khoa);
client.DefaultRequestHeaders.Add("Accept", "application/json");
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
using var phanHoi = await client.GetAsync("https://api-tools.hitechcloud.vn/api/tax/business/0316954486");
var than = await phanHoi.Content.ReadAsStringAsync();
if (!phanHoi.IsSuccessStatusCode)
{
throw new HttpRequestException($"HTTP {(int)phanHoi.StatusCode}: {than}");
}
Console.WriteLine(JsonSerializer.Serialize(
JsonDocument.Parse(than).RootElement,
new JsonSerializerOptions { WriteIndented = true }));
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g csharp \
-o ./sdk/api-tools-csharp \
--additional-properties='packageName=HitechCloud.Api,targetFramework=net8.0'
PHP
ExperimentalPHP 8.1 trở lên, Guzzle 7.9 trở lên. Đặt http_errors => false để tự đọc mã lỗi: mặc định Guzzle ném ngoại lệ ở 4xx/5xx và thân phản hồi chứa thông điệp tiếng Việt bị chôn trong đối tượng ngoại lệ.
composer require guzzlehttp/guzzle:^7.9 php vi-du.php
<?php
// Guzzle 7 là client HTTP phổ biến nhất của PHP và là thứ Laravel dùng bên
// dưới Http::; chọn nó thì mã ví dụ dán được thẳng vào dự án Laravel. Bản
// thuần cURL cũng chạy nhưng phải tự xử lý chuyển hướng, hạn chờ và lỗi TLS.
require __DIR__ . '/vendor/autoload.php';
$khoa = getenv('HITECHCLOUD_API_KEY') ?: throw new RuntimeException('Thiếu biến môi trường HITECHCLOUD_API_KEY.');
$client = new GuzzleHttp\Client([
'base_uri' => 'https://api-tools.hitechcloud.vn',
'timeout' => 15,
'http_errors' => false,
]);
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
$phanHoi = $client->get('/api/tax/business/0316954486', [
'headers' => [
'X-API-Key' => $khoa,
'Accept' => 'application/json',
],
]);
$than = (string) $phanHoi->getBody();
if ($phanHoi->getStatusCode() >= 400) {
throw new RuntimeException("HTTP {$phanHoi->getStatusCode()}: {$than}");
}
print_r(json_decode($than, true, 512, JSON_THROW_ON_ERROR));
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g php \
-o ./sdk/api-tools-php \
--additional-properties='invokerPackage=HitechCloud\Api,composerPackageName=hitechcloud/api-tools'
Ruby
ExperimentalRuby 3.1 trở lên. use_ssl phải bật thủ công — thiếu nó thì net/http gọi HTTPS qua cổng 443 bằng giao thức thường và lỗi trả về không hề nhắc tới TLS.
# net/http nằm trong thư viện chuẩn, không cần gem nào. ruby vi_du.rb
# Dùng net/http của thư viện chuẩn thay vì Faraday hay HTTParty: một lời gọi
# đọc dữ liệu không đáng để kéo thêm gem vào Gemfile. Khi đã cần retry, đo
# đạc hay nhiều adapter thì hãy chuyển sang Faraday.
require "json"
require "net/http"
require "uri"
khoa = ENV.fetch("HITECHCLOUD_API_KEY")
dia_chi = URI("https://api-tools.hitechcloud.vn/api/tax/business/0316954486")
# Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
yeu_cau = Net::HTTP::Get.new(dia_chi)
yeu_cau["X-API-Key"] = khoa
yeu_cau["Accept"] = "application/json"
phan_hoi = Net::HTTP.start(
dia_chi.hostname, dia_chi.port,
use_ssl: dia_chi.scheme == "https",
open_timeout: 15, read_timeout: 15
) { |http| http.request(yeu_cau) }
raise "HTTP #{phan_hoi.code}: #{phan_hoi.body}" unless phan_hoi.is_a?(Net::HTTPSuccess)
puts JSON.pretty_generate(JSON.parse(phan_hoi.body))
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g ruby \
-o ./sdk/api-tools-ruby \
--additional-properties='gemName=hitechcloud,moduleName=HitechCloud'
Swift
ExperimentalSwift 5.7 trở lên để dùng await ở cấp cao nhất, và tệp phải đặt tên main.swift. Trên Linux bắt buộc có import FoundationNetworking, thiếu nó thì URLSession.data(for:) không tồn tại lúc biên dịch.
# URLSession nằm trong Foundation, không cần gói SwiftPM nào. swift main.swift
// URLSession là client HTTP chính thức của Apple: có sẵn trên iOS, macOS và
// Linux, tuân thủ App Transport Security và chạy nền được khi ứng dụng bị
// treo. Alamofire chỉ thêm đường cú pháp lên trên chính lớp này.
import Foundation
#if canImport(FoundationNetworking)
import FoundationNetworking
#endif
let khoa = ProcessInfo.processInfo.environment["HITECHCLOUD_API_KEY"] ?? ""
var yeuCau = URLRequest(url: URL(string: "https://api-tools.hitechcloud.vn/api/tax/business/0316954486")!)
yeuCau.httpMethod = "GET"
yeuCau.timeoutInterval = 15
yeuCau.setValue(khoa, forHTTPHeaderField: "X-API-Key")
yeuCau.setValue("application/json", forHTTPHeaderField: "Accept")
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
let (duLieu, phanHoi) = try await URLSession.shared.data(for: yeuCau)
let ma = (phanHoi as? HTTPURLResponse)?.statusCode ?? 0
let than = String(data: duLieu, encoding: .utf8) ?? ""
guard (200..<300).contains(ma) else {
fatalError("HTTP \(ma): \(than)")
}
print(than)
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g swift5 \
-o ./sdk/api-tools-swift5 \
--additional-properties='projectName=HitechCloudApi,responseAs=AsyncAwait'
Rust
ExperimentalRust 1.75 trở lên. error_for_status() biến 4xx/5xx thành Err; bỏ nó đi thì json() sẽ cố giải mã thân lỗi và báo sai nguyên nhân.
cargo new vi-du && cd vi-du cargo add reqwest --features json,rustls-tls cargo add tokio --features macros,rt-multi-thread cargo add serde_json cargo run
// reqwest là client HTTP phổ biến nhất của Rust; chọn tính năng rustls-tls
// thay cho OpenSSL mặc định để bản dựng không phụ thuộc thư viện hệ thống —
// khác biệt này quyết định việc build trong Docker alpine có chạy hay không.
use std::time::Duration;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let khoa = std::env::var("HITECHCLOUD_API_KEY")?;
let client = reqwest::Client::builder()
.timeout(Duration::from_secs(15))
.build()?;
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
let phan_hoi = client
.get("https://api-tools.hitechcloud.vn/api/tax/business/0316954486")
.header("X-API-Key", khoa)
.header("Accept", "application/json")
.send()
.await?
.error_for_status()?;
let ket_qua: serde_json::Value = phan_hoi.json().await?;
println!("{}", serde_json::to_string_pretty(&ket_qua)?);
Ok(())
}
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g rust \
-o ./sdk/api-tools-rust \
--additional-properties='packageName=hitechcloud-api,library=reqwest,supportAsync=true'
Kotlin
ExperimentalKotlin 1.9 trở lên, OkHttp 4.12, JDK 8 trở lên. Khối use { } là bắt buộc: thân phản hồi của OkHttp phải đóng, không đóng là rò kết nối cho tới khi cạn bể kết nối.
// build.gradle.kts
dependencies {
implementation("com.squareup.okhttp3:okhttp:4.12.0")
}
// OkHttp là client HTTP mặc định của hệ sinh thái JVM và Android: gộp kết nối,
// trong suốt với GZIP, và tự thử lại khi một tuyến mạng hỏng. Ktor hợp hơn nếu
// dự án đã đa nền tảng, còn cho JVM thuần thì OkHttp là lựa chọn ít bất ngờ nhất.
import okhttp3.OkHttpClient
import okhttp3.Request
import java.util.concurrent.TimeUnit
fun main() {
val khoa = System.getenv("HITECHCLOUD_API_KEY")
?: error("Thiếu biến môi trường HITECHCLOUD_API_KEY.")
val client = OkHttpClient.Builder()
.callTimeout(15, TimeUnit.SECONDS)
.build()
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
val yeuCau = Request.Builder()
.url("https://api-tools.hitechcloud.vn/api/tax/business/0316954486")
.header("X-API-Key", khoa)
.header("Accept", "application/json")
.build()
client.newCall(yeuCau).execute().use { phanHoi ->
val than = phanHoi.body?.string().orEmpty()
check(phanHoi.isSuccessful) { "HTTP ${phanHoi.code}: $than" }
println(than)
}
}
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g kotlin \
-o ./sdk/api-tools-kotlin \
--additional-properties='library=jvm-okhttp4,packageName=vn.hitechcloud.api'
Dart
ExperimentalDart 3.0 trở lên. Giải mã bằng utf8.decode(bodyBytes) chứ không dùng phanHoi.body: thuộc tính đó đoán bảng mã từ header và trả về chữ Việt sai dấu khi máy chủ không ghi rõ charset.
dart pub add http dart run vi_du.dart
// package:http do chính nhóm Dart bảo trì và là lớp bọc chung cho cả Flutter
// lẫn Dart phía máy chủ, nên cùng đoạn mã chạy trên di động, web và server.
// Gọi dart:io HttpClient trực tiếp thì mất khả năng chạy trên Flutter web.
import 'dart:convert';
import 'dart:io';
import 'package:http/http.dart' as http;
Future<void> main() async {
final khoa = Platform.environment['HITECHCLOUD_API_KEY'];
if (khoa == null) {
throw StateError('Thiếu biến môi trường HITECHCLOUD_API_KEY.');
}
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
final phanHoi = await http.get(
Uri.parse('https://api-tools.hitechcloud.vn/api/tax/business/0316954486'),
headers: {
'X-API-Key': khoa,
'Accept': 'application/json',
},
).timeout(const Duration(seconds: 15));
final than = utf8.decode(phanHoi.bodyBytes);
if (phanHoi.statusCode >= 400) {
throw HttpException('HTTP ${phanHoi.statusCode}: $than');
}
print(jsonDecode(than));
}
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g dart-dio \
-o ./sdk/api-tools-dart-dio \
--additional-properties='pubName=hitechcloud_api,pubLibrary=hitechcloud.api'
C++
ExperimentalC++17 trở lên, libcurl 7.68 trở lên. curl_slist_free_all phải gọi SAU curl_easy_perform — giải phóng sớm thì libcurl đọc vào bộ nhớ đã thu hồi và lỗi chỉ hiện ra ngẫu nhiên khi chạy tải cao.
# Debian / Ubuntu sudo apt-get install -y libcurl4-openssl-dev g++ -std=c++17 vi_du.cpp -lcurl -o vi_du && ./vi_du
// libcurl là thư viện HTTP có mặt trên mọi nền tảng C++ và là thứ đứng sau
// curl trong terminal, nên hành vi TLS, proxy và chuyển hướng giống hệt lệnh
// bạn đã thử tay. Đánh đổi lại: phải tự cấp phát và tự giải phóng từng thứ.
#include <curl/curl.h>
#include <cstdlib>
#include <iostream>
#include <string>
static size_t ghi(char* du_lieu, size_t co, size_t so_khoi, void* dich) {
static_cast<std::string*>(dich)->append(du_lieu, co * so_khoi);
return co * so_khoi;
}
int main() {
const char* khoa = std::getenv("HITECHCLOUD_API_KEY");
if (khoa == nullptr) {
std::cerr << "Thiếu biến môi trường HITECHCLOUD_API_KEY.\n";
return 1;
}
curl_global_init(CURL_GLOBAL_DEFAULT);
CURL* phien = curl_easy_init();
std::string than;
const std::string xac_thuc = std::string("X-API-Key: ") + khoa;
curl_slist* dau_muc = nullptr;
dau_muc = curl_slist_append(dau_muc, xac_thuc.c_str());
dau_muc = curl_slist_append(dau_muc, "Accept: application/json");
// Thông tin đăng ký thuế của doanh nghiệp: tên pháp lý
curl_easy_setopt(phien, CURLOPT_URL, "https://api-tools.hitechcloud.vn/api/tax/business/0316954486");
curl_easy_setopt(phien, CURLOPT_HTTPHEADER, dau_muc);
curl_easy_setopt(phien, CURLOPT_TIMEOUT, 15L);
curl_easy_setopt(phien, CURLOPT_WRITEFUNCTION, ghi);
curl_easy_setopt(phien, CURLOPT_WRITEDATA, &than);
const CURLcode ket_qua = curl_easy_perform(phien);
long ma = 0;
curl_easy_getinfo(phien, CURLINFO_RESPONSE_CODE, &ma);
if (ket_qua != CURLE_OK) {
std::cerr << curl_easy_strerror(ket_qua) << "\n";
} else {
std::cout << ma << " " << than << "\n";
}
curl_slist_free_all(dau_muc);
curl_easy_cleanup(phien);
curl_global_cleanup();
return ket_qua == CURLE_OK && ma < 400 ? 0 : 1;
}
# 1) Tải đặc tả về máy.
curl -sS -H "X-API-Key: ${HITECHCLOUD_API_KEY}" \
"https://doc-api-tools.hitechcloud.vn/openapi.json" -o hitechcloud-api-tools.openapi.json
# 2) Sinh SDK đầy đủ cho 455 endpoint.
npx @openapitools/openapi-generator-cli generate \
-i hitechcloud-api-tools.openapi.json \
-g cpp-restsdk \
-o ./sdk/api-tools-cpp-restsdk \
--additional-properties='packageName=HitechCloudApi'
CLI đa nền tảng
Gói @hitechcloud/cli cài lệnh hitech cho Linux, macOS và Windows. Công cụ tra cứu danh mục, gọi endpoint, tải đặc tả OpenAPI và Postman, và chạy được như một máy chủ MCP qua stdio. Yêu cầu Node.js 18.17 trở lên; không có phụ thuộc runtime nào ngoài Node.
# Chạy thẳng, không cài gì vào máy npx @hitechcloud/cli --giup # Hoặc cài toàn cục để gõ gọn npm install -g @hitechcloud/cli hitech --giup
# PowerShell hoặc Command Prompt — cùng một lệnh npx @hitechcloud/cli --giup npm install -g @hitechcloud/cli hitech --giup
hitech auth login # dán khoá, CLI kiểm chứng với máy chủ rồi mới lưu hitech nhom # xem các nhóm dịch vụ hitech tim "ma so thue" # gõ không dấu vẫn khớp mô tả có dấu hitech goi get_api_airports_country_By_iso --tham-so iso=<giá trị>
claude mcp add hitechcloud -- npx -y @hitechcloud/cli mcp
Khoá lưu trong thư mục cấu hình của người dùng (~/.config/hitech/ trên Linux, ~/Library/Application Support/hitech/ trên macOS, %APPDATA%\hitech\ trên Windows) với quyền 0600 — không bao giờ nằm trong thư mục dự án. Trong CI thì dùng biến môi trường HITECH_API_KEY thay cho tệp.
Agent SDK
Nối danh mục vào mô hình ngôn ngữ mà không nạp từng endpoint làm một tool. Máy chủ MCP phơi bốn meta-tool, model tìm rồi mới gọi, nên phần định nghĩa tool chiếm dưới một phần trăm cửa sổ ngữ cảnh dù danh mục có bao nhiêu endpoint. Mỗi nền tảng dưới đây có mã cấu hình đầy đủ ở trang MCP.
npm install @anthropic-ai/claude-agent-sdk # Khoá lấy trong portal, mục Khoá API. Đừng viết thẳng vào tệp cấu hình. export HITECHCLOUD_API_KEY="hitechcloud_..."
pip install claude-agent-sdk export HITECHCLOUD_API_KEY="hitechcloud_..."
pip install anthropic export HITECHCLOUD_API_KEY="hitechcloud_..." export ANTHROPIC_API_KEY="sk-ant-..."
pip install openai-agents export HITECHCLOUD_API_KEY="hitechcloud_..." export OPENAI_API_KEY="sk-..."
pip install openai requests export HITECHCLOUD_API_KEY="hitechcloud_..." export OPENAI_API_KEY="sk-..." # Xem trước tệp định nghĩa tool (chuẩn Responses API): curl -sS "https://doc-api-tools.hitechcloud.vn/mcp/tools" -H "X-API-Key: $HITECHCLOUD_API_KEY" # Bản cho Chat Completions (định nghĩa lồng trong khoá "function"): curl -sS "https://doc-api-tools.hitechcloud.vn/mcp/tools?chuan=chat" -H "X-API-Key: $HITECHCLOUD_API_KEY"
# Không phải cài gói nào: Cursor tự nối tới máy chủ MCP từ tệp cấu hình. mkdir -p .cursor # Phạm vi dự án: .cursor/mcp.json · Phạm vi toàn cục: ~/.cursor/mcp.json
pip install langchain-mcp-adapters langchain export HITECHCLOUD_API_KEY="hitechcloud_..."
pip install llama-index-tools-mcp llama-index export HITECHCLOUD_API_KEY="hitechcloud_..."