VertexClient
The Vertex Client Ruby Gem provides an interface to integrate with Vertex SMB which is also known as Vertex Cloud Indirect Tax.
Usage
Quotation
response = VertexClient.quotation(
# The top level transaction date for all line items.
date: "2018-11-15",
# Optional delivery term to specify correct pricing all line items.
delivery_term: "DAP",
# The top level customer for all line items.
customer: {
code: "inky@customink.com",
address_1: "11 Wall Street",
address_2: "#300",
city: "New York",
state: "NY",
postal_code: "10005",
# Optional tax_exempt status for customer
is_tax_exempt: true,
# Optional tax_area_id for customer location
tax_area_id: "330612010"
},
# The top level seller for all line items.
seller: {
company: "CustomInk",
},
line_items: [
{
# Internal product ID or code
product_code: "4600",
# Mapped product class, or "commodity code", in Vertex Cloud
product_class: "123456",
quantity: 7,
# Total price of this line item
price: "35.50"
},
{
product_code: "5200",
product_class: "123456",
quantity: 4,
price: "25.40",
# Optional transaction date override for a line item.
date: "2018-11-14",
# Optional seller override for a line item.
seller: {
company: "CustomInkStores"
},
# Optional customer override for a line item.
customer: {
code: "prez@customink.com",
address_1: "1600 Pennsylvania Ave NW",
city: "Washington",
state: "DC",
postal_code: "20500"
}
},
{
product_code: "5400",
product_class: "123456",
quantity: 2,
price: "35.40",
# Optional transaction date override for a line item.
date: "2018-11-14",
# Optional seller override for a line item.
seller: {
company: "CustomInkStores",
# Optional physical origin of a line item
physical_origin: {
address_1: "Prujezdna 320/62",
address_2: "",
city: "Praha",
state: "",
postal_code: "100 00",
country: "CZ"
}
}
}
]
)
response.total_tax #=> Total tax amount
response.total #=> Total price plus total tax
response.subtotal #=> Total price before taxLocation specific data (required for :customer and specified :physical_origin of :seller in :line_items)
You are required to specify a state or a country. The client will raise an error if none is specified.
At the moment specifying state automatically implies country is US. For US locations postal_code is also required.
US address example
customer: {
...
state: "NY",
postal_code: "10005",
country: "US", # Optional, you don't have to explicitly specify a country once state is set
...
}Non-US address example
state and postal_code are optional attributes for non-US countries
customer: {
...
country: "CZ",
...
}Invoice
Invoice is the same payload as quotation, but with one added identifier.
VertexClient.invoice(
# Vertex's Document Number is a unique referencial identifier for this invoice.
document_number: "unique-identifier-1a43b",
# ... All of the of the payload from quotation here ...
)Distribute Tax
Distribute Tax is the same payload as Invoice, but you pass total_tax on each line item. The product_code and quantity are optional.
VertexClient.distribute_tax(
# ...
line_items: [
{
price: "100.00",
total_tax: "6.00",
}
]
)Tax Area
Look up the internal Vertex location identifier for a given address. Including tax_area_id as part of the customer information in calls to invoice and quotation should improve performance, especially in situations where there are many destination addresses.
response = VertexClient.tax_area(
address_1: "11 Wall Street",
address_2: "#300",
city: "New York",
state: "NY",
postal_code: "10005"
)
response.tax_area_id # => '330612010'Adjustment Allocator
Allocates a given monetary adjustment, such as a service charge or a discount, across a given array of weights, such as line items. The adjustment parameter must be passed in as a positive or negative numeric dollar amount, such as -0.56, 7.00 or 12.34, and the weights parameter must be passed in as an array of non-negative numeric values, such as [1.23, 4.56, 7.89] or [1, 2, 3, 4], which can represent prices or ratios.
VertexClient::Utils::AdjustmentAllocator.new(1234.56, [310.00, 350.00, 200.00, 140.00]).allocate
#=> [#<BigDecimal:7fa6bba053c0,'0.38271E3',18(36)>,
#<BigDecimal:7fa6bba0fcd0,'0.4321E3',18(36)>,
#<BigDecimal:7fa6bba0dfc0,'0.24691E3',18(36)>,
#<BigDecimal:7fa6bba17b88,'0.17284E3',18(36)>]Installation
Add this line to your application's Gemfile:
gem 'vertex_client'And then execute:
$ bundle
Or install it yourself as:
$ gem install vertex_client
Configuration
Configure the client's connection to Vertex using environment variables or an initializer.
Environment Variables
The following environment variables are used to configure the client.
VERTEX_TRUSTED_ID=your-trusted-id
VERTEX_SOAP_API=https://connect.vertexsmb.com/vertex-ws/services/
Initializer
If you are using Rails, take advantage of the included generator:
$ bundle exec rails g vertex_client:install
Otherwise reference our initializer template
Development
This project follows Github's Scripts to rule them all conventions. After cloning the app, run the following:
bin/bootstrap
bin/setup
bin/test
After pulling down changes, run the following:
bin/update
After checking out the repo, run bin/setup to install dependencies. Then, run bin/test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/customink/vertex_client. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the VertexClient project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.