mercado de serviços / Documentação de desenvolvimento da API de cálculo experimental de imposto de importação

API de cálculo de teste de imposto de importação de Taiwan · v1

Documentação de desenvolvimento da API de cálculo experimental de imposto de importação

Com base no produto (código de imposto CCC ou apenas classificação AI automática da descrição do produto) + valor em moeda estrangeira, calcule instantaneamente os impostos de importação de Taiwan: tarifa (incluindo ECFA / imposto fixo), imposto comercial, taxa de promoção, imposto sobre mercadorias, imposto sobre tabaco e álcool e determine automaticamente a pequena quantidade de NT$2.000 isenta de impostos. Especialmente projetado para integração com plataformas de comércio eletrônico transfronteiriças, como 0337.tw.

5 principais impostos e taxas

Tarifa + imposto comercial + taxa de promoção + imposto sobre mercadorias + imposto sobre tabaco e álcool

NT$2,000

Determinação automática de isenção de impostos de pequeno valor

Regras fiscais de IA

Classifique automaticamente as descrições dos produtos CCC

Taxa de câmbio por dez dias

Conversão da taxa de câmbio da declaração aduaneira oficial

1 Visão geral

Deixe sua plataforma exibir diretamente "Quanto imposto será pago ao importar este produto para Taiwan?" na recepção.

o que pode ser feito

Cálculo de imposto - Traga as mercadorias (código de imposto CCC ou descrição do produto) + valor em moeda estrangeira, devolva os detalhes fiscais completos (tarifa/imposto comercial/taxa de promoção/imposto sobre mercadorias/imposto sobre tabaco e álcool) e o custo total de implementação, incluindo impostos.
Consultar alíquota do imposto — Verificar alíquota tarifária e bandeira de imposto sobre mercadorias conforme número tarifário CCC.
tarifa automática — Quando não há CCC, apenas product_description é fornecido, e o sistema usa o modelo AI da Administração Aduaneira para recomendar automaticamente a tarifa e calcular o imposto.

Moeda fiscal: Novo dólar taiwanês (TWD). A quantidade de mercadorias que você traz em moeda estrangeira (como CNY) será calculada pelo sistema após convertê-la em novos dólares de Taiwan com base na taxa de câmbio oficial da declaração alfandegária de dez dias. O valor do imposto será todo em novos dólares de Taiwan.

O relacionamento entre e a API de frete :. O shipping_fee na resposta de cálculo de avaliação fiscal é o frete de referência HowBridge NT$ (para estimativa de custo de implementação). Para a taxa de coleta real cobrada de 0337.tw, use frete API (sea express, RMB). O imposto desta API não inclui frete (base tributária = mercadoria FOB, base conveniente; a declaração aduaneira formal estará sujeita à aprovação aduaneira de CIF).

2 Certificação e informações básicas

Todas as solicitações exigem uma chave de API (a mesma chave da taxa de envio/status da remessa é suficiente e a permissão tax:read é necessária).

Base URL

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

Cabeçalho de autenticação (escolha um)

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

Ligue do lado do servidor e não exponha a chave ao front-end. O limite de taxa está em unidades principais e o cabeçalho de resposta X-RateLimit-Remaining relata a cota restante e HTTP 429 é retornado quando o limite é excedido.

3 Ponto final: cálculo de avaliação fiscal

GETPOST /api/v1/tax/estimate

Recomenda-se usar POST + JSON.

Parâmetros de solicitação

parâmetro	Tipo	Obrigatório	ilustrar
`currency_code`	string(3)	Obrigatório	Tipo de moeda estrangeira, como `CNY`.
`price_foreign`	number	Obrigatório	Quantidade de mercadorias em moeda estrangeira.
`product_description`	string	Opcional*	Descrição do produto. Quando `hs_code` não é fornecido, a IA é usada para aplicar automaticamente as regras fiscais.
`hs_code`	string	Opcional*	Código tarifário CCC (8–11 dígitos).
`quantity`	int	Opcional	Quantidade, padrão 1.
`weight_kg` / `dimensions`	number / [3]	Opcional	Peso/Comprimento, Largura e Altura (consultar estimativa de frete).
`over_exempt_limit`	bool	Opcional	Esgotadas as seis isenções fiscais durante meio ano → tributação obrigatória.
`volume_liters` / `alcohol_degree` / `tobacco_sticks`	number/int	Opcional	Utilizado para cálculo do imposto fixo sobre álcool/cigarro.

* hs_code e product_description Escolha pelo menos um .

Exemplo de solicitação (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":"Tops femininos de algodão","currency_code":"CNY","price_foreign":300,"quantity":1}'

Respostas 200 (trecho)

{
  "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 tributária ≤ NT$2.000 → isenção de imposto de pequeno valor
      "duty": 0, "promo_fee": 0, "vat": 0, "total_tax": 0,
      "if_over_limit": {           // Se a isenção fiscal se esgotar 6 vezes num semestre, o valor a pagar
        "duty": 145.28, "vat": 76.44, "total_tax": 221.72
      }
    },
    "antidumping": [],
    "total_landed_cost": 1453.6,
    "disclaimer": "..."
  }
}

4 Ponto final: verifique a taxa de imposto

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

Verifique a alíquota tarifária e a bandeira do imposto sobre mercadorias de acordo com o número tarifário 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ão, camisetas…",
    "source": "tariffs_db"
  }
}

5 Descrição do campo de resposta (data)

campo	ilustrar
`exchange.rate_to_twd`	A taxa de câmbio diária da declaração alfandegária utilizada (Moeda Estrangeira → Novo Dólar de Taiwan).
`exchange.price_twd`	O valor do produto é convertido em novos dólares taiwaneses.
`tariff_info.duty_rate`	Taxa tarifária aplicada (%); Segunda coluna ECFA quando aplicável.
`tax_base`	Base tributária (NTD) = item FOB × quantidade (excluindo despesas de envio).
`tax_breakdown.is_tax_exempt`	Está isento de isenção de impostos de pequenos montantes (base tributável ≤ NT$2.000 e bebidas não-tabaco e alcoólicas).
`tax_breakdown.duty`	Tarifa (NTD).
`tax_breakdown.promo_fee`	Taxa de serviço comercial promocional (0,04%, sem cobrança se for inferior a NT$100).
`tax_breakdown.commodity_tax`	Imposto sobre consumo (eletrodomésticos, etc.; geralmente 0 para roupas prontas).
`tax_breakdown.alcohol_tax`	Imposto sobre tabaco e álcool (valor fixo).
`tax_breakdown.vat`	Imposto sobre vendas de 5%.
`tax_breakdown.total_tax`	Total de impostos a pagar (NTD).
`tax_breakdown.if_over_limit`	No caso de isenção fiscal, o imposto estimado a pagar se a isenção fiscal for utilizada 6 vezes em meio ano.
`antidumping`	Lembrete antidumping/imposto equilibrado (dependendo do país de origem, apenas o lembrete não é incorporado ao total).
`total_landed_cost`	Custo total de desembarque incluindo impostos (base tributária + frete de referência + impostos).

6 fórmula fiscal

Base tributária = mercadoria FOB (moeda estrangeira × taxa de câmbio) × quantidade
isenção de imposto de pequena quantia = base tributária ≤ NT$2.000 e não tabaco e álcool → imposto 0 (6 vezes em meio ano)
Tarifa = base tributária × taxa tarifária (ou imposto fixo, o que for maior)
Taxa de promoção = base tributária × 0,04% (sem cobrança se o valor não atingir NT$100)
Imposto sobre mercadorias = (Base tributária + Tarifa) × Taxa de imposto sobre mercadorias (itens aplicáveis)
Imposto comercial = (base tributária + tarifa + imposto sobre mercadorias + imposto sobre álcool e tabaco) × 5%
Imposto a pagar = Direitos aduaneiros + Taxa de promoção + Imposto sobre mercadorias + Imposto sobre tabaco e álcool + Imposto comercial

Base jurídica: Lei Tarifária, Lei Tributária Empresarial sobre Valor Agregado e Sem Valor Agregado, Lei Comercial (Taxas de Promoção de Serviços Comerciais), Regulamentação Fiscal de Mercadorias, Lei Tributária de Tabaco e Álcool. O valor real do imposto está sujeito à aprovação aduaneira.

7 código de erro

HTTP	`erro` / situação	ilustrar
401	missing_api_key / invalid_api_key	Nenhuma chave de API/inválida.
403	insufficient_scope	A chave não está ativada `tax:read`.
422	Moeda_code/price_foreign ausente	Os parâmetros necessários estão faltando ou estão no formato errado.
422	regras de deficiência fiscal	hs_code não fornecido e product_description não pode ser classificado.
422	Não há taxa de câmbio para esta moeda	O currency_code ainda não forneceu uma taxa de câmbio, entre em contato com o atendimento ao cliente.
429	rate_limit_exceeded	Limite por minuto excedido.

8 Exemplo 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' => 'Tops femininos de algodão',
        'currency_code' => 'CNY',
        'price_foreign' => 300,
    ],
]);
$tax = json_decode($res->getBody(), true)['data']['tax_breakdown'];
echo 'Impostos 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: 'Tops femininos de algodão', 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":"Tops femininos de algodão","currency_code":"CNY","price_foreign":300}'

9 Suporte e versões

suporte técnico: howyunqisoftware@gmail.com

Versão da API: v1 (estável).

Histórico de alterações: 01/06/2026 — A API de cálculo de teste de imposto de importação v1 está online.

API de envio API de disponibilidade Solicite uma chave de API