Fakturoid ruby gem
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



The Fakturoid gem is ruby library for API communication with web based invoicing service www.fakturoid.cz. Fakturoid API documentation.

Gem Version Circle CI


Add this line to your application's Gemfile:

gem 'fakturoid'

And then run:

$ bundle


Fakturoid gem is configured within config block placed in config/initializers/fakturoid.rb:

Fakturoid.configure do |config|
  config.email = 'yourfakturoid@email.com'
  config.api_key = 'fasdff823fdasWRFKW843ladfjklasdf834'
  config.account = 'applecorp' # former subdomain (first part of URL)
  config.user_agent = 'Name of your app (your@email.com)'


Account resource

To get informations about your account in Fakturoid run following code:

response = Fakturoid::Client::Account.current
response.status_code # returns response http code
response.body # contains hash with returned body

Accessing content of returned body:

response.body['name'] # return name of your company
response.name # alternative way of getting the name of your company

For the list of all returned account fields see the Account API documentation

User resource

For the information about current user use following code:

response = Fakturoid::Client::User.current

For all the users which belongs to current account:

response = Fakturoid::Client::User.all

If you want to get information about one user which belongs to account use:

response = Fakturoid::Client::User.find(user_id)

For the list of all returned user fields see the Users API documentation

Subject resource

To get all subjects run (Subjects are paginated by 20 per page):

response = Fakturoid::Client::Subject.all page: 2

Fulltext search subjects:

response = Fakturoid::Client::Subject.search 'Client name'

To find one subject use:

response = Fakturoid::Client::Subject.find subject_id

You can create new subject with:

response = Fakturoid::Client::Subject.create name: 'New client'

To update subject use following code:

response = Fakturoid::Client::Subject.update subject_id, name: 'Updated client'

Delete subject:

Fakturoid::Client::Subject.delete subject_id

For the list of all subject fields and options see the Subjects API documentation

Invoice resource

To get all invoices run (Invoices are paginated by 20 per page):

response = Fakturoid::Client::Invoice.all page: 2

Fulltext search invoices:

response = Fakturoid::Client::Invoice.search 'Client name'

To find one invoice use:

response = Fakturoid::Client::Invoice.find invoice_id

To download invoice in PDF format you can use following code:

response = Fakturoid::Client::Invoice.download_pdf invoice_id

File.open '/path/to/file.pdf', 'w' do |f|
  f.write response.body

You can create new invoice with:

invoice = {
  subject_id: 123,
  lines: [
      quantity: 5,
      unit_name: 'kg',
      name: 'Sand',
      unit_price: '100',
      vat_rate: 21
response = Fakturoid::Client::Invoice.create invoice

Invoice actions (eg. pay invoice):

response = Fakturoid::Client::Invoice.fire invoice_id, 'pay'

Send invoice with customized message (for more information see the API Documentation):

message = {
  email: 'testemail@testemail.cz',
  email_copy: 'some@emailcopy.cz',
  subject: 'I have an invoice for you',
  message: "Hi,\n\nyou can find invoice no. #no# on the following page #link#\n\nHave a nice day"

response = Fakturoid::Client::Invoice.deliver_message(181, message)
response.status_code # => 201

To update invoice use following code:

response = Fakturoid::Client::Invoice.update invoice_id, number: '2015-0015'

Delete invoice:

response = Fakturoid::Client::Invoice.delete invoice_id

For the list of all invoice fields and options see the Invoices API documentation

Handling error responses

The Fakturoid gem raises exceptions if error response is returned from the servers. All exceptions contains following attributes:

  • message - Error description
  • response_code - http code of error (only number)
  • response_body - response body parsed in the hash
Error classResponse codeDescription
ContentTypeError415 Unsupported Media TypeWrong content type
UserAgentError400 Bad RequestMissing `user_agent` configuration
PaginationError400 Bad RequestPage with given number does not exist
AuthenticationError401 UnauthorizedWrong authentication `email` or `api_key` configuration
BlockedAccountError402 Payment RequiredFakturoid account is blocked
RateLimitError429 Too Many RequestsToo many request sent during last 5 minutes
ReadOnlySiteError503 Service UnavailableFakturoid is read only
RecordNotFoundError404 Not FoundDocument with given ID does not exists or current account has read only permission and trying to edit something
InvalidRecordError422 Unprocessable EntityInvalid data sent to server
DestroySubjectError403 ForbiddenSubject has invoices or expenses and cannot be deleted
SubjectLimitError403 ForbiddenSubject quota reached for adding more subjects upgrade to higher plan
GeneratorLimitError403 ForbiddenGenerator quota reached for adding more recurring generators upgrade to higher plan
UnsupportedFeatureError403 ForbiddenFeature is not supported in your plan to use this feature upgrade to higher plan
ClientError4XXServer returns response code which is not specified above
ServerError5XXServer returns response code which is not specified above


Development was supported by eBallance Creative s.r.o.