Типизированное PHP SDK для API 1С-Битрикс и Битрикс24

Интеграция внешнего сервиса с Битрикс24 через REST API — рутинная задача, которая часто превращается в головную боль. Без типизированного SDK разработчик пишет десятки строк кода для каждого запроса, вручную обрабатывает пагинацию, ловит 401 при протухшем токене и 503 из-за rate limit. Через месяц код интеграции становится нечитаемым клубком curl_exec() с json_decode(). Типизированное SDK решает это кардинально: каждый метод API — отдельный класс с PHPDoc, автодополнение в IDE, единая точка конфигурации, встроенная обработка ошибок и автоматическое обновление токенов. Мы разрабатываем такие SDK под ключ — с нуля или на основе вашей кодовой базы. Наш опыт — более 50 интеграций, сертифицированные специалисты 1С-Битрикс.

Почему вам нужно типизированное SDK?

Сравните разработку с чистым curl и готовым SDK:

Типизированное SDK в 3–5 раз сокращает время разработки новых интеграций и исключает типовые ошибки: неправильные ключи, пропущенные обязательные поля, неверный формат даты. С SDK вы пишете 3 строки вместо 30 — это в 10 раз меньше кода. Для массовых операций, таких как импорт 10 000 лидов, SDK использует batch-метод Битрикс24 (до 50 команд за раз) и очереди (Laravel Queue, RabbitMQ), что даёт прирост скорости до 5 раз. Экономия бюджета на сопровождении — до 60%.

Согласно документации Битрикс24, при превышении лимита запросов сервер возвращает код 503 с заголовком X-RateLimit-Reset.

DTO: структура данных и типизация

DTO (Data Transfer Object) — это классы с типизированными свойствами, которые представляют структуру запроса или ответа. Например, LeadCreateRequest содержит поля title, name, phone с правильными типами. Это исключает ошибки вроде передачи строки вместо числа или пропуска обязательного поля. DTO также упрощают рефакторинг: изменение структуры API требует правки только одного класса. В нашем SDK все DTO имеют методы toApiArray() для преобразования в формат Битрикс24 и статические фабрики fromApiArray().

Как DTO упрощает рефакторинг?

При изменении схемы данных (например, добавлении нового поля) достаточно отредактировать соответствующий DTO-класс. IDE подсветит все места использования, а статические анализаторы (PHPStan, Psalm) проверят типы на этапе сборки. Это предотвращает регрессию в интеграциях.

Как SDK справляется с пагинацией?

При выборке списков (например, crm.lead.list) Битрикс24 возвращает постраничные результаты. SDK автоматизирует пагинацию через параметр start и предоставляет генератор, который подгружает все страницы без лишнего кода. В ответе приходит next — SDK использует его для продолжения. Дополнительно можно задать лимит на количество записей за один вызов (по умолчанию 50). Это позволяет обрабатывать каталоги любой размерности без ручного управления курсором.

Процесс разработки

1. Анализ API — выявляем необходимые методы, их параметры и ответы. Изучаем документацию REST API вашего портала.
2. Проектирование архитектуры — иерархия классов, DTO, исключения, middleware.
3. Реализация ядра — HTTP-клиент, работа с токенами, retry-механизм, логирование.
4. Создание типизированных методов — для каждой сущности: лиды, сделки, задачи, товары.
5. Тестирование — PHPUnit для unit-тестов и интеграционные тесты с реальным порталом (песочница). Покрытие кода не менее 80%.
6. Документация и примеры — README, PhpDoc для всех публичных методов, примеры использования в виде сниппетов.

Что входит в разработку SDK?

• Исходный код SDK в репозитории (GitHub/GitLab)
• Полная документация (PHPDoc, README с примерами)
• Тесты (unit + интеграционные)
• Настройка CI/CD (автоматическая сборка, тесты, деплой в packagist)
• Обучение вашей команды (1–2 часа онбординга)
• Поддержка в течение 3 месяцев после сдачи

Rate Limiting и очередь

Битрикс24 ограничивает запросы: 2 запроса/сек для облачных порталов. При превышении — HTTP 503 с X-RateLimit-Reset. SDK справляется с этим через RetryMiddleware, который делает несколько попыток с задержками (1, 2, 5 секунд). Если лимит не снят, выбрасывается RateLimitException. Для массовых операций SDK поддерживает batch-запросы и интеграцию с очередями, что позволяет загружать до 10 000 записей за минуту.

Пример реализации: клиент, DTO и API-класс

namespace BitrixSdk\Client; class BitrixClient { private string $baseUrl; private TokenStorage $tokenStorage; private \GuzzleHttp\Client $http; public function __construct(string $baseUrl, TokenStorage $tokenStorage) { $this->baseUrl = rtrim($baseUrl, '/') . '/rest/'; $this->tokenStorage = $tokenStorage; $this->http = new \GuzzleHttp\Client([ 'timeout' => 30, 'connect_timeout' => 10, ]); } public function call(string $method, array $params = []): array { $token = $this->tokenStorage->getAccessToken(); $url = $this->baseUrl . $method; try { $response = $this->http->post($url, [ 'json' => array_merge($params, ['auth' => $token]), ]); $data = json_decode($response->getBody()->getContents(), true); if (!empty($data['error'])) { $this->handleError($data); } return $data['result'] ?? $data; } catch (\GuzzleHttp\Exception\ClientException $e) { $statusCode = $e->getResponse()->getStatusCode(); if ($statusCode === 401) { $this->tokenStorage->refresh(); return $this->call($method, $params); } throw new BitrixApiException("HTTP {$statusCode}: " . $e->getMessage(), $statusCode); } } private function handleError(array $data): void { $errorCode = $data['error'] ?? 'UNKNOWN'; $errorDesc = $data['error_description'] ?? ''; if ($errorCode === 'QUERY_LIMIT_EXCEEDED') { throw new RateLimitException($errorDesc); } if (in_array($errorCode, ['NO_AUTH_FOUND', 'expired_token', 'invalid_token'])) { throw new AuthException($errorDesc); } throw new BitrixApiException("{$errorCode}: {$errorDesc}"); } public function batch(array $commands): array { $cmdParams = []; foreach ($commands as $key => $command) { $cmdParams[$key] = $command->toApiParam(); } $result = $this->call('batch', ['cmd' => $cmdParams]); return $result['result'] ?? []; } } 

namespace BitrixSdk\Dto\Crm; class LeadCreateRequest { public string $title; public ?string $name = null; public ?string $lastName = null; public ?string $phone = null; public ?string $email = null; public string $sourceId = 'WEB'; public ?string $comments = null; public int $responsibleId = 0; /** @var array<string, string> */ public array $utmFields = []; public function toApiArray(): array { $fields = [ 'TITLE' => $this->title, 'SOURCE_ID' => $this->sourceId, ]; if ($this->name) $fields['NAME'] = $this->name; if ($this->lastName) $fields['LAST_NAME'] = $this->lastName; if ($this->comments) $fields['COMMENTS'] = $this->comments; if ($this->phone) { $fields['PHONE'] = [['VALUE' => $this->phone, 'VALUE_TYPE' => 'WORK']]; } if ($this->email) { $fields['EMAIL'] = [['VALUE' => $this->email, 'VALUE_TYPE' => 'WORK']]; } foreach ($this->utmFields as $key => $value) { $fields[$key] = $value; } return $fields; } } class Lead { public int $id; public string $title; public ?string $name; public ?string $lastName; public string $status; public float $opportunity; public \DateTimeImmutable $dateCreate; public static function fromApiArray(array $data): self { $lead = new self(); $lead->id = (int)$data['ID']; $lead->title = $data['TITLE']; $lead->name = $data['NAME'] ?? null; $lead->lastName = $data['LAST_NAME'] ?? null; $lead->status = $data['STATUS_ID']; $lead->opportunity = (float)($data['OPPORTUNITY'] ?? 0); $lead->dateCreate = new \DateTimeImmutable($data['DATE_CREATE']); return $lead; } } 

namespace BitrixSdk\Api\Crm; class LeadApi { public function __construct(private BitrixClient $client) {} public function add(LeadCreateRequest $request): int { $result = $this->client->call('crm.lead.add', [ 'fields' => $request->toApiArray(), ]); return (int)$result; } public function get(int $id): Lead { $data = $this->client->call('crm.lead.get', ['id' => $id]); return Lead::fromApiArray($data); } /** * @return Lead[] */ public function list(array $filter = [], array $select = [], int $start = 0): array { $params = ['filter' => $filter, 'start' => $start]; if ($select) $params['select'] = $select; $data = $this->client->call('crm.lead.list', $params); return array_map(fn($item) => Lead::fromApiArray($item), $data); } public function update(int $id, array $fields): bool { return (bool)$this->client->call('crm.lead.update', [ 'id' => $id, 'fields' => $fields, ]); } } 

namespace BitrixSdk; class BitrixSdk { private BitrixClient $client; private ?Crm\LeadApi $leadApi = null; private ?Crm\DealApi $dealApi = null; private ?Tasks\TaskApi $taskApi = null; public static function create(string $webhookUrl): self { $sdk = new self(); $storage = new Client\WebhookTokenStorage($webhookUrl); $sdk->client = new Client\BitrixClient($webhookUrl, $storage); return $sdk; } public static function createOAuth(string $domain, string $clientId, string $clientSecret, TokenStorage $storage): self { $sdk = new self(); $sdk->client = new Client\BitrixClient("https://{$domain}", $storage); return $sdk; } public function crm(): CrmFacade { return new CrmFacade($this->client); } public function tasks(): TasksFacade { return new TasksFacade($this->client); } } // Использование $sdk = BitrixSdk::create('https://company.bitrix24.ru/rest/1/webhook_token/'); $lead = new LeadCreateRequest(); $lead->title = 'Заявка с сайта'; $lead->name = 'Иван'; $lead->phone = '+79001234567'; $leadId = $sdk->crm()->leads()->add($lead); 

Сроки разработки

Свяжитесь с нами для оценки вашего проекта — мы проанализируем ваше API и предложим оптимальный состав SDK. Закажите разработку SDK под ключ — получите готовую библиотеку с автодополнением и тестами.