VibeFox Servientrega for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

PHP: 8.0 или новее.

Аккаунт Servientrega (только для актуальных тарифов): актуальные тарифы используют Cotizador Corporativo Servientrega (API корпоративных расчётов). Вам нужен корпоративный (кредитный) аккаунт Servientrega с доступом к нему. Понадобятся три значения: пользователь, пароль и код оплаты (código de facturación, обычно начинается с SER). Это ваши учётные данные SISCLINET, которые выдаёт ваш менеджер Servientrega. Если вы используете только фиксированные цены, аккаунт Servientrega не нужен.

Доступ к серверу (только для актуальных тарифов): ваш сервер должен иметь доступ к web.servientrega.com по HTTP через порт 8058 (API расчётов) и порт 8081 (веб-служба шифрования паролей).

Лицензионный ключ VibeFox: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

Загрузка — это один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 vfd_servientrega-oc3-(version).ocmod.zip и пакет для OpenCart 4 vfd_servientrega.ocmod.zip. Устанавливайте только пакет для своей версии OpenCart. Лицензионный ключ один и тот же для обеих версий.

OpenCart 3

1. В админке откройте Extensions > Installer, нажмите Upload и выберите файл vfd_servientrega-oc3-(version).ocmod.zip. Расширение не добавляет модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо Installer можно скопировать содержимое папки upload из пакета в корневую папку магазина.

2. Откройте Extensions > Extensions, выберите тип расширений Shipping, найдите VibeFox Servientrega и нажмите Install (зелёная кнопка +).

3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек.

4. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Edit и нажмите Activate (см. Лицензионный ключ).

5. Для актуальных тарифов введите пользователя, пароль и код оплаты, выберите продукт Servientrega, введите код DANE отправления и, если валюта вашего магазина не COP, курс пересчёта валюты.

6. По желанию добавьте фиксированные цены по странам и весу и запасную стоимость, включите Enable Servientrega и нажмите Save.

OpenCart 4

1. В админке откройте Extensions > Installer, нажмите Upload и выберите файл vfd_servientrega.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появляется в списке установленных расширений на той же странице. Нажмите рядом с ним Install (зелёная кнопка +).

3. Откройте Extensions > Extensions, выберите тип расширений Shipping, найдите VibeFox Servientrega, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ и настройки, как в шагах 4–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.

После установки способ выключен, пока вы не включите Enable Servientrega и не сохраните настройки. Если вы установите расширение заново после удаления, сохранённые настройки Servientrega снова будут использованы.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Shipping > VibeFox Servientrega > Edit. Разделы перечислены слева. Они действуют для всех геозон. Одна кнопка Save внизу сохраняет всю страницу без перезагрузки. Каждое сохранение очищает кэш расчётов Servientrega и токен входа. Сохранять настройки могут только администраторы с правом изменения этого расширения.

Если актуальные тарифы не могут работать с сохранёнными настройками, предупреждение над настройками объяснит причину: не заполнены пользователь, пароль или код оплаты, не задан курс пересчёта или не задан код DANE отправления. Предупреждение также появляется, если в магазине нет весовой категории в кг или линейной категории в см, а единица по умолчанию неизвестна расширению; тогда веса читаются как кг, а размеры как см. При сохранении значение, которое не является числом, отрицательное число, курс пересчёта 0, минимальный вес больше максимального, неверная цена в таблице, пустое название способа, название длиннее 64 символов или содержащее < > ; = # { }, либо порядок сортировки, который не является целым числом, отклоняются с ошибкой, и ничего не сохраняется.

Общие

Enable Servientrega: показывает или скрывает Servientrega при оформлении заказа. По умолчанию: выключено.

Method title: название способа доставки, которое покупатель видит в корзине и при оформлении заказа. По умолчанию: Servientrega. Обязательно, не более 64 символов.

Sort order: позиция Servientrega среди способов доставки при оформлении заказа. Целое число.

API Servientrega (актуальные тарифы для Колумбии) (необязательно; без учётных данных используются только фиксированные цены)

User (login): ваш пользователь Servientrega / SISCLINET. Его очистка также удаляет сохранённый пароль.

Password: ваш пароль Servientrega / SISCLINET, как вы его вводите. Расширение передаёт его веб-службе Servientrega для шифрования перед входом. После сохранения поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Billing code: код оплаты (código de facturación) вашего аккаунта Servientrega, как он отображается в SISCLINET. Обычно начинается с SER.

Все три поля нужны для актуальных тарифов. Актуальные тарифы запрашиваются только для направлений в Колумбии. Для остальных стран используются фиксированные цены.

Servientrega product: услуга вашего соглашения с Servientrega, по которой запрашивается расчёт.

Оплачиваемый вес — большее из фактического и объёмного веса.

Currency conversion rate: Servientrega считает в COP. Если валюта по умолчанию вашего магазина не COP, введите значение 1 COP в валюте вашего магазина, например 0.00023. Объявленная стоимость посылки пересчитывается в COP так же. Если валюта вашего магазина — COP, поле сообщает, что пересчёт не нужен: оставьте его пустым. Если ваш магазин использует другую валюту, а это поле пустое, актуальные тарифы не используются и действуют фиксированные цены. Расширение не загружает курсы валют. Точка и запятая принимаются в качестве десятичного разделителя.

Ship from (используется для актуальных тарифов)

Origin city (DANE code): 8-значный код DANE муниципалитета, из которого вы отправляете, например 11001000 Bogotá, 05001000 Medellín, 76001000 Cali или 08001000 Barranquilla. Принимается также 5-значный код муниципалитета. Адрес магазина в OpenCart — свободный текст, поэтому отправление никогда не берётся из него: без этого поля актуальных тарифов не будет.

Fixed prices (используются, когда нет актуального тарифа: нет учётных данных, направление вне Колумбии, неизвестный муниципалитет, не задан курс пересчёта, ошибка API или нет покрытия маршрута)

Price per country: таблица стран и цен в валюте по умолчанию вашего магазина, без налога. Нажмите Add country, чтобы добавить строку, и кнопку удаления, чтобы удалить строку. Price действует для любого веса. Весовые столбцы XS (до 1 кг), S (1–2 кг), M (2–3 кг), L (3–5 кг) и XL (более 5 кг) заменяют её для этого веса, если они больше 0. Строка * Default действует для всех стран без собственной строки. Новая строка начинается как * Default. Строка без единой цены не сохраняется.

Fallback cost: используется, когда нет актуального тарифа и ни одна строка таблицы не подходит. Оставьте пустым, чтобы в этом случае скрывать способ.

Fixed price applies: как начисляются фиксированные цены.

Актуальные тарифы Servientrega всегда рассчитываются за отправление.

Conditions

Minimum weight (kg): скрывает способ, если вес корзины меньше этого значения. 0 означает без ограничения (по умолчанию).

Maximum weight (kg): скрывает способ, если вес корзины больше этого значения. По умолчанию: 50. 0 означает без ограничения.

Minimum order amount: показывает способ, только если сумма товаров, требующих доставки (после купона, до налога), достигает этой суммы. Оставьте пустым, чтобы показывать способ всегда.

Free shipping from: доставка бесплатна, когда эта сумма достигнута, и запрос в Servientrega не отправляется. Это относится к любому направлению, где предлагается способ, в том числе к странам без строки в таблице цен. Оставьте пустым, чтобы никогда не предлагать бесплатную доставку.

Tax class: налоговый класс стоимости доставки или No tax (по умолчанию). Расчёты Servientrega (ValorTotal) уже включают сборы перевозчика. Выберите No tax, если не хотите добавлять налог сверху.

Geo zone: предлагать Servientrega только для адресов в этой геозоне. All zones (по умолчанию) означает без ограничения. Геозоны управляются в System > Localisation > Geo Zones. Не проверяется, когда включён Ignore shipping zones.

Availability without geo zone

Обычно способ предлагается в геозоне, выбранной в Conditions, или везде.

Ignore shipping zones: предлагать Servientrega для стран ниже независимо от геозоны.

Countries: страны назначения для этого режима. Оставьте пустым, чтобы использовать все включённые страны вашего магазина. Это поле используется только при включённом Ignore shipping zones.

Advanced

Debug log: записывает расчёты тарифов и ошибки API в storage/logs/vfd_svtg_debug.log.php. Файл нельзя прочитать из веба. Учётные данные, токены и адреса покупателей не записываются. Когда журнал выключен, ничего не записывается, включая ошибки API. Когда файл достигает 5 МБ, он переносится в vfd_svtg_debug.old.log.php, и начинается новый журнал. Выключите журнал, когда закончите.

Log: показывает размер и последние записи журнала отладки. Нажмите Clear log, чтобы его очистить.

Remove data on uninstall: если включено, удаление расширения стирает все настройки Servientrega и журнал. Если выключено (по умолчанию), они сохраняются для повторной установки. Кэшированные расчёты удаляются всегда.

Import / Export

Export: нажмите Download JSON, чтобы сохранить настройки в файл JSON. Пароль не экспортируется.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки, например в другом магазине. Значения проверяются так же, как при обычном сохранении. Сохранённый пароль остаётся, пока задан пользователь.

Как это работает при оформлении заказа

Когда OpenCart показывает способы доставки, он запрашивает у расширения цену Servientrega. Если задана Geo zone и адрес находится вне неё, Servientrega не предлагается (если не включён Ignore shipping zones). Учитываются только товары с Requires Shipping, установленным в Yes: остальные товары не добавляют вес и не входят в сумму заказа. Сумма заказа — это цена этих товаров после скидки по купону и до налога. Подарочные сертификаты и бонусные баллы не учитываются. Расширение сначала проверяет условия: страну доставки (с Ignore shipping zones), вес корзины и минимальную сумму заказа. Если применяется бесплатная доставка, цена равна 0 и запрос в Servientrega не отправляется. Затем ищется цена: актуальный тариф Servientrega, затем таблица цен и, наконец, запасная стоимость. Если цены нет, способ для этой корзины скрывается.

Для направления в Колумбии с заданными учётными данными расширение находит код DANE муниципалитета покупателя. Оно использует код DANE, введённый в поле почтового индекса или города, или сопоставляет департамент и город со встроенной таблицей примерно 1 130 муниципалитетов. Департамент — это Region / State адреса: в OpenCart уже есть все 33 департамента Колумбии. Акценты и «D.C.» игнорируются. Город, существующий только в одном департаменте, находится даже без указания департамента.

Затем расширение отправляет в Servientrega одно место на заказ: общий вес, переведённый из весовой категории товара в кг, и коробку с длиной и шириной самого крупного товара и общим объёмом всех товаров, переведённым в см. Товары без размеров считаются как 10 × 10 × 10 см. Объявленная стоимость — это сумма заказа, пересчитанная в COP, но не менее 6 000 COP. Servientrega возвращает итог в COP. Расширение пересчитывает его в валюту по умолчанию вашего магазина и округляет до её знаков после запятой. Покупатель видит цену в своей валюте с налогом выбранного Tax class.

Токен входа хранится до истечения срока, но не более 4 дней. Отклонённый токен один раз продлевается автоматически. Каждый расчёт кэшируется на 1 час для маршрута и посылки, поэтому та же корзина не вызывает новый запрос. Неудачный запрос (шифрование, вход или расчёт) кэшируется на 10 минут, чтобы оформление заказа не ожидало Servientrega при каждом обновлении. Тайм-аут составляет 10 секунд на запрос.

Покупатель никогда не видит ошибку API. Причина записывается в журнал отладки, если он включён.

Расширение только рассчитывает тарифы. Оно не создаёт накладные (guías), этикетки или стикеры, не заказывает забор посылок, не отслеживает и не отменяет отправления и не позволяет покупателю выбрать отделение Servientrega (Centro de Soluciones). Создайте накладную в SISCLINET или в портале Servientrega. Наложенный платёж (logística de recaudo) не рассчитывается. Актуальные расчёты предназначены только для отправлений внутри Колумбии. Расширение ничего не добавляет к заказам: в заказе отображаются название способа и стоимость доставки, как для любого другого способа доставки OpenCart.

В OpenCart 4 покупатель нажимает Choose в блоке способов доставки на странице оформления заказа и выбирает Servientrega в окне Shipping method options, где название способа показано вместе с ценой. Способ работает так же, как в OpenCart 3.

Лицензионный ключ

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Servientrega — первый блок на странице Extensions > Extensions > Shipping > VibeFox Servientrega > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату окончания действия лицензии и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-shipping-servientrega и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только администраторы с правом Modify для этого расширения. Тексты блока следуют языку админки (включены английский и русский).

Если ключ не принят, блок сообщит причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on и дату. После смены адреса магазина или после освобождения слота домена в аккаунте нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте на vibefox.net.

Без активного ключа способ доставки Servientrega не показывается покупателям при оформлении заказа, и курсы не запрашиваются и не рассчитываются. Администратор, вошедший в админку в том же браузере, по-прежнему видит способ в магазине, помеченный как (unlicensed — visible to admins only), чтобы вы могли настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход в админку, поэтому без активного ключа способ скрыт для всех. После первого открытия страницы Edit в Dashboard админки появляется напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются.

Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова при открытии Dashboard или страницы Edit в админке: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление расширения всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

Servientrega не появляется при оформлении заказа: проверьте, что лицензия активна и что Enable Servientrega включено. Проверьте Geo zone или включите Ignore shipping zones и проверьте Countries. Проверьте ограничения по весу и Minimum order amount. Без актуального тарифа проверьте, что у страны или * Default есть цена или что задана Fallback cost. Проверьте, что у товаров Requires Shipping установлено Yes.

Актуальные тарифы не появляются: включите Debug log, перезагрузите оформление заказа и посмотрите поле Log на странице расширения. Частые причины: не задан курс пересчёта (валюта магазина не COP), нет кода DANE отправления, департамент или город покупателя ещё не введены либо не являются известным муниципалитетом, неверные учётные данные, нет покрытия маршрута или сервер не может обратиться к web.servientrega.com по портам 8058 и 8081. Фиксированные цены покрывают эти случаи, если вы их задали.

Вход не выполняется: проверьте пользователя, пароль и код оплаты у своего менеджера Servientrega. После неудачного входа расширение ждёт 10 минут перед следующей попыткой. Сохраните настройки, чтобы попробовать сразу.

Город покупателя не распознаётся: покупатель должен выбрать департамент в поле Region / State. Для редких написаний покупатель может ввести 8-значный код DANE вместо почтового индекса.

Тарифы выглядят устаревшими после изменения: нажмите Save на странице расширения. Это очистит кэш расчётов Servientrega и токен.

Страница пишет «Warning: You do not have permission to modify VibeFox Servientrega!»: ваша группа администраторов может только просматривать настройки. Дайте группе право на изменение для extension/shipping/vfd_servientrega (OpenCart 3) или extension/vfd_servientrega/shipping/vfd_servientrega (OpenCart 4) в System > Users > User Groups.

Для разработчиков: события OpenCart vfd_servientrega/dane_code и vfd_servientrega/quote_request позволяют другому расширению изменить код DANE назначения и запрос расчёта.

Удаление

Откройте Extensions > Extensions, выберите тип Shipping и нажмите Uninstall (красная кнопка −) рядом с VibeFox Servientrega. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда сбрасывает Enable Servientrega, Sort order, Tax class и Geo zone. Кэшированные расчёты, токены и зашифрованный пароль всегда удаляются. Если Remove data on uninstall включено, удаляются также остальные настройки и журнал. Если выключено, они сохраняются и будут использованы при повторной установке расширения. Существующие заказы сохраняют свой способ доставки и стоимость.

Чтобы на OpenCart 4 удалить также файлы расширения, после удаления откройте Extensions > Installer, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Servientrega в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

Servientrega — товарный знак её владельца. Это расширение не связано с Servientrega и не одобрено компанией Servientrega.