Skip to content
main
Switch branches/tags
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

Fakturoid

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

Gem Version Circle CI

Installation

Add this line to your application's Gemfile:

gem 'fakturoid'

And then run:

$ bundle

Configuration

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)'
end

Usage

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
end

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

Thanks

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

About

Fakturoid ruby gem

Topics

Resources

License

Packages

No packages published

Languages