README

PHP client for Skorozvon API v2 with full coverage of REST resources, reports, and webhook toolkit.

Installation

composer require skorozvon/php-sdk

Quick Start (OAuth2 + Modules)

<?php

use Skorozvon\ApiClient;
use Skorozvon\Auth\OAuthCredentials;
use Skorozvon\DTO\Query\LeadsListQuery;

$username = getenv('SKOROZVON_USERNAME') ?: '';
$apiKey = getenv('SKOROZVON_API_KEY') ?: '';
$clientId = getenv('SKOROZVON_CLIENT_ID') ?: '';
$clientSecret = getenv('SKOROZVON_CLIENT_SECRET') ?: '';

$client = ApiClient::withOAuth(
    credentials: new OAuthCredentials(
        username: $username,
        apiKey: $apiKey,
        clientId: $clientId,
        clientSecret: $clientSecret,
    ),
);

$leads = $client->leads()->list(new LeadsListQuery(page: 1, length: 20));
$calls = $client->calls()->list();

var_dump($leads->status, $calls->status);

Quality Status

• CI runs tests and static analysis on each push/PR.
• Local quality gate:

composer check

• Current project checks:
  • PHPUnit: passing
  • PHPStan: no errors

Safe Live Testing

Use only test/disposable data and keep writes disabled by default.

Read-only smoke check:

SKOROZVON_USERNAME='...' \
SKOROZVON_API_KEY='...' \
SKOROZVON_CLIENT_ID='...' \
SKOROZVON_CLIENT_SECRET='...' \
php -r '
require "vendor/autoload.php";
use Skorozvon\ApiClient;
use Skorozvon\Auth\OAuthCredentials;
$client = ApiClient::withOAuth(new OAuthCredentials(
    getenv("SKOROZVON_USERNAME") ?: "",
    getenv("SKOROZVON_API_KEY") ?: "",
    getenv("SKOROZVON_CLIENT_ID") ?: "",
    getenv("SKOROZVON_CLIENT_SECRET") ?: ""
));
$users = $client->users()->list();
$leads = $client->leads()->list();
echo "users={$users->status}, leads={$leads->status}\n";
'

If you run write-tests (create/update), always delete created entities in the same run.

Quick Start (Reports API Key)

<?php

use Skorozvon\ApiClient;
use Skorozvon\DTO\Request\CallsTotalReportRequest;

$reportApiKey = getenv('SKOROZVON_REPORTS_API_KEY') ?: '';
$client = ApiClient::withApiKey($reportApiKey);

$response = $client->reports()->callsTotal(
    new CallsTotalReportRequest(
        startTime: 1704067200,
        endTime: 1704153599,
        page: 1,
        length: 10,
    )
);

Supported Modules

• auth() - OAuth token access helper
• account() - account balance
• users() - users list
• userGroups() - list/create/update/add/remove users
• leads() - list/get/create/update/delete/bulk delete/import/status
• calls() - list/get/recording URL/download
• customFields() - CRUD
• scenarios() - CRUD
• scenarioResults() - CRUD
• callProjects() - list/start/stop/complete/assign/update/statistic
• reports() - calls_total, managers_employment, export records, generic run
• webhooks() - parse, validate, idempotency dedup support

Strict Typed Layer

Use $client->strict() for validated typed responses across all API domains.

<?php

use Skorozvon\ApiClient;
use Skorozvon\Auth\OAuthCredentials;
use Skorozvon\DTO\Query\LeadsListQuery;

$client = ApiClient::withOAuth(
    new OAuthCredentials(
        username: getenv('SKOROZVON_USERNAME') ?: '',
        apiKey: getenv('SKOROZVON_API_KEY') ?: '',
        clientId: getenv('SKOROZVON_CLIENT_ID') ?: '',
        clientSecret: getenv('SKOROZVON_CLIENT_SECRET') ?: '',
    )
);

$strictLeads = $client->strict()->leads()->list(new LeadsListQuery(page: 1, length: 20));
foreach ($strictLeads->items as $lead) {
    // $lead is Skorozvon\Strict\Type\Lead
}

Strict layer modules:

• strict()->account()
• strict()->users()
• strict()->userGroups()
• strict()->leads()
• strict()->calls()
• strict()->customFields()
• strict()->scenarios()
• strict()->scenarioResults()
• strict()->callProjects()
• strict()->reports()
• strict()->webhooks()

API Coverage (SkorozvonAPI.pdf)

REST v2 endpoints covered:

• GET /api/v2/account/balance
• GET /api/v2/users
• GET /api/v2/user_groups
• POST /api/v2/user_groups/
• PUT /api/v2/user_groups/{id}
• PUT /api/v2/user_groups/{id}/add_users
• PUT /api/v2/user_groups/{id}/remove_users
• GET /api/v2/leads
• GET /api/v2/leads/{id}
• POST /api/v2/leads
• PUT /api/v2/leads/{id}
• DELETE /api/v2/leads/{id}
• POST /api/v2/leads/bulk_deletes
• GET /api/v2/bulk_deletes/{id}
• POST /api/v2/leads/import
• GET /api/v2/leads/import/{id}
• GET /api/v2/leads?stored_file_id={id}
• GET /api/v2/custom_fields
• POST /api/v2/custom_fields
• PUT /api/v2/custom_fields/{id}
• DELETE /api/v2/custom_fields/{id}
• GET /api/v2/calls
• GET /api/v2/calls/{id}
• GET /api/v2/calls/{id}.mp3
• GET /api/v2/scenarios
• POST /api/v2/scenarios
• GET /api/v2/scenarios/{id}
• PUT /api/v2/scenarios/{id}
• DELETE /api/v2/scenarios/{id}
• GET /api/v2/scenarios/{id}/results
• POST /api/v2/scenarios/{id}/results
• GET /api/v2/scenarios/{id}/results/{result_id}
• PUT /api/v2/scenarios/{id}/results/{result_id}
• DELETE /api/v2/scenarios/{id}/results/{result_id}
• GET /api/v2/call_projects
• POST /api/v2/call_projects/{id}/start
• POST /api/v2/call_projects/{id}/stop
• POST /api/v2/call_projects/{id}/complete
• POST /api/v2/call_projects/{id}/assign_leads
• POST /api/v2/call_projects/{id}/update_leads
• GET /api/v2/call_projects/{id}/statistic

Reports endpoints covered:

• POST /api/reports/calls_total.json
• POST /api/reports/managers_employment.json
• POST /api/reports/{report}/records
• Generic report runner: POST /api/reports/{report}.json

Auth and webhook support:

• OAuth2 password + refresh_token lifecycle via authenticator
• Reports API Key auth (Authorization: Key)
• Webhook parsing/validation/idempotency for:
  • call_result
  • form_response
  • call_project_case_failed

Fallback

rawRequest() is available for custom or future endpoints not yet wrapped by DTO methods.