TajerSystem Connector for Magento 2

Official connector module that links a Magento 2 / Adobe Commerce store to
TajerSystem — real-time profit, VAT and inventory
analytics for Magento merchants.

See what it feeds: open the live TajerSystem demo — one click, no signup.

What's new in 2.7

Version 2.7 turns the sync from "orders and totals" into an accounting-grade
financial event ledger living inside your own Magento database:

• Immutable financial events — order placement, invoices, payment
  authorizations/captures, credit memos, refunds, shipments, deliveries and
  returns are each recorded as append-only events, protected by database
  triggers so history can never be rewritten (not even by the module itself).
• Outbox with auto-recovery — financial changes are delivered through a
  durable outbox (tajersystem_financial_change); a recovery cron re-queues
  anything missed within 5 minutes, so no financial change is ever lost.
• Delivery evidence endpoint — POST /V1/tajersystem/orders/:orderId/delivery-evidence
  records real carrier delivery confirmation instead of inferring it from a
  mutable order status (essential for COD profit recognition).
• Structured tax evidence — order payloads carry explicit net/tax/gross
  per line; VAT reports reconcile against evidence, not reverse-engineered totals.
• Consent-gated marketing touchpoints (dormant by default) — allowlisted
  UTM/referrer capture that only fires behind a CMP-owned consent cookie; the
  module never sets the cookie itself.
• Still zero extra infrastructure: DB-backed queues + standard Magento
  cron. No RabbitMQ, no middleware.

See CHANGELOG.md for details. 2.7.1 fixes trigger installation
on MariaDB / MySQL 8.

What it does

• Real-time push sync — observers on sales_order_save_after,
  catalog_product_save_after, inventory_source_item_save_after and
  customer_save_after push changes to TajerSystem the moment they happen.
• One-click connect — a Connect button in Stores → Configuration
  generates a short-lived setup token; TajerSystem exchanges it for a scoped
  integration token (POST /V1/tajersystem/exchange-token). No copying API
  keys around.
• Pull API for TajerSystem — REST endpoints under /V1/tajersystem/*
  let the platform manage orders (status, invoice, ship, refund, comment),
  adjust stock, and update product price/status — so actions taken in
  TajerSystem reflect back into Magento.
• Backfill commands — bin/magento tajersystem:sync:orders,
  tajersystem:sync:products, tajersystem:sync:stock for initial or
  catch-up sync.
• Housekeeping cron — expired setup tokens are cleaned automatically.

Requirements

• Magento Open Source / Adobe Commerce 2.4.x
• PHP 8.1+ (8.3 supported) with ext-bcmath (exact money math)
• MSI modules (magento/module-inventory-api) recommended for salable-qty sync

Installation

Via app/code

mkdir -p app/code/Bonlineco/TajerSystem
# copy this repository's contents there, then:
bin/magento module:enable Bonlineco_TajerSystem
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Via composer (path or VCS repository)

composer config repositories.tajersystem vcs https://github.com/o0mohd0o/magento2-tajersystem-connector
composer require bonlineco/module-tajersystem
bin/magento module:enable Bonlineco_TajerSystem && bin/magento setup:upgrade

Connecting your store

1. Create a free TajerSystem account at tajersystem.com (14-day trial, no card).
2. In Magento admin: Stores → Configuration → TajerSystem → Connect — click Generate connect link.
3. Open the link — TajerSystem exchanges the setup token and starts the first
   full sync automatically. Your profit numbers appear within minutes.

Security notes

• The setup token is single-use and short-lived; the permanent integration
  token is scoped to the endpoints listed above.
• The module only talks to the TajerSystem URL configured under
  Stores → Configuration → TajerSystem (default https://app.tajersystem.com).
• No telemetry, no third-party calls.

License

OSL-3.0 — the same license family as Magento Open Source itself.

Built by BONLINE TECHNOLOGIES LTD — a team
that runs Magento stores, for people who run Magento stores.

Changelog — Bonlineco_TajerSystem Magento 2 Module

All notable changes to the bonlineco/module-tajersystem module are documented in this file.

2.7.1 — 2026-07-24

Fixed

• Production activation compatibility fixes
  • Completed Magento service-contract and queue message PHPDoc metadata.
  • Created compound trigger bodies through Magento's multiQuery API.
  • Marked the three trigger data patches NonTransactionable so Magento does not wrap trigger DDL in a transaction.
  • Made the trigger patch intentionally non-revertable/data-preserving to avoid Magento's transactional DDL conflict.

2.7.0 — 2026-07-24

Added

• Immutable financial-event sync & payload contracts (Spec 001 Reconciled Profitability)
  • Added support for explicit contract-allowed financial event payload types (order_placed, invoice_issued, payment_authorized, payment_captured, credit_issued, refund_paid, shipment_completed, delivery_completed, return_received) carrying source_namespace=magento:{store_code} and immutable stored economic_origin_key.
• Structured sales-line tax evidence capture
  • Expanded order payload serialization in OrderPayloadBuilder to preserve explicit net/tax/gross and structured output-tax evidence without totals-based inference, leaving output line recoverability fields null.
• Consent-aware marketing touchpoint capture
  • CaptureMarketingTouchpoint observer wired to capture allowlisted UTM params, referrer, and consent-aware acquisition parameters on first landing.
  • CopyMarketingTouchpointToOrder observer transfers touchpoints from quote to order context for attribution processing.
• Durable queue topology & payload compatibility
  • Enhanced queue message consumers and payload serialization to maintain backward and forward compatibility between Magento and TajerSystem SaaS versions.

2.6.0 — 2026-03-01

Changed

• Outbound sync request context header (Sprint E Task 7.3)
  • Model/Client/TajerSystemClient now sends X-Magento-Website-Id on outbound sync requests (orders/upsert, products/upsert, stock/update, customers/upsert).
  • This header carries Magento website context to TajerSystem's inbound webhook receiver for safer multi-connection mapping.

2.5.0 — 2026-03-01

Added

• Customer sync pipeline (Sprint E Task 6.1)
  • CustomerSyncObserver wired to customer_save_after to publish customer sync messages.
  • Queue contract + wiring for customer sync: topic tajersystem.customer.sync, publisher/topology bindings, queue tajersystem.customer.sync.queue, consumer tajersystem.customer.sync.consumer.
  • Customer sync message + processing classes: CustomerSyncMessage, CustomerSyncConsumer, and CustomerPayloadBuilder.
• Customer pull endpoint — GET /rest/V1/tajersystem/customers for TajerSystem ERP pull sync with pagination and optional updated_after / website_id filtering.
  • Service contract: Bonlineco\TajerSystem\Api\CustomerManagementInterface (getList).
  • Implementation: Bonlineco\TajerSystem\Model\Customer\GetCustomersService.

Changed

• etc/acl.xml — added Bonlineco_TajerSystem::customers ACL resource.
• etc/di.xml — added CustomerManagementInterface to GetCustomersService preference.
• etc/webapi.xml — added route GET /V1/tajersystem/customers with Bonlineco_TajerSystem::customers resource.
• composer.json — version bumped to 2.5.0.

2.4.0 — 2026-03-01

Added

• Inbound product status update endpoint (Task 4.3) — POST /rest/V1/tajersystem/products/status allows TajerSystem ERP to enable or disable a product in the Magento catalog.
  • Service contract: Bonlineco\TajerSystem\Api\ProductStatusManagementInterface with updateStatus(string $sku, bool $enabled) method.
  • DTO interface: Bonlineco\TajerSystem\Api\Data\ProductStatusResultInterface — returns success, sku, oldStatus, newStatus, and message.
  • DTO implementation: Bonlineco\TajerSystem\Model\Product\ProductStatusResult — immutable constructor-promoted DTO.
  • Service implementation: Bonlineco\TajerSystem\Model\Product\UpdateStatusService — validates SKU (trims whitespace, rejects empty), loads product by SKU via ProductRepositoryInterface, sets catalog status (1=enabled, 2=disabled), detects no-ops (product already at desired status), saves via ProductRepositoryInterface::save(). Logs the status change with old/new status details.
  • Request body:
    • sku (string, required) — Product SKU to update.
    • enabled (boolean, required) — true to enable the product (status=1), false to disable it (status=2).
  • Response: { "success": bool, "sku": string, "old_status": string, "new_status": string, "message": string }
  • ACL resource: Reuses Bonlineco_TajerSystem::products — the existing dedicated ACL resource for product operations.
  • 8 unit tests in Test/Unit/Model/Product/UpdateStatusServiceTest.php covering: enable product, disable product, already-enabled no-op, already-disabled no-op, empty SKU rejection, whitespace-only SKU rejection, non-existent product rejection, and SKU whitespace trimming.
  • Total unit tests: 130 (across all module services).

Changed

• etc/webapi.xml — added route for POST /V1/tajersystem/products/status with Bonlineco_TajerSystem::products ACL resource.
• etc/di.xml — added preferences: ProductStatusManagementInterface → UpdateStatusService, ProductStatusResultInterface → ProductStatusResult.
• composer.json — version bumped to 2.4.0.

2.3.0 — 2026-02-28

Added

• Inbound product price update endpoint (Task 4.1) — POST /rest/V1/tajersystem/products/price allows TajerSystem ERP to update a product's regular price and optional special (sale) price in the Magento catalog.
  • Service contract: Bonlineco\TajerSystem\Api\ProductPriceManagementInterface with updatePrice(string $sku, float $price, ?float $specialPrice, ?string $specialFromDate, ?string $specialToDate) method.
  • DTO interface: Bonlineco\TajerSystem\Api\Data\ProductPriceResultInterface — returns success, sku, oldPrice, newPrice, specialPrice, and message.
  • DTO implementation: Bonlineco\TajerSystem\Model\Product\ProductPriceResult — immutable constructor-promoted DTO.
  • Service implementation: Bonlineco\TajerSystem\Model\Product\UpdatePriceService — validates inputs (non-empty SKU, non-negative price, special price less than regular price, Y-m-d date format), loads product by SKU via ProductRepositoryInterface, sets price and special price with date range (or clears special price when null), saves via ProductRepositoryInterface::save(). Trims SKU whitespace. Logs the update with old/new price details.
  • Request body:
    • sku (string, required) — Product SKU to update.
    • price (float, required) — New regular price. Must be zero or positive.
    • specialPrice (float, optional) — Special (sale) price. Must be less than regular price. Pass null to clear the special price and its date range.
    • specialFromDate (string, optional) — Start date for special price (Y-m-d format).
    • specialToDate (string, optional) — End date for special price (Y-m-d format).
  • Response: { "success": bool, "sku": string, "old_price": float, "new_price": float, "special_price": float|null, "message": string }
  • ACL resource: Bonlineco_TajerSystem::products — new dedicated ACL resource for product operations, nested under ::config, titled "TajerSystem Product Management".
  • 11 unit tests in Test/Unit/Model/Product/UpdatePriceServiceTest.php covering: regular price update only, price with special price and dates, special price without dates, SKU whitespace trimming, zero price allowed, empty SKU rejection, negative price rejection, negative special price rejection, special price exceeding regular price rejection, invalid date format rejection, and non-existent product rejection.
  • Total unit tests: 122 (across all module services).

Changed

• etc/webapi.xml — added route for POST /V1/tajersystem/products/price with Bonlineco_TajerSystem::products ACL resource.
• etc/di.xml — added preferences: ProductPriceManagementInterface → UpdatePriceService, ProductPriceResultInterface → ProductPriceResult.
• etc/acl.xml — added Bonlineco_TajerSystem::products resource nested under ::config.
• composer.json — version bumped to 2.3.0.

2.2.0 — 2026-02-28

Added

• Inbound stock adjustment endpoint (Sprint C) — POST /rest/V1/tajersystem/stock/adjust allows TajerSystem ERP to adjust stock quantities in Magento MSI (Multi-Source Inventory).
  • Request body:
    • sku (string, required) — Product SKU to adjust.
    • quantity (number, required) — Target quantity (set mode) or change amount (delta mode).
    • adjustment_type (string, required) — "set" for absolute quantity or "delta" for relative change (+/−).
    • source_code (string, optional) — MSI source code. Defaults to the default source if omitted.
    • reason (string, optional) — Human-readable reason for the adjustment, logged for audit trail.
  • Response: { "product_id": int, "sku": string, "source_code": string, "old_quantity": number, "new_quantity": number, "adjustment_type": string }
  • ACL resource: Bonlineco_TajerSystem::stock — new dedicated ACL resource for stock operations, nested under ::config.
  • Dependency: Requires Magento MSI (magento/module-inventory-api) for source item management.

Changed

• etc/webapi.xml — added route for POST /V1/tajersystem/stock/adjust with Bonlineco_TajerSystem::stock ACL resource.
• etc/di.xml — added preference for the stock adjustment service contract.
• etc/acl.xml — added Bonlineco_TajerSystem::stock resource nested under ::config.
• composer.json — version bumped to 2.2.0, added magento/module-inventory-api to require.

2.1.0 — 2026-02-28

Added

• Inbound shipment creation endpoint (Task 2.2) — POST /rest/V1/tajersystem/orders/:orderId/ship allows TajerSystem ERP to create shipments with optional tracking information in Magento.

  • Service contract: Bonlineco\TajerSystem\Api\ShipmentManagementInterface with createShipment(int $orderId, ?string $trackNumber, ?string $carrierCode, ?string $carrierTitle, ?string $comment, ?bool $notify) method.
  • Service implementation: Bonlineco\TajerSystem\Model\Order\CreateShipmentService — ships all eligible items using Magento's ShipOrderInterface. When $trackNumber is provided, creates a ShipmentTrackCreationInterface instance with the given carrier code and title. Adds an optional status history comment. Sends customer notification email when $notify is true. Returns OrderActionResultInterface.
  • 5 unit tests in Test/Unit/Model/Order/CreateShipmentServiceTest.php.

• Inbound refund/credit-memo endpoint (Task 2.3) — POST /rest/V1/tajersystem/orders/:orderId/refund allows TajerSystem ERP to create full credit memos (refunds) in Magento.

  • Service contract: Bonlineco\TajerSystem\Api\RefundManagementInterface with createRefund(int $orderId, ?string $comment, ?bool $notify) method.
  • Service implementation: Bonlineco\TajerSystem\Model\Order\CreateRefundService — creates a full credit memo for all eligible items using Magento's RefundOrderInterface. Adds an optional status history comment. Sends customer notification email when $notify is true. Returns OrderActionResultInterface.
  • 4 unit tests in Test/Unit/Model/Order/CreateRefundServiceTest.php.

• Inbound order comment endpoint (Task 2.4) — POST /rest/V1/tajersystem/orders/:orderId/comment allows TajerSystem ERP to add status history comments to Magento orders.

  • Service contract: Bonlineco\TajerSystem\Api\CommentManagementInterface with addComment(int $orderId, string $comment, ?bool $notify, ?bool $visibleOnFront) method.
  • Service implementation: Bonlineco\TajerSystem\Model\Order\AddCommentService — adds a status history entry with configurable storefront visibility via $visibleOnFront. Sends customer notification email when $notify is true. Persists via OrderRepositoryInterface::save(). Returns OrderActionResultInterface.
  • 4 unit tests in Test/Unit/Model/Order/AddCommentServiceTest.php.

• All three new service contracts reuse the shared OrderActionResultInterface DTO from v2.0.0.

• All three endpoints require the Bonlineco_TajerSystem::orders ACL resource.

• Total unit tests: 24 (11 from v2.0.0 + 13 new).

Changed

• etc/webapi.xml — added routes for POST /V1/tajersystem/orders/:orderId/ship, POST /V1/tajersystem/orders/:orderId/refund, and POST /V1/tajersystem/orders/:orderId/comment, all with Bonlineco_TajerSystem::orders ACL resource.
• etc/di.xml — added preferences: ShipmentManagementInterface → CreateShipmentService, RefundManagementInterface → CreateRefundService, CommentManagementInterface → AddCommentService.
• composer.json — version bumped to 2.1.0.

2.0.0 — 2026-02-28

Added

• Inbound order status endpoint — POST /rest/V1/tajersystem/orders/:orderId/status allows TajerSystem ERP to push order status changes into Magento. Supports standard transitions, hold/unhold, cancellation, status history comments, and customer notification.
  • Service contract: Bonlineco\TajerSystem\Api\OrderManagementInterface with updateStatus(int $orderId, string $status, ?string $comment, ?bool $notify) method.
  • DTO interface: Bonlineco\TajerSystem\Api\Data\OrderActionResultInterface — returns success, message, orderId, status, and state.
  • DTO implementation: Bonlineco\TajerSystem\Model\Order\OrderActionResult — immutable constructor-promoted DTO.
  • Service implementation: Bonlineco\TajerSystem\Model\Order\UpdateStatusService — handles the full transition logic:
    • Validates target status against ALLOWED_STATUSES (pending, pending_payment, processing, complete, closed, canceled, holded).
    • No-op shortcut when the order is already at the target status.
    • Special-case handling for holded (uses $order->hold()), canceled (uses $order->cancel()), and unhold transitions (uses $order->unhold() then applies target status if different).
    • General transitions set both state and status via STATUS_STATE_MAP.
    • Adds status history comment (default: "Status updated via TajerSystem ERP.") with configurable customer notification.
    • Persists via OrderRepositoryInterface::save().
    • Comprehensive logging (request received, success, failure).
  • ACL resource: Bonlineco_TajerSystem::orders — nested under ::config, titled "TajerSystem Order Management".
  • 11 unit tests in Test/Unit/Model/Order/UpdateStatusServiceTest.php covering: valid status transitions, no-op for same status, invalid status rejection, hold/unhold/cancel special cases, unhold-then-transition, customer notification flag, and error propagation.
  • Test stubs expanded: Phrase, LocalizedException, NoSuchEntityException classes added to Test/Stubs/magento_stubs.php; Order stub now implements OrderInterface.

Changed

• etc/webapi.xml — added route for POST /V1/tajersystem/orders/:orderId/status with Bonlineco_TajerSystem::orders ACL resource.
• etc/di.xml — added preferences for OrderManagementInterface → UpdateStatusService and OrderActionResultInterface → OrderActionResult.
• etc/acl.xml — added Bonlineco_TajerSystem::orders resource nested under ::config.
• composer.json — version bumped to 2.0.0.

1.1.1 — 2026-02-23

Fixed

• Integration authorization rules silently deleted during token exchange — Magento's Model\Plugin\Integration hooks afterCreate() and afterUpdate() on IntegrationServiceInterface. Without all_resources or resource set on the integration model, the plugin calls grantPermissions($id, []) with an empty array, which deletes all previously granted authorization rules. The fix sets 'all_resources' => true in the integration data so the plugin calls grantAllPermissions() instead, granting Magento_Backend::all => allow (full API access). This is appropriate for the TajerSystem ERP integration.

Removed

• AuthorizationServiceInterface dependency from IntegrationManager — no longer needed; permission granting is now handled automatically by Magento's Integration plugin via the all_resources flag.
• REQUIRED_RESOURCES constant from IntegrationManager — the explicit resource list is replaced by the all_resources approach.

1.1.0 — 2026-02-23

Added

• Auth link flow — One-click store connection via setup token exchange.
  • ConnectButton admin block — renders "Connect to TajerSystem" button with AJAX-powered token generation.
  • GenerateLink admin controller — generates setup token, derives TajerSystem app URL from API base URL, returns auth link. ACL-restricted to Bonlineco_TajerSystem::connect.
  • SetupTokenExchangeInterface service contract — defines the REST exchange method.
  • ExchangeTokenService — REST API handler: validates and consumes setup token atomically, creates Magento Integration via IntegrationManager, returns access token.
  • IntegrationManager — creates Integration with timestamped name, grants full API permissions via all_resources flag, creates OAuth token, activates. Cleans up orphaned Integrations on failure.
  • SetupTokenManager — generates 256-bit random tokens (10-min expiry), atomic validateAndConsume() via conditional SQL UPDATE, cleanup() for expired tokens.
  • SetupToken model with isExpired(), isUsed(), isValid() helpers.
  • tajersystem_setup_token DB table with unique token constraint and expires_at index.
  • Resource model and collection for setup tokens.
  • CleanupExpiredSetupTokens cron job — runs hourly, deletes tokens older than 60 minutes.
  • POST /rest/V1/tajersystem/exchange-token REST endpoint (anonymous access, token-based auth).
  • Admin route tajersystem/connect/generateLink via etc/adminhtml/routes.xml.
  • "TajerSystem Connection" config group in system.xml with connect button.
  • Bonlineco_TajerSystem::connect ACL resource.

Changed

• etc/di.xml — added SetupTokenExchangeInterface → ExchangeTokenService preference.
• etc/acl.xml — added Bonlineco_TajerSystem::connect nested under ::config.
• etc/adminhtml/system.xml — added "TajerSystem Connection" group.
• etc/module.xml — added Magento_Integration to sequence dependencies.
• etc/crontab.xml — added tajersystem_cleanup_setup_tokens hourly cron job.
• etc/db_schema.xml — added tajersystem_setup_token table.
• etc/db_schema_whitelist.json — whitelisted new table.
• composer.json — added magento/module-integration to require.

1.0.0 — 2026-02-23

Added

• Admin configuration — Website-scoped settings for API credentials, sync mode, retry limits, and debug logging under Stores > Configuration > TajerSystem > General Settings. API key stored encrypted via Magento's Encrypted backend model.
• Event observers — Three global-scope observers (OrderSyncObserver, ProductSyncObserver, StockSyncObserver) react to sales_order_save_after, catalog_product_save_after, and inventory_source_item_save_after events. Observers publish lightweight message DTOs to the queue without loading entities or calling APIs.
• DB-backed message queue — Three topics (tajersystem.order.sync, tajersystem.product.sync, tajersystem.stock.sync) with DB connection, single exchange (tajersystem.exchange), and three consumers (maxMessages=100 each).
• Queue consumers — OrderSyncConsumer, ProductSyncConsumer, StockSyncConsumer process messages by building payloads, tracking attempts via SyncLogManager, and POSTing to the TajerSystem API. Transient errors trigger queue retry; permanent errors are consumed.
• Payload builders — OrderPayloadBuilder, ProductPayloadBuilder, StockPayloadBuilder load entities and build API payloads with idempotency keys. Stock uses data-deterministic idempotency (MD5 of qty values).
• HTTP client — TajerSystemClient with Bearer auth, tenant ID header, idempotency key header, 30s timeout, debug logging, and transient error detection (0, 408, 429, 500, 502, 503, 504).
• Sync log — tajersystem_sync_log table with SyncLogManager for attempt tracking, outcome recording, and retry limiting. Unique constraints prevent duplicate rows and idempotency keys.
• CLI commands — tajersystem:sync:orders, tajersystem:sync:products, tajersystem:sync:stock for manual full/partial sync. Commands enqueue to the existing queue infrastructure.
• Cron incremental sync — IncrementalSync runs every 5 minutes for websites with sync_mode=cron, processing entities changed since last successful sync.
• Centralized topic constants — Model/Queue/Topics.php as single source of truth for all queue topic strings.
• Unit test suite — 78 tests, 168 assertions across 11 test classes:
  • ConfigTest (16 tests) — All 12 Config helper methods.
  • OrderPayloadBuilderTest (4), ProductPayloadBuilderTest (3), StockPayloadBuilderTest (5) — Payload structure, idempotency keys, edge cases.
  • TajerSystemClientTest (10) — Headers, responses, errors, debug logging.
  • OrderSyncConsumerTest (6), ProductSyncConsumerTest (3), StockSyncConsumerTest (3) — Consumer outcomes, retry logic.
  • OrderSyncObserverTest (5), ProductSyncObserverTest (4), StockSyncObserverTest (5) — Publishing, guards, exception isolation.
  • SyncLogManagerTest (8) — Attempt tracking, outcome recording, retry checks.
• Test infrastructure — PHPUnit 10.5, Magento type stubs (~370 lines), factory stubs, separate test Composer file, bootstrap that loads stubs before autoloader.