Документация по разработке API платы за доставку

что можно сделать

• Расчет перевозки — введите вес посылки (или длину, ширину и объем) и верните стоимость морской экспресс-доставки посылки (юаней).
• Получить ставку — запросить текущую ставку за килограмм, порог надбавки и коэффициент преобразования объема, который вам удобно вычислить или кэшировать на внешнем интерфейсе.

Все ответы представлены в формате JSON в едином формате конверта: в случае успеха success: true с data; в случае неудачи success: false с кодом error и message.

Base URL

Заголовок аутентификации (выберите один)

Метод A — токен на предъявителя (рекомендуется)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Метод Б — ключ X-API

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Ключ API начинается с lk_live_. Пожалуйста, храните в безопасности и никогда не помещайте во внешний JavaScript или общедоступные репозитории Git; все вызовы должны осуществляться со стороны вашего сервера.

Ограничение скорости

У каждого ключа есть лимит запросов в минуту, а в заголовке ответа будет сообщено об оставшемся лимите:

Для обеспечения наилучшего внешнего интерфейса рекомендуется кэшировать результаты /rates на несколько минут и вычислять их по той же формуле на своем собственном сервере. Звоните по /quote только для проверки на критических этапах размещения заказа.

GET /api/v1/freight/rates

Перечисляет все доступные на данный момент способы доставки и тарифы. Никакие параметры не требуются.

просить

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

Ответ 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

Стоимость морской экспресс-доставки рассчитывается в зависимости от веса/объема посылки. Допускаются как GET (строка запроса), так и POST (JSON или форма).

Параметры запроса

Пример запроса (GET)

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

Пример запроса (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}'

Ответ 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
  }
}

Описание поля ответа

0337.tw — это торговый центр Laravel. Рекомендуется упаковать API платы за доставку во внутреннюю службу и вызывать: в процессе оформления заказа:

• После получения общего веса (кг)/объема корзины покупок при оформлении заказа вызовите /api/v1/freight/quote на бэкэнде и установите возвращенный total_fee в качестве стоимости доставки.
• Ключ помещается в .env (например, LUCKY_FREIGHT_KEY) и читается с помощью config(). Не прописывайте ключ жёстко в программном коде или во фронтенде.
• При сбое вызова (тайм-аут / 429) ставка, кэшированная в /rates, рассчитывается локально с использованием той же формулы, что и резервная копия, для обеспечения непрерывного оформления заказа.
• Сумма указана в юанях; Если торговый центр оплачивает счет в новых тайваньских долларах, пожалуйста, примените конвертацию обменного курса самостоятельно.

Пример Laravel (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);
    }
}

Добавьте 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] в config/services.php, а затем добавьте LuckyFreightService в Контролер оформления заказа для получения груза.

техническая поддержка: howyunqisoftware@gmail.com

Версия API: v1 (стабильная). Любые критические изменения будут выпущены с новым номером версии (v2), версия v1 останется совместимой.

История изменений: 01.06.2026 — Freight API v1 доступен онлайн (Hai Express, цена в юанях).