buezli-api

The official schema-driven Ruby client for the read-only Buezli API. Buezli is straightforward invoicing, time tracking, and project management for small service teams. Learn more at buezli.app.

The gem builds its methods from a bundled, date-versioned API schema. It supports records, expansions, delta polling, pagination, PDFs, and receipts.

Install

gem "buezli-api"

buezli-api requires Ruby 3.2 or newer.

Quick start

require "buezli/api"

client = Buezli::Api::Client.new(
  access_token: ENV.fetch("BUEZLI_API_TOKEN")
)

invoices = client.retrieve_invoices(limit: 50)
invoice = client.retrieve_invoice(123, expand: ["client"])

invoice.id
invoice.issue_date       # Date
invoice.updated_at       # Time
invoice.total            # { "cents" => 10810, "currency" => "CHF" }
invoice.client.name
invoice.line_items.first.description

The default endpoint is https://api.buezli.app, and the newest bundled schema is selected automatically. Pin an API version when needed:

client = Buezli::Api::Client.new(
  access_token: ENV.fetch("BUEZLI_API_TOKEN"),
  version: "2026-07-14"
)

Schema-declared dates and timestamps become Date and Time. Decimal values remain strings and money remains a cents/currency hash, avoiding precision loss. Unknown record methods raise NoMethodError; declared but absent fields return nil.

Pagination and deltas

Collections are enumerable and retain the original query when paging:

invoices = client.retrieve_invoices(
  updated_since: Time.utc(2026, 7, 14, 10),
  expand: ["client"],
  page: 1,
  limit: 100
)

invoices.each do |invoice|
  invoice.deleted? ? remove_local(invoice.id) : replace_local(invoice.to_h)
end

invoices.pagination
next_page = invoices.next_page
previous_page = next_page&.previous_page

Downloads

pdf = client.retrieve_invoice_pdf(123)
receipt = client.retrieve_expense_receipt(456)

pdf.body
pdf.filename
pdf.content_type
pdf.headers

Save a download when needed:

File.binwrite(pdf.filename, pdf.body)

Schema and errors

Inspect the selected API schema with client.schema, or fetch the schema currently served by Buezli with client.retrieve_schema.

Failed requests raise Buezli::Api::Client::Error, exposing status, code, message, details, response_body, and headers. Access tokens are never included in errors or inspection output.

See the API documentation for available resources, fields, expansions, and authentication.

License

MIT