VibeFox Balikobot for PrestaShop — 도움말

요구 사항

PrestaShop: 8.0~9.x.

PHP: 8.0 이상. 모듈은 이전 버전의 PHP에는 설치되지 않습니다.

Balikobot 계정(실시간 요금 및 수령 지점용): API 접근 권한이 있는 Balikobot 계정이 필요합니다. API 사용자와 API 키는 Balikobot 고객 영역(client.balikobot.cz)에 있습니다. Balikobot 지원팀(podpora@balikobot.cz)이 계정과 운송업체에 대해 API를 활성화합니다. 실시간 요금에는 Balikobot이 "transportcosts"를 지원하는 운송업체와 서비스가 필요합니다. 수령 지점에는 "branchlocator"를 지원하는 운송업체가 필요합니다(예: Česká pošta, Zásilkovna, PPL, DPD, GLS). 확실하지 않으면 Balikobot 지원팀에 문의하십시오. 고정 요금은 계정 없이 사용할 수 있습니다.

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

설치

1. 관리 패널에서 Modules > Module Manager로 이동하고 Upload a module을 클릭합니다. 모듈의 ZIP 파일을 선택합니다.

2. 업로드가 끝나면 Configure를 클릭하거나, 나중에 모듈 목록에서 VibeFox Balikobot을 찾아 Configure를 클릭합니다.

3. Configure 페이지 상단의 라이선스 블록에 있는 License key 필드에 VibeFox 라이선스 키를 붙여 넣고 Activate를 클릭합니다(라이선스 키 참조).

4. API 사용자와 API 키를 입력하고, 운송업체와 서비스 유형, 요금 출처, 국가별 요금을 선택합니다(설정 참조). 수령 지점을 사용하는 서비스의 경우 Pickup point selection을 켭니다. Save를 클릭합니다.

설치 시 모듈은 Delivery by Balikobot 배송 시간 문구와 함께 Balikobot 운송업체를 생성합니다. 이 운송업체는 체코, 슬로바키아, 헝가리 지역과 모든 고객 그룹에 할당됩니다. 지역, 고객 그룹, 배송 시간, 로고, 크기 제한은 Shipping > Carriers에서 변경할 수 있습니다. 그곳에서 요금을 설정하지 마십시오. 요금은 항상 모듈에서 가져옵니다.

설정

모든 설정은 모듈 페이지에 있습니다: Modules > Module Manager > VibeFox Balikobot > Configure. 각 섹션에는 전체 페이지를 저장하는 자체 Save 버튼이 있습니다. 저장 후에는 Settings saved. Cached rates and pickup points were cleared.가 표시됩니다. 페이지 상단에는 운송업체, 실시간 요금 또는 수령 지점을 숨기게 되는 설정에 대한 경고가 표시됩니다. API 사용자 또는 API 키 없이 실시간 요금이나 수령 지점을 사용하는 경우, Exchange rate 없이 상점 통화가 CZK가 아닌 경우, 고정 요금이나 대체 모드를 사용하는데 Country prices가 비어 있는 경우, 모듈이 알지 못하는 상점 무게 단위인 경우(이때 무게는 kg으로 읽힙니다. kg, g, lb 또는 oz를 사용하십시오), 삭제된 운송업체인 경우입니다. 숫자가 아닌 값은 저장되지 않으며, 필드 이름이 포함된 경고가 표시됩니다.

General

Enable/Disable: Balikobot 배송을 켜거나 끕니다. Shipping > Carriers의 운송업체 상태와 같은 스위치입니다.

Name: 고객에게 표시되는 배송 방법 이름(운송업체 이름). 기본값: Balikobot. 필수 항목이며 최대 64자입니다.

Tax status: None, 또는 세금 규칙 중 하나를 선택한 Taxable. 세금 규칙을 선택하면 그 세금이 배송비에 추가됩니다. 선택 사항은 운송업체에 저장됩니다. Balikobot 요금은 대개 부가세 제외 금액입니다. 기본값: None.

Balikobot API 계정(실시간 요금 및 수령 지점에 필요)

API user: 고객 영역에서 발급받은 Balikobot API 사용자.

API key: 고객 영역에서 발급받은 Balikobot API 키. 저장 후 이 필드는 비어 있으며 Saved - leave empty to keep it. Clear the API user to remove the saved key.가 표시됩니다. 변경하려는 경우에만 새 값을 입력하십시오.

Carrier: 요금과 수령 지점에 사용하는 Balikobot 운송업체: Česká pošta(기본값), Zásilkovna(Packeta), PPL, DPD, GLS, DHL Express, UPS, TNT, FedEx, Geis, InTime, Uloženka, Toptrans, Pošta bez hranic, Slovenská pošta, SPS(Slovak Parcel Service) 또는 Magyar Posta. Balikobot 계정에서 활성화되어 있어야 합니다.

Service type: 운송업체의 Balikobot 서비스 코드. 기본값: NP. Česká pošta의 경우: NP = 우체국 택배, NB = Balíkovna 택배, DR = 자택 배송. 다른 운송업체의 코드는 Balikobot 고객 영역과 API 문서에 나와 있습니다.

요금(모든 요금은 상점의 기본 통화 기준입니다)

Price source: 요금이 계산되는 방식.

Country prices: 2자리 국가 코드(예: CZ, SK)와 요금의 표입니다. 국가를 추가하려면 Add row를, 삭제하려면 휴지통 아이콘을 클릭합니다. 그 밖의 모든 국가에는 국가 코드로 *를 사용합니다. 소수점은 점 또는 쉼표로 입력할 수 있습니다. 고정 모드와 API 대체 요금에 사용됩니다. 요금이 없는 국가(그리고 * 행도 없는 경우)에는 고정 요금이 적용되지 않습니다. 잘못된 행은 저장할 때 삭제되며, 경고에 목록이 표시됩니다.

Fixed price per: Order는 요금을 한 번만 부과합니다. Item (price x quantity)는 장바구니의 상품 수량을 곱합니다. 이는 고정 요금에만 적용됩니다. Balikobot 실시간 요금은 항상 전체 소포 기준입니다.

Exchange rate: Balikobot 요금 통화(보통 CZK) 1단위의 상점 기본 통화 환산 값(예: 0.04). Balikobot이 다른 통화로 요금을 반환할 때만 사용됩니다. 비워 두면 이러한 요금을 거부하므로, 고객이 잘못된 금액을 결제하는 일이 없습니다.

조건

Min weight (kg): 장바구니가 이보다 가벼우면 운송업체를 숨깁니다. 0은 제한 없음을 뜻합니다. 상품 무게는 상점의 무게 단위에서 변환됩니다.

Max weight (kg): 장바구니가 이보다 무거우면 운송업체를 숨깁니다. 기본값: 100. 0은 제한 없음을 뜻합니다. 빈 필드는 100kg를 뜻합니다. Min weight (kg)가 최댓값보다 크면 경고가 표시되고 이전 무게 값이 유지됩니다.

Minimum order amount: 장바구니 소계(할인 후, 세금 제외)가 이 금액 이상일 때만 운송업체를 표시합니다. 항상 표시하려면 비워 두십시오.

Free shipping: 아래 금액 이상일 때 무료 배송을 켭니다.

Free shipping from: 무료 배송이 적용되는 장바구니 소계(할인 후, 세금 제외). 이 경우 API 요청은 전송되지 않습니다.

배송 지역 없이 사용하기

보통 운송업체는 Shipping > Carriers에서 설정한 지역에서 제공됩니다.

Ignore shipping zones: 운송업체가 해당 지역에 연결되어 있지 않더라도, 아래 국가에서 운송업체를 제공합니다. 모듈은 나중에 만드는 지역을 포함한 모든 지역에 운송업체를 연결합니다. 이 옵션을 끄면 이런 방식으로 추가된 지역은 다시 제거됩니다. 직접 만든 지역은 유지됩니다.

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

수령 지점

Pickup point selection: 고객은 수령 지점을 반드시 선택해야 합니다. Česká pošta NP 또는 NB, Zásilkovna 등 수령 방식 서비스에 사용하십시오. API 사용자와 API 키가 필요합니다.

Selector width: 수령 지점 목록의 CSS 너비(예: 100% 또는 400px). 기본값: 100%.

고급

Debug log: API 요청과 요금 계산을 모듈 폴더의 logs/vfd_blkb_debug.log.php에 기록합니다. 이 파일은 웹에서 열 수 없습니다. API 오류는 항상 기록됩니다. 자격 증명과 고객 주소는 절대 기록되지 않습니다. 작업이 끝나면 로그를 끄십시오.

Log: 로그의 크기와 최근 항목을 표시합니다. Clear log를 클릭하면 비워집니다.

Remove data on uninstall: 켜져 있으면 모듈을 제거할 때 모듈 설정과 운송업체가 삭제됩니다. 이 옵션 없이 제거하면 데이터는 절대 삭제되지 않습니다. 주문에 저장된 수령 지점은 유지됩니다.

결제 시 작동 방식

배송 단계에서 PrestaShop은 모듈에 Balikobot 요금을 요청합니다. 실물 상품만 계산에 포함됩니다. 가상 상품은 무게를 더하지 않으며 주문 금액에도 포함되지 않습니다. 모듈은 먼저 국가(Ignore shipping zones 사용 시), 장바구니 무게, Minimum order amount를 확인합니다. 무료 배송이 적용되면 요금은 0이 되고 Balikobot에 요청이 전송되지 않습니다.

고정 모드에서는 요금을 Country prices에서 가져옵니다. 실시간 모드에서는 모듈이 Balikobot에 운송업체, 서비스 유형, 목적지 국가와 우편번호, kg 단위의 장바구니 무게를 보냅니다. 배송 주소에 우편번호가 있어야만 실시간 요금을 요청합니다. 다른 통화의 요금은 Exchange rate로 환산되며, 환율이 설정되지 않았으면 거부됩니다. 요금은 상점의 기본 통화로 계산된 다음 고객의 장바구니 통화로 표시됩니다.

실시간 요금은 1시간 동안 캐시되므로 같은 장바구니가 새 요청을 일으키지 않습니다. 실패한 요청은 5분 동안 캐시되며 API 제한 시간은 12초이므로, 결제 페이지를 새로 고칠 때마다 Balikobot을 기다리지 않습니다. API 오류는 고객에게 절대 표시되지 않습니다. 운송업체가 숨겨지거나, 대체 모드에서는 고정 요금이 사용됩니다. 자세한 내용은 디버그 로그에 기록됩니다.

운송업체에 주문이 있는 상태에서 Shipping > Carriers에서 운송업체를 편집하면, PrestaShop은 이를 운송업체의 새 버전으로 저장합니다. 모듈은 새 버전을 자동으로 따릅니다.

모듈은 Balikobot에서 배송 건을 생성하거나, 송장을 출력하거나, 집화를 예약하지 않습니다. 배송은 Balikobot 고객 영역에서 주문하십시오. 택배 추적이나 주문 상태 업데이트는 하지 않습니다. 모든 지역에 하나의 운송업체와 하나의 서비스 유형이 사용됩니다. 수령 지점은 지도 없이 드롭다운 목록으로 표시됩니다.

수령 지점

Pickup point selection이 켜져 있으면, 배송 단계에서 Balikobot 운송업체 아래에 수령 지점 목록이 나타납니다. 이 목록은 배송 주소의 국가, 도시, 우편번호를 기준으로 Balikobot "branchlocator"에서 불러옵니다. 주소에 도시가 입력되기 전까지 고객에게는 Enter your city to see the pickup points.가 표시됩니다. 목록은 12시간 동안 캐시됩니다.

고객이 지점을 선택하는 즉시 그 선택이 장바구니에 저장됩니다. 선택은 필수이며, 배송 단계의 Continue와 Place order는 Please select a pickup point.가 표시되며 차단됩니다. 서버도 선택한 지점이 배송 주소에 속하는지 확인합니다. 그렇지 않으면 고객에게 The selected pickup point is not available for your shipping address. Please choose a pickup point again.가 표시됩니다. 지점을 찾지 못하면 고객에게 도시와 우편번호를 확인하거나 다른 배송 방법을 선택하라는 안내가 표시됩니다. 지점을 불러올 수 없으면 나중에 다시 시도하거나 다른 배송 방법을 선택하라는 안내가 표시됩니다.

선택한 수령 지점은 주문에 저장됩니다. 관리 패널의 주문 페이지에서는 Balikobot pickup point 블록에 Balikobot 지점 ID 및 운송업체와 함께 표시됩니다. 이 정보는 Balikobot에서 배송 건을 생성할 때 필요합니다. Change를 클릭하면 주문 주소 근처의 다른 지점을 선택할 수 있으며, 이후 Save를 클릭합니다. 지점을 변경하려면 주문을 편집할 권한만 있으면 되며 모듈 페이지에 접근할 필요는 없습니다. 주문에 지점이 없으면 블록에 No pickup point was selected for this order.가 표시됩니다.

고객은 주문 확인 페이지와 주문 상세에서 지점을 Pickup point:로 봅니다. 주문 확인 이메일과 상점용 신규 주문 이메일(Mail alerts 모듈)에서는 운송업체 이름 뒤에 추가됩니다. 기존 주문은 수령 지점 데이터를 그대로 유지합니다.

라이선스 키

이 모듈은 vibefox.net에서 발급받은 VibeFox 라이선스 키로 작동합니다. 라이선스 블록 License — VibeFox Balikobot은 Modules > Module Manager > VibeFox Balikobot > Configure에서 설정 위쪽에 있는 첫 번째 블록입니다. License key에 키를 붙여 넣고 Activate를 클릭하십시오. 그러면 블록에 마스킹된 키, 상태(예: 라이선스 사용 기한 날짜와 도메인), 그리고 상태를 다시 확인하는 Check now, 다른 키를 입력하는 Change key, 이 상점에서 키를 제거하는 Remove key 버튼이 나타납니다. 그 아래에는 Product: presta-shipping-balikobot 줄과 vibefox.net 계정을 여는 Manage licenses and domains in your account 링크가 있습니다. 키를 변경할 수 있는 사람은 이 모듈의 Configure 권한이 있는 직원뿐입니다. 블록의 문구는 백오피스 언어를 따릅니다(영어와 러시아어가 포함됩니다).

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

키 하나는 도메인 하나에서 작동합니다. 다중 상점 설정에서도 기본 상점의 도메인에 해당합니다. 상점에서 키를 제거해도 도메인 슬롯은 비워지지 않습니다. vibefox.net 계정에서 슬롯을 비우십시오.

유효한 키가 없으면 결제 시 고객에게 Balikobot 운송업체가 표시되지 않으며 요금도 계산되지 않습니다. PrestaShop 스토어프론트는 백오피스에 로그인한 사실을 알지 못하므로 운송업체는 관리자에게도 숨겨집니다. 키를 구매하기 전에 모듈을 설정할 수는 있지만, 결제 시 테스트할 수는 없습니다. Modules > Module Manager의 Alerts 탭에 알림이 나타납니다. 기존 주문에는 영향을 주지 않습니다.

라이선스가 만료되어도 모듈은 계속 작동하지만, 업데이트와 지원을 받으려면 갱신이 필요합니다. 백오피스에서 작업하는 동안 상태는 자동으로 다시 확인됩니다. 키를 입력한 후 처음 14일 동안은 하루에 한 번, 그 후에는 일주일에 한 번입니다. cron 작업은 필요하지 않습니다. 모듈을 제거하거나 재설정하면 라이선스 키와 라이선스 상태는 항상 삭제됩니다.

문제 해결

결제 시 Balikobot이 나타나지 않음: 라이선스가 활성 상태인지, Enable/Disable이 켜져 있는지 확인하십시오. 모듈 페이지 상단의 경고를 읽어 보십시오. Shipping > Carriers에서 운송업체가 고객 국가의 지역과 고객 그룹을 포함하는지 확인하거나, Ignore shipping zones를 켜고 Countries를 확인하십시오. 무게 제한과 Minimum order amount도 확인하십시오. 고정 모드에서는 해당 국가나 *에 요금이 있는지 확인하십시오. 상품 페이지에서 상품이 특정 운송업체로만 제한되어 있을 수도 있습니다.

실시간 요금이 표시되지 않음: Debug log를 켜고 결제 페이지를 새로 고친 다음, 모듈 페이지의 Log 필드를 확인하십시오. 원인이 표시됩니다. API 자격 증명 누락, 아직 입력되지 않은 우편번호, 운송업체 및 서비스에 대한 Balikobot 오류(예: authorization failed - API 사용자와 API 키를 확인하십시오), 또는 Exchange rate 없이 다른 통화로 된 요금이 원인일 수 있습니다. 문제를 해결하는 동안에도 Live Balikobot rate, fixed price if the API fails를 사용하면 고객은 고정 요금을 받을 수 있습니다.

요금 통화가 잘못됨: 고정 요금은 상점의 기본 통화로 설정됩니다. Balikobot은 실시간 요금을 Balikobot 계약 통화(보통 CZK)로 반환합니다. 기본 통화와 다르다면 Exchange rate를 설정하십시오.

부가세 포함 여부: Balikobot 요금은 대개 부가세 제외 금액입니다. Tax status를 세금 규칙으로 설정하면 PrestaShop이 배송비에 세금을 추가합니다.

목록에 수령 지점이 없음: API 사용자와 키가 입력되어 있는지, 운송업체가 "branchlocator"를 지원하는지, 배송 주소에 도시와 우편번호가 있는지 확인하십시오. 로그에서 Balikobot 오류를 확인하십시오.

변경 후 요금이나 수령 지점이 오래된 것 같음: 모듈 페이지에서 Save를 클릭하십시오. 캐시된 요금과 수령 지점이 지워집니다.

Balikobot 운송업체를 찾을 수 없다는 페이지 메시지: Shipping > Carriers에서 운송업체가 삭제되었습니다. Modules > Module Manager에서 모듈을 재설정하면 다시 생성됩니다.

개발자용: 모듈에는 API 주소(actionVfdBlkbApiUrl), "transportcosts" 패키지(actionVfdBlkbTransportcostsPackage), 수령 지점 개수(actionVfdBlkbPickupMaxResults, 기본값 30)를 변경하기 위한 고유 훅이 있습니다.

제거

Modules > Module Manager로 이동하여 VibeFox Balikobot 옆의 메뉴를 열고 Uninstall을 선택하십시오. 라이선스 키, 라이선스 상태, 캐시된 요금과 수령 지점은 항상 삭제됩니다. Remove data on uninstall이 켜져 있으면 운송업체가 삭제되고(주문은 기록을 유지합니다), 설정, 로그, 주문이 없는 장바구니의 수령 지점도 삭제됩니다. 꺼져 있으면 운송업체는 비활성화되기만 하고 모든 설정이 유지됩니다. 모듈을 다시 설치하거나(또는 재설정하면) 저장된 운송업체는 제거 전 상태를 되찾습니다. 켜져 있던 것은 켜진 상태로, 꺼져 있던 것은 꺼진 상태로 돌아갑니다. 주문에 저장된 수령 지점 데이터는 절대 삭제되지 않습니다.

Balikobot은 해당 소유자의 상표입니다. 본 모듈은 Balikobot과 제휴하거나 Balikobot의 승인을 받은 것이 아닙니다.