Documentación de desarrollo de API de tarifa de envío

¿Qué se puede hacer?

• Cálculo de flete : ingrese el peso del paquete (o largo, ancho y volumen) y devuelva la tarifa de envío marítimo expreso (RMB) del paquete.
• Obtener tasa : consulta la tasa actual por kilogramo, el umbral de recargo y el coeficiente de conversión de volumen, lo cual le resulta conveniente calcular o almacenar en caché en la interfaz.

Todas las respuestas están en JSON, en un formato de sobre unificado: cuando tienen éxito, success: true con data; cuando falla, success: false con el código error y message.

Base URL

Encabezado de autenticación (elija uno)

Método A: Token al portador (recomendado)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Método B: clave X-API

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

La clave API comienza con lk_live_. Mantenga seguro y nunca coloque en repositorios frontales de JavaScript o Git públicos; Todas las llamadas deben realizarse desde el lado del servidor.

Límite de tarifa

Cada clave tiene un límite de solicitudes por minuto y el encabezado de respuesta informará el límite restante:

encabezamiento	ilustrar
X-RateLimit-Limit	Número de solicitudes permitidas por minuto
X-RateLimit-Remaining	Número de solicitudes restantes en este minuto
Retry-After	Número de segundos para esperar hasta que se superó el límite de tiempo (HTTP 429)

Para obtener la mejor experiencia de front-end, se recomienda almacenar en caché los resultados de /rates durante unos minutos y calcularlos con la misma fórmula en su propio servidor. Llame únicamente a /quote para verificación durante los pasos críticos de realizar un pedido.

GET /api/v1/freight/rates

Enumera todos los métodos y tarifas de envío actualmente habilitados. No se requieren parámetros.

preguntar

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

Respuesta 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

La tarifa de envío marítimo exprés se calcula en función del peso/volumen del paquete. Tanto GET (cadena de consulta) como POST (JSON o formulario) son aceptables.

Solicitar parámetros

parámetro	Tipo	Requerido	ilustrar
weight	number	Opcional*	Peso real en kilogramos (kg).
length	number	Opcional*	Longitud, la unidad es centímetros (cm).
width	number	Opcional*	Ancho en centímetros (cm).
height	number	Opcional*	Altura, la unidad es centímetros (cm).
method	string	Opcional	El método de envío actualmente es sea (sea express). Cuando se omite, se supone sea.

Ejemplo de solicitud (OBTENER)

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

Ejemplo de solicitud (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}'

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

Descripción del campo de respuesta

campo	ilustrar
actual_weight	Peso real (kg). 0 si no se proporciona.
volume_weight	Volumen (volumen) peso (kg) = largo × ancho × alto ÷ 10000. 0 si no se proporciona el tamaño.
billable_weight	Peso facturable (kg) = máx (peso real, peso volumétrico).
billable_basis	La facturación se basa en :actual (basado en el peso real) o volumetric (basado en el volumen).
freight	Flete básico = peso de facturación × tarifa por kilogramo (sin incluir recargos).
surcharge	El recargo real para esta transacción (0 si no se activa).
surcharge_applied	Si se debe activar el recargo (peso de facturación
total_fee	El flete final por cobrar es (RMB, redondeado al número entero más cercano).

HTTP	error	ilustrar
401	missing_api_key	No se proporciona ninguna clave API. Agregue el encabezado Autorización o X-API-Key.
401	invalid_api_key	La clave API no es válida.
403	key_suspended / key_revoked / key_expired	La clave ha sido desactivada/revocada/caducada.
403	insufficient_scope	La clave no tiene el permiso freight:read.
422	validation_failed	Error de formato de parámetro (tipo, rango).
422	missing_parameters	No se proporciona peso ni longitud/ancho/alto completo.
422	unsupported_method	El método no está en la lista disponible.
429	rate_limit_exceeded	Exceder el límite de solicitudes por minuto, consulte Reintentar después.

0337.tw es el centro comercial Laravel. Se recomienda empaquetar la API de tarifa de envío en un Servicio backend y llamar a: durante el proceso de pago:

• Después de obtener el peso/volumen total (kg) del carrito de compras al finalizar la compra, llame a /api/v1/freight/quote en el backend y establezca el total_fee devuelto como tarifa de envío.
• La clave se coloca en .env (por ejemplo, LUCKY_FREIGHT_KEY) y se lee con config(). No escriba la clave directamente en el código del programa ni en el front-end.
• Cuando la llamada falla (tiempo de espera/429), la tarifa almacenada en caché en /rates se calcula localmente utilizando la misma fórmula que una copia de seguridad para garantizar un pago ininterrumpido.
• El importe está en RMB; Si el centro comercial paga la factura en nuevos dólares taiwaneses, aplique usted mismo la conversión del tipo de cambio.

Ejemplo de 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);
    }
}

Agregue 'lucky' => ['freight_key' => env('LUCKY_FREIGHT_KEY')] en config/services.php y luego inyecte LuckyFreightService en el controlador de pago para obtener el flete.

apoyo técnico: howyunqisoftware@gmail.com

Versión API: v1 (estable). Cualquier cambio importante se publicará con un nuevo número de versión (v2), la v1 seguirá siendo compatible.

Historial de cambios: 01/06/2026: Freight API v1 está en línea (Hai Express, precio en RMB).