VibeFox GIG Logistics for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

WooCommerce: 5.0 이상, 설치 및 활성화되어 있어야 합니다. WooCommerce가 없으면 플러그인이 활성화되지 않습니다.

PHP: 8.0 이상.

GIG Logistics API 자격 증명(실시간 요금에만 필요): 실시간 요금은 GIG Logistics 타사 API를 사용합니다. GIG Logistics는 법인 고객에게 API 사용자 이름(보통 이메일 주소)과 비밀번호를 발급합니다. GIG Logistics 개발자 페이지(giglogistics.com/developer)에서 신청하세요. 테스트 자격 증명은 테스트 API에서만 작동합니다. 요금표와 대체 요금만 사용한다면 API 자격 증명은 필요하지 않습니다.

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

설치

1. WordPress에서 Plugins > Add New > Upload Plugin으로 이동하여 플러그인 ZIP 파일을 선택하고 Install Now를 클릭합니다. FTP로 vfd_gig_logistics 폴더를 /wp-content/plugins/에 업로드할 수도 있습니다.

2. Activate를 클릭합니다.

3. 설정을 엽니다: WooCommerce > Settings > Shipping > VibeFox GIG Logistics, 또는 플러그인 페이지에서 플러그인 이름 아래의 Settings를 클릭합니다.

4. 페이지 상단의 라이선스 블록에 VibeFox 라이선스 키를 입력하고 Activate를 클릭합니다.

5. 요금표 및/또는 대체 요금을 입력합니다. 실시간 요금을 사용하려면 API 사용자 이름과 비밀번호, 집화 전화번호, 도시와 주(State)도 입력하고, 쇼핑몰 통화가 NGN이 아니라면 통화 환산 비율도 입력합니다(설정 참조).

6. WooCommerce > Settings > Shipping > Shipping zones에서 나이지리아용 배송 지역에 VibeFox GIG Logistics를 추가하거나, Ignore shipping zones를 켜고 국가를 선택합니다.

설정

모든 설정은 한 페이지에 있습니다: WooCommerce > Settings > Shipping > VibeFox GIG Logistics. 모든 배송 지역에 적용됩니다. 배송 지역에 방법을 추가하면 지역 창에는 필드가 하나만 표시됩니다:

Title (zone): 이 지역에서 고객이 보는 이름입니다. 비워 두면 전역 Method title을 사용합니다.

필드 위에는 실시간 요금을 사용할 수 없을 때 경고가 표시됩니다. API 사용자 이름과 비밀번호 중 하나만 입력되었거나, Sender phone 또는 집화 도시와 주가 없거나, 쇼핑몰 통화가 NGN이 아니고 Currency conversion rate가 설정되지 않은 경우입니다. 설정을 저장할 때마다 캐시된 요금과 API 토큰이 지워집니다.

General

Enable/Disable: 모든 지역에서 방법을 한꺼번에 켜거나 끕니다. 기본값: 켜짐.

Method title: 장바구니와 체크아웃에 표시되는 배송 방법 이름입니다. 기본값: GIG Logistics. 지역 제목이 이것을 대체합니다.

Tax status: Taxable은 요금에 쇼핑몰의 배송 세금을 더하고, None은 더하지 않습니다. GIG 요금에 청구하려는 모든 항목이 이미 포함되어 있다면 None을 선택하세요.

GIG Logistics API(실시간 요금)(선택 사항)

API 자격 증명을 입력하면 나이지리아의 각 주소에 대해 GIG Logistics에 요금을 요청합니다. 자격 증명이 없거나 API가 요금을 반환하지 않으면 요금표와 대체 요금이 사용됩니다.

API username: GIG Logistics 타사 API 사용자 이름입니다. 보통 이메일 주소입니다.

API password: GIG Logistics 타사 API 비밀번호입니다. API 로그인에만 사용되며, 로그에 기록되지 않습니다.

Test mode: GIG Logistics 테스트(dev) API를 사용합니다. 테스트 자격 증명은 테스트 API에서만 작동합니다. 실제 요금을 받으려면 끄세요. 기본값: 꺼짐.

Currency conversion rate: GIG Logistics는 요금을 NGN으로 반환합니다. 쇼핑몰 통화가 NGN이 아니라면, 1 NGN이 쇼핑몰 통화로 얼마인지 입력하세요(1 NGN = ? 쇼핑몰 통화, 예: 0.0006). 이 값이 없으면 GIG 실시간 요금은 사용되지 않습니다. 쇼핑몰 통화가 NGN이면 이 필드는 필요하지 않습니다. 소수점으로 점과 쉼표 모두 사용할 수 있습니다.

집화(발송인) 주소

GIG Logistics가 나이지리아에서 소포를 집화하는 위치입니다. 쇼핑몰이 나이지리아에 있다면, 비워 둔 도로명, 도시, 주 필드는 WooCommerce > Settings > General의 쇼핑몰 주소를 사용합니다.

Sender name: GIG Logistics에 전달되는 발송인 이름입니다. 비워 두면 사이트 이름을 사용합니다.

Sender phone: 전화번호입니다(예: 08030000000). 실시간 요금에 GIG Logistics가 요구합니다.

Street address: 집화 도로명 주소입니다.

City / area: 집화 도시 또는 지역입니다(예: Victoria Island). 실시간 요금에 필요합니다.

State: 집화 주소의 나이지리아 주입니다. 기본적으로 쇼핑몰의 주를 사용합니다. 실시간 요금에 필요합니다.

Pickup latitude: 지도상 집화 지점의 위도입니다(선택 사항, 예: 6.4281). GIG Logistics는 거리에 따라 요금을 계산합니다. 비워 두면 주소에서 좌표를 찾습니다.

Pickup longitude: 지도상 집화 지점의 경도입니다(선택 사항, 예: 3.4219).

Address lookup: OpenStreetMap(Nominatim)으로 주소의 지도 좌표를 찾습니다. GIG Logistics는 집화 및 배송 좌표로 요금을 계산합니다. 고객의 도로명, 도시, 주는 nominatim.openstreetmap.org로 전송되며, 결과는 30일 동안 캐시됩니다. 이 옵션을 끄면 주소 텍스트만 전송되며, GIG Logistics가 요금을 반환하지 않을 수 있습니다. 기본값: 켜짐.

요금표 및 대체 요금

실시간 요금이 설정되지 않았거나 GIG Logistics가 요금을 반환하지 않을 때 다른 국가에 사용됩니다. 요금은 쇼핑몰 통화로 입력합니다.

Country prices: 국가별 기본 요금이 있는 표입니다. Add country를 클릭하여 행을 추가하고, X 표시를 클릭하여 행을 제거합니다. 자체 행이 없는 모든 국가에는 * Any other country를 선택합니다. XS(1kg 이하), S(2kg 이하), M(3kg 이하), L(5kg 이하), XL(5kg 초과) 열은 선택적인 무게 구간 요금입니다. 0보다 큰 구간 요금은 해당 구간 장바구니의 기본 요금을 대체합니다. 요금 0은 무료 배송을 의미합니다. 빈 요금 칸은 0으로 저장되므로, 추가하는 각 행에 기본 요금을 입력하세요. 행이 없는 국가(* 행이 없는 경우)는 요금표 요금을 받지 않습니다.

Fallback cost: GIG Logistics와 요금표 모두 요금을 제공하지 않을 때 사용됩니다. 비워 두면 그 경우 배송 방법이 숨겨집니다.

Table / fallback price is: Per order는 요금을 한 번만 청구합니다. Per item (multiplied by the number of items)는 장바구니의 상품 수를 곱합니다. GIG 실시간 요금은 항상 주문 전체에 대한 것입니다.

조건

Free shipping from: 배송이 무료가 되는 장바구니 소계 금액입니다. 비워 두면 무료가 되지 않습니다.

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

Min weight (kg): 장바구니의 최소 무게(kg)입니다. 상품 무게는 쇼핑몰의 무게 단위에서 변환됩니다. 0은 제한 없음을 의미합니다.

Max weight (kg): 장바구니의 최대 무게(kg)입니다. 기본값: 30. 0은 제한 없음을 의미합니다.

Excluded shipping classes: 장바구니에 이 WooCommerce 배송 클래스의 상품이 있으면 방법을 숨깁니다.

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

Ignore shipping zones: 방법이 지역에 추가되지 않았더라도 아래 국가에 대해 제공합니다. 꺼져 있으면 방법은 추가된 배송 지역에서만 표시됩니다.

Countries: 이 모드의 배송 대상 국가입니다. 비워 두면 배송하는 모든 국가가 대상이 됩니다. Ignore shipping zones와 함께 사용될 때만 적용됩니다.

고급

Debug log: 요금 계산을 WooCommerce > Status > Logs에 기록합니다(출처: vfd-gig-logistics). 로그가 꺼져 있어도 API 오류는 항상 기록됩니다. 비밀번호, 토큰, 고객 주소는 기록되지 않습니다.

Remove data on uninstall: 켜면 플러그인을 삭제할 때 설정, 지역 방법, 캐시가 제거됩니다. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다.

체크아웃에서의 작동 방식

고객이 배송 주소를 입력하면 WooCommerce가 플러그인에 요금을 요청합니다. 플러그인은 먼저 조건을 확인합니다: 배송 국가, 장바구니 무게, 최소 소계, 제외된 배송 클래스. 소계가 Free shipping from에 도달하면 방법이 요금 0으로 표시되지만, 해당 국가에 요금이 있는 경우에만 표시됩니다: Country prices의 행, Fallback cost, 또는 GIG Logistics 실시간 요금. GIG Logistics는 요금표와 대체 요금이 요금을 제공하지 않을 때만 조회됩니다.

그런 다음 요금은 요금을 제공하는 첫 번째 출처에서 가져옵니다. 먼저 API 자격 증명이 입력되어 있고, 주소가 나이지리아에 있으며, 고객이 도시 또는 주를 입력했고, 집화 전화번호·도시·주가 설정되어 있으며, NGN이 아닌 쇼핑몰의 경우 환산 비율이 설정되어 있으면 GIG Logistics 실시간 요금을 사용합니다. 플러그인은 GIG Logistics API에 로그인하고, 집화 및 배송 주소와 좌표, 그리고 장바구니 상품의 이름, 수량, 무게, 가치를 전송합니다. 무게가 없는 상품은 1kg으로 전송됩니다. 요금은 bike 배송으로 요청됩니다. 두 번째는 Country prices 요금표입니다. 세 번째는 Fallback cost입니다. 어떤 출처도 요금을 제공하지 않으면, 그 장바구니에서는 배송 방법이 숨겨집니다.

GIG의 각 응답은 1시간 동안 캐시되므로, 같은 장바구니가 새 요청을 일으키지 않습니다. 실패한 요청이나 로그인은 10분 동안 캐시되므로, 체크아웃이 새로 고침될 때마다 GIG Logistics를 기다리지 않습니다. 로그인 토큰은 30분 동안 유지되며, GIG가 거부하면 자동으로 갱신됩니다. API 제한 시간은 10초, 주소 조회 제한 시간은 5초입니다.

GIG Logistics가 오류 또는 0 요금을 반환하더라도 고객에게는 오류가 표시되지 않습니다. 요금표 또는 대체 요금이 사용되며, 오류는 로그에 기록됩니다.

이 방법은 클래식 체크아웃과 장바구니 및 체크아웃 블록에서 작동합니다. WooCommerce 고성능 주문 저장소(HPOS)와 호환됩니다.

이 플러그인은 요금만 계산합니다. GIG Logistics 배송, 운송장, 라벨은 생성하지 않으며, 집화 예약, 택배 추적, 고객의 서비스 센터 선택 기능도 제공하지 않습니다. 주문은 평소처럼 귀사의 GIG Logistics 계정을 통해 배송됩니다. 실시간 요금은 나이지리아 주소에 대해서만 요청됩니다. 다른 국가에는 요금표를 사용하세요.

라이선스 키

이 플러그인은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록은 WooCommerce > Settings > Shipping > VibeFox GIG Logistics 페이지 상단에 있습니다. 키를 License key에 붙여 넣고 Activate를 클릭합니다. 블록에는 상태가 표시됩니다. 예를 들어 라이선스가 유효한 날짜와 도메인이 나타납니다. 상태를 다시 확인하려면 Check now, 다른 키를 입력하려면 Change key, 이 사이트에서 키를 제거하려면 Remove key를 사용하세요. Manage licenses and domains in your account 링크는 vibefox.net 계정을 엽니다.

키 하나는 도메인 하나에서 작동합니다. 사이트에서 키를 제거해도 그 도메인 슬롯은 해제되지 않습니다. vibefox.net 계정에서 슬롯을 해제하세요.

활성 키가 없으면 GIG Logistics는 체크아웃에서 고객에게 표시되지 않습니다. 로그인한 쇼핑몰 관리자에게는 (unlicensed — visible to admins only)라고 표시되어 여전히 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 표시됩니다. 기존 주문에는 영향이 없습니다.

라이선스가 만료되어도 플러그인은 계속 작동하지만, 업데이트와 지원에는 갱신이 필요합니다. 상태는 백그라운드에서 자동으로 다시 확인됩니다.

문제 해결

GIG Logistics가 체크아웃에 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 방법이 고객 국가의 지역에 추가되어 있는지(또는 Ignore shipping zones가 켜져 있고 국가가 허용되어 있는지) 확인하세요. 무게 제한, Minimum subtotal, Excluded shipping classes도 확인하세요. 요금표(해당 국가 또는 *) 또는 Fallback cost가 해당 국가에 요금을 제공하는지 확인하세요.

요금이 GIG Logistics가 아니라 요금표에서 옴: 실시간 요금에는 API 사용자 이름과 비밀번호, Sender phone, 집화 도시와 주, 도시 또는 주가 포함된 나이지리아 배송 주소가 필요합니다. 그리고 NGN이 아닌 쇼핑몰의 경우 Currency conversion rate가 필요합니다. 설정 페이지 상단의 경고를 확인하세요. Debug log를 켜고 체크아웃을 새로 고침한 다음, WooCommerce > Status > Logs(출처: vfd-gig-logistics)를 열어 이유를 확인하세요. 실패한 요청은 10분 후에 다시 시도됩니다.

로그에 Login failed 표시: GIG Logistics가 API 사용자 이름 또는 비밀번호를 거부했습니다. 두 값을 확인하고 Test mode도 확인하세요. 테스트 자격 증명은 테스트 API에서만 작동합니다. 설정을 저장하면 즉시 다시 시도합니다.

GIG Logistics가 요금을 반환하지 않음: GIG는 거리에 따라 요금을 계산합니다. Address lookup을 켜 두거나 Pickup latitude와 Pickup longitude를 입력하세요. 실제 운영 전에 GIG Logistics 계정에서 요금을 확인하세요.

GIG 요금 위에 세금이 부과됨: GIG 요금에 청구하려는 모든 항목이 이미 포함되어 있다면 Tax status를 None으로 설정하세요.

변경 후 요금이 오래된 것처럼 보임: 설정 페이지를 저장하세요. 이렇게 하면 캐시된 요금과 토큰이 지워집니다.

자체 지오코더: 개발자는 vfd_gigl_pre_geocode 필터로 자체 주소 조회를 제공할 수 있습니다.

라이선스 블록에 오류가 표시됨: 블록의 메시지를 따르세요. 예를 들어 키가 다른 도메인에서 이미 사용 중이라면, vibefox.net 계정에서 슬롯을 해제하고 Check now를 클릭하세요. 사이트 주소가 바뀌었다면 Check now를 클릭해 새 도메인에 키를 활성화하세요. 라이선스 서버에 연결할 수 없으면 플러그인은 마지막으로 확인된 상태로 계속 작동합니다.

삭제

플러그인을 비활성화하면 모든 데이터가 유지됩니다. 완전히 제거하려면 비활성화한 후 Plugins 페이지에서 삭제하세요. 이 플러그인의 라이선스 키와 라이선스 상태는 항상 제거됩니다. 설정, 지역 방법, 캐시된 요금, 토큰, 주소 조회는 Remove data on uninstall이 켜져 있었을 때만 제거됩니다. 그렇지 않으면 나중에 재설치할 때를 위해 남겨집니다. 기존 주문은 배송 항목을 유지합니다.

GIG Logistics는 해당 소유자의 상표입니다. 이 플러그인은 GIG Logistics와 제휴하거나 GIG Logistics의 승인을 받은 제품이 아닙니다.