Documentação de desenvolvimento de API de taxa de envio

o que pode ser feito

• Cálculo de frete - Insira o peso do pacote (ou comprimento, largura e volume) e devolva a taxa de envio expresso marítimo (RMB) do pacote.
• Obter taxa - Consulte a taxa atual por quilograma, limite de sobretaxa e coeficiente de conversão de volume, que é conveniente para você calcular ou armazenar em cache no front-end.

Todas as respostas estão em JSON, em um formato de envelope unificado: quando bem-sucedido, success: true com data; quando falhou, success: false com código error e message.

Base URL

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

Método A – Token ao Portador (recomendado)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Método B - Chave X-API

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

A chave de API começa com lk_live_. Mantenha seguro e nunca coloque em JavaScript front-end ou repositórios Git públicos; todas as chamadas devem ser feitas do lado do servidor.

Limite de taxa

Cada chave tem um limite de solicitações por minuto, e o cabeçalho da resposta informará o limite restante:

cabeçalho	ilustrar
X-RateLimit-Limit	Número de solicitações permitidas por minuto
X-RateLimit-Remaining	Número de solicitações restantes neste minuto
Retry-After	Número de segundos de espera pelo limite de tempo excedido (HTTP 429)

Para obter a melhor experiência de front-end, é recomendável armazenar em cache os resultados /rates por alguns minutos e calculá-los com a mesma fórmula em seu próprio servidor. Ligue apenas para /quote para verificação durante as etapas críticas de fazer um pedido.

GET /api/v1/freight/rates

Lista todos os métodos e taxas de envio atualmente ativados. Nenhum parâmetro é necessário.

perguntar

curl https://0523.tw/api/v1/freight/rates \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Resposta 200

{
  "success": true,
  "currency": "CNY",
  "data": [
    {
      "method": "sea",
      "name_zh": "海快",
      "name_en": "Sea Express",
      "rate_per_kg": 10,
      "surcharge": 20,
      "min_threshold": 15,
      "volume_divisor": 10000,
      "currency": "CNY"
    }
  ]
}

GETPOST /api/v1/freight/quote

A taxa de envio expresso marítimo é calculada com base no peso/volume do pacote. Tanto GET (query string) quanto POST (JSON ou formulário) são aceitáveis.

Parâmetros de solicitação

parâmetro	Tipo	Obrigatório	ilustrar
weight	number	Opcional*	Peso real em quilogramas (kg).
length	number	Opcional*	Comprimento, a unidade é centímetros (cm).
width	number	Opcional*	Largura em centímetros (cm).
height	number	Opcional*	Altura, a unidade é centímetros (cm).
method	string	Opcional	O método de envio é atualmente sea (sea express). Quando omitido, sea é assumido.

Exemplo de solicitação (GET)

curl "https://0523.tw/api/v1/freight/quote?weight=8&method=sea" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Exemplo de solicitação (POST JSON)

curl -X POST https://0523.tw/api/v1/freight/quote \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"weight": 5, "length": 40, "width": 30, "height": 30}'

Resposta 200

{
  "success": true,
  "data": {
    "method": "sea",
    "method_name_zh": "海快",
    "method_name_en": "Sea Express",
    "currency": "CNY",
    "currency_symbol": "¥",
    "actual_weight": 5,
    "volume_weight": 3.6,
    "volume_divisor": 10000,
    "billable_weight": 5,
    "billable_basis": "actual",
    "rate_per_kg": 10,
    "freight": 50,
    "surcharge": 20,
    "surcharge_applied": true,
    "min_threshold": 15,
    "total_fee": 70
  }
}

Descrição do campo de resposta

campo	ilustrar
actual_weight	Peso real (kg). 0 se não for fornecido.
volume_weight	Volume (volume) peso (kg) = comprimento × largura × altura ÷ 10000. 0 se nenhum tamanho for fornecido.
billable_weight	Peso faturável (kg) = máx (peso real, peso volumétrico).
billable_basis	O faturamento é baseado em :actual (com base no peso real) ou volumétrico (com base no volume).
freight	Frete básico = peso faturado × taxa por quilograma (sem sobretaxas).
surcharge	A sobretaxa real para esta transação (0 se não for acionada).
surcharge_applied	Se deve acionar a sobretaxa (peso de faturamento
total_fee	O frete final a receber é (RMB, arredondado para o número inteiro mais próximo).

HTTP	error	ilustrar
401	missing_api_key	Nenhuma chave de API é fornecida. Adicione autorização ou cabeçalho X-API-Key.
401	invalid_api_key	A chave de API é inválida.
403	key_suspended / key_revoked / key_expired	A chave foi desativada/revogada/expirada.
403	insufficient_scope	A chave não possui a permissão freight:read.
422	validation_failed	Erro no formato do parâmetro (tipo, intervalo).
422	missing_parameters	Nenhum peso ou comprimento/largura/altura total fornecido.
422	unsupported_method	método não está na lista disponível.
429	rate_limit_exceeded	Excedendo o limite de solicitações por minuto, consulte Tentar novamente após.

0337.tw é o shopping Laravel. Recomenda-se empacotar a API de taxa de envio em um serviço de back-end e ligar: durante o processo de finalização da compra:

• Depois de obter o peso total (kg)/volume do carrinho de compras na finalização da compra, ligue para /api/v1/freight/quote no backend e defina o total_fee devolvido como a taxa de envio.
• A chave é colocada em .env (por exemplo, LUCKY_FREIGHT_KEY) e lida com config(). Não escreva a chave diretamente no código do programa nem no front-end.
• Quando a chamada falha (tempo limite/429), a taxa armazenada em cache em /rates é calculada localmente usando a mesma fórmula de um backup para garantir uma verificação ininterrupta.
• O valor está em RMB; se o shopping liquidar a conta em novos dólares de Taiwan, aplique você mesmo a conversão da taxa de câmbio.

Exemplo Laravel (fachada HTTP)

// app/Services/LuckyFreightService.php
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;

class LuckyFreightService
{
    public function quote(float $weight): int
    {
        $res = Http::withToken(config('services.lucky.freight_key'))  // 讀 .env
            ->acceptJson()
            ->timeout(8)
            ->get('https://0523.tw/api/v1/freight/quote', [
                'weight' => $weight,
                'method' => 'sea',
            ]);

        if ($res->successful()) {
            return (int) $res->json('data.total_fee');  // 人民幣
        }

        // 後備:用快取費率本地計算,結帳不中斷
        return $this->fallbackQuote($weight);
    }
}

Adicione 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] em config/services.php e, em seguida, injete LuckyFreightService no controlador de checkout para obter o frete.

suporte técnico: howyunqisoftware@gmail.com

Versão da API: v1 (estável). Quaisquer alterações importantes serão lançadas com um novo número de versão (v2), a v1 permanecerá compatível.

Histórico de alterações: 01/06/2026 — A API de frete v1 está online (Hai Express, com preço em RMB).