README

Official PHP client library for the Enlivy API. Follows Semantic Versioning; breaking changes ship only in major versions, with migration notes in UPGRADING.md.

Requirements

PHP 8.3+
ext-curl, ext-json, ext-mbstring

Installation

composer require enlivy/enlivy-php

Quick Start

$client = new \Enlivy\EnlivyClient([
    'api_key' => '1|your_api_token',
    'organization_id' => 'org_xxx',
]);

// List invoices
$invoices = $client->invoices->list(['per_page' => 25]);

foreach ($invoices as $invoice) {
    echo $invoice->id . "\n";
}

// Create
$invoice = $client->invoices->create([
    'organization_receiver_user_id' => 'org_user_xxx',
    'status' => 'draft',
    'currency' => 'EUR',
    'payment_method' => 'bank_transfer',
    'delivery_method' => 'email',
    'line_items' => [
        [
            'name_lang_map' => ['en' => 'Consulting Services'],
            'quantity' => 10,
            'price' => 100.00,
            'type' => 'service',
        ],
    ],
]);

// Retrieve with related data
$invoice = $client->invoices->retrieve('org_inv_xxx', [
    'include' => ['sender_user', 'receiver_user', 'line_items'],
]);

// Update
$client->invoices->update('org_inv_xxx', ['status' => 'pending']);

// Delete
$client->invoices->delete('org_inv_xxx');

Configuration

// Per-client configuration
$client = new \Enlivy\EnlivyClient([
    'api_key' => '1|your_token',
    'organization_id' => 'org_xxx',
    'api_base' => 'https://api.enlivy.com',
    'timeout' => 30,
]);

// Or global configuration
\Enlivy\Enlivy::setApiKey('1|your_token');
\Enlivy\Enlivy::setOrganizationId('org_xxx');
$client = new \Enlivy\EnlivyClient();

Documentation

Detailed guides with code examples for every feature:

Getting Started

Guide	Description
Authentication	API keys, OAuth client credentials, global config
OAuth Server	OAuth 2.0 server for third-party app integrations
Includes (Eager Loading)	Load related resources in a single request
Filters	Search, sort, paginate, and filter list endpoints
Sandboxes	Mirror an organization to test against, with outbound calls blocked

Billing & Invoicing

Guide	Description
Invoices	Create, send, charge, and chase invoices, including scheduled payment reminders
Receipts	Receipt management and tracking
Billing Packages	Reusable billing templates with payment plans
Proposals	Send proposals to prospects and customers
Products	Product and service catalog
Taxes	Tax classes and rates, plus the compliance engine: registrations, the tax-event subledger, and filing periods

CRM & Sales

Guide	Description
Prospects	Sales pipeline, lead tracking, and CRM
Organization Users	Customers, employees, and roles
Blocked Identifiers	Keep an email, domain, or phone number out of your organization
Projects	Projects, team members, and permissions

Support

Guide	Description
Helpdesk	Inboxes, conversations, teammates, inbound mail, and the widget's visitors
Embedded Support	Put an authenticated support chat on your own application

Payroll

Guide	Description
Payroll	Employments, working-time terms and days, month attestation, and typed payslip lines

Contracts

Guide	Description
Contracts	Contract management, e-signatures, templates, and what references a contract

Banking

Guide	Description
Bank Accounts	Bank accounts, transactions, and reconciliation

Content & Reports

Guide	Description
Reports	Dynamic reports with custom schemas
Files	File uploads and attachments
Data Imports	Bulk-load products, users, prospects, and transactions from CSV
Trash	See what soft-deleted records are still held, and empty them early

Integrations

Guide	Description
Event Destinations	Real-time event delivery (webhooks, Slack) and signature verification
Event Trails	Read-only audit history for invoices, receipts, and billing schedules
Customer Portal	Client-facing portal for invoices, contracts, and proposals
Integrations	Stripe, ANAF, and other third-party services
AI Agents	AI-powered automation

Error Handling

use Enlivy\Exception\{
    ValidationException,
    NotFoundException,
    AuthenticationException,
    RateLimitException,
};

try {
    $invoice = $client->invoices->retrieve('org_inv_xxx');
} catch (ValidationException $e) {
    $errors = $e->errors(); // ['field' => ['error message']]
} catch (NotFoundException $e) {
    // 404
} catch (AuthenticationException $e) {
    // 401
} catch (RateLimitException $e) {
    $retryAfter = $e->retryAfter(); // seconds
}

Pagination

$invoices = $client->invoices->list(['page' => 1, 'per_page' => 25]);

echo "Page " . $invoices->getCurrentPage() . " of " . $invoices->getTotalPages();

foreach ($invoices as $invoice) {
    echo $invoice->id;
}

// Or iterate every item across all pages; follow-up pages are fetched lazily
foreach ($invoices->autoPagingIterator() as $invoice) {
    echo $invoice->id;
}

Request Options

Every service method accepts an optional RequestOptions as its last argument:

use Enlivy\Util\RequestOptions;

$invoice = $client->invoices->create($params, new RequestOptions(
    organizationId: 'org_other',      // per-request organization override
    idempotencyKey: 'idem_xyz',       // safe write retries
    locale: 'ro',                     // Accept-Language for localized fields
    timeout: 60,                      // per-request timeout (seconds)
    headers: ['X-Custom' => 'value'], // extra headers
));

Retries

Transient failures (connection errors, 429, 5xx) are retried automatically with exponential backoff — for GET requests, and for writes that carry an Idempotency-Key. Configure via max_retries on the client (default 2, 0 disables) or globally with Enlivy::setMaxNetworkRetries().

Response Metadata

Every object the SDK returns carries the raw response it was hydrated from — status code, headers, and the decoded body — via lastResponse(). Reach for it when an endpoint returns data alongside the resource in meta, such as the inline first-charge result on a newly created billing schedule:

$schedule = $client->billingSchedules->fromBillingPackage([/* … */]);

$response = $schedule->lastResponse();
$response?->statusCode;                 // 201
$response?->getHeader('X-Request-Id');
$response?->json['meta']['charge_result'] ?? null;

API Discovery

The SDK includes a discovery service for programmatic API introspection:

// List all available API resources
$resources = $client->discovery->list();

// Get detailed metadata for a specific resource
$invoiceSpec = $client->discovery->resource('organization_invoices');

Key Concepts

Multilingual Fields

Most text fields use _lang_map for multilingual support:

'name_lang_map' => [
    'en' => 'Consulting Services',
    'ro' => 'Servicii de Consultanta',
],

ID Prefixes

All IDs use prefixes to identify the resource type:

Prefix	Resource
`org_`	Organization
`org_user_`	Organization User
`org_inv_`	Invoice
`org_cont_`	Contract
`org_pros_`	Prospect
`org_proj_`	Project
`org_prod_`	Product
`org_prop_`	Proposal

Testing

./vendor/bin/phpunit              # Unit tests
./vendor/bin/phpstan analyse      # Static analysis

License

MIT License. See LICENSE for details.

enlivy / enlivy-php

Package info

Security

Statistics

README

Requirements

Installation

Quick Start

Configuration

Documentation

Getting Started

Billing & Invoicing

CRM & Sales

Support

Payroll

Contracts

Banking

Content & Reports

Integrations

Error Handling

Pagination

Request Options

Retries

Response Metadata

API Discovery

Key Concepts

Multilingual Fields

ID Prefixes

Testing

License

Support