The Pennylane Ruby library provides convenient access to the Pennylane API from applications written in the Ruby language. It includes a pre-defined set of classes for API resources that initialize themselves dynamically from API responses which makes it compatible with a wide range of versions of the Pennylane API. It only works with the buys and sales API.
It was inspired by the Stripe Ruby library.
See the Pennylane API docs.
Install the gem and add to the application's Gemfile by executing:
$ bundle add pennylaneIf bundler is not being used to manage dependencies, install the gem by executing:
# Add to gemfile
gem 'pennylane'For Rails app :
# Create initializers/pennylane.rb
Pennylane.api_key = Rails.application.credentials.dig(:pennylane, :api_key)
# Add credentials to config/credentials.yml.enc
$ EDITOR=vim bin/rails credentials:edit
pennylane:
api_key: 'x0fd....'Ruby 2.3+.
The library needs to be configured with your account's token api which is available in your Pennylane Settings. Set Pennylane.api_key to its value:
require 'pennylane'
Pennylane.api_key = 'x0fd....'
# list customers
Pennylane::Customer.list# filter and paginate customers
Pennylane::Customer.list(filter: [{field: 'name', operator: 'eq', value: 'Apple'}], page: 2)
# Retrieve single customer
Pennylane::Customer.retrieve('38a1f19a-256d-4692-a8fe-0a16403f59ff')
# Update a customer
cus = Pennylane::Customer.retrieve('38a1f19a-256d-4692-a8fe-0a16403f59ff')
cus.update(name: 'Apple Inc')
# Create a customer
Pennylane::Customer.create customer_type: 'company', name: 'Tesla', address: '4 rue du faubourg', postal_code: '75008', city: 'Paris', country_alpha2: 'FR'# Create a customer invoice
Pennylane::CustomerInvoice.create(
create_customer: true,
create_products: true,
invoice: {
date: '2021-01-01',
deadline: '2021-01-31',
customer: {
name: 'Tesla',
customer_type: 'company',
address: '4 rue du faubourg',
postal_code: '75001',
city: 'Paris',
country_alpha2: 'FR',
emails: ['stephane@tesla.com'] },
line_items: [
{
description: 'Consulting',
quantity: 1,
unit_price: 1000
}
]
}
)
# List customer invoices
Pennylane::CustomerInvoice.list
# Retrieve a customer invoice
invoice = Pennylane::CustomerInvoice.retrieve('38a1f19a-256d-4692-a8fe-0a16403f59ff')
# Finalize a customer invoice
invoice.finalize
# Send a customer invoice
invoice.send_by_email
# Mark a customer invoice as paid
invoice.mark_as_paid
# Link an invoice and a credit note
credit_note = Pennylane::CustomerInvoice.retrieve('some-credit-note-id')
Pennylane::CustomerInvoice.links(invoice.quote_group_uuid, credit_note.quote_group_uuid)
# Import a customer invoice
Pennylane::CustomerInvoice.import(file: Util.file(File.expand_path('../fixtures/files/invoice.pdf', __FILE__)),
create_customer: true,
invoice: { date: Date.today, deadline: Date.today >> 1,
customer: {
name: 'Tesla',
customer_type: 'company',
address: '4 rue du faubourg',
postal_code: '75001',
city: 'Paris',
country_alpha2: 'FR',
emails: ['stephane@tesla.com'] },
line_items: [
{
description: 'Consulting',
quantity: 1,
unit_price: 1000
}
]
}
)# Create a supplier
Pennylane::Supplier.create(name: 'Apple Inc', address: '4 rue du faubourg', postal_code: '75008', city: 'Paris', country_alpha2: 'FR')
# Retrieve a supplier
Pennylane::Supplier.retrieve('supplier_id')
# List all suppliers
Pennylane::Supplier.list# Create a product
Pennylane::Product.create(label: 'Macbook Pro', unit: 'piece', price: 2_999, vat_rate: 'FR_200', currency: 'EUR')
# List all products
Pennylane::Product.list
# Retrieve a product
product = Pennylane::Product.retrieve('product_id')
# Update a product
product.update(label: 'Macbook Pro 2021')# Create a category
Pennylane::Category.create(name: 'IT')
# Retrieve a category
Pennylane::Category.retrieve('category_id')
# List all categories
Pennylane::Category.list
# Update a category
category = Pennylane::Category.retrieve('category_id')
category.update(name: 'IT Services')# List all category groups
Pennylane::CategoryGroup.listFor apps that need to use multiple keys during the lifetime of a process. it's also possible to set a per-request key:
require "pennylane"
Pennylane::Customer.list(
{},
{
api_key: 'x1fa....'
}
)
Pennylane::Customer.retrieve(
'38a1f19a-256d-4692-a8fe-0a16403f59ff',
{
api_key: 'x1fa....'
}
)
Both indexer and accessors can be used to retrieve values of resource properties.
customer = Pennylane::Customer.retrieve('customer_id')
puts customer['name']
puts customer.name
# NOTE: To do this the gem will try to guess the key of the resource.
# Otherwise we will have to do Pennylane::Customer.retrieve('customer_id').customer.name
# We rely on `method_missing` to do Pennylane::Customer.retrieve('customer_id').namePennylane provide a test environment. You can use the library with your test token api by setting the Pennylane.api_key to its value.
bundle install
bundle exec rake testResources implemented so far :
Bug reports and pull requests are welcome on GitHub at https://github.com/sbounmy/pennylane. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Pennylane project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.