배송비 API 개발 문서

무엇을 할 수 있나요?

• 운임 계산 — 패키지 중량(또는 길이, 너비 및 부피)을 입력하고 패키지의 Sea Express 배송비(RMB)를 반환합니다.
• 요율 가져오기 — 프런트 엔드에서 계산하거나 캐시하는 데 편리한 현재 킬로그램당 요율, 추가 요금 기준 및 부피 변환 계수를 쿼리합니다.

모든 응답은 JSON 형식으로 통합 봉투 형식입니다: success: true with data; 실패 시 오류 코드 및 메시지와 함께 success: false.

Base URL

인증 헤더(하나 선택)

방법 A - 전달자 토큰(권장)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

방법 B - X-API-키

X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

API 키는 lk_live_로 시작합니다. 안전하게 보관하고 절대로 프런트엔드 JavaScript나 공개 Git 저장소에 넣지 마세요. 모든 호출은 서버 측에서 이루어져야 합니다.

비율 제한

각 키에는 분당 요청 제한이 있으며 응답 헤더는 나머지 제한을 보고합니다.

헤더	설명
X-RateLimit-Limit	분당 허용되는 요청 수
X-RateLimit-Remaining	현재 남은 요청 수
Retry-After	시간 제한이 초과될 때까지 기다리는 시간(초)(HTTP 429)

최상의 프런트엔드 경험을 위해서는 /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 또는 양식)가 모두 허용됩니다.

요청 매개변수

매개변수	유형	필수	설명
weight	number	선택사항*	실제 중량(kg)입니다.
length	number	선택사항*	길이, 단위는 센티미터(cm)입니다.
width	number	선택사항*	센티미터(cm) 단위의 너비입니다.
height	number	선택사항*	높이, 단위는 센티미터(cm)입니다.
method	string	선택 과목	현재 배송 방법은 sea(바다 익스프레스)입니다. 생략하면 sea로 간주됩니다.

요청 예시(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
  }
}

응답 필드 설명

필드	설명
actual_weight	실제 체중(kg). 제공되지 않은 경우 0입니다.
volume_weight	부피(부피) 무게(kg) = 길이 × 너비 × 높이 ÷ 10000. 크기가 제공되지 않은 경우 0입니다.
billable_weight	청구 중량(kg) = 최대(실제 중량, 부피 중량)
billable_basis	청구 기준: 실제(실제 중량 기준) 또는 부피(재료 부피 기준).
freight	기본 운임 = 청구 중량 × 킬로그램당 요금(할증료 제외)
surcharge	이 거래에 대한 실제 추가 요금입니다(트리거되지 않은 경우 0).
surcharge_applied	추가 요금 발생 여부(청구 가중치 < 임계값)
total_fee	최종 미수금(RMB, 가장 가까운 정수로 반올림).

HTTP	error	설명
401	missing_api_key	API 키가 제공되지 않습니다. Authorization 또는 X-API-Key 헤더를 추가하세요.
401	invalid_api_key	API 키가 잘못되었습니다.
403	key_suspended / key_revoked / key_expired	키가 비활성화/해지/만료되었습니다.
403	insufficient_scope	키에 freight:read 권한이 없습니다.
422	validation_failed	매개변수 형식 오류(유형, 범위)입니다.
422	missing_parameters	무게나 전체 길이/너비/높이는 제공되지 않습니다.
422	unsupported_method	메소드가 사용 가능한 목록에 없습니다.
429	rate_limit_exceeded	분당 요청 제한을 초과하는 경우 Retry-After를 참조하세요.

0337.tw는 Laravel 쇼핑몰입니다. 배송비 API를 백엔드 서비스에 패키징하고 결제 프로세스 중에 다음을 호출하는 것이 좋습니다.

• 결제 시 장바구니의 총 중량(kg)/부피를 가져온 후 백엔드에서 /api/v1/freight/quote를 호출하고 반환된 total_fee를 배송비로 설정하세요.
• 키는 .env(예: LUCKY_FREIGHT_KEY)에 있으며 config()를 사용하여 읽습니다. 프로그램 코드나 프런트 엔드에 하드 코딩하지 마세요.
• 호출이 실패하면(timeout/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은 계속 호환됩니다.

변경 내역: 2026-06-01 — Freight API v1이 온라인에 출시되었습니다(Hai Express, RMB로 가격 책정).