VibeFox Delhivery for WooCommerce — 도움말

요구 사항

WordPress: 5.8 이상.

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

PHP: 8.0 이상.

Delhivery API 토큰(실시간 요금에만 필요): Delhivery One에 로그인하고 Settings > API setup을 여세요. Delhivery 도움말 문서 "API token generation"에 단계가 설명되어 있습니다. 테스트 토큰은 스테이징 환경에서 사용할 수 있습니다. 또한 집화 장소의 6자리 PIN 코드가 필요합니다. 고정 요금만 사용하는 경우 토큰은 필요하지 않습니다.

VibeFox 라이선스 키: vibefox.net에서 구매합니다. 키 1개는 도메인 1개에서 사용할 수 있습니다.

설치

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

2. Activate를 클릭하세요.

3. 설정을 여세요: WooCommerce > Settings > Shipping > VibeFox Delhivery. 또는 플러그인 목록 페이지에서 플러그인 이름 아래의 Settings를 클릭하세요.

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

5. API 토큰과 출발지 PIN 코드를 입력하고, Express 또는 Surface와 Pre-paid 또는 COD를 선택하세요. 쇼핑몰 통화가 INR이 아니면 환율을 입력하세요. 필요하면 고정 요금을 입력하세요(설정 항목 참조).

6. WooCommerce > Settings > Shipping > Shipping zones에서 VibeFox Delhivery를 배송 지역(예: 인도)에 추가하거나, Ignore zones를 켜고 국가를 선택하세요.

설정

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

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

설정을 저장할 때마다 캐시된 Delhivery 요금이 삭제됩니다. 가격과 금액은 "9.99"와 "9,99"를 모두 입력할 수 있습니다.

일반

Enable/Disable: 모든 지역에서 이 방법을 한 번에 켜거나 끕니다.

Method title: 체크아웃에 표시되는 배송 방법 이름. 기본값: Delhivery. 지역별로 자체 Title을 설정해 재정의할 수 있습니다.

Tax status: Taxable은 배송비에 WooCommerce 세금을 추가하고, None은 추가하지 않습니다.

Delhivery API 계정(실시간 요금에만 필요)

Environment: Production (track.delhivery.com)(기본값) 또는 Staging / test account (staging-express.delhivery.com). Staging은 Delhivery 테스트 토큰을 사용할 때만 선택하세요.

API token: Delhivery API 토큰. 인증 헤더로만 전송되며 로그에는 절대 기록되지 않습니다.

Origin pincode: 집화 장소나 창고의 6자리 PIN 코드(예: 110001).

실시간 요금

실시간 요금은 유효한 6자리 PIN 코드가 있는 인도 목적지에 대해, 정방향(배송) 출고의 경우 요청됩니다.

Shipping mode: 요금에 사용되는 Delhivery 과금 방식: Express(기본값) 또는 Surface.

Payment type: Delhivery에 전송되는 결제 유형: Pre-paid(기본값) 또는 COD(착불, Delhivery가 COD 요금을 추가합니다). 플러그인은 고객이 선택한 결제 수단에 따라 이 값을 바꾸지 않습니다.

Rate amount: Delhivery는 GST 포함 금액과 GST 제외 금액을 모두 반환합니다.

INR to (store currency) conversion rate: Delhivery 요금은 인도 루피로 표시됩니다. 쇼핑몰 통화가 INR이 아니면, 1루피가 쇼핑몰 통화로 몇 단위인지 입력하세요(예: 0.011). 비워 두면 실시간 요금은 사용되지 않고 고정 요금이 적용되며, 설정 위에 경고가 표시됩니다. 쇼핑몰 통화가 INR이면 필요하지 않습니다.

고정 요금(실시간 요금이 없을 때 사용)

고정 요금은 토큰이나 PIN 코드가 아직 없는 경우, 목적지가 인도 외 지역인 경우, PIN 코드가 배송 불가 지역인 경우, 또는 API가 오류를 반환하는 경우에 사용됩니다. 쇼핑몰 통화로 표시됩니다.

Prices per country: 한 줄에 하나씩, COUNTRY_CODE:price 형식으로 입력합니다(예: IN:120). 대체 요금보다 먼저 확인됩니다.

Fallback price: 실시간 요금도 국가별 요금도 적용되지 않을 때 사용됩니다. 비워 두면 이 방법이 숨겨집니다. 0은 무료를 의미합니다.

Fixed price is charged: Per order는 요금을 한 번만 청구합니다. Per item (price × quantity)은 장바구니의 상품 수량을 곱합니다. Delhivery 실시간 요금은 항상 전체 소포 무게 기준입니다.

조건

Free shipping from: 장바구니 소계가 이 금액 이상이면 배송이 무료입니다. Delhivery로 요청이 전송되지 않습니다. 비워 두면 기능이 꺼집니다.

Show from subtotal: 장바구니 소계가 이 금액 이상일 때만 이 방법을 표시합니다. 비워 두면 항상 표시됩니다.

Min weight (kg): 이 방법을 표시하기 위한 최소 장바구니 무게. 0은 제한 없음을 의미합니다.

Max weight (kg): 장바구니가 이보다 무거우면 이 방법을 숨깁니다. 기본값: 30. 0은 제한 없음을 의미합니다.

상품 무게는 쇼핑몰의 무게 단위에서 kg으로 변환됩니다. 요금은 실제 장바구니 무게(상품 무게의 합계)를 사용하며, 부피 무게나 박스는 고려하지 않습니다.

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

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

Ignore zones: 배송 지역에 추가하지 않고, 아래 국가를 대상으로 Delhivery를 제공합니다.

Countries: 이 모드의 배송 대상 국가. 비워 두면 배송하는 모든 국가를 사용합니다. Ignore zones가 켜진 경우에만 사용됩니다.

고급

Debug log: 요금 계산을 WooCommerce > Status > Logs에 기록합니다(소스: vfd_delhivery). 이 옵션이 꺼져 있어도 API 오류는 항상 기록됩니다. 토큰과 고객의 전체 PIN 코드는 절대 기록되지 않습니다.

Remove data on uninstall: 켜면 플러그인을 삭제할 때 모든 설정, 지역별 배송 방법, 캐시된 요금이 삭제됩니다. 플러그인을 비활성화해도 아무것도 삭제되지 않습니다.

체크아웃에서의 동작 방식

고객이 배송 주소를 입력하면 WooCommerce는 플러그인에 요금을 요청합니다. 플러그인은 먼저 장바구니 무게, 소계, 제외된 배송 클래스를 확인합니다. 무료 배송이 적용되면 고객은 무료로 배송받고 Delhivery로 요청이 전송되지 않습니다.

유효한 6자리 PIN 코드가 있는 인도 주소의 경우, 플러그인은 Delhivery에 출발지와 도착지 PIN 코드, 그램 단위의 장바구니 무게, 배송 모드, 결제 유형을 보내고, 반환된 금액을 쇼핑몰 통화로 환산해 보여 줍니다. 각 응답은 1시간 동안 캐시됩니다. 실패한 요청은 10분 동안 캐시되므로, 체크아웃이 새로 고침될 때마다 Delhivery를 기다리지 않습니다. API 제한 시간은 10초입니다.

실시간 요금이 없으면 국가별 요금이나 대체 요금을 사용합니다. 둘 다 설정되지 않았다면 이 방법은 숨겨집니다. 고객이 API 오류를 보는 일은 없습니다.

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

플러그인은 요금을 계산하고 추적 링크를 보여 줍니다. 배송이나 송장(waybill)을 생성하지 않고, 라벨을 인쇄하지 않으며, 집화나 매니페스트를 요청하지 않고, PIN 코드 배송 가능 여부를 확인하지 않으며, 배송 예정일을 추정하지 않고, 배송 상태를 동기화하지 않으며, Delhivery의 국제 요금을 산정하지 않습니다. 인도 외 지역에서는 고정 요금만 사용됩니다.

주문 및 추적

주문 화면의 배송 주소 아래에 있는 Delhivery 블록에는 배송 모드(Express 또는 Surface)와 요금 출처(Delhivery 실시간 요금, 고정 요금, 무료 배송 기준 금액)가 표시됩니다.

Delhivery One에서 배송을 생성한 다음, AWB를 Delhivery AWB / tracking number 필드에 붙여넣고 주문을 저장하세요. 관리자 화면에 Track on delhivery.com 링크가 나타납니다. 고객은 내 계정의 주문 페이지와 주문 이메일(HTML 및 텍스트)에서 링크가 포함된 Delhivery tracking을 보게 됩니다. AWB는 주문 상태보다 먼저 저장되므로, 같은 저장에서 주문을 완료하면 "완료된 주문" 이메일에 이미 AWB가 포함됩니다.

라이선스 키

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

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

활성 키가 없으면 체크아웃에서 고객에게 Delhivery가 표시되지 않습니다. 로그인한 스토어 관리자에게는 (unlicensed — visible to admins only) 표시와 함께 계속 보이므로, 키를 구매하기 전에 플러그인을 설정하고 테스트할 수 있습니다. 플러그인 페이지와 WooCommerce 페이지에 알림이 나타납니다. 기존 주문은 영향을 받지 않습니다.

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

문제 해결

체크아웃에 Delhivery가 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지, 고객 국가의 지역에 이 방법이 추가되어 있는지(또는 Ignore zones가 켜져 있고 국가가 허용되어 있는지) 확인하세요. 무게 제한, Show from subtotal, Excluded shipping classes도 확인하세요. 실시간 요금이 없으면 국가별 요금이나 Fallback price가 필요합니다.

실시간 요금이 나타나지 않음: API 토큰, 올바른 Origin pincode, 그리고 INR이 아닌 쇼핑몰이라면 환율을 확인하세요. 고객은 유효한 6자리 인도 PIN 코드를 입력해야 합니다. Debug log를 켜고 WooCommerce > Status > Logs에서 소스 vfd_delhivery를 열면 배송 불가 PIN 코드 같은 API 오류를 확인할 수 있습니다.

GST가 이중으로 부과됨: Delhivery의 총액에는 이미 GST가 포함되어 있습니다. Rate amount를 Gross amount (excluding GST)로 설정하거나, Tax status를 None으로 설정하세요.

테스트: Environment를 Staging으로 설정하고 Delhivery 테스트 토큰을 사용하세요.

변경 후 요금이 오래된 것처럼 보임: 설정 페이지를 저장하세요. 캐시된 Delhivery 요금이 삭제됩니다.

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

삭제

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

Delhivery는 각 소유자의 상표입니다. 이 플러그인은 Delhivery와 제휴하거나 Delhivery의 승인을 받은 것이 아닙니다.