README

PHP client for Bizowie's ERP API. Port of the Perl WWW::Bizowie::API module.

Zero runtime dependencies (uses built-in ext-curl and ext-json)
Supports both the v1 and v2 API endpoints
PSR-4 autoloaded, strict types

Requirements

PHP 8.2 or newer
ext-curl and ext-json (both standard)

Install

composer require bizowie/api

Quick start

<?php

require __DIR__ . '/vendor/autoload.php';

use Bizowie\API;

$bz = new API([
    'api_key'    => '02cc7058-cd22-4c8e-ad7c-a8f3f2a64bd0',
    'secret_key' => '58c57abc-1e16-3571-bb35-73876bcef746',
    'site'       => 'mysite.bizowie.com',
    'v2'         => true, // recommended for new integrations
]);

$res = $bz->call('databases/add_note/3/10/123', [
    'comment' => 'I added this comment via the API!',
]);

if ($res->success === 1) {
    echo "ok: " . json_encode($res->data) . PHP_EOL;
} else {
    fwrite(STDERR, "failed: " . json_encode($res->data) . PHP_EOL);
}

API

`new Bizowie\API(array $options)`

Creates a client instance. Throws InvalidArgumentException if site, api_key, or secret_key is missing.

Key	Type	Required	Description
`api_key`	`string`	yes	Your Bizowie API key.
`secret_key`	`string`	yes	Your Bizowie secret key.
`site`	`string`	yes	Hostname of your Bizowie instance (e.g. `mysite.bizowie.com`).
`v2`	`bool`	no	Route calls through the v2 endpoint (`/bz/apiv2/call/`). Recommended.
`api_version`	`string`	no	API version sent with each v2 request. Defaults to `'1.00'`.
`debug`	`bool`	no	Log the raw HTTP body to stderr when the response can't be parsed as JSON.

`$client->call(string $method, ?array $params = null): Bizowie\APIResponse`

Makes an API call.

$method — path to the API method (everything after /bz/api/ for v1 or /bz/apiv2/call/ for v2). Throws RuntimeException if empty.
$params — associative array of parameters; JSON-encoded for you. May be omitted.

In v2 mode, api_key, secret_key, and api_version are injected automatically — don't include them in $params.

`Bizowie\APIResponse`

Readonly value object with two properties:

Property	Type	Description
`$success`	`int`	`1` on success, `0` otherwise. Pulled from the response body's `success` field.
`$data`	`array`	Decoded JSON response (with `success` removed). On a non-JSON response this is `['unprocessed' => 1]`.

Error handling

call() does not throw on HTTP-level errors — application-level failures are surfaced via success === 0 and whatever the server returned in data. Network-level failures (DNS, connection refused, TLS errors, cURL transport errors) throw RuntimeException. try/catch if you want to distinguish them:

try {
    $res = $bz->call('some/method', ['foo' => 'bar']);
    if ($res->success !== 1) {
        // application-level failure
    }
} catch (\RuntimeException $e) {
    // network/TLS/cURL failure
}

If the server returns non-JSON (e.g., an HTML error page), $res->success will be 0 and $res->data will be ['unprocessed' => 1]. Pass 'debug' => true to the constructor to log the raw body to stderr while wiring things up.

v1 vs v2

Aspect	v1 (default)	v2 (`'v2' => true`)
Endpoint	`https://{site}/bz/api/{method}`	`https://{site}/bz/apiv2/call/{method}`
Auth	Sent as separate multipart form fields	Injected into the JSON request body
Body	`multipart/form-data` with a `request` JSON field	Raw JSON body with `Content-Type: form-data`
`api_version`	not sent	sent (defaults to `'1.00'`)

v2 is recommended for new integrations.

TLS

Uses cURL's default TLS verification (on). For self-signed dev hosts, install the cert into your trust store rather than disabling verification.

License

Dual-licensed under the Artistic License 1.0 or the GPL 1.0+, matching the original Perl module.

bizowie / api

Maintainers

Package info

Statistics

Security