Versandkosten API-Entwicklungsdokumentation

was kann getan werden

• Frachtberechnung – Geben Sie das Gewicht des Pakets (oder Länge, Breite und Volumen) ein und erstatten Sie die Seeexpress-Versandgebühr (RMB) des Pakets.
• Tarif abrufen – Fragen Sie den aktuellen Tarif pro Kilogramm, den Zuschlagsschwellenwert und den Volumenumrechnungskoeffizienten ab, die Sie bequem im Frontend berechnen oder zwischenspeichern können.

Alle Antworten sind in JSON, in einem einheitlichen Umschlagformat: bei Erfolg, success: true mit data; wenn fehlgeschlagen, success: false mit error Code und message.

Base URL

Authentifizierungsheader (wählen Sie einen aus)

Methode A – Inhabertoken (empfohlen)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Methode B – X-API-Key

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Der API-Schlüssel beginnt mit lk_live_. Bitte bewahren Sie sicher auf und platzieren Sie niemals in Front-End-JavaScript oder öffentlichen Git-Repositorys. Alle Anrufe sollten von Ihrer Serverseite aus erfolgen.

Ratenbegrenzung

Jeder Schlüssel hat ein Anforderungslimit pro Minute und der Antwortheader meldet das verbleibende Limit:

Kopfzeile	veranschaulichen
X-RateLimit-Limit	Anzahl der zulässigen Anfragen pro Minute
X-RateLimit-Remaining	Anzahl der in dieser Minute verbleibenden Anfragen
Retry-After	Anzahl der Sekunden, die gewartet werden muss, bis das Zeitlimit überschritten wurde (HTTP 429)

Für das beste Front-End-Erlebnis wird empfohlen, die Ergebnisse von /rates einige Minuten lang zwischenzuspeichern und sie mit derselben Formel auf Ihrem eigenen Server zu berechnen. Rufen Sie /quote zur Überprüfung nur während der kritischen Schritte einer Bestellung an.

GET /api/v1/freight/rates

Listet alle derzeit aktivierten Versandmethoden und -tarife auf. Es sind keine Parameter erforderlich.

fragen

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

Antwort 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

Die Gebühr für den Seeexpress-Versand wird auf der Grundlage des Gewichts/Volumens des Pakets berechnet. Sowohl GET (Abfragezeichenfolge) als auch POST (JSON oder Formular) sind akzeptabel.

Parameter anfordern

Parameter	Typ	Erforderlich	veranschaulichen
weight	number	Optional*	Tatsächliches Gewicht in Kilogramm (kg).
length	number	Optional*	Länge, Einheit ist Zentimeter (cm).
width	number	Optional*	Breite in Zentimetern (cm).
height	number	Optional*	Höhe, Einheit ist Zentimeter (cm).
method	string	Optional	Die Versandart ist derzeit sea (Seeexpress). Wenn es weggelassen wird, wird sea angenommen.

Anforderungsbeispiel (GET)

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

Anforderungsbeispiel (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}'

Antwort 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
  }
}

Beschreibung des Antwortfelds

Feld	veranschaulichen
actual_weight	Tatsächliches Gewicht (kg). 0, wenn nicht angegeben.
volume_weight	Volumen (Volumen) Gewicht (kg) = Länge × Breite × Höhe ÷ 10000. 0, wenn keine Größe angegeben ist.
billable_weight	Abrechnungsfähiges Gewicht (kg) = max. (tatsächliches Gewicht, Volumengewicht).
billable_basis	Die Abrechnung erfolgt nach :actual (basierend auf tatsächlichem Gewicht) oder volumetrisch (basierend auf Volumen).
freight	Grundfracht = Abrechnungsgewicht × Tarif pro Kilogramm (ohne Zuschläge).
surcharge	Der tatsächliche Zuschlag für diese Transaktion (0, wenn nicht ausgelöst).
surcharge_applied	Ob ein Zuschlag ausgelöst werden soll (Abrechnungsgewicht < Schwellenwert).
total_fee	Die endgültige Frachtforderung beträgt (RMB, auf die nächste ganze Zahl gerundet).

HTTP	error	veranschaulichen
401	missing_api_key	Es wird kein API-Schlüssel bereitgestellt. Bitte fügen Sie den Autorisierungs- oder X-API-Key-Header hinzu.
401	invalid_api_key	Der API-Schlüssel ist ungültig.
403	key_suspended / key_revoked / key_expired	Der Schlüssel wurde deaktiviert/entzogen/abgelaufen.
403	insufficient_scope	Der Schlüssel verfügt nicht über die Berechtigung freight:read.
422	validation_failed	Parameterformatfehler (Typ, Bereich).
422	missing_parameters	Kein Gewicht oder volle Länge/Breite/Höhe angegeben.
422	unsupported_method	Die Methode ist nicht in der verfügbaren Liste enthalten.
429	rate_limit_exceeded	Bei Überschreitung des Anforderungslimits pro Minute siehe „Retry-After“.

0337.tw ist das Einkaufszentrum Laravel. Es wird empfohlen, die Versandkosten-API in einen Backend-Dienst zu packen und während des Bestellvorgangs Folgendes aufzurufen:

• Nachdem Sie an der Kasse das Gesamtgewicht (kg)/Volumen des Warenkorbs erhalten haben, rufen Sie /api/v1/freight/quote im -Backend auf und legen Sie die zurückgegebene Gebühr total_fee als Versandkosten fest.
• Der Schlüssel wird in .env platziert (z. B. LUCKY_FREIGHT_KEY) und mit config() gelesen. Der Schlüssel darf nicht im Programmcode oder im Frontend fest codiert werden.
• Wenn der Anruf fehlschlägt (Timeout / 429), wird die in /rates zwischengespeicherte Rate lokal nach der gleichen Formel wie bei einer Sicherung berechnet, um einen unterbrechungsfreien Checkout sicherzustellen.
• Der Betrag ist in RMB; Wenn das Einkaufszentrum die Rechnung in neuen Taiwan-Dollar begleicht, nehmen Sie die Wechselkursumrechnung bitte selbst vor.

Laravel-Beispiel (HTTP-Fassade)

// 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);
    }
}

Fügen Sie 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] in config/services.php hinzu und fügen Sie dann LuckyFreightService in den Checkout-Controller ein, um die Fracht zu erhalten.

technische Unterstützung: howyunqisoftware@gmail.com

API-Version: v1 (stabil). Alle wichtigen Änderungen werden mit einer neuen Versionsnummer (v2) veröffentlicht, v1 bleibt kompatibel.

Änderungshistorie: 01.06.2026 – Freight API v1 ist online (Hai Express, Preis in RMB).