Laravel Neto Laravel Package

Product Decisions This Supports

• Build vs. buy for Neto/Maropost integration: The package covers the highest-value surface area most commerce integrations need on day one — order lifecycle (get, find, create, update, cancel, status, tracking), items, and customers (including findByEmail) — so it can replace a bespoke API wrapper for a first integration or migration off Neto.
• Roadmap sequencing for commerce/ops features: Because orders, tracking, and status transitions are first-class, this unblocks roadmap items like order sync to a WMS/3PL, fulfilment status dashboards, customer lookup at support/checkout time, and inventory-aware item sync.
• Escape hatch planning: request() / get() for arbitrary Neto actions means the roadmap is not bounded by resource coverage — you can commit to less-common Neto endpoints (e.g., vouchers, content, warehouses, RMA) without waiting on package releases, reducing vendor lock-in to this package.
• Operational reliability decisions: Built-in timeouts, retries on transient failures, and masked-key request logging make it viable to treat Neto as a dependency in customer-facing flows, and give you a defensible answer on "what happens when Neto is slow or 5xx-ing?"
• Security/compliance posture: Header-based auth with a masked API key in logs supports a clean answer at security review; worth confirming no other PII (customer records, order data) lands in logs.
• Use cases to prioritise: order ingestion/fulfilment automation, customer self-service lookups, catalogue/price sync, and support tooling — all of which map onto the shipped resources.

When to Consider This Package

Adopt when:

• You are on Laravel 12–13 / PHP 8.3–8.5 — the version floor is aggressive and will exclude most existing applications, so confirm your upgrade path first.
• You need read/write Neto order, item, and customer operations and want typed exceptions (ConfigurationException, RequestException, ResponseException, NotFoundException) rather than parsing HTTP status codes by hand — a real win for error-handling UX and retry logic.
• Your team values a thin, configurable client over a heavy abstraction; the generic request()/get() escape hatch means low risk of being blocked by missing endpoints.
• You are integrating a single Neto storefront and want to avoid maintaining a homegrown SDK.

Look elsewhere or wait when:

• v0.1.0 pre-release status is disqualifying for production. No stated 1.0 commitment, no deprecation policy, no BC guarantees. For revenue-critical paths, pin the version, plan to vendor/fork, or budget for a thin internal wrapper until it stabilises.
• You need pagination, batching, or rate-limit-aware scheduling. These are not mentioned; Neto's API limits and multi-page result handling are typically the hard part of a real integration, not single-record CRUD.
• You need webhooks/event subscriptions. Only pull-based access is described — this matters a lot if you wanted event-driven order sync. Confirm whether Neto's event/filter endpoints can be reached via the generic request().
• You are on PHP < 8.3 or Laravel ≤ 11, or depend on a first-party/officially supported Maropost SDK.
• You need multi-store/multi-tenant credential handling — configuration appears single-client; assess whether one client instance per store is workable for you.
• You want guarantees around retry safety. Retries on create/update/cancel carry idempotency risk; confirm whether retries are scoped to safe/idempotent GETs or applied blindly.

How to Pitch It (Stakeholders)

For executives: This is a small, focused integration library for Maropost Commerce Cloud (Neto) that lets our engineering team connect orders, items, and customers to our Laravel platform without building an API client from scratch. It handles the unglamorous-but-essential parts — authentication, timeouts, retries, structured error handling, and safe logging that doesn't leak credentials — which is where these integrations usually break in production. Expect to save engineering weeks versus a bespoke wrapper, and to keep the door open to any Neto endpoint via a generic escape hatch. The caveat is maturity: it's an initial pre-release with no stability guarantees, so we should pilot it on a non-critical path and pin the version before depending on it for order fulfilment.

For engineering: Single Neto client with header auth, configurable timeout, transient-failure retries, and optional logging with a masked API key. Typed resources for Orders (get, find, create, update, cancel, status, tracking), Items and Customers (get, find, create, update, plus findByEmail), and request()/get() for anything else. Errors are surfaced as four typed exceptions, so you can distinguish configuration mistakes, transport failures, bad responses, and 404s instead of checking status codes. Constraint: PHP 8.3–8.5 and Laravel 12–13 only. Open questions to resolve before we commit: pagination and large-result handling, rate-limit/backoff behaviour, idempotency of retries on mutating calls, and whether webhook-style order events are reachable through the generic request method.

Recommended next step: timeboxed spike — wire it to a sandbox Neto store, integrate order status/tracking reads, validate retry and logging behaviour under simulated 5xx and timeout conditions, and decide on version pinning plus a fork-or-fallback plan if the package stalls.