PHPackages                             maguto/dilovod-sdk - 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. maguto/dilovod-sdk

ActiveLibrary[API Development](/categories/api)

maguto/dilovod-sdk
==================

PHP SDK for Dilovod API — Ukrainian online accounting and reporting service

2.0.0(4mo ago)02MITPHPPHP ^8.2CI passing

Since Apr 3Pushed 4mo agoCompare

[ Source](https://github.com/magutodev/dilovod-php-sdk)[ Packagist](https://packagist.org/packages/maguto/dilovod-sdk)[ RSS](/packages/maguto-dilovod-sdk/feed)WikiDiscussions 2.x Synced 1w ago

READMEChangelogDependencies (10)Versions (4)Used By (0)

Dilovod PHP SDK
===============

[](#dilovod-php-sdk)

[![CI](https://github.com/magutodev/dilovod-php-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/magutodev/dilovod-php-sdk/actions/workflows/ci.yml)[![Latest Stable Version](https://camo.githubusercontent.com/ca7e15a86ddd3df89ac2911285ec8350b9592d7f50e8a387d53fecc81682994d/68747470733a2f2f706f7365722e707567782e6f72672f6d616775746f2f64696c6f766f642d73646b2f76)](https://packagist.org/packages/maguto/dilovod-sdk)[![PHP Version](https://camo.githubusercontent.com/6d66575ab30acbe73998051ad1bd7c3ba990aa00306b7cbe2661d9e41a72c1e2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6d616775746f2f64696c6f766f642d73646b2f706870)](https://packagist.org/packages/maguto/dilovod-sdk)[![License](https://camo.githubusercontent.com/667b907e3677f2312f718e03cd21d369f290508d623932261e5314336093eb44/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d616775746f2f64696c6f766f642d73646b)](LICENSE)

PHP SDK для роботи з [Dilovod API](https://help.dilovod.ua/uk/article/api-dilovod-1gwt3m0/) — українським онлайн-сервісом бухгалтерського, управлінського обліку та звітності.

> **Версія 2.x** — потребує PHP 8.2+. Для PHP 7.4+ дивіться гілку [`1.x`](https://github.com/magutodev/dilovod-php-sdk/tree/1.x).

Встановлення
------------

[](#встановлення)

```
composer require maguto/dilovod-sdk
```

SDK потребує реалізації PSR-18 (HTTP client) та PSR-17 (HTTP factories). Рекомендовані пакети:

```
# Guzzle (найпопулярніший)
composer require guzzlehttp/guzzle nyholm/psr7

# або тільки Nyholm + Symfony HTTP Client
composer require nyholm/psr7 symfony/http-client
```

Швидкий старт
-------------

[](#швидкий-старт)

```
use Maguto\Dilovod\Config;
use Maguto\Dilovod\DilovodClient;
use Maguto\Dilovod\Enum\Operator;
use Maguto\Dilovod\Transport\PsrTransport;
use GuzzleHttp\Client as GuzzleClient;
use Nyholm\Psr7\Factory\Psr17Factory;

// Конфігурація
$config = new Config(
    apiKey: 'ваш_api_ключ',
    // apiUrl: 'https://vps.example.com',  // для VPS-серверів
    // clientId: 'my-app',                 // для партнерської статистики
);

// Ініціалізація
$psr17 = new Psr17Factory();
$transport = new PsrTransport(
    config: $config,
    httpClient: new GuzzleClient(['timeout' => 30]),
    requestFactory: $psr17,
    streamFactory: $psr17,
    // logger: $psrLogger,  // опціонально, PSR-3
);

$client = new DilovodClient($config, $transport);
```

Основні методи
--------------

[](#основні-методи)

### Отримання об'єкта за ID

[](#отримання-обєкта-за-id)

```
$product = $client->getObject('1100300000022632');

$header = $product->get('header');
echo $header['name']['uk'];
```

### Збереження об'єкта

[](#збереження-обєкта)

```
// Створення
$id = $client->saveObject(
    header: [
        'id' => 'catalogs.goods',
        'name' => ['uk' => 'Новий товар', 'ru' => 'Новый товар'],
    ],
);

// Оновлення
$client->saveObject(
    header: ['id' => $id, 'name' => ['uk' => 'Оновлена назва']],
);

// Створення та проведення документа
use Maguto\Dilovod\Enum\SaveType;

$client->saveObject(
    header: [
        'id' => 'documents.saleOrder',
        'firm' => '1100400000001001',
        'person' => '1100100000001001',
        'currency' => '1101200000001001',
        'date' => '2026-04-03 14:00:00',
    ],
    saveType: SaveType::Register,
);
```

### Позначка на видалення

[](#позначка-на-видалення)

```
$client->setDelMark('1100300000022632');
```

Query Builder
-------------

[](#query-builder)

Fluent API для вибірки даних. Підтримує 5 типів запитів.

> **Важливо:** alias, що використовується у `where()`, повинен бути оголошений у `fields()`.

### Прямий запит до довідника

[](#прямий-запит-до-довідника)

```
$products = $client->query('catalogs.goods')
    ->fields(['id' => 'good', 'code' => 'code', 'name' => 'name', 'parent.code' => 'parentCode'])
    ->where('parentCode', Operator::Equal, 101010)
    ->limit(50)
    ->get();

foreach ($products as $product) {
    echo $product['name'] . PHP_EOL;
}

// Отримати перший запис
$first = $client->query('catalogs.firms')
    ->fields(['id' => 'id', 'name' => 'name'])
    ->first();

// Отримати значення одного поля з усіх записів
$codes = $client->query('catalogs.goods')
    ->fields(['id' => 'id', 'code' => 'code'])
    ->withoutLinks()
    ->get()
    ->pluck('code');
```

### Товарні залишки на дату

[](#товарні-залишки-на-дату)

```
$stock = $client->query()
    ->balance('goods', '2025-01-01 00:00:00', ['good', 'storage'])
    ->fields([
        'good' => 'good',
        'good.code' => 'code',
        'storage' => 'storage',
        'qty' => 'qty',
    ])
    ->where('good', Operator::Equal, '1100300000022619')
    ->get();
```

### Обороти за період

[](#обороти-за-період)

```
$sales = $client->query()
    ->turnover('saleIncomes', '2025-01-01', '2025-06-30', ['good', 'firm'])
    ->fields([
        'good' => 'good',
        'good.code' => 'code',
        'amountReciept' => 'income',
    ])
    ->get();
```

### Залишки + обороти

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

```
$report = $client->query()
    ->balanceAndTurnover('goods', '2025-01-01', '2025-06-30')
    ->fields([
        'good' => 'good',
        'qtyStart' => 'start',
        'qtyReceipt' => 'receipt',
        'qtyExpense' => 'expense',
        'qtyFinal' => 'final',
    ])
    ->get();
```

### Зріз актуальних значень (ціни)

[](#зріз-актуальних-значень-ціни)

```
$prices = $client->query()
    ->sliceLast('goodsPrices', new \DateTimeImmutable())
    ->fields([
        'good' => 'good',
        'priceType' => 'priceType',
        'price' => 'price',
        'currency' => 'currency',
    ])
    ->where('priceType', Operator::Equal, '1101300000001002')
    ->get();
```

### Мультимовні поля

[](#мультимовні-поля)

При `multilang()` API змінює формат імен полів: `name` → `name__uk`, `name__ru`.

```
$result = $client->query('catalogs.firms')
    ->fields(['id' => 'id', 'name' => 'name'])
    ->multilang()
    ->get();

// $result->first() = ['id' => '...', 'name__uk' => '...', 'name__ru' => '...']
```

### Швидкий режим (без збірки посилань)

[](#швидкий-режим-без-збірки-посилань)

```
$result = $client->query('catalogs.goods')
    ->fields(['id' => 'id', 'code' => 'code', 'name' => 'name'])
    ->withoutLinks()
    ->get();

// ResultSet містить columns
$result->getColumns(); // ['id', 'code', 'name']
```

Створення замовлення покупця
----------------------------

[](#створення-замовлення-покупця)

```
$orderId = $client->createOrder()
    ->firm('1100400000001001')
    ->person('1100100000001001')
    ->remarkFromPerson('Зателефонуйте, будь ласка')
    ->addProduct('1100300000022632', qty: 1)
    ->addProduct('1100300000022876', qty: 2, price: 150.00)
    ->addProductByArticle('ART-001', qty: 3)
    ->withAutoPlacement()
    ->send();
```

Довільні спецметоди (call)
--------------------------

[](#довільні-спецметоди-call)

```
$response = $client->call('saleOrderCreate', [
    'header' => ['firm' => '1100400000001001', 'person' => '1100100000001001'],
    'goods' => [['good' => '1100300000022632', 'qty' => 1]],
]);
```

Метадані
--------

[](#метадані)

```
// Список усіх об'єктів системи
$objects = $client->listMetadata('uk');

// Опис реквізитів об'єкта
$meta = $client->getMetadata(objectName: 'catalogs.goods');
// або за ID
$meta = $client->getMetadata(objectId: '1000000000001258');
```

Партнерська статистика
----------------------

[](#партнерська-статистика)

> **Увага:** метод `getStatistic` реалізовано за документацією, але не верифіковано реальним API (потребує налаштованої партнерської інтеграції).

```
$stats = $client->getStatistic(
    partnerApiKey: 'ваш_партнерський_ключ',
    dateFrom: new \DateTimeImmutable('2025-01-01'),
    dateTo: new \DateTimeImmutable('2025-12-31'),
);
```

Webhook
-------

[](#webhook)

```
use Maguto\Dilovod\Webhook\WebhookParser;

// У вашому контролері
$packetJson = $_GET['packet'] ?? '';

if (!WebhookParser::isValidSource($_SERVER['REMOTE_ADDR'])) {
    http_response_code(403);
    exit;
}

$event = WebhookParser::parse($packetJson);

echo $event->action;     // 'objectChanged'
echo $event->objectName; // 'documents.saleOrder'
echo $event->id;         // '1109100000001038'
```

Value Objects
-------------

[](#value-objects)

```
use Maguto\Dilovod\ValueObject\ObjectId;
use Maguto\Dilovod\ValueObject\MultiLangString;

// ObjectId — 16-значний ID з типом та номером
$id = new ObjectId('1100300000022632');
$id->getPrefix(); // '11003' (тип — товари)
$id->getNumber(); // '00000022632'
$id->isSameType(new ObjectId('1100300000022876')); // true

// MultiLangString — мультимовний рядок
$name = MultiLangString::fromArray(['uk' => 'Товар', 'ru' => 'Товар']);
echo $name->get('uk');   // 'Товар'
echo $name;              // 'Товар' (uk за замовчуванням)
```

Обробка помилок
---------------

[](#обробка-помилок)

```
use Maguto\Dilovod\Exception\ApiException;
use Maguto\Dilovod\Exception\TransportException;
use Maguto\Dilovod\Exception\DilovodException;

try {
    $client->getObject('0000000000000000');
} catch (ApiException $e) {
    // Помилка від Dilovod API
    echo $e->getMessage();        // 'object with id ... not found'
    $e->getRawResponse();         // повний масив відповіді
} catch (TransportException $e) {
    // Мережева помилка або HTTP 5xx
    echo $e->getHttpStatusCode(); // 502, null для мережевих
} catch (DilovodException $e) {
    // Будь-яка помилка SDK
}
```

Розробка
--------

[](#розробка)

```
# Встановити залежності
composer install

# Запустити всі перевірки (стиль + аналіз + тести)
composer check

# Unit-тести
composer test:unit

# Інтеграційні тести (потребують API-ключ)
cp .env.example .env    # вкажіть DILOVOD_API_KEY
composer test:integration

# Виправити стиль коду
composer cs:fix

# Статичний аналіз (PHPStan level max)
composer analyse
```

Вимоги
------

[](#вимоги)

- PHP 8.2+
- Будь-яка реалізація PSR-18 HTTP client
- Будь-яка реалізація PSR-17 HTTP factories

Посилання
---------

[](#посилання)

- [Офіційна документація Dilovod API](https://help.dilovod.ua/uk/article/api-dilovod-1gwt3m0/)
- [FAQ по API](https://help.dilovod.ua/uk/article/api-dilovod-zapitannya-i-vidpovidi-lkkiux/)
- [Telegram-канал API](https://t.me/dilovodapi)

Ліцензія
--------

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

MIT — дивіться [LICENSE](LICENSE).

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance75

Regular maintenance activity

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 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.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

137d ago

Major Versions

1.x-dev → 2.0.02026-04-03

PHP version history (2 changes)1.0.0PHP ^7.4 || ^8.0

2.0.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/f3ac880e24521ea863a8d05f6c6d46e16148cfadd76971b8e645ea5ef53356ee?d=identicon)[magutodev](/maintainers/magutodev)

---

Top Contributors

[![maguto-tech](https://avatars.githubusercontent.com/u/108077214?v=4)](https://github.com/maguto-tech "maguto-tech (1 commits)")

---

Tags

apisdke-commerceAccountingukraineopencartdilovod

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/maguto-dilovod-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/maguto-dilovod-sdk/health.svg)](https://phpackages.com/packages/maguto-dilovod-sdk)
```

###  Alternatives

[tempest/framework

The PHP framework that gets out of your way.

2.3k37.6k21](/packages/tempest-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

86337.5k](/packages/flow-php-flow)[cakephp/cakephp

The CakePHP framework

8.9k20.0M1.9k](/packages/cakephp-cakephp)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

36826.2k2](/packages/telnyx-telnyx-php)[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[getbrevo/brevo-php

Official PHP SDK for the Brevo API.

1004.1M59](/packages/getbrevo-brevo-php)

PHPackages © 2026

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