README

PHP SDK for Uspacy – a single workspace for managing key processes of your organization with a focus on results. Communication, collaboration and CRM. All-in-one.

Built on Saloon and designed to mirror the official JS and Go SDKs. See the Uspacy API reference for endpoint details.

Requirements

• PHP ^8.2
• Laravel ^11 || ^12 || ^13 (the SDK ships as a Laravel package)

Installation

composer require uspacy/uspacy-php-sdk

The service provider is auto-discovered. Publish the config if you want to tune retries:

php artisan vendor:publish --provider="Uspacy\SDK\UspacySDKServiceProvider"

Quick start

use Uspacy\SDK\Http\Client\UspacySDK;

// Base URL is your portal host, e.g. https://<domain>.uspacy.ua
$sdk = new UspacySDK('https://acme.uspacy.ua', $accessToken);

// Most methods return a Saloon\Http\Response — use ->json(), ->status()
$deals = $sdk->crm()->getDeals(['page' => 1, 'list' => 20])->json();

// Some services return typed DTOs (see "Typed responses" below)
$user = $sdk->users()->getUserById(7); // UserDTO

Typed responses (DTOs)

Most methods return a raw Saloon\Http\Response. Selected services return typed DTOs (Uspacy\SDK\DTOs\...) for a nicer developer experience — currently:

• Auth — applicationSignIn() / refreshToken() return a Tokens DTO.
• Users — see the Users service guide.
• CRM entities — see the CRM service guide.
• Tasks — see the Tasks service guide.
• Messenger (partial) — see the Messenger service guide.

Every output DTO keeps the full raw payload, so portal-specific custom fields are never dropped. Read them with get() / has():

$user = $sdk->users()->getUserById(7);
$user->firstName;              // typed field
$user->get('customfield_1');   // custom field (or null)
$user->has('customfield_2');   // true / false
$user->raw;                    // the complete, untouched API payload

Service guides

• Users — full DTO reference and examples.
• CRM entities — entity + field DTOs, custom fields.
• Tasks — task + field DTOs, checklists, custom fields.
• Messenger — quick answers, chats, settings (partial).

Architecture

The SDK exposes service facades on the connector, mirroring the JS SDK's httpClient.client.get/post/... design:

• UspacySDK — the Saloon connector (auth, retries, base URL).
• HttpClient — a thin verb-oriented wrapper (get/post/patch/put/delete/postForm).
• Generic request classes (GetRequest, PostRequest, …) build the actual HTTP calls.
• One *Service per domain, each owning its API namespace.

Every service is reachable through an accessor on the connector:

CRM-family services (JS-parity)

Dedicated, entity-scoped CRM services mirroring the JS SDK:

Examples

CRM

// Entities
$sdk->crm()->getEntityTypes();
$sdk->crm()->getEntities('deals', ['page' => 1, 'list' => 50]);
$sdk->crm()->getContacts(['q' => 'ada@example.com']);

$sdk->crm()->createDeal(['title' => 'New deal', 'amount' => 1000]);
$sdk->crm()->patchEntity('deals', 42, ['amount' => 1500]);
$sdk->crm()->massEditEntities('deals', ['all' => true, 'settings' => [/* ... */]]);

// Fields
$sdk->crm()->getFields('deals');
$sdk->crm()->createField('deals', ['name' => 'Priority', 'type' => 'list']);
$sdk->crm()->deleteField('deals', 'priority');

// Funnels & kanban stages
$sdk->crm()->getFunnels('deals');
$sdk->crm()->getFunnelStagesByFunnelId('deals', 3);
$sdk->crm()->moveFunnelStage('deals', 42, 'stage-id', ['reason' => 'won']);

// Entity-scoped CRM services (JS-parity)
$sdk->crmDeals()->getEntities(['page' => 1]);
$sdk->crmDeals()->createEntity(['title' => 'New deal']);
$sdk->crmDeals()->massDeletion(entityIds: [1, 2, 3]);
$sdk->crmDeals()->moveFromStageToStage(42, 9, reasonId: 3);

$sdk->crmDealsFunnels()->getFunnels();
$sdk->crmDealsStages()->getStages();

// Products catalog
$sdk->crmProducts()->getProducts(['page' => 1]);
$sdk->crmProductsTaxes()->createProductTax(['name' => 'VAT', 'rate' => 20]);
$sdk->crmProductsForEntity()->createProductsForEntity([['product_id' => 1, 'quantity' => 2]]);

// Requisites & document templates
$sdk->crmRequisites()->getCardRequisites(['entity_id' => 5]);
$sdk->crmDocumentTemplates()->getDocumentTemplates();

// Products, calls, CRM tasks
$sdk->crm()->createProduct(['name' => 'Widget', 'price' => 9.99]);
$sdk->crm()->createCall(['direction' => 'inbound', 'phone' => '+380...']);
$sdk->crm()->createTask(['title' => 'Follow up']);

Tasks

$sdk->tasks()->getTasks(['page' => 1]);
$sdk->tasks()->getTask(15, ['crm_entity_list' => true]);
$sdk->tasks()->createTask(['title' => 'Ship SDK', 'responsibleId' => 7]);
$sdk->tasks()->updateTaskStatus(15, 'in_work');
$sdk->tasks()->delegateTask(15, 42);
$sdk->tasks()->markTaskReady(15);
$sdk->tasks()->massDeletionTasks(taskIds: ['15', '16']);

// Templates, checklists, transfers, trash
$sdk->tasks()->getRecurringTemplates();
$sdk->tasks()->createChecklist(15, ['name' => 'Launch']);
$sdk->tasks()->createChecklistItem(9, ['text' => 'Write tests']);
$sdk->tasks()->transferTasksToUser(['from_user_id' => 1, 'to_user_id' => 2]);
$sdk->tasks()->getTrashTasks();

Users & departments

$sdk->users()->getAllUsers();
$sdk->users()->getUsers(['page' => 2, 'list' => 20]);
$sdk->users()->updateUser(7, ['position' => 'CTO']);
$sdk->users()->deactivateUser(7);
$sdk->users()->updateRoles(7, ['admin']);
$sdk->users()->get2FaStatus(7);
$sdk->users()->search(['q' => 'ada@example.com']);
$sdk->users()->getUsersOnlineStatuses();
$sdk->users()->uploadAvatar(file_get_contents('/path/avatar.png'), userId: 7, filename: 'avatar.png');

$sdk->departments()->getDepartments();
$sdk->departments()->addUsers(4, [7, 8, 9]);

Files (multipart upload)

$sdk->files()->uploadFiles(
    [['name' => 'contract.pdf', 'data' => file_get_contents('/path/contract.pdf')]],
    entityType: 'deals',
    entityId: '42',
);

$sdk->files()->getFileById(101);
$sdk->files()->deleteFilesByEntity('deals', 42);

Messenger

$sdk->messenger()->getExternalLines();
$sdk->messenger()->createMessage(['chatId' => 1, 'text' => 'Hello']);
$sdk->messenger()->goToMessage('message-id');

// Chats, messages, widgets, quick replies, relations, settings
$sdk->messenger()->getChats(['status' => 'open']);
$sdk->messenger()->getMessages(['chatId' => 1]);
$sdk->messenger()->readAllMessages(1);
$sdk->messenger()->createQuickAnswer(['title' => 'Greeting', 'text' => 'Hi!']);
$sdk->messenger()->getChatRelations(1);
$sdk->messenger()->updateSettings(['sound' => false]);

Auth

$tokens = $sdk->auth()->applicationSignIn($clientId, $clientSecret); // Tokens DTO
$sdk->auth()->refreshToken();

Platform services

// Profile (current user)
$sdk->profile()->getProfile();
$sdk->profile()->enable2Fa();
$sdk->profile()->getRequisites();

// Roles & permissions
$sdk->roles()->getRoles();
$sdk->roles()->getPermissionsFunnels('admin');

// Webhooks (outgoing, or incoming via the $isIncoming flag)
$sdk->webhooks()->getWebhooks(page: 1);
$sdk->webhooks()->createWebhook(['url' => 'https://...'], isIncoming: true);

// OAuth clients, invites, notifications
$sdk->oauthClients()->getOAuthClients();
$sdk->invites()->createInvitesBatch(['ada@example.com']);
$sdk->notifications()->getNotifications();

// Task timer + change history
$sdk->tasksTimer()->startTimer($taskId);
$sdk->history()->getChangesHistory('crm', 'deals', 42, ['page' => 1]);

Growth / back-office

// Marketing: email templates, newsletters, domains, senders
$sdk->marketing()->getEmailTemplates(['page' => 1]);
$sdk->marketing()->createEmailNewsletter(['subject' => 'Launch']);
$sdk->marketing()->sendEmailNewsletter(5);
$sdk->marketing()->getSenders();

// Analytics: reports, dashboards, funnel conversion
$sdk->analytics()->getAnalyticsReportList();
$sdk->analytics()->getFunnelConversion(['funnel_id' => 3]);

// Automations: workers + workflows (processes)
$sdk->automations()->getWorkflows();
$sdk->automations()->createWorkflow(['name' => 'Onboarding']);

// Migrations: import status & control
$sdk->migrations()->getAllSystemsStatus();
$sdk->migrations()->stopImport('trello');

Error handling

The connector uses Saloon's AlwaysThrowOnErrors, so non-2xx responses throw a Saloon\Exceptions\Request\RequestException. Message creation additionally throws Uspacy\SDK\Exceptions\MessageDuplicationException on duplicate-key errors.

use Saloon\Exceptions\Request\RequestException;

try {
    $sdk->crm()->createDeal(['title' => 'New']);
} catch (RequestException $e) {
    $status = $e->getResponse()->status();
    $body = $e->getResponse()->json();
}

Development

composer install
composer test       # run the PHPUnit suite (Saloon MockClient, no network)
composer check-cs   # code style (ECS, PSR-12 + clean-code)
composer fix-cs     # auto-fix style