Documentation de développement de l'API sur les frais d'expédition

que peut-on faire

• Calcul du fret - Entrez le poids du colis (ou la longueur, la largeur et le volume) et renvoyez les frais d'expédition maritime express (RMB) du colis.
• Obtenir le taux - Recherchez le taux actuel par kilogramme, le seuil de supplément et le coefficient de conversion de volume, ce qui est pratique pour vous de calculer ou de mettre en cache sur le front-end.

Toutes les réponses sont au format JSON, dans un format d'enveloppe unifié : en cas de succès, success : true avec data ; en cas d'échec, success : false avec le code error et message.

Base URL

En-tête d'authentification (choisissez-en un)

Méthode A — Jeton au porteur (recommandé)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Méthode B — Clé X-API

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

La clé API commence par lk_live_. Veuillez garder en sécurité et ne jamais placer dans des référentiels JavaScript frontaux ou Git publics ; tous les appels doivent être effectués depuis votre serveur.

Limite de taux

Chaque clé a une limite de requêtes par minute, et l'en-tête de réponse indiquera la limite restante :

Pour la meilleure expérience frontale, il est recommandé de mettre en cache les résultats /rates pendant quelques minutes et de les calculer avec la même formule sur votre propre serveur. Appelez uniquement /quote pour vérification pendant les étapes critiques de la passation d'une commande.

GET /api/v1/freight/rates

Répertorie toutes les méthodes et tarifs d’expédition actuellement activés. Aucun paramètre n'est requis.

demander

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

Réponse 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

Les frais d'expédition maritime express sont calculés en fonction du poids/volume du colis. GET (chaîne de requête) et POST (JSON ou formulaire) sont acceptables.

Paramètres de la demande

Exemple de requête (GET)

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

Exemple de requête (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}'

Réponse 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
  }
}

Description du champ de réponse

0337.tw est le centre commercial Laravel. Il est recommandé de regrouper l'API des frais d'expédition dans un service backend et d'appeler : pendant le processus de paiement :

• Après avoir obtenu le poids total (kg)/volume du panier à la caisse, appelez /api/v1/freight/quote sur le backend et définissez le total_fee retourné comme frais d'expédition.
• La clé est placée dans .env (par exemple, LUCKY_FREIGHT_KEY) et lue avec config(). Ne codez pas la clé en dur dans le code du programme ni dans le front-end.
• Lorsque l'appel échoue (timeout / 429), le tarif mis en cache dans /rates est calculé localement en utilisant la même formule qu'une sauvegarde pour garantir un paiement ininterrompu.
• Le montant est en RMB ; Si le centre commercial règle la facture en nouveaux dollars taïwanais, veuillez appliquer vous-même la conversion du taux de change.

Exemple Laravel (façade 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);
    }
}

Ajoutez 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] dans config/services.php, puis injectez LuckyFreightService dans le contrôleur de caisse pour obtenir le fret.

assistance technique : howyunqisoftware@gmail.com

Version API : v1 (stable). Toutes les modifications importantes seront publiées avec un nouveau numéro de version (v2), la v1 restera compatible.

Historique des modifications : 01/06/2026 — L'API Freight v1 est en ligne (Hai Express, prix en RMB).