Quaderno-ruby is a ruby wrapper for the Quaderno API.
Current version is 3.0.1 → See the changelog here.
To learn more about our API and ecosystem, check developers.quaderno.io.
To install add the following to your Gemfile:
gem 'quaderno', require: 'quaderno-ruby'To configure just add this to your initializers
Quaderno::Base.configure do |config|
config.auth_token = 'my_authenticate_token'
config.url = 'https://my_subdomain.quadernoapp.com/api/'
config.api_version = API_VERSION # Optional, defaults to the API version set in your account
config.user_agent_header = 'my custom user agent' # Optional, will make support for your account more efficient if you are doing OAuth integrations
endQuaderno Sandbox is our public staging environment, a safe space to experiment with our set of APIs and products. As a completely separate environment, it has its own URL https://sandbox-quadernoapp.com and credentials.
It's perfect for your first steps with our tools. Please check https://developers.quaderno.io/developer-tools/sandbox/ to learn about its test data and limitations.
You can get your account subdomain by grabbing it from your account URL or by calling the authorization method with your personal API token.
response = Quaderno::Base.authorization 'my_authenticate_token', environment #=> Quaderno::Base
response.identity # => {"id"=>737000, "name"=>"Walter White", "email"=>"[email protected]", "href"=>"https://my_subdomain.quadernoapp.com/api/"}Note that environment is an optional argument. By passing :sandbox, you will retrieve your credentials for the sandbox environment and not for production.
This will return a hash with the information about your API URL, which includes the account subdomain.
You can ping the service in order to check if it is up with:
response = Quaderno::Base.ping #=> Quaderno::Base
response.status #=> BooleanThis will return status: true if the service is up or status: false if it is not.
response = Quaderno::Base.ping #=> Quaderno::Base
response.rate_limit_info #=> { :reset=> 4, :remaining=> 0 }This will return a hash with information about the seconds until the rate limit reset and your remaining requests per minute (check the API documentation for more information).
You can also check the rate limit for each request by checking the rate_limit_info method on the response:
invoices = Quaderno::Invoice.all #=> Quaderno::Collection
invoices.rate_limit_info #=> {:reset=> 5, :remaning=>6}
invoice = Quaderno::Invoice.find INVOICE_ID #=> Quaderno::Invoice
invoice.rate_limit_info #=> {:reset=>4, :remaining=>5}
result = invoice.deliver #=> Quaderno::Base
result.rate_limit_info #=> {:reset=>3, :remaining=>4}
begin
deleted_invoice = Quaderno::Invoice.delete(ANOTHER_INVOICE_ID) #=> Quaderno::Invoice
rescue Quaderno::Exceptions::InvalidSubdomainOrToken => e
# If the exception is triggered you can check the rate limit on the raised exception
e.rate_limit_info #=> {:reset=>2, :remaining=>3}
end
deleted_invoice.rate_limit_info #=> {:reset=>2, :remaining=>3}
# etc.Quaderno-ruby parses all the json responses in human readable data, so you can access each value just like this:
contact.id
invoice.items
estimates.payments
etc. Quaderno::Contact.all #=> Arraywill return an array with all your contacts. You can also pass query strings using the attribute :q in order to filter the results by contact name. For example:
Quaderno::Contact.all(q: 'John Doe') #=> Array Quaderno::Contact.find(id) #=> Quaderno::Contactwill return the contact with the id passed as parameter.
Quaderno::Contact.retrieve(PAYMENT_GATEWAY_CUSTOMER_ID, PAYMENT_GATEWAY) #=> Quaderno::Contactwill return the contact with the customer id passed as parameter.
Quaderno::Contact.create(params) #=> Quaderno::Contactwill create a contact using the information of the hash passed as parameter and return an instance of Quaderno::Contact with the created contact.
Quaderno::Contact.update(id, params) #=> Quaderno::Contactwill update the specified contact with the data of the hash passed as second parameter.
Quaderno::Contact.delete(id) #=> Quaderno::Contactwill delete the contact with the id passed as parameter. If the deletion was successful, an instance of Quaderno::Contact with the deleted attribute set to true will be returned.
Quaderno::Item.all #=> Arraywill return an array with all your items.
Quaderno::Item.find(id) #=> Quaderno::Itemwill return the items with the id passed as parameter.
Quaderno::Item.create(params) #=> Quaderno::Itemwill create an item using the information of the hash passed as parameter and return an instance of Quaderno::Item with the created contact.
Quaderno::Item.update(id, params) #=> Quaderno::Itemwill update the specified item with the data of the hash passed as second parameter.
Quaderno::Item.delete(id) #=> Quaderno::Itemwill delete the item with the id passed as parameter. If the deletion was successful, an instance of Quaderno::Item with the deleted attribute set to true will be returned.
Quaderno::Transaction.create(params) #=> Quaderno::Transactionwill create a sale or refund transaction using the information of the hash passed as parameter.
Quaderno::Invoice.all #=> Arraywill return an array with all your invoices. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
Quaderno::Invoice.find(id) #=> Quaderno::Invoicewill return the invoice with the id passed as parameter.
Quaderno::Invoice.retrieve(PAYMENT_GATEWAY_TRANSACTION_ID, PAYMENT_GATEWAY) #=> Quaderno::Invoicewill return the invoice with the transaction id passed as parameter.
Quaderno::Invoice.create(params) #=> Quaderno::Invoicewill create an invoice using the information of the hash passed as parameter.
Quaderno::Invoice.update(id, params) #=> Quaderno::Invoicewill update the specified invoice with the data of the hash passed as second parameter.
Quaderno::Invoice.delete(id) #=> Quaderno::Invoicewill delete the invoice with the id passed as parameter. If the deletion was successful, an instance of Quaderno::Item with the deleted attribute set to true will be returned.
In order to add a payment you will need the Invoice instance you want to update.
invoice = Quaderno::Invoice.find(invoice_id)
invoice.add_payment(params) #=> Quaderno::PaymentWhere params is a hash with the payment information. The method will return an instance of Quaderno::Payment wich contains the information of the payment.
In order to remove a payment you will need the Invoice instance you want to update.
invoice = Quaderno::Invoice.find(invoice_id)
invoice.remove_payment(payment_id) #=> BooleanIn order to deliver the invoice to the default recipient you will need the invoice you want to send.
invoice = Quaderno::Invoice.find(invoice_id)
result = invoice.deliver #=> Quaderno::Base
result.success #=> Boolean Quaderno::Credit.all #=> Arraywill return an array with all your credit notes. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
Quaderno::Credit.find(id) #=> Quaderno::Creditwill return the credit with the id passed as parameter.
Quaderno::Credit.retrieve(PAYMENT_GATEWAY_TRANSACTION_ID, PAYMENT_GATEWAY) #=> Quaderno::Creditwill return the credit note with the transaction id passed as parameter.
Quaderno::Credit.create(invoice_id: 42) #=> Quaderno::Creditwill create a credit from the invoice specified in the parameter.
Quaderno::Credit.update(id, params) #=> Quaderno::Creditwill update the specified credit with the data of the hash passed as second parameter.
Quaderno::Credit.delete(id) #=> Quaderno::Creditwill delete the credit with the id passed as parameter. If the deletion was successful, an instance of Quaderno::Credit with the deleted attribute set to true will be returned.
In order to add a payment you will need the Credit instance you want to update.
credit = Quaderno::Credit.find(credit_id)
credit.add_payment(params) #=> Quaderno::PaymentWhere params is a hash with the payment information. The method will return an instance of Quaderno::Payment wich contains the information of the payment.
In order to remove a payment you will need the Credit instance you want to update.
credit = Quaderno::Credit.find(credit_id)
credit.remove_payment(payment_id) #=> Quaderno::PaymentIf the deletion was successful, an instance of Quaderno::Payment with the deleted attribute set to true will be returned.
In order to deliver the credit to the default recipient you will need the credit you want to send.
credit = Quaderno::Credit.find(credit_id)
result = credit.deliver #=> Quaderno::Base
result.success #=> Boolean Quaderno::Estimate.all #=> Arraywill return an array with all your estimates.
Quaderno::Estimate.find(id) #=> Quaderno::Estimatewill return the estimate with the id passed as parameter.
Quaderno::Estimate.create(params) #=> Quaderno::Estimatewill create an estimate using the information of the hash passed as parameter.
Quaderno::Estimate.update(id, params)will update the specified estimate with the data of the hash passed as second parameter.
Quaderno::Estimate.delete(id) #=> Quaderno::Estimatewill delete the estimate with the id passed as parameter. If the deletion was successful, an instance of Quaderno::Contact with the deleted attribute set to true will be returned.
In order to add a payment you will need the estimate you want to update.
estimate = Quaderno::Estimate.find(estimate_id)
estimate.add_payment(params) #=> Quaderno::PaymentWhere params is a hash with the payment information. The method will return an instance of Quaderno::Payment wich contains the information of the payment.
In order to remove a payment you will need the estimate you want to update.
estimate = Quaderno::Estimate.find(estimate_id)
estimate.remove_payment(payment_id) #=> BooleanIn order to deliver the estimate to the default recipient you will need the estimate you want to send.
estimate = Quaderno::Estimate.find(estimate_id)
result = estimate.deliver #=> Quaderno::Base
result.success #=> Boolean Quaderno::Expense.all #=> Arraywill return an array with all your expenses. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date.
Quaderno::Expense.find(id) #=> Quaderno::Expensewill return the expense with the id passed as parameter.
Quaderno::Expense.create(params) #=> Quaderno::Expensewill create an expense using the information of the hash passed as parameter and return an instance of Quaderno::Expense with the created expense.
Quaderno::Expense.update(id, params) #=> Quaderno::Expensewill update the specified expense with the data of the hash passed as second parameter.
Quaderno::Expense.delete(id) #=> Quaderno::Expensewill delete the expense with the id passed as parameter. If the deletion was successful, an instance of Quaderno::Expense with the deleted attribute set to true will be returned.
Quaderno::Recurring.all #=> Arraywill return an array with all your recurring notes. You can also pass query strings using the attribute :q in order to filter the results by contact name, :state to filter by state or :date to filter by date
Quaderno::Recurring.find(id) #=> Quaderno::Recurringwill return the recurring with the id passed as parameter.
Quaderno::Recurring.create(params) #=> Quaderno::Recurringwill create a recurring using the information of the hash passed as parameter.
Quaderno::Recurring.update(id, params) #=> Quaderno::Recurringwill update the specified recurring with the data of the hash passed as second parameter.
Quaderno::Recurring.delete(id) #=> Quaderno::Recurringwill delete the recurring with the id passed as parameter. If the deletion was successful, an instance of Quaderno::Recurring with the deleted attribute set to true will be returned.
Quaderno::Webhook.all #=> Arraywill return an array with all the webhooks you have subscribed.
Quaderno::Webhook.find(id) #=> Quaderno::Webhookwill return the webhook with the id passed as parameter.
Quaderno::Webhook.create(params) #=> Quaderno::Webhookwill create a webhook using the information of the hash passed as parameter and return an instance of Quaderno::Webhook with the created webhook.
Quaderno::Webhook.update(id, params) #=> Quaderno::Webhookwill update the specified webhook with the data of the hash passed as second parameter.
Quaderno::Webhook.delete(id) #=> Quaderno::Webhookwill delete the webhook with the id passed as parameter. If the deletion was successful, an instance of Quaderno::Webhook with the deleted attribute set to true will be returned.
Quaderno::TaxRate.calculate(params) #=> Quaderno::TaxRatewill calculate the taxes applied for a customer based on the data pased as parameters.
Quaderno::TaxJurisdiction.all #=> Arraywill return an array with all the tax jurisdictions supported in Quaderno.
Quaderno::TaxJurisdiction.find(id) #=> Quaderno::TaxJurisdictionwill return the tax jurisdiction with the id passed as parameter.
Quaderno::TaxCode.all #=> Arraywill return an array with all the tax codes supported in Quaderno.
Quaderno::TaxCode.find(id) #=> Quaderno::TaxCodewill return the tax code with the id passed as parameter.
Quaderno::TaxId.all #=> Arraywill return an array with all the tax ids in the target account.
Quaderno::TaxId.find(id) #=> Quaderno::TaxIdwill return the tax id with the id passed as parameter.
Quaderno::TaxId.create(params) #=> Quaderno::TaxIdwill create a tax id using the information of the hash passed as parameter and return an instance of Quaderno::TaxId with the created tax id.
Quaderno::TaxId.update(id, params) #=> Quaderno::TaxIdwill update the specified tax id with the data of the hash passed as second parameter.
Quaderno::TaxId.delete(id) #=> Quaderno::TaxIdwill delete the tax id with the id passed as parameter. If the deletion was successful, an instance of Quaderno::TaxId with the deleted attribute set to true will be returned.
country = 'IE'
tax_id = 'IE6388047V'
result = Quaderno::TaxId.validate(country, tax_id) #=> Quaderno::TaxId
result.valid #=> Boolean or nilwill validate the tax ID or business number for the specified country.
Quaderno::Evidence.create(params) #=> Quaderno::Evidencewill create an evidence based on the data pased as parameters.
Quaderno::CheckoutSession.all #=> Arraywill return an array with all the checkout sessions in your account.
Quaderno::CheckoutSession.find(id) #=> Quaderno::CheckoutSessionwill return the checkout session with the id passed as parameter.
Quaderno::CheckoutSession.create(params) #=> Quaderno::CheckoutSessionwill create a checkout session using the information of the hash passed as parameter and return an instance of Quaderno::CheckoutSession with the created checout session.
Quaderno::CheckoutSession.update(id, params) #=> Quaderno::CheckoutSessionwill update the specified checkout session with the data of the hash passed as second parameter.
Quaderno::CheckoutSession.delete(id) #=> Quaderno::CheckoutSessionwill delete the checkout session with the id passed as parameter. If the deletion was successful, an instance of Quaderno::CheckoutSession with the deleted attribute set to true will be returned.
Quaderno::ReportRequest.all #=> Arraywill return an array with all your report requests.
Quaderno::ReportRequest.find(id) #=> Quaderno::ReportRequestwill return the report request with the id passed as parameter.
Quaderno::ReportRequest.create(params) #=> Quaderno::ReportRequestwill create a report request using the information of the hash passed as parameter and return an instance of Quaderno::ReportRequest with the created report request.
Quaderno::Account.all #=> Arraywill return an array with all your custom accounts
Quaderno::Account.find(id) #=> Quaderno::Accountwill return the account with the id passed as parameter.
Quaderno::Account.create(params) #=> Quaderno::Accountwill create a custom account using the information of the hash passed as parameter.
Quaderno::Account.update(id, params) #=> Quaderno::Accountwill update the specified custom account with the data of the hash passed as second parameter.
Quaderno::Account.deactivate(id) #=> Quaderno::Accountwill deactivate the custom account with the id passed as parameter.
Quaderno::Account.activate(id) #=> Quaderno::Accountwill activate the custom account with the id passed as parameter.
Quaderno::Address.all(access_token: ACCESS_TOKEN) #=> Arraywill return an array with all the addresses of the target custom account
Quaderno::Address.find(id, access_token: ACCESS_TOKEN) #=> Quaderno::Addresswill return the address with the id passed as parameter.
Quaderno::Address.create(params.merge(access_token: ACCESS_TOKEN)) #=> Quaderno::Addresswill add an address on the target custom account using the information of the hash passed as parameter.
Quaderno::Address.update(id, params.merge(access_token: ACCESS_TOKEN)) #=> Quaderno::Addresswill update the specified address with the data of the hash passed as second parameter.
Quaderno-ruby exceptions raise depending on the type of error:
Quaderno::Exceptions::UnsupportedApiVersion # Raised when the API version set is not supported.
Quaderno::Exceptions::InvalidSubdomainOrToken # Raised when the credentials are wrong, missing or do not match the permission for some object.
Quaderno::Exceptions::InvalidID # Raised when the requested resource by ID does not exist in the account context.
Quaderno::Exceptions::InvalidRequest # Raised when the requested requirements are not fulfilled.
Quaderno::Exceptions::ThrottleLimitExceeded # Raised when the throttle limit is exceeded.
Quaderno::Exceptions::RateLimitExceeded # Raised when the rate limit is exceeded.
Quaderno::Exceptions::HasAssociatedDocuments # Raised when trying to delete a contact with associated documents.
Quaderno::Exceptions::RequiredFieldsEmptyOrInvalid # Raised if the format of the request is right but some validations failed. You can JSON parse the exception message to get which field triggered the exception. For example: '{"errors":{"vat_number":["is not a valid German vat number"]}}'
Quaderno::Exceptions::ServerError # Raised when Quaderno returns an HTTP response code of the 50X family. Try again later or contact support if the issue persistsAll those exceptions inherit from Quaderno::Exceptions::BaseException.
You can inspect a the error response from the API by rescuing the exception and checking response_body:
begin
Quaderno::Invoice.find WRONG_ID
rescue Quaderno::Exceptions::BaseException => e
e.response_body # => {"error"=>"Unauthorized access or document does not exist."}
endWhenever you call the all method on one of the classes, the result will be a Quaderno::Collection. For example:
collection = Quaderno::Contact.all
collection.class #=> Quaderno::Collection
collection.has_more? #=> true
collection.next_page #=> another instance ofThe next_page method is an abstraction for the created_before parameter, which you may also use with the all method.
collection = Quaderno::Contact.all
Quaderno::Contact.all(created_before: collection.last.id)You can also use the limit parameter to determine how many results to retrieve. Its default is 25, and Quaderno will cap the limit at 100.
collection = Quaderno::Contact.all(limit: 50)
collection.length #=> 50If you are managing multiple accounts you may need a thread-safe way to configure the credentials. You can do it by passing the credentials on each request:
Quaderno::Invoice.all(
api_url: 'https://my_subdomain.quadernoapp.com/api/',
auth_token: 'my_authenticate_token'
)
Quaderno::Invoice.find(INVOICE_ID,
api_url: 'https://my_subdomain.quadernoapp.com/api/',
auth_token: 'my_authenticate_token'
)
Quaderno::Invoice.update(INVOICE_ID,
po_number: '12345',
api_url: 'https://my_subdomain.quadernoapp.com/api/',
auth_token: 'my_authenticate_token'
)
invoice = Quaderno::Invoice.find(INVOICE_ID,
api_url: 'https://my_subdomain.quadernoapp.com/api/',
auth_token: 'my_authenticate_token'
)
invoice.add_payment(params) # Credentials are already stored on the Quaderno::Invoice instance from the first request
invoice = Quaderno::Invoice.find(INVOICE_ID,
api_url: 'https://my_subdomain.quadernoapp.com/api/',
auth_token: 'my_authenticate_token'
)
invoice.remove_payment(PAYMENT_ID) # Credentials are already stored on the Quaderno::Invoice instance from the first request
Quaderno::Invoice.delete(INVOICE_ID,
api_url: 'https://my_subdomain.quadernoapp.com/api/',
auth_token: 'my_authenticate_token'
)Remember this is only a ruby wrapper for the Quaderno API. Checkout our OpenAPI documentation!
If you need examples of params objects, head to our tests. For instance, in case you're an online store and want to register your sales and refunds, here you can get examples of parameters to use with this Ruby gem.
(The MIT License)
Copyright © 2013-2023 Quaderno
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.