opero-crm/erli-api

Manual PHP client for the Erli marketplace shop API (OperoCRM).

v0.0.20 2026-05-11 11:42 UTC

Requires

• php: ^8.1
• ext-curl: *
• ext-json: *
• ext-mbstring: *
• guzzlehttp/guzzle: ^7.3
• guzzlehttp/psr7: ^1.7 || ^2.0
• illuminate/support: ^10.0|^11.0|^12.0

MIT

• OperoCRM

• php
• rest
• api
• crm
• laravel
• opero-crm
• erli
• erli-api

README

Manual PHP SDK for the Erli shop API, maintained for OperoCRM. All documented HTTP operations from the public OpenAPI spec are implemented as typed methods; requests are associative arrays matching the JSON schemas, while responses are returned as model objects (see the API reference).

Requirements

• PHP 8.1+
• Extensions: curl, json, mbstring

Install

composer require opero-crm/erli-api

Usage (plain PHP)

Set environment variables (or populate $_ENV before constructing the client). The HTTP layer reads them from BaseApi (see lib/Api/BaseApi.php).

Variable	Purpose	Default
ERLI_API_HOST	API base URL	https://erli.pl/svc/shop-api
ERLI_API_TOKEN	Bearer token	(empty)
ERLI_API_USER_AGENT	User-Agent header	opero-crm/erli-api (PHP)

use OperoCRM\ErliApi\ErliApiClient;

$_ENV['ERLI_API_TOKEN'] = $token;
$_ENV['ERLI_API_HOST'] = 'https://sandbox.erli.dev/svc/shop-api';

$client = new ErliApiClient(
    token: $token, // required if not present in ERLI_API_TOKEN
    userAgent: 'my-app/1.0', // optional
    baseUrl: 'https://sandbox.erli.dev/svc/shop-api', // optional
);

$shop = $client->me();
$hits = $client->products()->search([
    // body must match OpenAPI schema ProductSearch
]);

$firstProductArray = $hits[0]->toArray();

Errors (non-2xx or invalid JSON) throw OperoCRM\ErliApi\ApiException with HTTP code and decoded body when available.

Client accessors

ErliApiClient method	API group	Coverage
me()	Shop	GET /me
shop()	Shop	same via ShopApi::me()
products()	Product	search, batch update, CRUD, discounts
orders()	Order	search, get, update, status
payments()	Payment	payments, operations, payouts
priceLists()	Delivery price lists	CRUD + list + details
shipping()	Shipping	parcels, external parcels, posting points, pickup protocols
dictionary()	Dictionaries	attachments, attributes, categories, delivery, responsible entities
hooks()	Hooks	list, run, save, delete
inbox()	Inbox	unread, search, mark-read
billing()	Billing	shop + company entries/rebates
campaigns()	Campaigns	campaigns summary
commission()	Commission	commission estimate

Use hooks()->getHooks() for GET /hooks. Other hook helpers: runCheckBuyability, runProductsNeedSync, save, delete.

Return types

Client methods now return model instances (or lists of models), for example:

• me() returns Shop
• products()->search() returns list<Product>
• orders()->search() returns list<Order>
• payments()->searchPayments() returns list<Payment>
• inbox()->getUnread() returns list<Message>

If you need raw payloads (for logging, caching, or custom serialization), call toArray() on the returned model.

$payment = $client->payments()->getPayment('payment-id');
$payload = $payment->toArray();

Models (OperoCRM\ErliApi\Model)

DTOs in lib/Model/ are maintained in this repository (not produced from the vendor OpenAPI file, which can disagree with the live API). Use Model::fromArray() / toArray() and BaseModel::mapFromList() where types help; API client methods still accept plain array request payloads.

Notable types include Discount, Message, PriceList, ShippingMethod, Category, Attribute, DeliveryMethod, Vendor, ResponsibleSchema, Attachment, PostingPoint, Parcel, PickupProtocols / PickupProtocol, ExternalParcel, Payment, Payout, Transaction, CheckBuyabilityResult, and aliases such as Product → ProductResponse, Shop → ShopResponse.

BillingApi currently returns JsonObjectResponse because billing payload shapes are not fully normalized yet; use ->toArray() to read raw keys.

Laravel

The service provider and facade are registered via Composer extra.laravel.

You can configure the client in config/services.php:

'erli_api' => [
    'token' => env('ERLI_API_TOKEN'),
    'user_agent' => env('ERLI_API_USER_AGENT'),
    'base_url' => env('ERLI_API_HOST'),
],

token is expected for authenticated calls. user_agent and base_url are optional; if omitted, environment/default values are used.

use OperoCRM\ErliApi\Laravel\Facades\ErliApi;

$rows = ErliApi::orders()->search([
    // OrderSearch
]);

Query parameters

GET /products/{externalId} supports repeated fields query keys. Pass a list of strings:

$client->products()->get('sku-123', ['name', 'stock', 'price']);

Repeated list parameters (e.g. fields) are encoded as repeated keys (fields=name&fields=stock), not http_build_query()’s fields[0]= style. Booleans in query strings use 0 / 1.