Fakturoid
The Fakturoid gem is ruby library for API communication with web based invoicing service www.fakturoid.cz. Fakturoid API documentation.
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 = '[email protected]'
config.api_key = 'fasdff823fdasWRFKW843ladfjklasdf834'
config.account = 'applecorp' # former subdomain (first part of URL)
config.user_agent = 'Name of your app ([email protected])'
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):
= {
email: '[email protected]',
email_copy: '[email protected]',
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.(181, )
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 descriptionresponse_code
- http code of error (only number)response_body
- response body parsed in the hash
Error class | Response code | Description |
---|---|---|
ContentTypeError | 415 Unsupported Media Type | Wrong content type |
UserAgentError | 400 Bad Request | Missing `user_agent` configuration |
PaginationError | 400 Bad Request | Page with given number does not exist |
AuthenticationError | 401 Unauthorized | Wrong authentication `email` or `api_key` configuration |
BlockedAccountError | 402 Payment Required | Fakturoid account is blocked |
RateLimitError | 429 Too Many Requests | Too many request sent during last 5 minutes |
ReadOnlySiteError | 503 Service Unavailable | Fakturoid is read only |
RecordNotFoundError | 404 Not Found | Document with given ID does not exists or current account has read only permission and trying to edit something |
InvalidRecordError | 422 Unprocessable Entity | Invalid data sent to server |
DestroySubjectError | 403 Forbidden | Subject has invoices or expenses and cannot be deleted |
SubjectLimitError | 403 Forbidden | Subject quota reached for adding more subjects upgrade to higher plan |
GeneratorLimitError | 403 Forbidden | Generator quota reached for adding more recurring generators upgrade to higher plan |
UnsupportedFeatureError | 403 Forbidden | Feature is not supported in your plan to use this feature upgrade to higher plan |
ClientError | 4XX | Server returns response code which is not specified above |
ServerError | 5XX | Server returns response code which is not specified above |
Thanks
Development was supported by eBallance Creative s.r.o.