VibeFox Instabee for OpenCart — 도움말

요구 사항

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

PHP: 8.0 이상.

Budbee API 자격 증명(택배함 선택에만 필요): API 키와 API 시크릿. Instabee가 배송 계약을 맺은 판매자에게 발급합니다. Instabee 담당자에게 문의하거나 Instabee 판매자 포털을 이용하세요. API 문서는 developer.budbee.com에 있습니다. 자격 증명이 없어도 이 배송 방법은 고정 요금으로 작동하지만, 고객은 택배함을 선택할 수 없습니다.

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

설치

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

OpenCart 3

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

2. Extensions > Extensions로 이동하여 확장 프로그램 유형으로 Shipping을 선택하세요. VibeFox Instabee를 찾아 Install(녹색 + 버튼)을 클릭하세요.

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

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

5. Prices 섹션을 작성하고, 택배함 선택기를 사용하려면 Budbee의 API key와 API secret을 입력하세요(설정 항목 참조). Enable/Disable을 켜고 Save를 클릭하세요.

OpenCart 4

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

2. 패키지는 같은 페이지의 설치된 확장 프로그램 목록에 나타납니다. 그 옆에 있는 Install(녹색 + 버튼)을 클릭하세요.

3. Extensions > Extensions로 이동하여 확장 프로그램 유형으로 Shipping을 선택하세요. VibeFox Instabee를 찾아 Install(녹색 + 버튼)을 클릭한 다음 Edit(연필 버튼)을 클릭하세요.

4. 라이선스 키와 설정은 OpenCart 3의 4단계와 5단계에서처럼 입력하세요. 설정 페이지와 그 항목은 두 버전에서 동일합니다.

설치 직후에는 Enable/Disable을 켜고 저장하기 전까지 이 배송 방법이 꺼져 있습니다. 제거 후 확장 프로그램을 다시 설치하면, 보관해 둔 Instabee 설정이 다시 사용됩니다.

설정

모든 설정은 확장 프로그램 페이지에 있습니다: Extensions > Extensions > Shipping > VibeFox Instabee > Edit. 섹션은 왼쪽에 나열됩니다. 하나의 Save 버튼으로 페이지를 새로 고치지 않고 전체 페이지를 저장합니다. 저장할 때마다 캐시된 택배함 목록과 마지막 API 오류도 지워집니다. 이 확장 프로그램에 대한 수정 권한이 있는 관리자 사용자만 설정을 저장할 수 있습니다.

설정 위의 경고는 다음 상황을 알려 줍니다. API 자격 증명을 하나만 입력한 경우, API 자격 증명이 전혀 없는 경우, 국가별 요금과 대체 요금이 모두 없는 경우, 마지막 Budbee API 요청이 실패한 경우(날짜, 시간, 사유 포함), 그리고 쇼핑몰에 kg 단위의 무게 등급이 없고 기본 무게 등급의 단위를 인식할 수 없는 경우입니다(이때 무게는 kg로 처리됩니다. System > Localisation > Weight Classes에서 kg 무게 등급을 추가하세요).

Method name이 비어 있거나 너무 길거나, Min weight (kg)이 Max weight (kg)보다 크거나, Sort order가 정수가 아니거나, 세금 등급 또는 지오존이 존재하지 않으면 아무것도 저장되지 않고 오류가 표시됩니다.

일반

Enable/Disable: 체크아웃에서 Instabee를 표시하거나 숨깁니다. 기본값: off.

Method name: 체크아웃에서 고객에게 표시되는 배송 방법 이름. 기본값: Instabee parcel box. 필수, 최대 64자.

Tax class: None (the prices are final)(기본값)은 아래 요금이 최종 금액임을 뜻합니다. 세금 등급을 선택하면 아래 요금에 해당 등급의 배송 세금이 추가됩니다.

Sort order: 체크아웃에서 배송 방법 중 Instabee의 표시 순서. 정수.

택배함 선택기(Budbee API)

API 자격 증명이 있으면 고객은 체크아웃에서 우편번호 근처의 택배함을 선택하고, 그 택배함이 주문에 저장됩니다. 두 항목 모두 필요합니다. 둘 다 설정되기 전까지 선택기는 꺼진 상태로 남습니다.

API key: Budbee API 키(HTTP Basic 사용자 이름).

API secret: Budbee API 시크릿(HTTP Basic 비밀번호). 로그에 기록되지 않습니다.

저장한 후에는 두 입력란이 비어 있고 Saved - leave empty to keep it.이 표시됩니다. 변경하려는 경우에만 새 값을 입력하세요. 저장된 자격 증명을 삭제하려면 Remove the saved API key and secret을 선택한 후 저장하세요. 저장된 것이 없으면 페이지에 No credentials saved.가 표시됩니다.

Test environment: Budbee 스테이징 API(api.staging.budbee.com)를 사용합니다. Instabee에서 받은 스테이징 자격 증명을 사용할 때만 켜세요. 운영 쇼핑몰은 꺼 두세요(api.budbee.com). 기본값: off.

가격(섹션 제목에 쇼핑몰의 기본 통화가 표시됩니다)

모든 요금은 세금 제외 기준으로 쇼핑몰의 기본 통화로 입력합니다. 소수점은 쉼표와 마침표 모두 허용됩니다(49,90 = 49.90). 요금은 고객의 통화로 표시됩니다.

Calculation type: 요금이 적용되는 방식.

Country prices: Country, Price, XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg, XL >5 kg 열이 있는 표입니다. Add country를 클릭하면 행이 추가되고, × 버튼을 클릭하면 행이 삭제됩니다. 자체 행이 없는 모든 국가에 적용되는 행에는 * Any other country를 선택하세요. 비어 있거나 0인 구간은 Price 열을 사용합니다. Price가 0이면 무료 배송을 뜻합니다. 국가 행에 장바구니 무게에 대한 요금이 없으면 * 행이, 그것도 없으면 Fallback cost가 사용됩니다. 저장할 때 0 이상의 숫자가 아닌 요금은 지워지고, 알 수 없는 국가의 행은 삭제되며, 경고에 이들이 나열됩니다. 상품 무게는 OpenCart 무게 등급에서 kg로 변환됩니다.

Fallback cost: 도착 국가의 행과 * 행이 모두 요금을 제공하지 않을 때 사용됩니다. 해당 국가에서 배송 방법을 숨기려면 비워 두세요.

조건

Min weight (kg): 장바구니 무게가 이 값보다 낮으면 배송 방법을 숨깁니다. 기본값: 0(제한 없음).

Max weight (kg): 장바구니 무게가 이 값보다 높으면 배송 방법을 숨깁니다. 택배함은 약 20 kg까지 수용합니다. 기본값: 20. 0은 제한 없음을 뜻합니다. Min weight (kg)보다 낮게 설정할 수 없습니다.

Minimum order amount: 배송이 필요한 상품의 소계(쿠폰 적용 후, 세금 전)가 이 금액에 도달한 경우에만 배송 방법을 표시합니다. 항상 표시하려면 비워 두세요.

Free shipping from: 배송이 필요한 상품의 소계(쿠폰 적용 후, 세금 전)가 이 금액에 도달하면 배송 방법이 무료가 됩니다. 무료로 만들지 않으려면 비워 두세요.

이 항목이나 Fallback cost의 값이 0 이상의 숫자가 아니면 저장되지 않고 이전 값이 유지되며, 경고에 해당 필드명이 표시됩니다.

적용 범위

Geo zone: 이 지오존의 주소에만 Instabee를 제공합니다. All zones(기본값)는 모든 지역을 뜻합니다. Ignore shipping zones가 켜져 있으면 지오존은 확인되지 않습니다. 지오존은 System > Localisation > Geo Zones에서 관리합니다.

Ignore shipping zones: 켜면 Geo zone은 확인되지 않고, 아래 국가에 배송 방법이 제공됩니다. 끄면(기본값) Geo zone만 적용됩니다.

Countries: 이 모드의 배송 대상 국가. 모든 국가를 허용하려면 비워 두세요. 이 항목은 Ignore shipping zones가 켜져 있을 때만 사용됩니다.

고급

Debug log: 디버그 메시지를 storage/logs/vfd_ibee_debug.log.php(OpenCart 4에서는 system/storage/logs/vfd_ibee_debug.log.php)에 기록합니다. 이 파일은 웹에서 읽을 수 없습니다. API 오류와, API가 정상 작동하는 동안 택배함 없이 이루어진 주문은 이 옵션이 꺼져 있어도 항상 기록됩니다. API 키와 고객 데이터는 절대 기록되지 않습니다. 파일이 5 MB에 도달하면 vfd_ibee_debug.old.log.php로 옮겨지고 새 로그가 시작됩니다.

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

Remove data on uninstall: 켜면 확장 프로그램을 제거할 때 설정, 캐시된 택배함 목록, 로그, 미완료 체크아웃의 택배함이 삭제됩니다. 끄면(기본값) 재설치를 위해 설정이 유지됩니다. 주문에 저장된 택배함은 항상 유지됩니다.

가져오기 / 내보내기

Export: Download JSON을 클릭하면 설정을 JSON 파일로 저장합니다. API 키와 시크릿은 내보내지 않습니다.

Import: 이전에 내보낸 JSON을 붙여넣고 Import를 클릭하면 설정을 복원합니다(예: 다른 쇼핑몰에서). 값은 일반 저장과 같은 방식으로 확인됩니다. 저장된 API 키와 시크릿은 유지됩니다.

체크아웃에서의 동작 방식

OpenCart가 배송 방법을 표시할 때 확장 프로그램에 Instabee 요금을 요청합니다. Ignore shipping zones가 켜져 있으면 해당 국가가 허용된 경우에만 Instabee가 제공됩니다(지오존은 확인되지 않음). 그렇지 않은 경우, Geo zone이 설정되어 있고 주소가 그 밖에 있으면 Instabee는 제공되지 않습니다. Requires Shipping이 Yes로 설정된 상품만 계산에 포함됩니다. 다른 상품은 무게를 더하지 않으며 주문 금액에도 포함되지 않습니다. 주문 금액은 쿠폰 할인 후, 세금 전의 배송이 필요한 상품 요금입니다. 확장 프로그램은 장바구니 무게와 최소 주문 금액을 확인합니다. 소계가 Free shipping from에 도달하면 요금은 0입니다. 그 외에는 도착 국가의 Country prices 행, * 행 또는 Fallback cost에서 요금을 가져옵니다. 요금이 없으면 배송 방법은 숨겨집니다. 요금은 쇼핑몰의 기본 통화로 계산되고 그 통화의 소수점 자릿수에 맞게 반올림되며, 선택한 Tax class의 세금과 함께 고객의 통화로 표시됩니다.

고객이 배송 방법 단계에서 Instabee를 선택하고 API 자격 증명이 설정되어 있으면, 스웨덴, 핀란드, 덴마크, 네덜란드, 벨기에에 대해 해당 배송 방법 아래에 Parcel box 블록이 나타납니다. 이 블록에는 배송지 우편번호 근처의 택배함이 거리순으로 이름, 주소, 거리와 함께 나열됩니다. 고객은 다른 우편번호를 입력하고 Search를 클릭하거나(Enter 키를 누를 수도 있음) 할 수 있습니다. 우편번호가 입력되기 전까지 블록은 우편번호를 요청합니다. 택배함을 찾을 수 없으면 고객에게 다른 우편번호를 시도하거나 다른 배송 방법을 선택하라고 안내합니다. 그 밖의 국가에서는 택배함 없이 배송 방법이 제공됩니다.

택배함은 필수입니다. 선택한 택배함은 해당 우편번호의 Budbee 목록에 있을 때만 체크아웃용으로 저장됩니다. Search를 클릭하지 않고 입력한 우편번호는 사용되지 않습니다. 고객이 배송 방법 단계에서 Continue를 클릭하면 확장 프로그램은 서버에서 택배함을 다시 확인합니다. 그렇지 않으면 고객에게 Please choose an Instabee parcel box.가 표시됩니다. 택배함 이름은 브라우저가 아니라 Budbee 목록에서 가져옵니다. 고객이 배송 국가나 주소의 우편번호를 변경하면 이전의 선택은 취소됩니다.

OpenCart 4에서는 체크아웃 페이지의 배송 방법 블록에서 Choose를 클릭한 다음, Shipping method options 창에서 Instabee를 선택합니다. Parcel box 블록은 그 창에서 Instabee 옵션 아래에 나타나며, 같은 방식으로 동작합니다. 창의 Continue 버튼은 목록에서 택배함을 선택하지 않으면 진행되지 않습니다. 표시되는 메시지도 같습니다.

확장 프로그램은 Budbee에 도착 국가와 우편번호만 보내며, 이름, 주소, 이메일, 주문 데이터는 절대 보내지 않습니다. 택배함 목록은 우편번호별로 12시간, 택배함이 없는 우편번호는 1시간, 실패한 요청은 5분 동안 캐시되므로, 느리거나 고장 난 API 때문에 체크아웃 새로 고침마다 속도가 느려지지 않습니다. 체크아웃 페이지 자체는 Budbee를 기다리지 않습니다. 배송 방법이 선택되면 목록은 백그라운드에서 불러옵니다. API 제한 시간은 10초입니다.

Budbee API에 연결할 수 없으면 고객에게 Parcel boxes cannot be loaded right now. You can place the order without choosing a box - the shop will assign one.가 표시됩니다. 이 경우 주문에 표시가 남고, 배송을 예약할 때 택배함을 선택합니다. 이전에 선택한 택배함이 그 시점에 확인할 수 없는 경우에는 유지되며, 미확인으로 표시됩니다.

확장 프로그램은 실시간 요금 계산, 배송 예약, 라벨 출력, 운송장 번호나 배송 추적 이메일 제공, Budbee Home 배송 시간대 제공, 지도 표시를 하지 않습니다. 선택한 택배함에 대해 Instabee / Budbee 판매자 도구에서 소포를 예약하세요.

픽업 포인트

주문이 생성되면 택배함이 한 번 더 확인되고 주문에 저장됩니다. 그 이후에는 스토어프런트에서 변경할 수 없습니다. OpenCart 4는 체크아웃에 대한 주문을 하나 유지하고, 고객이 다시 확정할 때마다 그 주문을 갱신합니다. 이때 주문의 택배함도 함께 갱신됩니다. 고객이 그 주문을 다른 배송 방법으로 바꾸면 택배함은 삭제됩니다. 택배함은 다음 위치에 표시됩니다.

주문의 배송 방법: 택배함이 방법 이름에 추가됩니다. 예를 들어 Instabee parcel box:(방법 이름) 다음에 택배함 이름과 주소가 붙습니다. 이 텍스트는 관리자와 고객 계정의 주문 페이지, 주문 이메일, 송장에 나타납니다.

관리자 주문 페이지(Sales > Orders): 택배함 이름, 주소, Box ID가 표시되는 Instabee parcel box 패널. 체크아웃에서 택배함을 확인할 수 없었다면 not verified (Budbee API was unavailable at checkout)로 표시됩니다. API를 사용할 수 없어서 택배함이 선택되지 않았다면 패널에 Not chosen - the Budbee API was unavailable at checkout. Choose the box when you book the shipment.가 표시됩니다. 이 패널은 읽기 전용이며 배송 방법이 꺼져 있어도 표시됩니다. OpenCart 4에서는 이 패널이 History 위에 표시됩니다.

쇼핑몰로 보내는 신규 주문 이메일: 택배함 이름과 ID, 또는 Instabee parcel box: not chosen (Budbee API unavailable at checkout).

라이선스 키

이 확장 프로그램은 vibefox.net에서 받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox Instabee는 Extensions > Extensions > Shipping > VibeFox Instabee > Edit 페이지에서 설정 위에 있는 첫 번째 블록입니다. 키를 License key에 입력하고 Activate를 클릭하세요. 그러면 블록에 키가 마스킹되어 표시되고, 상태(예: 라이선스가 유효한 날짜와 도메인)와 함께 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 쇼핑몰에서 키를 제거하는 Remove key 버튼이 나타납니다. 그 아래에는 Product: opencart-shipping-instabee 줄과 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 계정에서 슬롯을 해제하세요.

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

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

문제 해결

체크아웃에 Instabee가 나타나지 않음: 라이선스가 활성 상태이고 Enable/Disable이 켜져 있는지 확인하세요. Geo zone을 확인하거나, Ignore shipping zones가 켜져 있다면 Countries에서 해당 국가가 허용되어 있는지 확인하세요. 해당 국가에 요금이 있는지, 또는 * 행이나 Fallback cost가 있는지 확인하세요. 무게 제한과 Minimum order amount를 확인하고, 상품의 Requires Shipping이 Yes로 설정되어 있는지 확인하세요. 요금이 설정되지 않으면 설정 위의 경고에 표시됩니다. Log 필드에서 원인을 보려면 Debug log를 켜세요.

고객에게 택배함 목록이 보이지 않음: 목록은 API key와 API secret이 모두 설정되어 있고, 스웨덴, 핀란드, 덴마크, 네덜란드, 벨기에 중 하나이며, 우편번호가 입력된 경우에만 나타납니다. 마지막 API 오류는 설정 위에 표시됩니다. 자세한 내용은 확장 프로그램 페이지의 Log 필드에 있습니다. 더 자세한 내용을 보려면 Debug log를 켜세요.

로그에 HTTP 401 또는 403이 있음: Budbee가 API 키 또는 시크릿을 거부했습니다. 두 값을 확인하고, Test environment가 자격 증명과 일치하는지 확인하세요(스테이징 자격 증명은 테스트 환경을 켠 경우에만 사용).

우편번호에 대한 택배함이 없음: Budbee가 해당 우편번호를 서비스하지 않습니다. 고객은 다른 우편번호를 검색하거나 다른 배송 방법을 선택할 수 있습니다.

고객이 배송 방법 단계에서 계속 진행할 수 없음: Budbee API에 연결할 수 없는 경우를 제외하고, 목록에서 택배함을 선택해야 합니다. 검색한 우편번호의 목록에 없는 택배함은 저장되지 않으며, 고객에게 This parcel box is not in the Budbee list for the postal code. Please choose the parcel box again.가 표시됩니다.

변경 후 이전 택배함 목록이 보임: 확장 프로그램 페이지에서 Save를 클릭하세요. 캐시된 택배함 목록이 지워집니다.

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

제거

Extensions > Extensions로 이동하여 유형으로 Shipping을 선택하고, VibeFox Instabee 옆의 Uninstall(빨간 − 버튼)을 클릭하세요. 이 확장 프로그램의 라이선스 키와 라이선스 상태는 항상 삭제됩니다. OpenCart는 항상 Enable/Disable, Sort order, Tax class, Geo zone을 초기화합니다. 캐시된 택배함 목록은 항상 삭제됩니다. Remove data on uninstall이 켜져 있으면 설정, 로그, 주문으로 이어지지 않은 체크아웃에서 선택된 택배함도 삭제됩니다. 꺼져 있으면 다른 설정은 유지되며, 확장 프로그램을 다시 설치할 때 다시 사용됩니다. 주문에 저장된 택배함은 항상 유지되며, 기존 주문은 배송 방법과 비용을 그대로 유지합니다.

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

Instabee와 Budbee는 각 소유자의 상표입니다. 이 확장 프로그램은 Instabee 또는 Budbee와 제휴하거나 그들의 승인을 받은 것이 아닙니다.