Download the PHP package ux2dev/microinvest without Composer

Microinvest PHP SDK

Warning: This is a developer testing version of the library -- use at your own risk.

The micro.bg backend is written against the Api_v1.4 PDF and has not yet been exercised against a live account.

Framework-agnostic PHP SDK for Microinvest, covering both of its APIs:

The two share a domain model (they sit on the same schema) but nothing on the wire, so each has its own config, transport and resources. What both support - partners, items, groups, VAT groups, payment types, objects, quantities - is expressed as Ux2Dev\Microinvest\Contracts\Client, so nomenclature code can be written once and pointed at either.

Works with plain PHP or Laravel.

Requirements

• PHP 8.3 or higher
• JSON extension
• A PSR-18 HTTP client and PSR-17 request/stream factories (Guzzle provides both)

Installation

Enabling the API

1. Open port 8700 in the firewall of the machine running Microinvest Utility Center.
2. In Microinvest Utility Center pick Microinvest API from the module list.
3. (Optional) Generate an API key in the settings and pass it as apiKey. If you skip this, the API is reachable anonymously.

Quick Start

Plain PHP

Plain PHP, micro.bg

Register the application first: sign in as owner, Администриране → Връзка с ел. магазини → Регистриране на ново приложение, type Външни приложения, status active. The Настройки link on that row reveals the two credentials and lets you pick the user whose permissions the API calls run as.

Laravel

Configuration

WarehouseProConfig

Every Warehouse Pro client takes a WarehouseProConfig. It is a final readonly value object: all inputs are validated at construction, the API key is private and redacted from var_dump(), and serialization is blocked.

Each Microinvest install is its own on-premise host, so baseUrl is per-machine. The API key (when set) is sent as the X-API-Key header on every request.

Laravel configuration

Publish the config file:

This creates config/microinvest.php:

Each connection declares a driver: warehouse_pro or micro_bg. MicroinvestManager::client() returns Contracts\Client; type-hint the concrete client when you need a backend's extras.

Multiple connections

Add more entries under connections and switch at runtime:

connection() returns an immutable clone; the default connection stays untouched.

How the SDK is organised

Resource methods come in three shapes:

• List operations ($microinvest->items()->list(...)) take named argument filters and return a ResultList<T> of typed result DTOs.
• Single-record operations ($microinvest->items()->get(2518)) return the typed result DTO directly.
• Mutations ($microinvest->items()->create(...)) take an input DTO (or a list of them for operations) and return the created record(s).

Resources

Filtering & pagination

Collections accept exact-value filters as named arguments. A * in a string value triggers a LIKE search (e.g. name: 'Cola*'). Paging uses page / pageSize arguments (default page size 500); the response's X-CurrentPage / X-TotalPages headers are surfaced on the returned list.

Every list() method also takes a trailing filters: array as an escape hatch for any wire field the named arguments don't cover (the Microinvest API can filter "quite all collections by the exact value name"). Keys are raw snake_case wire names, and they override a colliding named argument:

Response paging is surfaced on the returned list:

Iterating everything

partners() and items() implement Ux2Dev\Microinvest\Contracts\PartnerRepository / ItemRepository, whose each() walks the whole nomenclature one page at a time:

It is a generator - rows are fetched lazily, so memory stays flat regardless of how many pages the server reports.

Ux2Dev\Microinvest\Contracts\Client is the interface every Microinvest backend satisfies. Type-hint it when your code only needs the nomenclature; type-hint a concrete client when you need that backend's extras.

Which backend supports what

Anything in a - cell simply does not exist on that client, so reaching for it is a TypeError at the call site rather than a runtime surprise.

Operations are the one place the two backends model the same thing differently, which is why they are absent from the contract: Warehouse Pro returns one flat OperationResult per item line, while micro.bg returns an OperationDocumentResult header carrying OperationLineResult children. Code that pushes sales has to pick a backend.

Idempotent writes on micro.bg

micro.bg lets an integration stamp its own id on an operation and then work by that id, which makes re-running a sync safe:

Exceptions

All SDK exceptions extend Ux2Dev\Microinvest\Exception\MicroinvestException:

Testing

The suite mocks a PSR-18 client to exercise every resource method end-to-end.

License

MIT