Ozon Orders Laravel Package

Technical Evaluation

Architecture fit

• This is a Symfony-flavoured module, not a Laravel package. The README's installation and operation surface is bin/console, and the commands (baks:users-profile-type:ozon-fbs, baks:payment:ozon-fbs, baks:delivery:ozon-fbs) are registered against the BaksDev domain aggregates — user profile types, payments, deliveries. There is no service provider, no config publish tag, no migration set, and no Laravel facade documented. Treat the "Laravel/PHP" framing in the description as a hosting-environment claim, not a framework-integration claim.
• It is an extension of an ecosystem, not a standalone connector. Adding this package implies adopting (or already running) the parent BaksDev users/profile, payment, and delivery modules. In a greenfield Laravel app this is closer to adopting a platform than installing a library — a materially different procurement decision.
• Domain scope is narrow and opinionated by design: Ozon FBS and DBS order flows only. That is good for time-to-market on exactly those two schemes and a hard stop for FBA-equivalent, cross-border, or non-Ozon marketplaces. There is no abstraction layer for a second marketplace.
• Configuration and credential handling are undocumented. Nothing in the README states where Client-Id/Api-Key live, how the Ozon API client is constructed, or how webhook/callback endpoints are exposed. Any architecture review must assume this is discovered by reading source.

Integration feasibility

Technical risk

Key questions (to resolve before a build commitment)

1. Does the package work in a Laravel application at all, or does it require a full Symfony kernel plus the BaksDev parent bundles? What is the minimum viable dependency set?
2. Which Ozon endpoints are actually implemented — specifically refunds, partial cancellation, returns, and non-standard status transitions?
3. Where are credentials stored and rotated, and is there a config surface we control?
4. Are the setup commands idempotent, and is there a dry-run or preview mode?
5. Do the commands create rows in tables we already own, or in package-specific tables? What is the migration story if upstream changes them?
6. How are webhook/callback deliveries retried by Ozon, and what happens on our side when processing fails — is anything queued, or is it lost?
7. Is there any published support arrangement, SLA, or roadmap, or is this effectively a fork-and-own dependency?
8. What is the licence-compatible path to forking, and does the code structure permit it (size, coupling, test presence)?
9. What does a single order's lifecycle cost in API calls, and are batch/throughput characteristics documented for 10k+ orders/day?
10. Can this coexist with a Wildberries or Yandex Market integration in the same instance without namespace or table collisions?

Integration Approach

Stack fit

• Framework: best treated as a Symfony component wrapped in an anti-corruption layer, invoked from Laravel jobs and services rather than woven into controllers. Do not let Ozon semantics leak into our order domain.
• Runtime: PHP 8.4+ implies Laravel 11/12. Confirm the target app's Laravel and PHP versions first; if the app is on 10.x or PHP 8.2/8.3, this package forces an unrelated platform upgrade and should be re-scoped as its own initiative.
• Infrastructure we must supply regardless: queue workers with retry/backoff (Horizon or equivalent), a webhook ingress route, idempotency keys on order ingestion, structured logging for all outbound Ozon calls, and secret management for API credentials.
• Data: plan for an isolation boundary — either a dedicated schema for BaksDev-owned tables or a mapping layer between package entities and our canonical order/payment/delivery models.

Migration path

Sequencing constraints

• Schema audit must precede any command execution. Running baks:*:ozon-* against an unexamined database is a one-way door.
• Webhook ingress and idempotency must ship before the first order, not after — retrofitting deduplication onto live orders is expensive.
• DBS before FBS: DBS keeps fulfilment with us and shrinks the blast radius of a bad status mapping.
• Decide fork-vs-consume before writing adapter code; the answer changes the interface design.

Compatibility

• No dependency on other marketplace packages is declared, but the shared table names (payment, delivery, profile type) are the practical collision surface for a multi-marketplace roadmap. Validate with a Wildberries-style second integration in the spike if omnichannel is on the roadmap within 12 months.

Operational Impact

Maintenance

• Ownership model must be explicit. With a single maintainer, no dependents, and empty release notes, plan for fork-and-own from day one: pin a commit, mirror the repo internally, and budget ongoing maintenance as if it were our code. Realistic ongoing cost: 0.2–0.3 FTE steady state, spiking during Ozon API changes.
• Upgrade cadence is a trap. ~48 patch releases without changelogs means we cannot assess upgrade risk from release notes; every bump requires diff review. Recommend a quarterly upgrade window with a sandbox regression pass, not continuous updates.
• Deprecation exposure is unpriced. Any Ozon API version change becomes an unplanned work item with no upstream warning mechanism. Budget a contingency reserve for 1–2 forced upgrades per year.

Support

• No vendor support, no SLA, no English documentation. Internal knowledge must be documented deliberately during the pilot — runbooks, endpoint inventory, failure playbook — or the integration becomes a single-person dependency.
• Russian-language CLI output and docs mean at least one team member needs Russian fluency or we fund translation of operator-facing surfaces. This is a real resourcing item, not a footnote.

Scaling

• Throughput is unknown and gated by Ozon's own rate limits, not by the package. Design for queue-based, rate-limited outbound calls from the start; do not call Ozon synchronously from a web request.
• Webhook bursts (e.g., campaign-driven sales peaks) will hit our ingress first. Needs backpressure, a durable queue, and a dead-letter path with replay tooling.
• Data volume: order, payment, and delivery rows accumulate in tables we did not design. Confirm indexing and retention before volume ramp; retrofitting indexes on a hot order table is a production risk.

Failure modes

Ramp-up

• Engineering: ~1–2 weeks to productive on the package internals (source-reading is mandatory), plus ~1 week on Ozon FBS/DBS domain semantics.
• Operations/support: ~1 week for the runbook, reconciliation procedure, and failure playbook; add a shadowing week before go-live.
• Finance/ops: a defined daily reconciliation ritual with an owner, not an ad-hoc check.

Decision framing for the TPM

• This package buys weeks, not months, and only if the host application can absorb the BaksDev domain model. If a Laravel-native, marketplace-agnostic integration is the strategic direction, the thin-custom-client option (Phase 2 alternative c) is likely cheaper over an 18-month horizon despite a slower start.
• Recommended posture: time-boxed spike with a hard go/no-go at two weeks, DBS-first, fork rights secured before production, and a named owner for the dependency from day one. Kill criteria: no Laravel service-provider path, no refund/return coverage, or setup commands proven non-idempotent.