Sellsy Laravel Package

Getting Started

Splash connectors are thin, code-generated wrappers around a remote API, so the first move is to read the source rather than expect a tutorial.

1. Install via Composer:

   composer require splash/sellsy
   

2. Look at the repository root first: composer.json, the src/ tree, and any openapi.yaml / openapi.json spec. The spec is the authoritative reference for what endpoints, parameters, and payload shapes exist — the PHP classes mirror it 1:1.
3. Identify the client entry point (typically Splash\Sellsy\Client or similar). In Splash connectors this is usually instantiated with a base URL and an auth bearer/API key, or via a container/DI binding if the package ships a Laravel service provider.
4. First use case: a read-only smoke test. Pull a single record type you actually need — e.g. list companies or fetch one contact by ID — to verify credentials, base URL, and JSON decoding end-to-end before writing anything back.

use Splash\Sellsy\Client;

$client = new Client('https://api.sellsy.com/v2', $accessToken);

$companies = $client->companies()->list(['limit' => 5]);

If the constructor signature differs, open the client class and follow the __construct — Splash connectors are deliberately simple, so there is rarely more than one credential path.

Implementation Patterns

Wrap the client in a service. Don't scatter new Client(...) calls. Bind it as a singleton (in Laravel, a service provider or app()->singleton()) with credentials pulled from config/env, so token rotation and base-URL changes are one-file edits.

Treat the client as a typed HTTP layer, not a domain model. Sellsy's API deals in resources (companies, contacts, opportunities, invoices, items). Your application should have its own models/DTOs and map between them. This keeps the connector swappable and testable.

Use sub-clients / resource groups. Splash connectors typically expose grouped methods like $client->contacts()->get($id) or $client->invoices()->create($payload). Group your own code the same way — a SellsyContactRepository, SellsyInvoiceRepository — one wrapper per resource group, so integration tests and mocks target a narrow surface.

Paginate explicitly. Sellsy v2 is paginated (limit/offset or cursor-style). Build a small iterator helper once and reuse it:

foreach ($repo->paginate('contacts', ['limit' => 100]) as $contact) { ... }

Do not assume list() returns everything.

Idempotency and rate limits. Write operations should be safe to retry. Log the request payload and the returned resource ID together; when a rate limit hits mid-batch, you want to resume rather than duplicate.

Integration tip — webhooks first. If you're syncing Sellsy → your app, prefer Sellsy webhooks for inbound events and reserve polling for backfill/reconciliation. Polling a large tenant on every cron tick will burn your rate budget fast.

Testing. Because the connector is HTTP-only, stub at the PSR-18/HTTP-client boundary (Splash typically accepts a client or uses a PSR-18 client under the hood). Record real Sellsy responses against a sandbox tenant and replay them — hand-written fixtures drift from the real schema quickly.

Gotchas and Tips

• Thin docs, thick spec. With zero stars and no listed dependents, expect no tutorials, no Stack Overflow answers, and possibly breaking changes between minor versions. Pin the version ("splash/sellsy": "1.x" or an exact tag) and read the OpenAPI spec in the repo, not the README.
• Auth is the usual failure point. Sellsy v2 uses OAuth2 bearer tokens with short-ish lifetimes. If you're getting 401s after a while but the first call works, you're not refreshing. Centralize token refresh in your service wrapper and persist the refresh token securely.
• Splash method names mirror OpenAPI operation IDs. If a method seems missing, search the spec for the operation — the class method exists, it may just be named differently than you'd guess (e.g. search vs list vs getList).
• Dates and enums are your problem. The connector passes payloads through; it won't validate created_at formats or Sellsy-specific enum values. Validate before sending, or you'll get opaque 400s.
• Errors come back as HTTP exceptions. Catch the Splash/PSR-18 exception type, unwrap the response body, and surface Sellsy's own error message — it's usually the only useful breadcrumb.
• Debugging: log the outgoing method, path, and payload (redact tokens). Splash clients are transparent enough that this reproduces nearly any failure locally with curl against the spec's example.
• Extension points are limited by design. If you need custom retry/backoff, middleware, or tracing, wire it into the underlying HTTP client rather than patching the generated classes — regenerating or upgrading the package will otherwise wipe your changes.
• Check tenant/region. Sellsy's API base URL and some behaviors differ by environment; make the base URL configurable even if production is fixed today.