Api Bundle Laravel Package

Getting Started

The package is a helpdesk API layer (tickets, threads, agents, customers, groups, teams) that your Laravel app talks to over HTTP. Treat it as an external service: one configured client, one thin service class per resource.

Minimal setup:

1. composer require uvdesk/api-bundle (or point your composer.json at the v1.1.4 tag if you vendor it).
2. Publish the config and set credentials in .env: base URL, API token/keys, and timeout.
3. Register a single HelpdeskClient in a service provider that wraps Laravel's Http client with baseUrl(), withToken(), acceptJson(), and retry().
4. Look first at the bundle's routing/controller definitions for tickets and agents — that is where the request payload shape lives. Then read CHANGELOG-1.1.md, since v1.1.4 includes a refactor pass.
5. Check the ticket resource for custom-field handling; that is the newest and least-documented surface.

First use case: create a ticket from a contact form and store the returned ticket payload.

$response = $this->helpdesk->post('/api/tickets', [
    'subject'     => $request->subject,
    'message'     => $request->message,
    'customer'    => ['email' => $request->email, 'name' => $request->name],
    'customFields'=> ['priority_level' => 'high'], // new in 1.1.4
]);

$ticket = $response->json('data'); // now populated in 1.1.4
TicketMirror::updateOrCreate(['remote_id' => $ticket['id']], $ticket);

Implementation Patterns

One client, many resources. Build TicketService, AgentService, CustomerService, GroupService, TeamService on top of a shared client. Keep endpoints and payload keys in config so instance-specific custom fields do not leak into controllers.

Create-and-use-the-response. v1.1.4 returns the created/updated entity payload for tickets, agents, customers, groups, and teams. Stop doing POST then GET:

$ticket = $tickets->create($payload);          // returns ticket data
$thread = $tickets->reply($ticketId, $body);   // returns thread details

Persist the returned object directly into a local mirror table. This halves your request count and removes the race where a follow-up GET fires before the write is visible.

Mirror tables + upsert. Keep local Eloquent models (ticket_mirrors, agent_mirrors, …) keyed by the remote ID. Use updateOrCreate on every create/update response so the mirror stays warm for dashboards and search without hammering the API.

Custom fields: schema-first. Custom fields are per-instance. Fetch and cache the field definitions (config or a scheduled job), then validate user input against that schema before submitting. Send them as a keyed array; never hardcode field names in Blade or controllers.

$schema = Cache::remember('helpdesk.custom_fields', 3600, fn () => $client->get('/api/custom-fields')->json('data'));

$validated = validator($input, $this->rulesFromSchema($schema))->validate();

Agent creation event. 1.1.4 adds an agent-creation event and returns the agent ID. Register a listener that fires onboarding (welcome mail, local role assignment, team membership). Persist the local mirror record before dispatching dependent jobs so downstream workers can resolve the ID.

Queue everything that writes. Wrap create/reply/sync calls in jobs with $tries = 3, exponential backoff, and RateLimited middleware. Reads can be synchronous; writes should not block a web request.

Testing. Use Http::fake() with fixtures that match the 1.1.4 envelope (data populated). Add one test per resource asserting your service returns a hydrated DTO rather than an ID — that is where the behaviour actually changed.

Webhook/listener idempotency. If you consume agent-created or ticket-created events, dedupe on the remote ID with a unique index. Events can be delivered more than once.

Gotchas and Tips

• Response shape changed. Prior versions often returned a bare ID or an empty body on create/update. Code doing $response->json('id') will now miss — the payload lives under data. Audit every ->json('id') call before upgrading; this is the most likely upgrade break in 1.1.4 despite being labelled an improvement.
• The refactor is the risk, not the features. "Code Refactoring" with no detail means namespaces or method signatures may have shifted. Read CHANGELOG-1.1.md and diff the classes you touch before bumping the constraint.
• Custom fields fail silently if unknown. Sending a field key the instance does not define may be dropped rather than rejected. Validate against the fetched schema, and assert the field appears in the create response.
• Do not trust optional keys. Use data_get($payload, 'customer.email') rather than array access. Refactors in this release may omit nested relations you previously assumed were always present.
• Agent ID timing. The agent-creation event may fire before your HTTP call returns. If your listener needs the local record, resolve by email or queue the listener with a short delay rather than assuming the mirror row exists.
• Debugging. Add a tap on the client to log method, path, status, and a redacted body. The bundle's own logs plus your request log will pinpoint whether a mismatch is payload or routing.
• Extension points. Custom fields (schema-driven), the new agent-created event, and the resource serializers are the intended seams. Prefer a decorator around your service classes over editing vendor code — the refactor in this release proves the internals move.
• Pin the version. With a refactor plus response-shape additions in one minor bump, use "~1.1.4" and upgrade deliberately rather than floating on ^1.0.