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(3mo ago)02MITPHPPHP ^8.2CI passing

Since Apr 3Pushed 3mo 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 today

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

36

—

LowBetter than 79% of packages

Maintenance82

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity48

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

92d 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.2k34.4k15](/packages/tempest-framework)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

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

The CakePHP framework

8.9k19.5M1.8k](/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.

35789.4k2](/packages/telnyx-telnyx-php)[openai-php/client

OpenAI PHP is a supercharged PHP API client that allows you to interact with the Open AI API

5.8k28.0M318](/packages/openai-php-client)[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60216.0M85](/packages/mollie-mollie-api-php)

PHPackages © 2026

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