Ruby wrapper for the Lob.com API. This gem gives you an ActiveRecord-style syntax to use the Lob.com API.
Supports Ruby 1.9.3 and greater.
Add this line to your application's Gemfile
:
gem 'lob'
And then execute:
$ bundle
Or install it yourself as:
$ gem install lob
The library uses an ActiveRecord-style interface. You'll feel right at home. You'll need a Lob.com API key. It's free and you can get yours here.
For optional parameters and other details, refer the docs here - https://lob.com/docs
When using zip codes with zero-prefixes, always quote them. For example when specifying 02125
, pass it as a string "02125"
, instead of an integer.
The Ruby interpreter assumes it's not of base-10 and tries to convert it to base-10 number. So that might result in an entirely different zip-code than intended.
# To initialize a Lob object
@lob = Lob(api_key: "your-api-key")
# Alternatively, to set the API key for all calls in the future
Lob.api_key = "you-api-key"
@lob = Lob() # don't forget the paranthesis!
Lob.configure do |config|
config.api_key = "your-api-key" # get your own at http://lob.com :)
config.api_version = "v1" # default version
config.protocol = "https" # default protocol
config.api_host = "api.lob.com" # ofcourse it's Lob
end
# name, address, city, state, country and zip are required parameters
@lob.addresses.create(
name: "John Doe",
address_line1: "104, Printing Boulevard",
city: "Boston",
state: "MA",
country: "US"
zip: 12345
)
# You can also pass address_line2
@lob.addresses.create(
name: "John Doe",
email: "test@test.com", # see you can also pass other optional parameters?
address_line1: "104, Printing Boulevard",
address_line2: "Sunset Town",
city: "Boston",
state: "MA",
country: "US"
zip: 12345
)
# returns an array of addresses
@lob.addresses.list
#you can also pass count and offset
@lob.addresses.list(count: 10, offset: 3)
# returns the address with the corresponding ID
@lob.addresses.find("some-address-id")
# deletes the address with the corresponding ID
@lob.addresses.destroy("some-address-id")
# verifies and returns an address with more details
@lob.addresses.verify(
address_line1: "220 WILLIAM T MORRISSEY BLVD",
city: "Boston",
state: "MA",
zip: "02125"
)
# name, to-address and object are the arguments
# to-address can be specified as an address-id
@lob.jobs.create("New Cool Posters", "from-address-id", "to-address-id", "object-id")
# to-address can also be specified as address params to create new address
@lob.jobs.create(
"New Cool Posters",
{name: "FromAddress", address_line1: "120, 6th Ave", city: "Boston", country: "USA", zip: 12345},
{name: "ToAddress", address_line1: "120, 6th Ave", city: "Boston", country: "USA", zip: 12345},
"object-id"
)
# You can also pass new object params for the object
# and other options like packaging_id an setting_id
@lob.jobs.create(
"New Cool Posters",
"from-address-id",
"to-address-id",
"object-id",
{
name: "Your fantistic object",
file: "http://test.com/file.pdf",
setting_id: "some-setting-id"
}
)
# Or add a job with multiple objects
@lob.jobs.create(
"New Cool Posters",
"from-address-id",
{name: "ToAddress", address_line1: "120, 6th Ave", city: "Boston", country: "USA", zip: 12345},
["object-id", "another-object-id"]
)
# returns an array of jobs
@lob.jobs.list
#you can also pass count and offset
@lob.jobs.list(count: 10, offset: 3)
# returns the job with the corresponding ID
@lob.jobs.find("some-job-id")
# You can create by passing the name, file url and setting ID
@lob.objects.create(
"Your fantistic object",
"http://test.com/file.pdf",
"some-setting-id"
)
# You can also pass the quantity as an option
# Or pass a file for upload instead of a url
@lob.objects.create(
"Your fantistic object",
File.new("/path/to/file.pdf"),
"some-setting-id",
quantity: 12
)
# returns an array of objects
@lob.objects.list
#you can also pass count and offset
@lob.objects.list(count: 10, offset: 3)
# returns the object with the corresponding ID
@lob.objects.find("some-object-id")
# deletes the object with the corresponding ID
@lob.objects.destroy("some-object-id")
# returns a list of packagings
@lob.packagings.list
You'll have to specify either the message
option or the back
option.
# accepts the name, address-id to send to and options
@lob.postcards.create(
"John Joe",
"to-address-id",
message: front: File.read("/path/to/file.pdf")
)
# create using address params, front, back and from address
@lob.postcards.create(
"John Joe",
{name: "ToAddress", address_line1: "120, 6th Ave", city: "Boston", country: "USA", zip: 12345},
message: "Hey buddy. Waiting to hear your stories",
front: "http://test.com/file.pdf",
back: File.read("/path/to/file.pdf"),
from: {name: "FromAddress", address_line1: "120, 6th Ave", city: "Boston", country: "USA", zip: 12345},
)
@lob.postcards.list
#you can also pass count and offset
@lob.postcards.list(count: 10, offset: 3)
@lob.postcards.find "post-card-id"
# returns a list of services
@lob.services.list
# returns a list of accounts
@lob.bank_accounts.list
bank_address = {name: "ToAddress", address_line1: "120, 6th Ave", city: "Boston", country: "USA", zip: 12345}
account_address = {name: "ToAddress", address_line1: "120, 6th Ave", city: "Boston", country: "USA", zip: 12345}
# Pass address params or address IDs
# The 5th argument is the options argument and is optional
@lob.bank_accounts.create("routing_number", bank_address, "account_number", account_address)
@lob.bank_accounts.find "bank-account-id"
# Transfer $5000 to a bank account.
@lob.checks.create("bank-account-id", "to-address-ID", 5000)
# For the "to" address, you can pass params or an address ID
# You can also specify an optional 4th argument, with other options.
@lob.checks.list
@lob.checks.find("check-id")
# returns a list of countries
@lob.countries.list
Make sure you have Ruby 2.0 installed. Copy and paste the following commands in your projects directory.
git clone https://github.com/lob/lob-ruby.git
cd lob
bundle install
You are powered up and ready to roll ~!
To run the tests, download the required sample files by running the following command:
bundle exec rake dev:setup
Tests are written using MiniTest, a testing library that comes with Ruby stdlib. The remote responses are tested using vcr.
You'll need to pass in your Lob.com API as the environment variable LOB_API_KEY
, to run the tests. Be sure to use your Test API key, and not the Live one.
Here's how you can run the tests:
LOB_API_KEY=your_test_api_key bundle exec rake test
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Make sure the tests pass and add tests if required
- Create new Pull Request
Copyright © 2013 Lob.com
Released under the MIT License, which can be found in the repository in LICENSE.txt
.