mercado de servicios / Documentación de desarrollo de API de cálculo de prueba de impuestos de importación

API de cálculo de prueba de impuestos de importación de Taiwán · v1

Documentación de desarrollo de API de cálculo de prueba de impuestos de importación

Según el producto (código fiscal CCC, o simplemente clasificación AI automática de la descripción del producto) + monto de moneda extranjera, calcule instantáneamente los impuestos de importación de Taiwán: arancel (incluido ECFA/impuesto fijo), impuesto comercial, tarifa de promoción, impuesto sobre bienes, impuesto sobre tabaco y alcohol, y determine automáticamente la pequeña cantidad de NT$2 000 libre de impuestos. Especialmente diseñado para acoplarse a plataformas de comercio electrónico transfronterizo como 0337.tw.

5 impuestos y tasas principales

Tarifa + impuesto comercial + tarifa de promoción + impuesto sobre bienes + impuesto sobre tabaco y alcohol

NT$2,000

Determinación automática de exención de impuestos por pequeñas cantidades

Normas fiscales de IA

Clasificar automáticamente descripciones de productos CCC

Tipo de cambio por diez días

Conversión del tipo de cambio de la declaración oficial de aduanas

1 Descripción general

Deje que su plataforma muestre directamente "¿Cuánto impuesto se pagará al importar este producto a Taiwán?" en la recepción.

¿Qué se puede hacer?

Cálculo de impuestos - Traiga los bienes (código de impuestos CCC o descripción del producto) + monto en moneda extranjera, devuelva los detalles completos de los impuestos (arancel/impuesto comercial/tarifa de promoción/impuesto sobre bienes/impuesto sobre tabaco y alcohol) y el costo total de implementación, incluidos los impuestos.
Verifique la tasa impositiva : verifique la tasa arancelaria y el indicador de impuestos sobre bienes de acuerdo con el número de tarifa CCC.
arancel automático : cuando no hay CCC, solo se proporciona product_description, y el sistema utiliza el modelo de IA de la Administración de Aduanas para recomendar automáticamente el arancel y calcular el impuesto.

Moneda fiscal: Nuevo dólar taiwanés (TWD). La cantidad de mercancías que usted trae en moneda extranjera (como CNY) será calculada por el sistema después de convertirla a nuevos dólares taiwaneses según el tipo de cambio oficial de la declaración de aduanas de diez días. El monto del impuesto estará todo en nuevos dólares taiwaneses.

La relación entre y la API de carga :. El envío_fee en la respuesta de cálculo de prueba de impuestos es el flete de referencia HowBridge NT$ (para la estimación del costo de implementación). Para conocer la tarifa de cobro real cobrada desde 0337.tw, utilice flete API (sea express, RMB). El impuesto de esta API no incluye el flete (base imponible = mercancía FOB, base conveniente; la declaración aduanera formal estará sujeta a la aprobación aduanera de CIF).

2 Certificación e información básica.

Todas las solicitudes requieren una clave API (la misma clave que la tarifa de envío/estado del envío es suficiente y se requiere el permiso tax:read).

Base URL

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

Encabezado de autenticación (elija uno)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// o
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Llame desde el lado del servidor y no exponga la clave al front-end. El límite de tasa está en unidades clave y el encabezado de respuesta X-RateLimit-Remaining informa la cuota restante y se devuelve HTTP 429 cuando se excede el límite.

3 Punto final: cálculo de prueba de impuestos

GETPOST /api/v1/tax/estimate

Se recomienda utilizar POST + JSON.

Solicitar parámetros

parámetro	Tipo	Requerido	ilustrar
`currency_code`	string(3)	Requerido	Tipo de moneda extranjera, como `CNY`.
`price_foreign`	number	Requerido	Cantidad de mercancías en moneda extranjera.
`product_description`	string	Opcional*	Descripción del Producto. Cuando no se proporciona `hs_code`, se utiliza IA para impulsar automáticamente las reglas fiscales.
`hs_code`	string	Opcional*	Código arancelario CCC (8 a 11 dígitos).
`quantity`	int	Opcional	Cantidad, por defecto 1.
`weight_kg` / `dimensions`	number / [3]	Opcional	Peso / Largo, Ancho y Alto (consulte estimación de flete).
`over_exempt_limit`	bool	Opcional	Se han agotado las seis exenciones fiscales durante medio año → tributación obligatoria.
`volume_liters` / `alcohol_degree` / `tobacco_sticks`	number/int	Opcional	Se utiliza para calcular el impuesto fijo sobre alcohol/cigarrillos.

* hs_code y product_description Elija al menos un .

Ejemplo de solicitud (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":"Camisetas de algodón para mujer.","currency_code":"CNY","price_foreign":300,"quantity":1}'

Respuestas 200 (extracto)

{
  "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,            // Base imponible ≤ NT$2 000 → exención de impuestos por pequeñas cantidades
      "duty": 0, "promo_fee": 0, "vat": 0, "total_tax": 0,
      "if_over_limit": {           // Si la exención fiscal se agota 6 veces en medio año, el importe a pagar
        "duty": 145.28, "vat": 76.44, "total_tax": 221.72
      }
    },
    "antidumping": [],
    "total_landed_cost": 1453.6,
    "disclaimer": "..."
  }
}

4 Punto final: comprobar la tasa impositiva

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

Verifique la tasa arancelaria y el indicador de impuestos sobre bienes de acuerdo con el número de tarifa CCC (números puros).

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": "Camisetas de algodón, camisetas interiores…",
    "source": "tariffs_db"
  }
}

5 Descripción del campo de respuesta (data)

campo	ilustrar
`exchange.rate_to_twd`	El tipo de cambio diario de la declaración de aduanas utilizado (Moneda extranjera → Nuevo dólar taiwanés).
`exchange.price_twd`	El importe del producto se convierte a nuevos dólares taiwaneses.
`tariff_info.duty_rate`	Tipo arancelario aplicado (%); ECFA segunda columna cuando corresponda.
`tax_base`	Base imponible (NTD) = artículo FOB × cantidad (sin incluir los gastos de envío).
`tax_breakdown.is_tax_exempt`	¿Está exento de la exención del impuesto sobre pequeñas cantidades (base imponible ≤ NT$2.000 y bebidas alcohólicas y no tabaco)?
`tax_breakdown.duty`	Tarifa (NTD).
`tax_breakdown.promo_fee`	Tarifa de servicio comercial promocional (0,04 %, sin cargo si es inferior a NT$100).
`tax_breakdown.commodity_tax`	Impuesto especial (electrodomésticos, etc.; generalmente 0 para prendas de vestir confeccionadas).
`tax_breakdown.alcohol_tax`	Impuesto sobre el tabaco y el alcohol (monto fijo).
`tax_breakdown.vat`	Impuesto sobre las ventas 5%.
`tax_breakdown.total_tax`	Impuesto total a pagar (NTD).
`tax_breakdown.if_over_limit`	En el caso de exención de impuestos, el impuesto estimado a pagar si la exención de impuestos se agota 6 veces en medio año.
`antidumping`	Recordatorio de antidumping/impuesto equilibrado (dependiendo del país de origen, sólo el recordatorio no se incorpora al total).
`total_landed_cost`	Coste total de aterrizaje incluyendo impuestos (base imponible + flete de referencia + impuestos).

6 fórmula de impuestos

base imponible = producto FOB (moneda extranjera × tipo de cambio) × cantidad
exención de impuestos por pequeñas cantidades = base imponible ≤ NT$2 000 y no tabaco y alcohol → impuesto 0 (6 veces en medio año)
Tarifa = base imponible × tasa arancelaria (o impuesto fijo, el que sea mayor)
Tarifa de promoción = base imponible × 0.04% (sin cargo si el monto no llega a NT$100)
Impuesto sobre bienes = (Base imponible + Arancel) × Tasa impositiva sobre bienes (artículos aplicables)
Impuesto empresarial = (base imponible + arancel + impuesto sobre bienes + impuesto sobre alcohol y tabaco) × 5%
Impuesto a pagar = Derechos de aduana + Tarifa de promoción + Impuesto sobre bienes + Impuesto sobre tabaco y alcohol + Impuesto comercial

Base jurídica: Ley Arancelaria, Ley del Impuesto Comercial con Valor Agregado y Sin Valor Agregado, Ley Comercial (Promoción de Tarifas de Servicios Comerciales), Reglamento del Impuesto sobre Bienes, Ley del Impuesto sobre el Tabaco y el Alcohol. El monto real del impuesto está sujeto a la aprobación de la aduana.

7 código de error

HTTP	`error` / situación	ilustrar
401	missing_api_key / invalid_api_key	Clave API nula o no válida.
403	insufficient_scope	La clave no está activada `tax:read`.
422	Falta el código_moneda/precio_extranjero	Faltan los parámetros requeridos o están en el formato incorrecto.
422	reglas de deficiencia fiscal	hs_code no proporcionado y product_description no se puede clasificar.
422	No hay tipo de cambio para esta moneda.	El código_moneda aún no ha proporcionado un tipo de cambio; comuníquese con el servicio de atención al cliente.
429	rate_limit_exceeded	Se superó el límite por minuto.

8 Ejemplo de programa

$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' => 'Camisetas de algodón para mujer.',
        'currency_code' => 'CNY',
        'price_foreign' => 300,
    ],
]);
$tax = json_decode($res->getBody(), true)['data']['tax_breakdown'];
echo 'Impuestos a pagar 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: 'Camisetas de algodón para mujer.', 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":"Camisetas de algodón para mujer.","currency_code":"CNY","price_foreign":300}'

9 Soporte y versiones

apoyo técnico: howyunqisoftware@gmail.com

Versión API: v1 (estable).

Historial de cambios: 2026-06-01: La API v1 de cálculo de prueba de impuestos de importación está en línea.

API de envío API de disponibilidad Solicite una clave API