HitechCloud v2
VI EN
Portal Lấy khoá API
Bộ công cụ

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ữ

Nhãn Experimental ở đây nghĩa là gì Bộ mã cho ngôn ngữ đó sinh ra được và đã chạy thử, nhưng chưa qua hồi quy trên toàn danh mục: tên kiểu và chữ ký hàm còn có thể đổi giữa hai lần phát hành. Dùng cho việc thật vẫn được — hãy ghim phiên bản đặc tả bạn đã sinh SDK và sinh lại có chủ đích, thay vì sinh lại tự động trong quy trình dựng.

TypeScript

Ổn định

Node 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.

Cài đặt
TypeScript
# 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
Code copied
Gọi thử
TypeScript
// 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());
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
TypeScript
# 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'
Code copied

Python

Ổn định

Python 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ỗ.

Cài đặt
Python
python -m venv .venv && source .venv/bin/activate
pip install "httpx>=0.27"
python vi_du.py
Code copied
Gọi thử
Python
# 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())
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
Python
# 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'
Code copied

CLI

Ổn định

curl 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.

Cài đặt
CLI
# macOS
brew install curl jq

# Debian / Ubuntu
sudo apt-get install -y curl jq
Code copied
Gọi thử
CLI
# 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"
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
CLI
# 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
Code copied

Go

Ổn định

Go 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.

Cài đặt
Go
go mod init vi-du
go run .
Code copied
Gọi thử
Go
// 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)
}
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
Go
# 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'
Code copied

Java

Experimental

JDK 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.

Cài đặt
Java
# JDK 11 trở lên chạy thẳng tệp nguồn, không cần Maven/Gradle:
java ViDu.java
Code copied
Gọi thử
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());
    }
}
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
Java
# 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'
Code copied

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.

Cài đặt
C#
dotnet new console -o vi-du
cd vi-du
dotnet run
Code copied
Gọi thử
C#
// 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 }));
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
C#
# 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'
Code copied

PHP

Experimental

PHP 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ệ.

Cài đặt
PHP
composer require guzzlehttp/guzzle:^7.9
php vi-du.php
Code copied
Gọi thử
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));
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
PHP
# 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'
Code copied

Ruby

Experimental

Ruby 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.

Cài đặt
Ruby
# net/http nằm trong thư viện chuẩn, không cần gem nào.
ruby vi_du.rb
Code copied
Gọi thử
Ruby
# 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))
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
Ruby
# 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'
Code copied

Swift

Experimental

Swift 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.

Cài đặt
Swift
# URLSession nằm trong Foundation, không cần gói SwiftPM nào.
swift main.swift
Code copied
Gọi thử
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)
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
Swift
# 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'
Code copied

Rust

Experimental

Rust 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.

Cài đặt
Rust
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
Code copied
Gọi thử
Rust
// 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(())
}
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
Rust
# 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'
Code copied

Kotlin

Experimental

Kotlin 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.

Cài đặt
Kotlin
// build.gradle.kts
dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.12.0")
}
Code copied
Gọi thử
Kotlin
// 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)
    }
}
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
Kotlin
# 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'
Code copied

Dart

Experimental

Dart 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.

Cài đặt
Dart
dart pub add http
dart run vi_du.dart
Code copied
Gọi thử
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));
}
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
Dart
# 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'
Code copied

C++

Experimental

C++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.

Cài đặt
C++
# Debian / Ubuntu
sudo apt-get install -y libcurl4-openssl-dev

g++ -std=c++17 vi_du.cpp -lcurl -o vi_du && ./vi_du
Code copied
Gọi thử
C++
// 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;
}
Code copied
Sinh SDK đầy đủ từ đặc tả OpenAPI
C++
# 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'
Code copied

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.

Linux và macOS
# 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
Windows
# PowerShell hoặc Command Prompt — cùng một lệnh
npx @hitechcloud/cli --giup

npm install -g @hitechcloud/cli
hitech --giup
Bốn lệnh đầu tiên
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ị>
Dùng chính CLI làm máy chủ MCP
claude mcp add hitechcloud -- npx -y @hitechcloud/cli mcp
Chạy qua stdio nên không phải mở cổng nào và khoá không rời khỏi máy bạn.

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.

Claude Agent SDK — TypeScript
Anthropic · TypeScript · .mcp.json
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_..."
Claude Agent SDK — Python
Anthropic · Python · .mcp.json
pip install claude-agent-sdk

export HITECHCLOUD_API_KEY="hitechcloud_..."
MCP connector — Messages API
Anthropic · Python
pip install anthropic

export HITECHCLOUD_API_KEY="hitechcloud_..."
export ANTHROPIC_API_KEY="sk-ant-..."
OpenAI Agents SDK — Python
OpenAI · Python
pip install openai-agents

export HITECHCLOUD_API_KEY="hitechcloud_..."
export OPENAI_API_KEY="sk-..."
Responses API — function calling qua /mcp/tools
OpenAI · Python
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"
Cursor — máy chủ MCP trong Agent
Cursor · JSON · .cursor/mcp.json
# 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
LangChain — MCP adapters (tuỳ chọn) Tuỳ chọn
LangChain · Python
pip install langchain-mcp-adapters langchain

export HITECHCLOUD_API_KEY="hitechcloud_..."
LlamaIndex — MCP ToolSpec (tuỳ chọn) Tuỳ chọn
LlamaIndex · Python
pip install llama-index-tools-mcp llama-index

export HITECHCLOUD_API_KEY="hitechcloud_..."
Xem cấu hình MCP đầy đủ