VibeFox SF Express for OpenCart — 도움말

요구 사항

OpenCart: 3.0.x(3.0.5.0에서 테스트됨) 또는 4.0.2 이상(4.1.0.3에서 테스트됨).

PHP: 8.0 이상.

SF Express 계정(실시간 요금에만 해당): 실시간 요금은 SF Express FengQiao 오픈 플랫폼(open.sf-express.com)을 사용합니다. SF Express 월 결제 계정과 FengQiao 개발자 계정이 필요합니다. 그곳에 가입하여 애플리케이션을 만들고, API "Delivery time standard and price query"(EXP_RECE_QUERY_DELIVERTM)를 추가한 뒤 고객 코드와 체크워드를 복사하세요. 샌드박스와 운영 환경의 체크워드는 다릅니다. 요금표만 사용한다면 SF Express 계정은 필요하지 않습니다.

중국의 성(실시간 요금에만 해당): 실시간 요금에는 배송 주소의 성이 필요하며, 이는 주소의 OpenCart 지역(Region / State)입니다. OpenCart에는 중국의 지역이 등록되어 있지만 티베트는 없습니다. 이 확장 기능이 대신 추가해 드릴 수 있습니다(아래 Chinese provinces 참조).

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 하나는 도메인 하나에서 작동합니다.

설치

다운로드는 OpenCart 두 버전용 패키지가 들어 있는 zip 파일 하나입니다. 컴퓨터에서 압축을 푸세요. 여기에는 README.txt, OpenCart 3 패키지 vfd_sf_express-oc3-(version).ocmod.zip, OpenCart 4 패키지 vfd_sf_express.ocmod.zip이 들어 있습니다. 사용 중인 OpenCart 버전의 패키지만 설치하세요. 라이선스 키는 두 버전에 동일하게 사용됩니다.

OpenCart 3

1. 관리자 페이지에서 Extensions > Installer로 이동하여 Upload를 클릭하고 vfd_sf_express-oc3-(version).ocmod.zip 파일을 선택합니다. 이 확장 기능은 OCMOD 수정 사항을 추가하지 않으므로 Extensions > Modifications를 새로 고칠 필요가 없습니다. Installer 대신, 패키지의 upload 폴더 내용을 쇼핑몰의 루트 폴더에 복사할 수도 있습니다.

2. Extensions > Extensions로 이동하여 확장 기능 유형으로 Shipping을 선택합니다. VibeFox SF Express를 찾아 Install(녹색 + 버튼)을 클릭합니다.

3. Edit(연필 버튼)을 클릭하여 설정 페이지를 엽니다.

4. Edit 페이지 상단의 라이선스 블록에 있는 License key에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다(라이선스 키 참조).

5. 요금표 및/또는 기본 요금을 입력합니다.

6. 중국 본토에서 실시간 요금을 사용하려면 고객 코드와 체크워드, 발송 성과 도시를 입력하세요. 쇼핑몰의 통화가 CNY가 아니라면 통화 환산 환율도 입력합니다. 페이지에서 요청하면 Add Chinese provinces를 클릭합니다. 먼저 Sandbox와 샌드박스 인증 정보로 테스트하세요.

7. Enable SF Express를 켜고 Save를 클릭합니다.

OpenCart 4

1. 관리자 페이지에서 Extensions > Installer로 이동하여 Upload를 클릭하고 vfd_sf_express.ocmod.zip 파일을 선택합니다. 파일 이름을 바꾸지 마세요. OpenCart 4는 파일 이름에서 확장 기능 코드를 가져오므로, 이름을 바꾼 패키지는 작동하지 않습니다.

2. 패키지는 같은 페이지의 설치된 확장 기능 목록에 나타납니다. 그 옆의 Install(녹색 + 버튼)을 클릭합니다.

3. Extensions > Extensions로 이동하여 확장 기능 유형으로 Shipping을 선택합니다. VibeFox SF Express를 찾아 Install(녹색 + 버튼)을 클릭한 다음 Edit(연필 버튼)을 클릭합니다.

4. 라이선스 키와 설정은 OpenCart 3의 4~7단계와 같이 입력합니다. 설정 페이지와 그 필드는 두 버전에서 동일합니다.

설치 후에는 Enable SF Express를 켜고 저장하기 전까지 이 배송 방법이 꺼져 있습니다. 제거 후 확장 기능을 다시 설치하면, 보존해 둔 SF Express 설정이 다시 사용됩니다.

구성

모든 설정은 확장 기능 페이지에 있습니다: Extensions > Extensions > Shipping > VibeFox SF Express > Edit. 섹션은 왼쪽에 나열됩니다. 설정은 모든 지역(geo zone)에 적용됩니다. 페이지 하단의 Save 버튼 하나로 페이지를 새로 고치지 않고 전체를 저장합니다. 저장할 때마다 캐시된 SF Express 요금도 삭제됩니다. 이 확장 기능의 수정 권한이 있는 관리자 사용자만 설정을 저장할 수 있습니다.

저장할 때 확장 기능은 값을 검사합니다. 빈 배송 방법 이름, 64자를 넘거나 < > ; = # { } 문자가 포함된 이름, 숫자가 아닌 값, 음수 금액 또는 무게, 환율 0, Max weight (kg)보다 큰 Min weight (kg), 요금표의 잘못된 요금, 정수가 아닌 정렬 순서는 메시지와 함께 거부되며, 수정할 때까지 아무것도 저장되지 않습니다. 설정 위쪽의 경고는 실시간 요금 설정이 일부만 완료된 경우(누락된 설정이 나열됨), 통화 환산 환율이 없는 경우, 쇼핑몰에 중국 지역이 없는 경우, 또는 쇼핑몰에 kg 무게 단위나 cm 길이 단위가 없고 기본 단위를 확장 기능이 알 수 없는 경우를 알려 줍니다.

일반

Enable SF Express: 체크아웃에서 SF Express를 표시하거나 숨깁니다. 기본값: 끔.

Method title: 장바구니와 체크아웃에 표시되는 배송 방법 이름. 기본값: SF Express. 필수 항목이며 최대 64자입니다.

Tax class: 배송비의 세금 클래스, 또는 No tax. 세금 클래스를 선택하면 쇼핑몰의 배송 세금이 배송비에 더해집니다. SF Express 요금에 청구하려는 모든 항목이 이미 포함되어 있다면 No tax를 선택하세요.

Sort order: 체크아웃에서 배송 방법 목록 중 SF Express의 위치. 정수입니다.

SF Express FengQiao API(실시간 요금)(선택 사항, 중국 본토 배송 주소용)

Customer code (partnerID): FengQiao 애플리케이션의 고객 코드(顾客编码). 이 값을 지우면 저장된 체크워드도 함께 지워지므로 인증 정보를 제거할 수 있습니다.

Checkword: 같은 환경의 체크워드(校验码). 요청에 서명하는 데만 사용되며, 전송되거나 기록되지 않습니다. 저장한 후 이 필드는 비어 있으며 Saved — leave empty to keep it.를 표시합니다. 변경하려는 경우에만 새 값을 입력하세요.

Sandbox: 샌드박스 인증 정보로 테스트할 때 FengQiao 샌드박스(sfapi-sbox.sf-express.com)를 사용합니다. 샌드박스 요금은 실제 요금이 아닙니다. 실제 운영 쇼핑몰에서는 끄세요. 기본값: 끔.

SF Express product: 요금이 표시될 SF Express 상품.

Cheapest product offered by SF Express: 기본값. SF Express가 반환하는 가장 낮은 요금을 사용합니다.

SF Express Priority (顺丰特快, code 1): 이 상품의 요금만 사용합니다.

SF Standard Express (顺丰标快, code 2): 이 상품의 요금만 사용합니다.

Sender province: 소포를 발송하는 성. 예: Guangdong / 广东. 쇼핑몰이 중국에 있을 경우 첫 번째 옵션은 쇼핑몰 지역(System > Settings > Store > Local)을 사용합니다. 그러면 성 이름과 함께 Same as the store region이 표시되며, 그렇지 않으면 — Select —가 표시됩니다.

Sender city: 표준 중국어 도시 이름. 예: 深圳市. 실시간 요금에 필수입니다. OpenCart의 쇼핑몰 주소는 자유 형식 텍스트이므로 도시는 거기서 가져오지 않습니다.

Currency conversion rate: SF Express 요금은 CNY(위안) 단위입니다. 쇼핑몰의 기본 통화가 CNY가 아니면, 1 CNY가 해당 통화로 얼마인지 입력하세요(1 CNY = ? 단위). 예: 0.13. 이 값이 없으면 실시간 요금을 사용하지 않습니다. 쇼핑몰 통화가 CNY라면 이 필드는 필요 없다고 표시되며, 요금은 그대로 사용됩니다. 소수점으로 점과 쉼표 모두 사용할 수 있습니다.

Chinese provinces: SF Express의 32개 성, 자치구, 직할시 중 OpenCart에서 중국 지역으로 되어 있는 수와 누락된 항목을 보여 줍니다. 누락된 성의 주소는 요금표 요금을 받습니다. Add Chinese provinces를 클릭하면 누락된 항목만 중국 지역(ISO 코드, "Tibet / 西藏" 같은 이름)으로 추가됩니다. 기존 지역은 변경되지 않습니다. 이 클릭 없이는 아무것도 변경되지 않습니다. 이렇게 추가된 지역은 제거 후에도 쇼핑몰에 남습니다.

요금표 및 기본 요금(홍콩, 마카오, 대만 및 기타 국가에 사용됩니다. 실시간 요금이 설정되지 않았거나 SF Express가 요금을 제공하지 않을 때 사용됩니다. 요금은 쇼핑몰의 기본 통화이며 세금은 제외됩니다)

Country prices: 국가별 기본 요금을 입력하는 표입니다. Add country를 클릭하면 행을 추가하고, 삭제 버튼으로 행을 삭제합니다. * All other countries 행은 자체 행이 없는 모든 국가에 적용됩니다. 0보다 큰 무게 구간 요금은 해당 구간의 소포에 대해 기본 요금을 대체합니다: XS는 1 kg까지, S는 2 kg까지, M은 3 kg까지, L은 5 kg까지, XL은 5 kg 초과입니다. Base 요금이 0이면 무료 배송을 의미합니다. 기본 요금이 비어 있으면 해당 국가의 요금이 없으며 기본 요금(fallback cost)이 사용됩니다. "9.99"와 "9,99" 모두 입력할 수 있습니다. 요금이 하나도 없는 행은 저장되지 않습니다.

Fallback cost: SF Express와 요금표 모두 요금을 제공하지 않을 때 사용됩니다. 이 경우 배송 방법을 숨기려면 비워 두세요.

Table / fallback price is: 요금표와 기본 요금을 어떻게 청구할지 정합니다.

Per order (tier by the total cart weight): 장바구니 총 무게에 맞는 구간의 요금을 한 번만 청구합니다.

Per item (every item is priced by its own weight): 각 상품은 자체 무게 구간의 요금으로 계산되고 수량을 곱합니다. 기본 요금은 상품 개수만큼 곱해집니다.

SF Express 실시간 요금은 항상 주문 전체를 기준으로 합니다.

조건

Free shipping from: 배송이 필요한 상품의 소계(쿠폰 적용 후, 세금 전) 금액으로, 이 금액 이상이면 배송이 무료입니다. 무료 배송을 제공하지 않으려면 비워 두세요. 무료 배송은 요금을 조회하기 전에 확인되므로, 이 금액 이상이면 요금표에 행이 없거나 Fallback cost가 없는 국가를 포함해 이 배송 방법을 사용할 수 있는 모든 배송지에 무료로 제공됩니다.

Minimum subtotal: 장바구니 소계가 이 금액에 도달한 경우에만 배송 방법을 표시합니다. 항상 표시하려면 비워 두세요.

Min weight (kg): 배송 방법을 표시하기 위한 최소 장바구니 무게(kg). 상품 무게는 해당 무게 클래스에서 변환됩니다. 0은 제한 없음을 의미합니다.

Max weight (kg): 장바구니 무게가 이 값을 넘으면 배송 방법을 숨깁니다. 기본값: 50. 0 또는 비어 있으면 제한 없음을 의미합니다.

Geo zone: 이 지역의 주소에만 SF Express를 제공합니다. All zones(기본값)는 제한 없음을 의미합니다. 지역은 System > Localisation > Geo Zones에서 관리합니다. Ignore shipping zones가 켜져 있으면 확인하지 않습니다.

배송 지역 없이 사용 가능 여부

Ignore shipping zones: 지역과 관계없이 아래 국가에 대해 SF Express를 제공합니다. 꺼져 있으면 지역에 따라 결정되며 국가 목록은 사용되지 않습니다.

Countries: 이 모드의 배송 대상 국가. 비워 두면 활성화된 모든 국가를 허용합니다. 이 필드는 Ignore shipping zones가 켜져 있을 때만 사용됩니다.

고급

Debug log: 요금 계산을 storage/logs/vfd_sfex_debug.log.php에 기록합니다. 이 파일은 웹에서 읽을 수 없습니다. 이 옵션이 꺼져 있어도 API 오류는 항상 기록됩니다. 체크워드나 고객 주소는 기록되지 않습니다. 파일이 5 MB에 도달하면 vfd_sfex_debug.old.log.php로 이동되고 새 로그가 시작됩니다.

Log: 로그의 크기와 최근 항목을 보여 줍니다. Clear log를 클릭하면 로그를 비웁니다.

Remove data on uninstall: 켜면 확장 기능을 제거할 때 설정과 로그가 삭제됩니다. 꺼져 있으면(기본값) 재설치를 위해 보존됩니다. 캐시된 요금은 항상 삭제됩니다.

가져오기 / 내보내기

Export: Download JSON을 클릭하면 체크워드를 제외한 설정을 JSON 파일로 저장합니다.

Import: 이전에 내보낸 JSON을 붙여 넣고 Import를 클릭하면 설정을 복원합니다. 값은 일반 저장과 같은 방식으로 검사됩니다. 저장된 체크워드는 유지됩니다.

체크아웃에서의 작동 방식

OpenCart가 배송 방법을 표시할 때 확장 기능에 SF Express 요금을 요청합니다. Geo zone이 설정되어 있고 주소가 그 밖에 있으면 SF Express는 제공되지 않습니다(Ignore shipping zones가 켜져 있는 경우는 제외). Requires Shipping이 Yes로 설정된 상품만 계산에 포함됩니다. 다른 상품은 무게를 더하지 않으며 소계에도 포함되지 않습니다. 소계는 이 상품들의 쿠폰 할인 후, 세금 전 가격입니다. 기프트 카드, 적립 포인트, 쇼핑몰 적립금은 고려되지 않습니다. 이후 확장 기능은 조건을 확인합니다. 허용된 국가(Ignore shipping zones 사용 시), 장바구니 무게, 최소 소계 금액입니다. 소계가 Free shipping from에 도달하면 요금은 0이 되고 SF Express로 요청을 보내지 않습니다.

고객 코드와 체크워드가 설정된 중국 본토 배송 주소의 경우, 확장 기능은 발송 성과 도시, 고객의 성과 도시, 장바구니 무게(최소 0.1 kg), 장바구니 부피(세 변이 모두 입력된 상품 기준)를 SF Express에 보냅니다. 요청은 체크워드로 서명됩니다. SF Express는 CNY로 요금을 반환하고, 확장 기능은 선택된 요금을 쇼핑몰의 기본 통화로 환산하여 소수점 자릿수에 맞게 반올림합니다. 그런 다음 선택된 Tax class의 세금과 함께 고객의 통화로 요금이 표시됩니다.

SF Express는 표준 중국어 이름으로 주소를 인식합니다. 고객의 성은 주소의 Region / State 지역에서 가져오며, 이름으로 매칭됩니다. "Hong Kong" 지역은 중국 본토의 성이 아니므로 요금표 요금을 받습니다. 도시는 중국어로 입력해야 합니다(예: 广州市). 베이징, 상하이, 톈진, 충칭의 경우 도시는 자동으로 채워집니다. "Guangzhou"처럼 라틴 문자로 입력한 도시는 요금표 요금을 받습니다.

각 요금은 1시간 동안 캐시되므로 같은 장바구니가 새로운 요청을 일으키지 않습니다. 실패한 요청은 10분 동안 캐시되므로 체크아웃이 새로 고칠 때마다 SF Express를 기다리지 않습니다. HTTP 제한 시간은 10초입니다.

실시간 요금이 없으면 요금은 요금표에서, 그 다음에는 Fallback cost에서 가져옵니다. 둘 다 적용되지 않으면 배송 방법은 숨겨집니다. 고객은 오류를 보지 않습니다. 오류는 로그에 기록됩니다.

이 확장 기능은 요금만 계산합니다. 운송장이나 라벨을 만들지 않고, SF Express에 주문을 생성하지 않으며, 방문 수거를 예약하거나 배송을 취소하거나 추적하지 않습니다. 평소처럼 SF Express 계정에서 배송을 생성하고 추적하세요. 고객은 SF 서비스 지점이나 사물함을 선택할 수 없습니다. SF Express는 문 앞까지 배송하는 택배로 사용됩니다. 실시간 요금은 중국 본토 배송 주소에만 제공됩니다. 이 확장 기능은 FengQiao 문서와 모의 응답을 바탕으로 개발되었으므로, 실제 운영 전에 (먼저 샌드박스에서) SF Express 계정으로 요금을 확인하세요.

OpenCart 4에서는 고객이 체크아웃 페이지의 배송 방법 블록에서 Choose를 클릭하고, Shipping method options 창에서 SF Express를 선택합니다. 이 창에는 배송 방법 이름과 요금이 표시됩니다. 이 배송 방법은 OpenCart 3과 같은 방식으로 작동합니다.

라이선스 키

이 확장 기능은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. License — VibeFox SF Express 라이선스 블록은 Extensions > Extensions > Shipping > VibeFox SF Express > Edit 페이지에서 설정 위쪽에 있는 첫 번째 블록입니다. 키를 License key에 붙여 넣고 Activate를 클릭하세요. 그러면 블록에 마스킹된 키, 상태(예: 라이선스 사용 기한 날짜와 도메인), 그리고 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 표시됩니다. 그 아래에는 Product: opencart-shipping-sf-express 줄과 vibefox.net 계정을 여는 링크 Manage licenses and domains in your account가 있습니다. 확장 기능에 대한 Modify 권한이 있는 관리자 사용자만 키를 변경할 수 있습니다. 블록의 문구는 관리자 언어를 따릅니다(영어와 러시아어가 포함됨).

키가 승인되지 않으면 블록에 이유가 표시됩니다. 예: Key not found, This key belongs to another product, Domain limit reached, 또는 날짜가 포함된 License expired on. 쇼핑몰 주소를 변경한 후, 또는 계정에서 도메인 슬롯을 해제한 후에는 Check now를 클릭하세요. 라이선스 서버에 연결할 수 없으면 확장 기능은 마지막으로 확인된 상태로 계속 작동합니다.

키 하나는 도메인 하나에서 작동합니다. 도메인은 OpenCart 설정의 쇼핑몰 주소입니다. 쇼핑몰에서 키를 제거해도 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하세요.

활성 키가 없으면 SF Express 배송 방법은 체크아웃에서 고객에게 표시되지 않고 요금도 계산되지 않습니다. 같은 브라우저에서 관리자 페이지에 로그인한 관리자 사용자에게는 쇼핑몰에 (unlicensed — visible to admins only) 표시와 함께 이 방법이 계속 보이므로, 키를 구매하기 전에 확장 기능을 설정하고 테스트할 수 있습니다. OpenCart 4에서는 이 미리보기를 사용할 수 없습니다. 쇼핑몰이 관리자 로그인을 인식하지 못하므로, 활성 키가 없으면 모든 사용자에게 이 방법이 숨겨집니다. Edit 페이지를 한 번 열면 관리자 Dashboard에 알림이 나타납니다. ×를 눌러 닫으면 7일 동안 숨겨집니다. 기존 주문에는 영향을 주지 않습니다.

라이선스가 만료되어도 확장 기능은 계속 작동하지만, 업데이트와 지원을 받으려면 갱신이 필요합니다. 관리자 Dashboard나 Edit 페이지를 열면 상태가 자동으로 다시 확인됩니다. 키를 입력한 후 처음 14일 동안은 하루에 한 번, 그 후에는 일주일에 한 번입니다. 크론 작업은 필요하지 않습니다. 확장 기능을 제거하면 라이선스 키와 라이선스 상태는 항상 삭제됩니다.

문제 해결

체크아웃에 SF Express가 나타나지 않음: 라이선스가 활성 상태이고 Enable SF Express가 켜져 있는지 확인하세요. Geo zone을 확인하거나 Ignore shipping zones를 켜고 Countries를 확인하세요. 무게 제한과 Minimum subtotal을 확인하세요. 요금표나 Fallback cost에 해당 국가의 요금이 있는지 확인하세요. 상품의 Requires Shipping이 Yes로 설정되어 있는지 확인하세요.

요금이 SF Express가 아니라 요금표에서 나옴: 실시간 요금에는 고객 코드와 체크워드, 발송 성과 도시, 성과 중국어 도시 이름이 있는 중국 본토 배송 주소, 그리고(CNY가 아닌 쇼핑몰의 경우) 통화 환산 환율이 필요합니다. 확장 기능 페이지 상단의 경고를 읽은 다음 Debug log를 켜고, 체크아웃을 새로 고친 후 Log 필드에서 원인을 확인하세요. 실패한 요청은 10분 후에 다시 시도됩니다.

로그에 서명 오류가 표시됨: 체크워드가 잘못되었거나 다른 환경의 것입니다. Sandbox 설정을 확인하세요. SF Express가 API 사용이 허용되지 않는다고 알리면, FengQiao 애플리케이션에 요금 조회 API를 추가하세요.

티베트 주소가 요금표 요금을 받음: 확장 기능 페이지의 API 섹션에서 Add Chinese provinces를 클릭하세요.

홍콩: 요금표와 기본 요금으로 작동합니다. FengQiao 요금 조회는 중국 본토 주소를 대상으로 합니다.

변경 후 요금이 오래된 것처럼 보임: 확장 기능 페이지에서 Save를 클릭하세요. 캐시된 SF Express 요금이 삭제됩니다.

페이지에 "Warning: You do not have permission to modify VibeFox SF Express!"가 표시됨: 관리자 사용자 그룹이 설정을 보기만 할 수 있습니다. System > Users > User Groups에서 그룹에 extension/shipping/vfd_sf_express(OpenCart 3) 또는 extension/vfd_sf_express/shipping/vfd_sf_express(OpenCart 4)에 대한 수정 권한을 부여하세요.

개발자용: OpenCart 이벤트 vfd_sf_express/quote_request와 vfd_sf_express/api_url을 사용하면 다른 확장 기능이 요금 요청(예: 다른 상품 코드로 변경)과 게이트웨이 URL을 변경할 수 있습니다.

제거

Extensions > Extensions로 이동하여 유형으로 Shipping을 선택하고, VibeFox SF Express 옆의 Uninstall(빨간색 − 버튼)을 클릭하세요. 이 확장 기능의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. OpenCart는 항상 Enable SF Express, Sort order, Tax class, Geo zone을 초기화합니다. 캐시된 요금은 항상 삭제됩니다. Remove data on uninstall이 켜져 있으면 다른 설정과 로그도 삭제됩니다. 꺼져 있으면 보존되며, 확장 기능을 다시 설치할 때 다시 사용됩니다. Add Chinese provinces로 추가한 중국 지역은 남아 있습니다. 기존 주문은 배송 방법과 비용을 그대로 유지합니다.

OpenCart 4에서 확장 기능의 파일도 함께 제거하려면, 제거 후 Extensions > Installer로 이동하여 설치된 확장 기능 목록에서 VibeFox SF Express 옆의 Uninstall(주황색 − 버튼)을 클릭한 다음, 업로드한 패키지를 삭제하도록 Delete(빨간색 휴지통 버튼)를 클릭하세요.

SF Express는 각 소유자의 상표입니다. 이 확장 기능은 SF Express와 제휴하거나 SF Express의 승인을 받은 것이 아닙니다.