Sdk Laravel Package

Getting Started

Install with Composer:

composer require wizaplace/sdk

The SDK is a thin, typed wrapper around the Wizaplace REST API. There is no service provider bundled — you wire it up yourself.

Where to look first:

1. The Wizaplace\SDK\ root namespace — the entry point is the client/factory class (e.g. ApiClient / Marketplace), which takes your API credentials and the marketplace base URL.
2. The sub-namespaces, which are the real map of the API surface: Catalog, User, Order, Company, Basket, Payment, Cms, Discussion, Favorite, Shipping, Tax. Each is a service class you instantiate with the client.
3. The tests in the repo — since the README is thin, the test suite is the most reliable documentation of payload shapes and method signatures.

Minimal first use case — fetch a product:

use Wizaplace\SDK\ApiClient;

$client = new ApiClient('https://your-marketplace.example.com', 'YOUR_API_KEY');

$product = $client->getCatalogService()->getProductById(123);

echo $product->getName();

Auth is API-key based for server-to-server calls; user-scoped operations require an authenticated user session token. Get the product/catalog read path working first — it validates credentials, base URL, and response deserialization in one shot before you touch anything stateful.

Implementation Patterns

Wrap the client in your container. The client is stateful only in its HTTP layer, so register it as a singleton and inject the per-domain services where needed rather than passing the factory around:

$this->app->singleton(ApiClient::class, fn () => new ApiClient(
    config('services.wizaplace.url'),
    config('services.wizaplace.key'),
));

Treat services as repositories. Each domain service maps to an aggregate (OrderService, UserService). Resolve them lazily at the call site; there is no benefit to constructing all of them at boot.

Pagination is manual. Catalog and order listings return paginated result objects (page/limit or offset). Wrap iteration in a generator so you can stream a full catalog sync into your own DB without holding everything in memory:

foreach ($this->paginate(fn ($page) => $service->listProducts($page, 100)) as $product) {
    // upsert locally
}

Bidirectional sync, not just reads. The common production pattern is: Wizaplace is the source of truth for catalog/orders, your app mirrors it. Push writes through the SDK, pull reads on a schedule or via webhooks. Keep your local model decoupled from SDK DTOs — map to your own entities at the boundary, because DTO shapes are tied to the API version you're on.

Error handling at the boundary. Wrap SDK calls in a small adapter that catches the SDK's exception hierarchy and translates to your domain exceptions. Catch the specific HTTP-status-mapped exceptions (404 → NotFound, 4xx validation → your ValidationException), and let 5xx bubble as retryable.

Webhook receivers. Configure the endpoint in the Wizaplace back office, verify the payload signature/secret, then re-fetch the canonical object via the SDK rather than trusting the webhook body — payloads are notifications, not full snapshots.

Multi-marketplace (if applicable). The base URL is per-client, so a per-marketplace client instance (keyed by marketplace ID) is cleaner than mutating config.

Gotchas and Tips

• It's stale. Last release 2020-01-31 and effectively unmaintained. Pin your PHP and Guzzle versions deliberately; expect transitive guzzlehttp/guzzle constraint conflicts with modern Laravel/Symfony HTTP stacks. If conflicts bite, install with --with-all-dependencies and be prepared to fork.
• Thin docs. The README won't cover most endpoints — read the service classes and tests. Method names and DTO getters are your contract.
• DTOs are read-mostly. Setters/constructors vary between response DTOs and request payload objects. Don't assume a fetched Product can be passed straight back to an update call; check the method signature for what it actually wants.
• No built-in retry/backoff. Wire retries around the SDK (Laravel's Http::retry won't help — it's Guzzle underneath, so add middleware or a decorator). Respect rate limits; bulk catalog pushes will get throttled.
• Timeouts default low. Set connect/read timeouts explicitly on the underlying Guzzle client — large catalog downloads and order exports need generous read timeouts.
• Localization. Product/category fields are often translated arrays keyed by locale. Read the shape rather than assuming a scalar; a missing locale key is a common silent null.
• Debugging tip: drop a Guzzle logging middleware (or tap on the handler stack) into the client's HTTP stack so you can see raw requests/responses — invaluable when a DTO deserializes to empty fields because the API changed a key.
• Extension points are limited but real: inject a custom Guzzle handler/middleware for logging, retries, and auth headers; otherwise subclass or decorate the domain services if you need behavior the SDK doesn't expose.
• Version-pin hard. Because there are zero dependents and no recent releases, treat the SDK as vendored code: lock the exact version and isolate it behind your adapter layer so a future fork or direct-API replacement is a contained change.