Интеграция, API и поддръжка

Версии, обхват и граници

Документът описва изпълнявания код на CVC for WooCommerce 2.0.0. Минимумите в заглавната част на плъгина са WordPress 6.5, WooCommerce 8.0 и PHP 8.1. Проверената демонстрационна комбинация е WordPress 7.1.3, WooCommerce 11.2.1, PHP 8.3, MariaDB 10.11, bg_BG, EUR и HPOS.

Поддържат се класическите shortcode количка и checkout. HPOS е изрично деклариран като съвместим. Checkout Blocks не се поддържа; директното Store API приключване на CVC поръчка се отказва. В демото Store API checkout е изцяло изключен.

Външните endpoints са фиксирани. Плъгинът не предоставя обща публична REST услуга за издаване, не създава автоматично товарителници при checkout/смяна на статус и няма автоматично заявяване на куриер, анулиране или фонова синхронизация на статуса.

Единна версия 2.0.0 в заглавната част, CVC_WC_VERSION и readme. Пакетът съдържа само cvc-woocommerce; нужни са WordPress и WooCommerce.

Инсталация и първоначално настройване

1. Осигурете архив на базата, wp-config.php със salts и предишната версия. Използвайте HTTPS, PHP с OpenSSL и mbstring, WordPress HTTP API и работеща WooCommerce сесия.
2. Инсталирайте директория cvc-woocommerce в wp-content/plugins/ и активирайте WooCommerce, после CVC for WooCommerce.
3. Използвайте [woocommerce_cart] и [woocommerce_checkout]. Изберете правилните страници в WooCommerce.
4. От „CVC доставка“ активирайте интеграцията, настройте подателя и точния му CVC код. Палети е началният вид.
5. Добавете метод cvc_wc към подходящата зона за България. Методът и зоната трябва да са активни.
6. Настройте продуктите с измерени физически единици, стойности и допустими лимити. Проверете данъчната конфигурация.
7. При API активиране въведете ключа в защитеното поле. „Запази и провери CVC обектите“ извиква get_custom_locations. Изберете действителния ID на подателя, контакт и платци.
8. Повторете матрицата за приемане в контролирана среда. Реален API тест се прави по изрично уговорен с CVC ред.

Самостоятелният CVC панел работи със стандартните WooCommerce полета. Допълнителен фирмен плъгин не е нужен.

Архитектура и точки на интеграция

Основни Woo hooks: woocommerce_shipping_methods, woocommerce_cart_shipping_packages (контекст на кеша), woocommerce_checkout_update_order_review, woocommerce_after_checkout_validation, woocommerce_cart_emptied, woocommerce_checkout_order_processed и woocommerce_store_api_checkout_update_order_from_request.

Допустимите доставки за наложен платеж се задават изрично в WooCommerce → Плащания. Плъгинът запазва платежните ограничения на магазина; началният COD код е cod.

Всички общи параметри

Стойностите в таблицата са фабрични, извлечени от дефинициите в кода. Общата конфигурация е в cvc_wc_settings. В демото интеграцията е включена, подателят е тестов Ямбол, наложеният платеж е условен по платежен метод, включени са хъб/офис и диагностичният журнал.

API ключ и параметри за товарителница

Настройките са отделени в cvc_wc_waybill_settings; ключът е отделна non-autoload опция cvc_wc_api_secret. CVC_WC_API_TOKEN, ако е дефиниран, има предимство и блокира редакцията на полето. Парола за e-CVC не е API ключ.

Ключът се криптира с AES-256-GCM: 12-byte IV, 16-byte tag, версия v1:, ключ от SHA-256 на wp_salt("auth") и името на secret опцията. Смяна на salts изисква повторно въвеждане на CVC ключа. Архивите с salts и база са чувствителни.

Допълнителните услуги са булеви; обявената стойност е включена фабрично, останалите флагове са изключени. Разрешаването им в WordPress не ги активира по договора с куриера.

Продуктови метаданни и опаковане

Вариациите наследяват липсващи метаданни от родителя. Брой физически пратки = quantity / units_per_parcel; допуска се положително цяло число с толеранс 0,00001. Пакетите от всички продукти трябва да имат един и същ вид. Виртуалните стоки се пропускат.

За палет винаги се изискват положителни CVC overrides за четирите измервания. За пакет се допуска WooCommerce тегло и размери с преобразуване на мерните единици. За гуми размерите могат да бъдат нулеви при автоматична калкулация, но операторският текстов редактор приема четири положителни числа. Ограниченията се проверяват преди заявката.

За пакети тарифното тегло е сборът на max(реално тегло, L × W × H / 6000) за всеки пакет, закръглен нагоре. За палети и гуми е сборът на теглата, също закръглен нагоре за публичния калкулатор. Стойност на стоките = line_total + line_tax след отстъпки.

Цени, видимост, сесия и кеш

Публичният parser връща EUR; BGN се преобразува по 1,95583. Други валути се отказват. Крайна цена = gross × (1 − discount / 100) + handling, закръглена по WooCommerce. При taxable режим включеният данък се отделя с WC_Tax; не се начислява втори път.

Видимост: плъгинът не сравнява куриерски цени. В активната зона CVC е достъпен постоянно; при липсваща цена се показва причина. Само демо адаптерът ограничава списъка с методи до CVC.

CVC панелът е видим за физическа количка в активна CVC зона, включително преди получаване на цена. cvc_wc_recipient съдържа тип/точка, cvc_wc_error — код на последен отказ. Няма резервна нулева тарифа; проверките за пратки, адрес и прясна цена се запазват. Ключът cvc_demo_profile=sole-cvc-v2 обновява кеша на стари сесии.

Shipping package identity включва настройки, получател, платежен метод, метрики, валута и времеви интервал. Повече от един Woo shipping package не се поддържа автоматично.

Публичен калкулатор: HTTP действия

GET https://cvc.bg/new-calculator/ извлича динамичния публичен параметър token. POST заявките са form encoded към https://cvc.bg/wp-admin/admin-ajax.php. Общи полета: action, token, country_id=100. Това е адаптер към публичния сайт, а не гарантиран официален договорен API; промени в HTML/JavaScript могат да наложат поправка.

action=get_price_pallet
country_id=100
token=<динамичен публичен параметър; не клиентски API ключ>
total_parcels=1&total_kgs=100
send_type_from_pallet=3&send_type_to_pallet=3
send_from_id=<проверен ID>&send_to_id=<проверен ID>
dim_d[]=120&dim_w[]=80&dim_h[]=100&dim_kg[]=100
cod_amount=120.00&os_value=120.00
city_name_send_pallet=<етикет от справочника>
city_name_recipient_pallet=<етикет от справочника>

Типовете са 3=адрес, 1=хъб, 2=офис. Палет до/от офис се отказва. Адрес се разпознава по нормализирано име и ПК; единствено съвпадение по град се допуска за градове с много пощенски райони. Няколко възможни съвпадения водят до ambiguous_city.

Калкулаторът получава кодове на места, измервания и стойности; не получава имена, улици, телефон или имейл. Parser-ът премахва markup и изисква точно по една обозначена net/gross стойност в EUR/€ или лв. Нулеви, отрицателни, дублирани или неконсистентни цени се отказват. Върнат HTML никога не се изпълнява.

Transport: TLS verify=true, redirects=0, response limit 8 MiB, configurable timeout 3–20 секунди (начално 8). Parser-ът избира първата изрично обозначена валута; вторичното превалутирано показване в сайта не се използва за цена.

Account API: транспорт и endpoints

База https://lox.e-cvc.bg/. Заглавки Authorization: Bearer <secret>, Accept: application/json, Content-Type: application/json. POST body е JSON; GET параметрите са query. Ключът никога не се поставя в URL. Изчакване 25 секунди, без redirects, TLS проверка, отговор до 1 MiB.

Успех се признава само при boolean true или integer 1 в success. false/0 е отхвърляне; липсващо или друго success е непотвърден резултат. HTTP 401/403 се класифицира като отказ на достъп. Транспортна грешка, невалиден JSON или друг неподходящ HTTP статус се третират като uncertain. Произволният текст на доставчика не се показва и не се журнализира.

// Вътре в WordPress, след проверка на операторските права.
$result = CVC_WC_API::request( 'get_custom_locations' );
if ( is_wp_error( $result ) ) {
    // Запишете само get_error_code(), без body, headers или ключ.
    return $result;
}
$locations = $result['locations'] ?? array();

Това са вътрешни PHP класове без обещание за стабилен външен SDK. Не изграждайте общодостъпен endpoint, който ги извиква без WooCommerce права, nonce, проверка на поръчката и защита от повторение.

Схема на товарителницата

{
  "parcel_type": "pallet",
  "pickup_date": "YYYY-MM-DD",
  "description": "Тестови стоки",
  "payer": "rec",
  "reject_payer": "contract",
  "total_kgs": 100,
  "total_parcels": 1,
  "parcels": [{"kgs":100,"dim_d":120,"dim_w":80,"dim_h":100}],
  "sender": {
    "custom_location_id":90001,
    "name":"ДЕМО подател","phone":"0000000000",
    "email":"sender@example.invalid"
  },
  "rec": {
    "name":"Демо Получател","phone":"0000000000",
    "email":"demo@example.invalid","country_id":100,
    "city_id":100,"zip":"1000","street":"Демонстрационен адрес 1"
  },
  "ref1":"Поръчка 123","ref2":"cvc-wc-SITEHASH-123",
  "cod_amount":120,"os_value":120,
  "is_cod_ppp":false,"is_observe":false,"is_test":false,
  "is_fragile":false,"is_sat":false,"is_sms":false,
  "is_return_receipt":false,"is_return_docs":false
}

Издаването изисква една записана CVC доставка, EUR, валиден статус, без възстановяване и без чужда Еконт/Спиди товарителница. Записаният адрес се разпознава отново, вместо да се използва стар city_id. При неплатен метод, който не е COD, издаването се отказва.

Операторският parser приема 1–100 реда по четири положителни числа до 10000. Преди API preview и issue допълнително се прилагат настроените лимити за брой, тегло, размери, палетна височина и общо тегло. Палет до/от офис се отказва. Договорната допустимост на услугите се потвърждава с CVC.

Операторски действия и защита от повторение

Двете AJAX операции използват manage_woocommerce и edit_shop_order, nonce за конкретната поръчка и MariaDB/MySQL GET_LOCK с идентификатор от database prefix + order ID. Зает lock връща HTTP 409, липсващи права/nonce — 403. Логическите отказы могат да бъдат HTTP 200 с success=false; клиентът трябва да проверява JSON.

Preview е еднократен 40-символен случаен token, съхранен като hash в transient. Срокът е 10 минути. Обвързан е с оператор и поръчка. Подписът обхваща текущите данни, артикулите и реда за доставка, настройки и, при товарителница, fingerprint на ключа.

При apply на доставка се правят нова цена и повторно прочитане на поръчката; preview се консумира преди записа. Старият ред за доставка се заменя и общата сума се актуализира изрично. При issue на товарителница общата сума и статусът на Woo поръчката остават непроменени.

Ръчното съгласуване не доказва автоматично, че номерът принадлежи на поръчката: операторската проверка по референция в e-CVC е задължителна. То не възстановява автоматично PDF. За потвърдено несъздадена пратка няма бутон за сляпо зануляване на защитата — първо се изяснява с CVC.

Съхранение, PDF и лични данни

Общи настройки: cvc_wc_settings. API настройки: cvc_wc_waybill_settings. Криптиран ключ: cvc_wc_api_secret. Товарителница: order meta _cvc_wc_waybill със състояние, референция, опит, оператор, време, подпис и при успех номер/PDF/цени. Доставката пази скрито shipping-item meta _cvc_wc_quote и видими „CVC получаване“, „CVC услуга“, „CVC брой пратки“.

Account API обработва имена, адреси, телефони и при наличие имейли след операторско действие. Debug режимът записва кодове в WooCommerce logger със source cvc-woocommerce, без raw payload. Не записвайте Bearer headers, provider bodies или клиентски PDF в публични логове.

PDF URL е допустим само по HTTPS към точните lox.e-cvc.bg и my.e-cvc.bg, без URL credentials и с порт 443 или без порт. Относителен път се разрешава спрямо lox. Bearer се изпраща само към lox. Няма redirects. Приема се HTTP 200, начало %PDF- и до 10 MiB. Файлът се стриймва след права и nonce, не се публикува в uploads.

Деактивацията запазва настройки, поръчки и състояния. Не изтривайте CVC метаданните с цел повторно издаване. Архивите трябва да обхващат HPOS таблиците, shipping items/meta, options и salts.

Диагностика и типични откази

Събирайте версия, време, order ID, код на грешката и конкретната стъпка. За диагностична проба използвайте демо данни. Проверете browser console, network status и JSON success; премахнете tokens, cookies, nonces и лични данни преди споделяне.

Как е реализирана демонстрацията

Отделни WordPress root, база, потребители и фиктивен каталог на cvc.abc-engineering.bg. Няма копие на реални клиенти/поръчки. Използва се самостоятелният CVC for WooCommerce 2.0.0; отделен MU адаптер симулира CVC HTTP отговорите и ограничава методите до CVC. Активни са само WooCommerce и CVC for WooCommerce. Това е логическо разделяне в хостинга, не отделен виртуален сървър.

Първи guard блокира CVC/e-CVC HTTP и wp_mail. Demo Lab обработва познатите операции с фиктивни IDs и цени. Непознатите куриерски действия се отказват. Ключът е невалиден демонстрационен маркер. Изборите success/keyless/auth_error/rejected/unknown важат за текущия тестов потребител.

Shop manager има продуктови/поръчкови и CVC права, но отнети file upload/edit/install/update/delete, theme operations, user administration и системни екрани. Има директни проверки за страници и API. DISALLOW_FILE_EDIT е включен; браузърните file modifications са забранени. Публичните статични изображения и ръководства остават достъпни.

Допуска се точно фиктивният телефон 0000000000 само при checkout от разрешения демо управител. Другите невалидни номера не получават изключение. Линковете за проследяване се пренасочват към локален демо портал.

Този хост използва отделен PHP 8.3 FastCGI wrapper с opcache.interned_strings_buffer=32 MiB, opcache.memory_consumption=128 MiB и memory_limit=256M. Това отстрани измерен отказ при продуктовия редактор с първоначален 8 MiB interned pool. Настройката важи само за демо поддомейна; PHP грешките се записват извън публичната директория.

Имейлът и плащанията са симулирани; cron е изключен. Индексирането е забранено с noindex headers и настройки. Демо файловете и фиктивният ключ не трябва да се прехвърлят към реален магазин.

Приемателни тестове и визуални доказателства

Използвайте готовите сценарии и отделна нова тестова поръчка за всяко издаване. Автоматичните проверки не заменят финално потвърждение на CVC account API с разрешени тестови данни.

Резултатите от проверките са публикувани в QA протокола.

Преглед за интеграционния екип на CVC

Отстранени са специфичните за магазин зависимости, ценовото филтриране, неявните платежни промени и разминаването между лимитите в калкулацията и API редактора. Публичните идентификатори са CVC_WC_ / cvc_wc_ / _cvc_wc_; няма помощен плъгин в пакета.

Двата extension hooks cvc_wc_units_per_parcel($factor, $product, $cart_item) и cvc_wc_requires_manual_quote($required, $product, $cart_item) позволяват интеграция с външни системи за мерни единици без зависимост от тях. Факторът трябва да е положителен и краен. cvc_wc_after_settings добавя секция към настройките.

Преди реален API прием: CVC трябва да потвърди Bearer удостоверяването, схемите на четирите операции, договорните цени, справочниците, услугите и sandbox процедурата. Публичният HTML калкулатор не е версиониран API. За ref2 няма потвърдена гаранция за идемпотентност, а принадлежността на номер при reconcile изисква операторска проверка. Checkout Blocks и автоматични анулирания/вземания са извън текущия обхват.

При прехвърляне от друга директория на плъгин е необходима отделна контролирана миграция на options, product meta, shipping-item meta, order state и шифрования ключ. Промяна само на името на secret опцията не е достатъчна за AES-GCM. Миграционните инструменти и симулаторът не са в разпространявания ZIP.

Поддръжка, обновяване и възстановяване

1. Преди обновяване запишете WordPress/Woo/PHP/CVC версии и hash на архива. Архивирайте базата, конфигурацията и предходните файлове.
2. Сравнете публичния калкулатор и account API с реалните договорени спецификации. Повторете unit, integration и browser сценариите в демото.
3. Обновете ограничената директория на плъгина. Проверете версията, PHP lint и логовете. Не презаписвайте целия wp-content.
4. При дефект върнете предходните файлове. Ако е нужна база, възстановете под контрол така, че да не изгубите нови поръчки или durable waybill state. Стар архив без последните издадени пратки може да позволи опасно повторение.
5. След rollback сверете номерата в e-CVC, прочетете текущото състояние и проверете отново. Не създавайте реална товарителница за технически smoke test.

За реален API са необходими потвърдена схема, профил/ключ, точен подател, позволени услуги, ценова политика и приемателни тестове. Демо ключът и MU симулаторът не доказват реален достъп.

Първични източници: публичен калкулатор CVC, bgERP CVC адаптер, WooCommerce HPOS, WordPress Plugin Handbook. Поведението е сверено с изходния код на версия 2.0.0.