bizowie-api (Ruby)

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

• Zero runtime dependencies (only Ruby stdlib: net/http, json)
• Supports both the v1 and v2 API endpoints

Requirements

• Ruby 2.7 or newer

Install

Add to your Gemfile:

gem 'bizowie-api'

Or install directly:

gem install bizowie-api

Quick start

require 'bizowie/api'

bz = Bizowie::API.new(
  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: 'hello from Ruby')

if res.success == 1
  puts "ok: #{res.data.inspect}"
else
  warn "failed: #{res.data.inspect}"
end

API

Bizowie::API.new(**options)

Creates a client instance. Raises ArgumentError if site, api_key, or secret_key is missing.

Option	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	Boolean	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	Boolean	no	Log the raw HTTP body to stderr when the response can't be parsed as JSON.

client.call(method, params = nil) → Bizowie::API::Response

Makes an API call.

• method — path to the API method (everything after /bz/api/ for v1 or /bz/apiv2/call/ for v2). Raises if empty.
• params — Hash 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::API::Response

Method	Returns	Description
success	Integer	1 on success, 0 otherwise. Pulled from the response body's success field.
data	Hash	Decoded JSON response (with success removed). On a non-JSON response this is { 'unprocessed' => 1 }.

Error handling

call does not raise on HTTP errors — application-level failures are surfaced via success: 0 and whatever the server returned in data. It does raise on network-level failures (DNS, connection refused, TLS errors), since those bubble up from Net::HTTP. Rescue if you want to handle those distinctly:

begin
  res = bz.call('some/method', foo: 'bar')
  warn 'application-level failure' unless res.success == 1
rescue StandardError => e
  warn "network/TLS failure: #{e.message}"
end

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 verification

Unlike the Perl module, this client does not disable TLS verification. If you need to talk to a host with a self-signed certificate (e.g., a dev instance), the cleanest approach is to install the cert into your trust store rather than to disable verification.

License

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