thị trường dịch vụ / Tài liệu phát triển API tính toán thử nghiệm thuế nhập khẩu

API tính toán thử nghiệm thuế nhập khẩu Đài Loan · v1

Tài liệu phát triển API tính toán thử nghiệm thuế nhập khẩu

Dựa trên sản phẩm (mã thuế CCC hoặc chỉ phân loại AI tự động của mô tả sản phẩm) + số tiền ngoại tệ, tính ngay thuế nhập khẩu Đài Loan: thuế quan (bao gồm ECFA / thuế cố định), thuế kinh doanh, phí khuyến mãi, thuế hàng hóa, thuế thuốc lá và rượu và tự động xác định số lượng nhỏ NT$2.000 miễn thuế. Được thiết kế đặc biệt để kết nối với các nền tảng thương mại điện tử xuyên biên giới như 0337.tw.

5 loại thuế, phí chính

Thuế quan + thuế kinh doanh + phí khuyến mãi + thuế hàng hóa + thuế thuốc lá và rượu

NT$2,000

Tự động xác định số tiền miễn thuế nhỏ

Quy tắc thuế AI

Tự động phân loại mô tả sản phẩm CCC

Tỷ giá hối đoái mỗi mười ngày

Quy đổi tỷ giá tờ khai hải quan chính thức

1 Tổng quan

Hãy để nền tảng của bạn hiển thị trực tiếp "Sẽ phải nộp bao nhiêu thuế khi nhập sản phẩm này vào Đài Loan?" trên quầy lễ tân.

những gì có thể được thực hiện

Tính thuế - Mang hàng vào (mã số thuế CCC hoặc mô tả sản phẩm) + số ngoại tệ, trả lại thông tin thuế đầy đủ (thuế quan/thuế kinh doanh/phí khuyến mãi/thuế hàng hóa/thuế thuốc lá và rượu) và tổng chi phí thực hiện bao gồm thuế.
Kiểm tra thuế suất — Kiểm tra thuế suất và cờ thuế hàng hóa theo mã số thuế CCC.
Biểu thuế tự động — Khi không có CCC, chỉ có product_description được cung cấp và hệ thống sử dụng mô hình AI của Cơ quan Hải quan để tự động đề xuất biểu giá và tính thuế.

TTiền thuế: Đô la Đài Loan mới (TWD). Số lượng hàng hóa bạn mang bằng ngoại tệ (chẳng hạn như CNY) sẽ được hệ thống tính toán sau khi chuyển đổi sang Đô la Đài Loan mới dựa trên tỷ giá hối đoái khai báo hải quan chính thức trong 10 ngày. Tất cả số tiền thuế sẽ được tính bằng Đô la Đài Loan mới.

Mối quan hệ giữa và API vận chuyển hàng hóa :. Shipping_fee trong phản hồi tính toán thử nghiệm thuế là cước phí tham chiếu HowBridge NT$ (để ước tính chi phí triển khai). Đối với phí thu gom thực tế được thu từ 0337.tw, vui lòng sử dụng API vận chuyển hàng hóa API (sea express, RMB). Thuế của API này không bao gồm cước vận chuyển (cơ sở tính thuế = hàng hóa FOB, cơ sở thuận tiện; tờ khai hải quan chính thức phải được phê duyệt hải quan của CIF).

2 Chứng nhận và thông tin cơ bản

Tất cả các yêu cầu đều yêu cầu Khóa API (cùng một khóa với phí vận chuyển/trạng thái lô hàng là đủ và cần có quyền tax:read).

Base URL

https://0523.tw/api/v1/tax

Tiêu đề xác thực (chọn một)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// hoặc
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Vui lòng gọi từ phía máy chủ và không để lộ chìa khóa ở mặt trước. Giới hạn tốc độ được tính theo đơn vị chính và tiêu đề phản hồi X-RateLimit-Remaining báo cáo hạn ngạch còn lại và HTTP 429 được trả về khi vượt quá giới hạn.

3 Điểm cuối: Tính toán thử thuế

GETPOST /api/v1/tax/estimate

Nên sử dụng POST + JSON.

Thông số yêu cầu

tham số	Kiểu	Yêu cầu	minh họa
`currency_code`	string(3)	Yêu cầu	Loại ngoại tệ, chẳng hạn như `CNY`.
`price_foreign`	number	Yêu cầu	Số lượng hàng hóa bằng ngoại tệ.
`product_description`	string	Không bắt buộc*	Mô tả sản phẩm. Khi không cung cấp `hs_code`, AI sẽ được sử dụng để tự động đẩy các quy tắc thuế.
`hs_code`	string	Không bắt buộc*	Mã thuế CCC (8–11 chữ số).
`quantity`	int	Không bắt buộc	Số lượng, mặc định 1.
`weight_kg` / `dimensions`	number / [3]	Không bắt buộc	Trọng lượng/Chiều dài, Chiều rộng và Chiều cao (tham khảo ước tính cước phí).
`over_exempt_limit`	bool	Không bắt buộc	Sáu lần miễn thuế trong nửa năm đã hết → đánh thuế bắt buộc.
`volume_liters` / `alcohol_degree` / `tobacco_sticks`	number/int	Không bắt buộc	Được sử dụng để tính thuế cố định rượu/thuốc lá.

* hs_code và product_description Chọn ít nhất một .

Ví dụ về yêu cầu (POST JSON)

curl -X POST https://0523.tw/api/v1/tax/estimate \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"product_description":"Áo cotton nữ","currency_code":"CNY","price_foreign":300,"quantity":1}'

Phản hồi 200 (trích)

{
  "success": true,
  "data": {
    "input": { "hs_code": "61061000", "currency_code": "CNY", "price_foreign": 300 },
    "exchange": { "rate_to_twd": 4.612, "price_twd": 1383.6 },
    "tariff_info": { "duty_rate": 10.5, "duty_rate_text": "10.5%", "ecfa_applied": false },
    "tax_base": 1383.6,
    "tax_breakdown": {
      "is_tax_exempt": true,            // Cơ sở tính thuế ≤ NT$2.000 → miễn thuế số tiền nhỏ
      "duty": 0, "promo_fee": 0, "vat": 0, "total_tax": 0,
      "if_over_limit": {           // Nếu hết thời gian miễn thuế 6 lần trong nửa năm, số tiền phải nộp
        "duty": 145.28, "vat": 76.44, "total_tax": 221.72
      }
    },
    "antidumping": [],
    "total_landed_cost": 1453.6,
    "disclaimer": "..."
  }
}

4 Điểm cuối: kiểm tra thuế suất

GET /api/v1/tax/rate/{hsCode}

Kiểm tra thuế suất và cờ thuế hàng hóa theo mã số thuế CCC (số thuần).

curl https://0523.tw/api/v1/tax/rate/6109100000 \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "hs_code": "6109100000",
    "duty_rate": 10.5,
    "duty_rate_text": "10.5%",
    "is_commodity_tax": false,
    "name_zh": "Áo thun cotton, áo lót…",
    "source": "tariffs_db"
  }
}

5 Mô tả trường phản hồi (data)

cánh đồng	minh họa
`exchange.rate_to_twd`	Tỷ giá hối đoái khai báo hải quan hàng ngày được sử dụng (Ngoại tệ → Đô la Đài Loan mới).
`exchange.price_twd`	Số lượng sản phẩm được quy đổi thành Đô la Đài Loan mới.
`tariff_info.duty_rate`	Thuế suất áp dụng (%); ECFA cột thứ hai khi áp dụng.
`tax_base`	Cơ sở tính thuế (NTD) = mặt hàng FOB × số lượng (không bao gồm phí vận chuyển).
`tax_breakdown.is_tax_exempt`	Có được miễn thuế số tiền nhỏ không (cơ sở tính thuế ≤ NT$2.000 và đồ uống không có cồn và thuốc lá).
`tax_breakdown.duty`	Thuế quan (NTD).
`tax_breakdown.promo_fee`	Phí dịch vụ thương mại khuyến mại (0,04%, miễn phí nếu nhỏ hơn NT$100).
`tax_breakdown.commodity_tax`	Thuế tiêu thụ đặc biệt (đồ gia dụng, v.v.; thường là 0 đối với quần áo may sẵn).
`tax_breakdown.alcohol_tax`	Thuế thuốc lá và rượu (số tiền cố định).
`tax_breakdown.vat`	Thuế bán hàng 5%.
`tax_breakdown.total_tax`	Tổng số thuế phải nộp (NTD).
`tax_breakdown.if_over_limit`	Trong trường hợp miễn thuế, số thuế dự kiến phải nộp nếu sử dụng hết số tiền miễn thuế 6 lần trong nửa năm.
`antidumping`	Nhắc nhở chống bán phá giá/cân bằng thuế (tùy thuộc vào nước xuất xứ, chỉ có lời nhắc nhở không được tính vào tổng số).
`total_landed_cost`	Tổng chi phí cập bến bao gồm thuế (cơ sở tính thuế + cước tham chiếu + thuế).

6 công thức tính thuế

Cơ sở tính thuế = hàng hóa FOB (ngoại tệ × tỷ giá hối đoái) × số lượng
miễn thuế số lượng nhỏ = cơ sở tính thuế ≤ NT$2,000 và không phải thuốc lá và rượu → thuế 0 (6 lần trong nửa năm)
Thuế quan = cơ sở thuế × thuế suất (hoặc thuế cố định, tùy theo mức nào cao hơn)
Phí khuyến mãi = cơ sở tính thuế × 0,04% (không tính phí nếu số tiền không đạt NT$100)
Thuế hàng hóa = (Căn cứ tính thuế + Biểu thuế) × Thuế suất hàng hóa (mặt hàng áp dụng)
Thuế kinh doanh = (cơ sở tính thuế + thuế quan + thuế hàng hóa + thuế rượu và thuốc lá) × 5%
Số thuế phải nộp = Thuế hải quan + Phí khuyến mãi + Thuế hàng hóa + Thuế thuốc lá, rượu + Thuế kinh doanh

Cơ sở pháp lý: Luật Thuế quan, Luật thuế kinh doanh giá trị gia tăng và không giá trị gia tăng, Luật thương mại (Khuyến mãi phí dịch vụ thương mại), Quy định về thuế hàng hóa, Luật thuế thuốc lá và rượu. Số tiền thuế thực tế phải được hải quan phê duyệt.

7 mã lỗi

HTTP	`error` / tình huống	minh họa
401	missing_api_key / invalid_api_key	Không có/Khóa API không hợp lệ.
403	insufficient_scope	Khóa chưa được kích hoạt `tax:read`.
422	Thiếu tiền_code / price_foreign	Các tham số bắt buộc bị thiếu hoặc ở định dạng sai.
422	quy định thiếu thuế	hs_code không được cung cấp và không thể phân loại sản phẩm.
422	Không có tỷ giá hối đoái cho loại tiền này	Loại tiền tệ_code chưa cung cấp tỷ giá hối đoái, vui lòng liên hệ với bộ phận dịch vụ khách hàng.
429	rate_limit_exceeded	Đã vượt quá giới hạn mỗi phút.

8 Ví dụ về chương trình

$client = new GuzzleHttp\Client(['base_uri' => 'https://0523.tw']);
$res = $client->post('/api/v1/tax/estimate', [
    'headers' => ['Authorization' => 'Bearer ' . env('LUCKY_FREIGHT_KEY')],
    'json' => [
        'product_description' => 'Áo cotton nữ',
        'currency_code' => 'CNY',
        'price_foreign' => 300,
    ],
]);
$tax = json_decode($res->getBody(), true)['data']['tax_breakdown'];
echo 'Thuế phải nộp NT$' . $tax['total_tax'];

const r = await fetch('https://0523.tw/api/v1/tax/estimate', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.LUCKY_FREIGHT_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ product_description: 'Áo cotton nữ', currency_code: 'CNY', price_foreign: 300 }),
});
const { data } = await r.json();
console.log(data.tax_breakdown.total_tax);

curl -X POST https://0523.tw/api/v1/tax/estimate \
  -H "Authorization: Bearer $LUCKY_FREIGHT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_description":"Áo cotton nữ","currency_code":"CNY","price_foreign":300}'

9 Hỗ trợ và phiên bản

hỗ trợ kỹ thuật: howyunqisoftware@gmail.com

Phiên bản API: v1 (ổn định).

Lịch sử thay đổi: 01/06/2026 — API tính toán thử nghiệm thuế nhập khẩu v1 đang trực tuyến.

API vận chuyển API sẵn có Đăng ký khóa API