PHPackages                             geekcodev/laravel-commercejson - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. geekcodev/laravel-commercejson

ActiveLibrary[API Development](/categories/api)

geekcodev/laravel-commercejson
==============================

CommerceJSON v1.0.8 integration package for Laravel 12

049PHPCI passing

Since May 29Pushed 1w agoCompare

[ Source](https://github.com/geekcodev/laravel-commercejson)[ Packagist](https://packagist.org/packages/geekcodev/laravel-commercejson)[ RSS](/packages/geekcodev-laravel-commercejson/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (2)Used By (0)

Laravel CommerceJSON
====================

[](#laravel-commercejson)

[![Latest Version on Packagist](https://camo.githubusercontent.com/1304eda2ed4320293532d2bd7b79d3f5d2a52186c5de3799dd6d3162cad58ee7/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6765656b636f6465762f6c61726176656c2d636f6d6d657263656a736f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/geekcodev/laravel-commercejson)[![Total Downloads](https://camo.githubusercontent.com/d66ba1f76085cca06b70ffee731d91fd2652d87b6ff9b6c3f3b62baa966d988b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6765656b636f6465762f6c61726176656c2d636f6d6d657263656a736f6e2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/geekcodev/laravel-commercejson)[![Code Coverage](https://camo.githubusercontent.com/8de5921f0e6a3a5f87cd69e2d8e01a1393d39da734f2aaa9a68cdccb040d16ad/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f6765656b636f6465762f6c61726176656c2d636f6d6d657263656a736f6e2f6d61696e3f7374796c653d666c61742d737175617265)](https://codecov.io/gh/geekcodev/laravel-commercejson)[![GitHub Actions (main)](https://camo.githubusercontent.com/27ceb78ff2957234fa187fc5117ad7db3f364104cf1984e3a95c62e20a10c094/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6765656b636f6465762f6c61726176656c2d636f6d6d657263656a736f6e2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/27ceb78ff2957234fa187fc5117ad7db3f364104cf1984e3a95c62e20a10c094/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6765656b636f6465762f6c61726176656c2d636f6d6d657263656a736f6e2f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)[![GitHub Actions (main)](https://camo.githubusercontent.com/f52d02e6e20342530a3addd750d682617f389635e09bbc7cdb20265c35c068c4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6765656b636f6465762f6c61726176656c2d636f6d6d657263656a736f6e2f7068707374616e2e796d6c3f6272616e63683d6d61696e266c6162656c3d7068707374616e267374796c653d666c61742d737175617265)](https://camo.githubusercontent.com/f52d02e6e20342530a3addd750d682617f389635e09bbc7cdb20265c35c068c4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6765656b636f6465762f6c61726176656c2d636f6d6d657263656a736f6e2f7068707374616e2e796d6c3f6272616e63683d6d61696e266c6162656c3d7068707374616e267374796c653d666c61742d737175617265)[![License](https://camo.githubusercontent.com/942e017bf0672002dd32a857c95d66f28c5900ab541838c6c664442516309c8a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e7376673f7374796c653d666c61742d737175617265)](LICENSE)

Пакет для интеграции с CommerceJSON API v1.0.8 в Laravel 13. Предназначен для обмена данными с системами 1С и другими ERP-системами, поддерживающими стандарт CommerceJSON.

Оглавление
----------

[](#оглавление)

- [Возможности](#%D0%B2%D0%BE%D0%B7%D0%BC%D0%BE%D0%B6%D0%BD%D0%BE%D1%81%D1%82%D0%B8)
- [Установка](#%D1%83%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0)
- [Использование](#%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)
    - [Быстрый старт](#%D0%B1%D1%8B%D1%81%D1%82%D1%80%D1%8B%D0%B9-%D1%81%D1%82%D0%B0%D1%80%D1%82)
    - [Использование сервисов](#%D0%B8%D1%81%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D0%BE%D0%B2)
    - [Console-команды](#console-%D0%BA%D0%BE%D0%BC%D0%B0%D0%BD%D0%B4%D1%8B)
- [Архитектура](#%D0%B0%D1%80%D1%85%D0%B8%D1%82%D0%B5%D0%BA%D1%82%D1%83%D1%80%D0%B0)
    - [Структура пакета](#%D1%81%D1%82%D1%80%D1%83%D0%BA%D1%82%D1%83%D1%80%D0%B0-%D0%BF%D0%B0%D0%BA%D0%B5%D1%82%D0%B0)
    - [Таблицы базы данных](#%D1%82%D0%B0%D0%B1%D0%BB%D0%B8%D1%86%D1%8B-%D0%B1%D0%B0%D0%B7%D1%8B-%D0%B4%D0%B0%D0%BD%D0%BD%D1%8B%D1%85)
- [Тестирование](#%D1%82%D0%B5%D1%81%D1%82%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5)
    - [Покрытие кода](#%D0%BF%D0%BE%D0%BA%D1%80%D1%8B%D1%82%D0%B8%D0%B5-%D0%BA%D0%BE%D0%B4%D0%B0)
- [Документация](#%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D1%86%D0%B8%D1%8F)
    - [Доступные методы](#%D0%B4%D0%BE%D1%81%D1%82%D1%83%D0%BF%D0%BD%D1%8B%D0%B5-%D0%BC%D0%B5%D1%82%D0%BE%D0%B4%D1%8B)
    - [События](#%D1%81%D0%BE%D0%B1%D1%8B%D1%82%D0%B8%D1%8F)
- [Конфигурация](#%D0%BA%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B0%D1%86%D0%B8%D1%8F)
- [Синхронизация](#%D1%81%D0%B8%D0%BD%D1%85%D1%80%D0%BE%D0%BD%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F)
    - [Полная синхронизация](#%D0%BF%D0%BE%D0%BB%D0%BD%D0%B0%D1%8F-%D1%81%D0%B8%D0%BD%D1%85%D1%80%D0%BE%D0%BD%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F)
    - [Инкрементальная синхронизация](#%D0%B8%D0%BD%D0%BA%D1%80%D0%B5%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D0%BB%D1%8C%D0%BD%D0%B0%D1%8F-%D1%81%D0%B8%D0%BD%D1%85%D1%80%D0%BE%D0%BD%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F)
    - [Планирование синхронизации](#%D0%BF%D0%BB%D0%B0%D0%BD%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5-%D1%81%D0%B8%D0%BD%D1%85%D1%80%D0%BE%D0%BD%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8)
- [Обработка ошибок](#%D0%BE%D0%B1%D1%80%D0%B0%D0%B1%D0%BE%D1%82%D0%BA%D0%B0-%D0%BE%D1%88%D0%B8%D0%B1%D0%BE%D0%BA)
- [Очереди заданий](#%D0%BE%D1%87%D0%B5%D1%80%D0%B5%D0%B4%D0%B8-%D0%B7%D0%B0%D0%B4%D0%B0%D0%BD%D0%B8%D0%B9)
- [Чеклист для production](#%D1%87%D0%B5%D0%BA%D0%BB%D0%B8%D1%81%D1%82-%D0%B4%D0%BB%D1%8F-production)
- [История версий](#%D0%B8%D1%81%D1%82%D0%BE%D1%80%D0%B8%D1%8F-%D0%B2%D0%B5%D1%80%D1%81%D0%B8%D0%B9)
- [Лицензия](#%D0%BB%D0%B8%D1%86%D0%B5%D0%BD%D0%B7%D0%B8%D1%8F)
- [Поддержка](#%D0%BF%D0%BE%D0%B4%D0%B4%D0%B5%D1%80%D0%B6%D0%BA%D0%B0)
- [Ссылки](#%D1%81%D1%81%D1%8B%D0%BB%D0%BA%D0%B8)

Возможности
-----------

[](#возможности)

- HTTP-клиент с поддержкой повторных запросов, идемпотентности и пагинации
- 23 модели Eloquent с отношениями и приведением типов
- 24 миграции базы данных с оптимизированными индексами
- 49 Data-классов для валидации данных
- 6 сервисов для бизнес-логики
- 7 очередей заданий для асинхронных операций
- 7 Artisan-команд для работы через CLI
- 11 событий для интеграции
- Фабрики и сидеры для тестирования
- Полная документация

Установка
---------

[](#установка)

После установки пакета и публикации конфига, маршруты автоматически регистрируются в `CommerceJsonServiceProvider`:

```
// Автоматическая регистрация в boot() методе
$this->loadRoutesFrom(__DIR__.'/routes/api.php');
```

**Готовые REST API endpoints** становятся доступны по префиксу `/api/commercejson` (настраивается через `config('commercejson.api_routes.prefix')`).

```
composer require geekcodev/laravel-commercejson
```

### Публикация конфигурации и миграций

[](#публикация-конфигурации-и-миграций)

```
# Публикация конфигурации
php artisan vendor:publish --tag=commercejson-config

# Публикация миграций
php artisan vendor:publish --tag=commercejson-migrations

# Запуск миграций
php artisan migrate
```

### Переменные окружения

[](#переменные-окружения)

Добавьте в файл `.env`:

```
# CommerceJSON API
COMMERCEJSON_BASE_URL=https://api.your-erp.com/v1
COMMERCEJSON_AUTH_TYPE=bearer
COMMERCEJSON_AUTH_TOKEN=your-api-token
COMMERCEJSON_TIMEOUT=30
COMMERCEJSON_RETRY_ATTEMPTS=3

# Очереди (рекомендуется для production)
COMMERCEJSON_QUEUE_ENABLED=true
COMMERCEJSON_QUEUE_CONNECTION=redis

# Синхронизация
COMMERCEJSON_SYNC_SCHEDULE=0 * * * *
COMMERCEJSON_INCREMENTAL_SYNC=true

# Логирование
COMMERCEJSON_LOGGING=true
COMMERCEJSON_LOG_CHANNEL=stack
COMMERCEJSON_LOG_REQUESTS=false
```

Использование
-------------

[](#использование)

### Быстрый старт

[](#быстрый-старт)

```
use GeekCo\CommerceJson\Facades\CommerceJson;

// Получить товары
$products = CommerceJson::products()->getProducts(
    page: 1,
    limit: 100,
    categoryId: 'uuid-here'
);

// Получить заказ
$order = CommerceJson::orders()->getOrder($orderId);

// Создать заказ
$newOrder = CommerceJson::orders()->createOrder($orderData);

// Импортировать предложения (цены и остатки)
CommerceJson::offers()->importOffers($offerImportData);
```

### Два способа работы с пакетом

[](#два-способа-работы-с-пакетом)

#### 1. REST API (Headless CMS) — рекомендуется для frontend

[](#1-rest-api-headless-cms--рекомендуется-для-frontend)

Пакет предоставляет готовые REST API endpoints. Используйте HTTP запросы из вашего frontend приложения:

```
// Frontend (React/Vue/Next.js) или мобильное приложение
const response = await fetch('https://your-app.test/api/commercejson/products');
const products = await response.json();

// Или через axios
const {data} = await axios.get('/api/commercejson/products');

// Создать заказ
const {data: order} = await axios.post('/api/commercejson/orders', {
    number: 'ORD-001',
    status: 'new',
    items: [...]
});
```

**Преимущества:**

- ✅ Готовые endpoints из коробки
- ✅ Не нужно писать контроллеры
- ✅ Идеально для React/Vue/Next.js frontend
- ✅ Мобильные приложения получают доступ к API
- ✅ CQRS архитектура внутри контроллеров

#### 2. Сервисы — для кастомной бизнес-логики

[](#2-сервисы--для-кастомной-бизнес-логики)

Если вам нужна кастомная логика, используйте сервисы напрямую:

```
use GeekCo\CommerceJson\Services\ProductService;
use GeekCo\CommerceJson\Services\OrderService;
use GeekCo\CommerceJson\Http\Client\HttpClientInterface;

class OrderController extends Controller
{
    public function __construct(
        private HttpClientInterface $http,
        private OrderService $orderService
    ) {}

    public function index()
    {
        // Чтение через HTTP API
        $orders = $this->orderService->getOrders(page: 1, limit: 100);
        return view('orders.index', compact('orders'));
    }

    public function store(OrderCreateData $data)
    {
        // Создание через HTTP API + сохранение через CommandBus
        $order = $this->orderService->createOrder($data);
        return response()->json($order);
    }
}
```

### Тестирование

[](#тестирование)

```
use GeekCo\CommerceJson\Tests\TestCase;
use GeekCo\CommerceJson\Http\Client\HttpClientInterface;
use Mockery;

class ProductServiceTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        $this->mockHttp = Mockery::mock(HttpClientInterface::class);
        $this->productService = new ProductService($this->mockHttp, ...);
    }

    /** @test */
    public function get_products_returns_product_list(): void
    {
        $this->mockHttp->shouldReceive('get')
            ->once()
            ->andReturn(new ResponseDto(200, [], $mockResponse, ...));

        $products = $this->productService->getProducts(page: 1, limit: 100);
        $this->assertCount(10, $products->products);
    }
}
```

#### Использование factory для Data-классов

[](#использование-factory-для-data-классов)

```
// Создание тестовых данных
$productData = ProductData::factory()->from([
    'id' => 'uuid-here',
    'name' => 'Test Product',
    'code' => 'TEST-001',
    'is_active' => true,
]);

// В тестах
protected function createProductData(array $attributes = []): ProductData
{
    return ProductData::factory()->from([
        'id' => $this->createTestUuid(),
        'name' => 'Test Product',
        ...$attributes,
    ]);
}
```

### Console-команды

[](#console-команды)

```
# Проверка соединения
php artisan commercejson:handshake

# Полная синхронизация
php artisan commercejson:sync --full

# Инкрементальная синхронизация (изменения за последний час)
php artisan commercejson:sync --incremental

# Импорт товаров
php artisan commercejson:import-products --queue

# Импорт заказов
php artisan commercejson:import-orders --updated-after=2026-01-01T00:00:00Z

# Экспорт заказов в ERP
php artisan commercejson:export-orders --limit=50
```

Архитектура
-----------

[](#архитектура)

Пакет использует архитектурные паттерны **CQRS** (Command Query Responsibility Segregation) и **Repository** для разделения операций чтения и записи, что обеспечивает:

- **Чёткое разделение ответственности** — команды для записи, запросы для чтения
- **Тестируемость** — легко мокировать зависимости через интерфейсы
- **Масштабируемость** — независимое масштабирование чтения/записи
- **Поддерживаемость** — понятная структура кода
- **Headless CMS** — готовые REST API контроллеры и роуты из коробки

### Готовые REST API endpoints

[](#готовые-rest-api-endpoints)

Пакет автоматически регистрирует маршруты в соответствии с OpenAPI спецификацией CommerceJSON v1.0.8:

```
Без auth:
  GET  /handshake  →  HandshakeController

С auth middleware:
  GET    /catalog/classifier          →  ClassifierController@index
  POST   /catalog/classifier          →  ClassifierController@store
  GET    /catalog/products            →  ProductController@index
  POST   /catalog/products            →  ProductController@store
  GET    /catalog/products/{id}       →  ProductController@show
  DELETE /catalog/products/{id}       →  ProductController@destroy
  GET    /offers                      →  OfferController@index
  POST   /offers                      →  OfferController@store
  GET    /offers/price-types          →  OfferController@priceTypes
  GET    /orders                      →  OrderController@index
  POST   /orders                      →  OrderController@store
  POST   /orders/bulk                 →  OrderController@bulkUpdate
  GET    /orders/{id}                 →  OrderController@show
  PATCH  /orders/{id}                 →  OrderController@update
  GET    /counterparties              →  CounterpartyController@index
  POST   /counterparties              →  CounterpartyController@store
  GET    /counterparties/{id}         →  CounterpartyController@show
  GET    /warehouses                  →  WarehouseController@index
  POST   /warehouses                  →  WarehouseController@store

```

**Важно:** `POST /orders/bulk` должен быть объявлен до `GET /orders/{id}`.

**Пример запроса:**

```
# Получить список товаров
curl -X GET "https://your-app.test/api/commercejson/catalog/products?page=1&limit=20" \
  -H "Accept: application/json"

# Создать товар
curl -X POST "https://your-app.test/api/commercejson/catalog/products" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"id": "uuid-here", "name": "Product 1", "code": "PROD-001", "is_active": true}'
```

### Структура пакета

[](#структура-пакета)

```
src/
├── CommerceJsonServiceProvider.php    # Регистрация сервисов, Bus::map()
├── config/
│   └── commercejson.php               # Конфигурация (235 строк)
├── routes/
│   └── api.php                        # OpenAPI-совместимые роуты
├── Commands/                          # Command DTO (запись, 27)
│   ├── CreateProductCommand.php
│   └── ...
├── Queries/                           # Query DTO (чтение, 14)
│   ├── GetProductQuery.php
│   └── ...
├── Bus/                               # Шины
│   └── QueryBusInterface.php          # Кастомная шина запросов
├── Handlers/                          # Обработчики (39)
│   ├── Commands/                      # Обработчики команд (Laravel Bus)
│   └── Queries/                       # Обработчики запросов
├── Repositories/                      # Репозитории (10)
│   ├── RepositoryInterface.php
│   ├── BaseRepository.php
│   ├── ProductRepository.php
│   └── ...
├── Http/
│   ├── Client/                        # HTTP-клиент для ERP
│   └── Controllers/                   # API контроллеры (7 + Handshake)
├── Services/                          # Сервисы бизнес-логики (6)
│   ├── ProductService.php
│   ├── OrderService.php
│   └── ...
├── Exchange/                          # Синхронизация
│   ├── Import/
│   └── Export/
├── Jobs/                              # Очереди заданий (7)
│   ├── Import/
│   ├── Export/
│   └── Sync/
├── Console/Commands/                  # Artisan команды (7)
├── Events/                            # События (11)
├── Exceptions/                        # Исключения
│   └── SyncException.php
├── Models/                            # Eloquent модели (23)
├── Data/                              # Spatie Data DTO (49)
├── Enums/                             # Перечисления (11)
├── Facades/
│   └── CommerceJson.php
└── database/
    ├── migrations/                    # Миграции (24)
    ├── factories/                     # Фабрики (17)
    └── seeders/                       # Сидеры (8)

```

### Компоненты архитектуры

[](#компоненты-архитектуры)

#### 1. HTTP Client Layer

[](#1-http-client-layer)

```
use GeekCo\CommerceJson\Http\Client\HttpClientInterface;

// Внедрение зависимости
public function __construct(
    private HttpClientInterface $http
) {}

// Использование
$response = $this->http->get('/catalog/products', ['page' => 1]);
$data = $response->data; // Массив данных
```

#### 2. Command/Query Bus

[](#2-commandquery-bus)

```
use GeekCo\CommerceJson\Bus\QueryBusInterface;
use GeekCo\CommerceJson\Commands\CreateProductCommand;
use GeekCo\CommerceJson\Queries\GetProductQuery;
use Illuminate\Contracts\Bus\Dispatcher;

// Команда (запись) — через Laravel Bus
$command = new CreateProductCommand($productData);
$product = $this->commandBus->dispatch($command); // Dispatcher

// Запрос (чтение) — через кастомный QueryBus
$query = new GetProductQuery($id);
$product = $this->queryBus->ask($query); // QueryBusInterface
```

#### 3. Services (бизнес-логика)

[](#3-services-бизнес-логика)

```
use GeekCo\CommerceJson\Services\ProductService;

public function __construct(
    private ProductService $productService
) {}

// Чтение через HTTP API
$products = $this->productService->getProducts(page: 1, limit: 100);

// Запись через CommandBus
$product = $this->productService->syncProduct($productData);
```

#### 4. Controllers (API endpoints)

[](#4-controllers-api-endpoints)

```
use GeekCo\CommerceJson\Http\Controllers\ProductController;

// GET /api/commercejson/products
public function index(Request $request): JsonResponse
{
    $query = new GetProductsQuery(perPage: 15);
    $products = $this->queryBus->ask($query);

    return response()->json(ProductData::collect($products->items()));
}

// POST /api/commercejson/products
public function store(Request $request): JsonResponse
{
    $command = new CreateProductCommand(ProductData::from($request->all()));
    $product = $this->commandBus->dispatch($command);

    return response()->json(ProductData::from($product), 201);
}
```

#### 5. Exceptions

[](#5-exceptions)

```
use GeekCo\CommerceJson\Http\Client\Exceptions\AuthenticationException;
use GeekCo\CommerceJson\Http\Client\Exceptions\ValidationException;
use GeekCo\CommerceJson\Http\Client\Exceptions\BusinessException;
use GeekCo\CommerceJson\Http\Client\Exceptions\RateLimitException;

try {
    $this->http->post('/orders', $data);
} catch (AuthenticationException $e) {
    // 401, 403
} catch (ValidationException $e) {
    // 400 - $e->errorsAsString()
} catch (BusinessException $e) {
    // 422, 429
}
```

### Таблицы базы данных

[](#таблицы-базы-данных)

**24 таблицы:**

- `categories` — категории товаров (иерархия)
- `price_types` — типы цен (розница, опт, дилер)
- `warehouses` — склады
- `property_definitions` — свойства товаров
- `property_values` — значения свойств
- `counterparties` — контрагенты
- `contacts` — контактная информация
- `bank_accounts` — банковские счета
- `representatives` — представители
- `products` — каталог товаров
- `product_variants` — варианты товаров
- `product_images` — изображения товаров
- `offers` — торговые предложения
- `offer_prices` — цены предложений
- `stocks` — остатки на складах
- `orders` — заказы клиентов
- `order_items` — позиции заказов
- `order_item_taxes` — налоги позиций
- `status_history_entries` — история статусов
- `custom_attributes` — пользовательские атрибуты
- `signatories` — подписанты документов
- `product_analogues` — аналоги товаров
- `product_components` — комплектующие
- `order_linked_documents` — связанные документы

Тестирование
------------

[](#тестирование-1)

Документация по генерации большого объёма данных для нагрузочного тестирования: [TESTING.md](TESTING.md).

```
# Запуск всех тестов (Pest)
vendor/bin/pest

# Параллельный запуск
vendor/bin/pest --parallel

# С покрытием (HTML отчёт)
composer test:coverage

# PHPStan статический анализ
composer analyse

# Laravel Pint code style
composer format
```

После генерации HTML отчёта, откройте `coverage/index.html` в браузере.

### Покрытие кода

[](#покрытие-кода)

Текущее покрытие: [![Code Coverage](https://camo.githubusercontent.com/8de5921f0e6a3a5f87cd69e2d8e01a1393d39da734f2aaa9a68cdccb040d16ad/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f6765656b636f6465762f6c61726176656c2d636f6d6d657263656a736f6e2f6d61696e3f7374796c653d666c61742d737175617265)](https://codecov.io/gh/geekcodev/laravel-commercejson)

**37 тестов, 180 assertions.** Покрытие требует расширения — см. [CODE\_AUDIT.md](CODE_AUDIT.md) (Фазы 2–5) и [COVERAGE.md](COVERAGE.md).

Документация
------------

[](#документация)

### Доступные методы

[](#доступные-методы)

#### ProductService

[](#productservice)

```
// Получить товары с пагинацией
$products = $productService->getProducts(
    page: 1,
    limit: 100,
    categoryId: 'uuid',
    isActive: true,
    updatedAfter: new DateTime('2026-01-01')
);

// Получить товар по ID
$product = $productService->getProduct($id);

// Импортировать товары
$result = $productService->importProducts($productsData);

// Деактивировать товар
$productService->deactivateProduct($id);
```

#### OrderService

[](#orderservice)

```
// Получить заказы
$orders = $orderService->getOrders(
    page: 1,
    limit: 50,
    status: 'new',
    updatedAfter: new DateTime('2026-01-01')
);

// Создать заказ
$order = $orderService->createOrder($orderCreateData);

// Обновить статус заказа
$orderService->updateOrderStatus($orderId, 'confirmed');

// Экспортировать новые заказы
$exported = $orderService->exportOrders(limit: 50);
```

### События

[](#события)

```
use GeekCo\CommerceJson\Events\ProductsImported;
use GeekCo\CommerceJson\Events\OrderImported;
use GeekCo\CommerceJson\Events\SyncCompleted;

Event::listen(ProductsImported::class, function ($event) {
    Log::info("Импортировано {$event->importedCount} товаров");
});

Event::listen(OrderImported::class, function ($event) {
    // Обработка нового заказа
});

Event::listen(SyncCompleted::class, function ($event) {
    Log::info("Синхронизация завершена за {$event->durationSeconds}с");
});
```

Конфигурация
------------

[](#конфигурация)

```
// config/commercejson.php
return [
    'base_url' => env('COMMERCEJSON_BASE_URL'),

    'auth' => [
        'type' => env('COMMERCEJSON_AUTH_TYPE', 'bearer'),
        'token' => env('COMMERCEJSON_AUTH_TOKEN'),
    ],

    'timeout' => env('COMMERCEJSON_TIMEOUT', 30),
    'retry_attempts' => env('COMMERCEJSON_RETRY_ATTEMPTS', 3),

    'exchange' => [
        'mode' => env('COMMERCEJSON_EXCHANGE_MODE', 'auto'),
        'batch_size' => [
            'products' => 100,
            'offers' => 200,
            'orders' => 50,
        ],
        'queue' => [
            'enabled' => env('COMMERCEJSON_QUEUE_ENABLED', true),
            'connection' => env('COMMERCEJSON_QUEUE_CONNECTION', 'redis'),
        ],
    ],

    'sync' => [
        'schedule' => env('COMMERCEJSON_SYNC_SCHEDULE', '0 * * * *'),
        'incremental' => [
            'enabled' => env('COMMERCEJSON_INCREMENTAL_SYNC', true),
        ],
    ],

    'logging' => [
        'enabled' => env('COMMERCEJSON_LOGGING', true),
        'channel' => env('COMMERCEJSON_LOG_CHANNEL', 'stack'),
    ],
];
```

Синхронизация
-------------

[](#синхронизация)

### Полная синхронизация

[](#полная-синхронизация)

```
# Синхронизация всех данных
php artisan commercejson:sync --full
```

### Инкрементальная синхронизация

[](#инкрементальная-синхронизация)

```
# Синхронизация изменений за последний час
php artisan commercejson:sync --incremental

# Синхронизация изменений с указанной даты
php artisan commercejson:sync --incremental --since=2026-01-01T00:00:00Z
```

### Планирование синхронизации

[](#планирование-синхронизации)

Добавьте в `app/Console/Kernel.php`:

```
protected function schedule(Schedule $schedule): void
{
    // Ежечасная инкрементальная синхронизация
    $schedule->command('commercejson:sync --incremental')
        ->hourly();

    // Еженедельная полная синхронизация
    $schedule->command('commercejson:sync --full')
        ->weeklyOn(0, '2:00');
}
```

Обработка ошибок
----------------

[](#обработка-ошибок)

### HTTP исключения

[](#http-исключения)

```
use GeekCo\CommerceJson\Http\Client\Exceptions\AuthenticationException;
use GeekCo\CommerceJson\Http\Client\Exceptions\ValidationException;
use GeekCo\CommerceJson\Http\Client\Exceptions\BusinessException;
use GeekCo\CommerceJson\Http\Client\Exceptions\RateLimitException;
use GeekCo\CommerceJson\Http\Client\Exceptions\ConnectionException;

try {
    $order = CommerceJson::orders()->createOrder($data);
} catch (AuthenticationException $e) {
    // 401, 403 - Неверные учётные данные
    Log::error('Ошибка авторизации: ' . $e->getMessage());
} catch (ValidationException $e) {
    // 400 - Ошибка валидации
    Log::error('Валидация: ' . $e->errorsAsString());
    foreach ($e->errors() as $error) {
        Log::error($error);
    }
} catch (BusinessException $e) {
    // 422, 429 - Бизнес-ошибка или rate limit
    Log::error('Бизнес-ошибка [' . $e->getCode() . ']: ' . $e->getMessage());
} catch (RateLimitException $e) {
    // 429 - Превышен лимит запросов
    $retryAfter = $e->retryAfter(); // секунд до повторной попытки
    $retryAt = $e->retryAt();       // DateTime для повторной попытки
    Log::warning("Превышен лимит запросов. Повтор через {$retryAfter}с");
} catch (ConnectionException $e) {
    // Ошибка соединения
    Log::error('Ошибка соединения: ' . $e->getMessage());
}
```

### Бизнес исключения

[](#бизнес-исключения)

```
use GeekCo\CommerceJson\Exceptions\SyncException;

try {
    CommerceJson::syncFull();
} catch (SyncException $e) {
    Log::error('Синхронизация [' . $e->getSyncType() . ']: ' . $e->getMessage());
    $lastSync = $e->getLastSyncTime(); // DateTime последней успешной синхронизации
}
```

Очереди заданий
---------------

[](#очереди-заданий)

```
use GeekCo\CommerceJson\Jobs\Import\ImportProductsJob;
use GeekCo\CommerceJson\Jobs\Import\ImportOrdersJob;
use GeekCo\CommerceJson\Jobs\Sync\SyncFullJob;

// Импорт товаров асинхронно
ImportProductsJob::dispatch(
    page: 1,
    limit: 100,
    updatedAfter: now()->subHour()
);

// Цепочка заданий
ImportProductsJob::dispatch()->chain([
    new ImportOrdersJob(),
    new \GeekCo\CommerceJson\Jobs\Export\ExportOrdersJob(),
]);

// Полная синхронизация
SyncFullJob::dispatch();
```

Чеклист для production
----------------------

[](#чеклист-для-production)

- Опубликовать конфигурацию: `php artisan vendor:publish --tag=commercejson-config`
- Опубликовать миграции: `php artisan vendor:publish --tag=commercejson-migrations`
- Запустить миграции: `php artisan migrate`
- Настроить worker очередей для асинхронных операций
- Настроить планирование синхронизации в Kernel.php
- Настроить мониторинг неудачных заданий
- Настроить канал логирования
- Проверить соединение: `php artisan commercejson:handshake`
- Запустить начальную полную синхронизацию: `php artisan commercejson:sync --full`

История версий
--------------

[](#история-версий)

### 1.0.0 (2026-04-24)

[](#100-2026-04-24)

- Начальный выпуск
- Поддержка CommerceJSON v1.0.8
- 24 миграции
- 23 модели
- 49 Data-классов
- 6 сервисов
- 7 очередей заданий
- 7 console-команд
- 11 событий
- Полное тестовое покрытие

Лицензия
--------

[](#лицензия)

Пакет распространяется под лицензией [MIT](LICENSE).

Поддержка
---------

[](#поддержка)

- **Email:**
- **Issues:** [GitHub Issues](https://github.com/geekcodev/laravel-commercejson/issues)
- **Документация:** [Wiki](https://github.com/geekcodev/laravel-commercejson/wiki)

Ссылки
------

[](#ссылки)

- [Packagist](https://packagist.org/packages/geekcodev/laravel-commercejson)
- [GitHub](https://github.com/geekcodev/laravel-commercejson)
- [Спецификация CommerceJSON](https://commercejson.ru/docs)

###  Health Score

24

—

LowBetter than 31% of packages

Maintenance64

Regular maintenance activity

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity13

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/2421ba0622fad89e516855478d693dd25c853898c58414ce5633116901bf2323?d=identicon)[Evgeny Semenov](/maintainers/Evgeny%20Semenov)

---

Top Contributors

[![geekcodev](https://avatars.githubusercontent.com/u/245257060?v=4)](https://github.com/geekcodev "geekcodev (101 commits)")

### Embed Badge

![Health badge](/badges/geekcodev-laravel-commercejson/health.svg)

```
[![Health](https://phpackages.com/badges/geekcodev-laravel-commercejson/health.svg)](https://phpackages.com/packages/geekcodev-laravel-commercejson)
```

###  Alternatives

[facebook/php-business-sdk

PHP SDK for Facebook Business

90923.5M35](/packages/facebook-php-business-sdk)[exsyst/swagger

A php library to manipulate Swagger specifications

35916.3M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24015.5M18](/packages/hubspot-api-client)[botman/driver-telegram

Telegram driver for BotMan

93452.6k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)