Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


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

Gem Version Tests Rubocop


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.api_key = "fasdff823fdasWRFKW843ladfjklasdf834"
  config.account = "applecorp" # former subdomain (first part of URL)
  config.user_agent = "Name of your app ("


Account resource

To get information 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 # 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

Number Format resource

For the list of invoice number formats which belong to the current account:

response = Fakturoid::Client::NumberFormat.invoices

For the list of all returned user fields see the Number formats 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 ="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 ="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)"/path/to/file.pdf", "wb") do |f|

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 =, "pay")

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

message = {
  email: "",
  email_copy: "",
  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

InventoryItem resource

To get all inventory items:

response = Fakturoid::Client::InventoryItems.all

To filter inventory items by certain SKU code:

response = Fakturoid::Client::InventoryItems.all(sku: 'SKU1234')

To search inventory items (searches in name, article_number and sku):

response ='Item name')

To get all archived inventory items:

response = Fakturoid::Client::InventoryItems.archived

To get a single inventory item:

response = Fakturoid::Client::InventoryItems.find(inventory_item_id)

To create an inventory item:

inventory_item = {
  name: "Item name",
  sku: "SKU1234",
  track_quantity: true,
  quantity: 100,
  native_purchase_price: 500,
  native_retail_price: 1000
response = Fakturoid::Client::InventoryItems.create(inventory_item)

To update an inventory item:

response = Fakturoid::Client::InventoryItems.update(inventory_item_id, name: "Another name")

To archive an inventory item:

response = Fakturoid::Client::InventoryItems.archive(inventory_item_id)

To unarchive an inventory item:

response = Fakturoid::Client::InventoryItems.unarchive(inventory_item_id)

To delete an inventory item:

response = Fakturoid::Client::InventoryItems.delete(inventory_item_id)

InventoryMove resource

To get get all inventory moves across all inventory items:

response = Fakturoid::Client::InventoryMoves.all

To get inventory moves for a single inventory item:

response = Fakturoid::Client::InventoryMoves.all(inventory_item_id: inventory_item_id)

To get a single inventory move:

response = Fakturoid::Client::InventoryMoves.find(inventory_item_id, inventory_move_id)

To create a stock-in inventory move:

response = Fakturoid::Client::InventoryMoves.create(
  direction: "in",
  quantity_change: 5,
  purchase_price: "249.99",
  purchase_currency: "CZK",
  private_note: "Bought with discount"

To create a stock-out inventory move:

response = Fakturoid::Client::InventoryMoves.create(
  direction: "out",
  quantity_change: "1.5",
  retail_price: 50,
  retail_currency: "EUR",
  native_retail_price: "1250"

To update an inventory move:

inventory_move = {
  private_note: "Text"
  # Plus other fields if necessary
response = Fakturoid::Client::InventoryMoves.update(inventory_item_id, inventory_move_id, inventory_move)

To delete an inventory move:

response = Fakturoid::Client::InventoryMoves.delete(inventory_item_id, inventory_move_id)

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