avadev / avatax-rest-v2-ruby-sdk

Sales Tax API SDK for Ruby and AvaTax REST

The AvaTax Ruby Gem

A Ruby wrapper for the AvaTax REST V2 APIs

Installation

gem install avatax

Simple Code Example

@client = AvaTax::Client.new({ :logger => true, :log_request_and_response_info => true })

createTransactionModel = {
  "type" => 'SalesInvoice',
  "companyCode" => '12670',
  "date" => '2017-06-05',
  "customerCode" => 'ABC',
  "addresses" => {
    "ShipFrom" => {
      "line1" => "123 Main Street",
      "city" => "Irvine",
      "region" => "CA",
      "country" => "US",
      "postalCode" => "92615"
    },
    "ShipTo" => {
      "line1" => "100 Market Street",
      "city" => "San Francisco",
      "region" => "CA",
      "country" => "US",
      "postalCode" => "94105"
    }
  },
  "lines" => [ { "amount" => 100 }]
}

transaction = @client.create_transaction(createTransactionModel)

If you'd like to see a more complete code example with credentials, check out our example folder.

AvaTax REST and Search APIs

Our developer site documents all the AvaTax REST and other APIs. Subscribe to the RSS feed to stay up to date on the lates news and announcements.

API docs

Blog

The Developer Blog features news and important announcements about the AvaTax Platform and SDKs. You will also find tutorials and best practices to help you build great platform integrations.

Contributing

In the spirit of free software, everyone is encouraged to help improve this project.

Here are some ways you can contribute:

• by using alpha, beta, and prerelease versions
• by reporting bugs
• by suggesting new features
• by writing or editing documentation
• by writing specifications
• by writing code (no patch is too small: fix typos, add comments, clean up inconsistent whitespace)
• by refactoring code
• by closing issues
• by reviewing patches

Submitting an Issue

We use the GitHub issue tracker to track bugs and features. Before submitting a bug report or feature request, check to make sure it hasn't already been submitted. You can indicate support for an existing issue by voting it up. When submitting a bug report, please include a Gist that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. Ideally, a bug report should include a pull request with failing specs.

Submitting a Pull Request

1. Fork the project.
2. Create a topic branch.
3. Implement your feature or bug fix.
4. Add documentation for your feature or bug fix.
5. Run rake doc:yard. If your changes are not 100% documented, go back to step 4.
6. Add specs for your feature or bug fix.
7. Commit and push your changes.
8. Submit a pull request. Please do not include changes to the gemspec, version, or history file. (If you want to create your own version for some reason, please do so in a separate commit.)

Build Status

Copyright

Copyright (c) 2017, Avalara, Inc. All rights reserved. By contributing to AvaTax Ruby Gem, you agree that your contributions will be licensed under its Apache License. See LICENSE for details.

avatax-rest-v2-ruby-sdk's Issues

No tags

Versions should be tagged for release.

https://www.atlassian.com/git/tutorials/inspecting-a-repository/git-tag

Authenticating via account ID and license key

Is it possible to authenticate via Account ID/license key using this SDK?

I don't think adding it as a header to the connection_options argument works because the options are merged instead of deep merged and would overwrite the initial headers here.

I don't think this works:

client = AvaTax::Client.new(connection_options: { :headers => { 'Authorization' => 'Basic MjAwMDI2NjEyODo3MUIwQTg3QjhGNzNFQ0M5' } })

Do you have any suggestions? I definitely could have just misread something.

Thanks!

Estimating And Commiting TaxInvoices?

Hey all!

I am working on an integration for an existing Avalara customer and was wondering how ready this API is and or how far out do you all think a V1 is? What I mainly have to do is calculate tax which looks like is doable through https://github.com/avadev/AvaTax-Calc-REST-Ruby .

I guess my question is, should I start tracking the master here or keep to the old gem? Thank you.

Faraday 1.0.0 compatibility

Hey guys!

Faraday 1.0.0 was released recently and avatax gem does not support it. It's causing conflicts with other gems that depend on faraday too. Do you have any plans to bump faraday version?

Does this even work?

How do I create a transaction? Why did you decide to provide so little documentation?

API docs inaccessible

https://www.rubydoc.info/github/avadev/AvaTax-REST-V2-Ruby-SDK/ is no longer working

Dependency on deprecated `faraday_middleware` gem

The avatax gem declares a dependency on faraday_middleware.

AvaTax-REST-V2-Ruby-SDK/avatax.gemspec

Line 8 in be6248d

s.add_runtime_dependency('faraday_middleware', '>= 0.10')

This faraday_middleware library is deprecated and does not support faraday version 2.0.

⚠️ DEPRECATION WARNING ⚠️

As highlighted in Faraday's UPGRADING guide, faraday_middleware is DEPRECATED, and will not be updated to support Faraday 2.0.
If you rely on faraday_middleware in your project and would like to support Faraday 2.0:

• The json middleware (request and response) are now both bundled with Faraday 🙌
• The instrumentation middleware is bundled with Faraday
• All other middlewares, they'll be re-released as independent gems compatible with both Faraday v1 and v2, look for awesome-faraday

This dependency should be removed to allow consumers of avatax to upgrade faraday to version 2.0.

Should release 20.8.0 be named 20.9.0?

In Github the latest release is named 20.8.0 but in Rubygems it's 20.9.0 and even in version.rb of 20.8.0

AvaTax-REST-V2-Ruby-SDK/lib/avatax/version.rb

Line 2 in 7dc6e38

VERSION = '20.9.0'.freeze unless defined?(::AvaTax::VERSION)

So it's a little bit confusing

Returning a Hashie::Mash response isn't useful

The default response is a Hashie::Mash of the body instead of returning the Faraday::Response. Since the response is lost, you can't check the response code or successfulness of API calls.

for reference

    def request(method, path, options)
      response = connection.send(method) do |request|
        case method
        when :get, :delete
          request.url(URI.encode(path), options)
        when :post, :put
          request.path = URI.encode(path)
          request.headers['Content-Type'] = 'application/json'
          request.body = options.to_json unless options.empty?
        end
      end

      ::Hashie::Mash.new response.body
    end

Getting UnknownNexusError on creating a nexus

I'm getting UnknownNexusError on creating a nexus. Below is the data, i'm sending in body:
{
"country": "CN",
"region": "AB",
"jurisTypeId": "STA",
"jurisdictionTypeId": "State",
"jurisCode": "AB",
"jurisName": "ALBERTA"
}

Latest commits break gem again

commit 636ed9d and on from Sep 8th once again put the gem in a broken state. post() is not being called correctly.

ECommerceToken module not included in latest release

In the 20.9.0 (or 20.8.0) release, the ECommerceToken module was introduced but it was not added to the includes in the client.rb, so it is not usable yet.

Adding a CHANGELOG.md

Hi there!

I really appreciate that you've committed to keeping this SDK open-source.

Could you add and maintain a CHANGELOG file to the root of the repository?

There have been a number of updates recently from commits that contain no details as to what the affects the changes have or why they were made.
As an example: the most recent release (20.7.1) is a patch release with 608 additions and 1,520 deletions and the commit message ("20-7-update update") gives no helpful information. For example, if this is a patch release, is it important for us to update it in our clients immediately?

Thanks!

Using Pessimistic Constraint for ActiveSupport in Gemspec Prevents using Rails 7.0

A recent update to the Avatax rest client has resulted in failures while bundling our application under Rails version 7.0

Your lockfile doesn't include a valid resolution.
You can fix this by regenerating your lockfile or trying to manually editing the bad locked gems to a version that satisfies all dependencies.
The unmet dependencies are:
* activesupport (~> 6.1.7), depended upon avatax-22.11.0, unsatisfied by activesupport-7.0.4

ActiveSupport was pinned pessimistically to version '~> 6.1.7' in #134

I believe that this could be resolved by changing this version constraint to '>= 6.1.7'

Upgrade to rest-client 2.0

The AvaTax gem is currently dependent on version ~>1.7.0 of the rest-client gem. rest-client 2.0 has been available since 2015.

Due to how bundler works, Rails apps that are using gems with other, more updated versions of rest-client, cannot install AvaTax due to dependency conflicts.

rest-client offers this guide on upgrading that says most gems see no changes after upgrade.

Releasing a new version of this gem with the updated gem spec would make this gem more accessible.

Gem is non-functional as-is

Multiple issues with this gem that make it non-functional, as-is:

• Client::Transactions methods add_lines, create_or_adjust_transaction, create_transaction, delete_lines, and refund_transaction try to use post() incorrectly, it doesn't take both a model argument and options.
• Incorrect encoding used with Faraday request.

Other issues:

• Documentation implies that model should be an object, but request() code is written expecting a JSON string. Request should call to_json before setting the body or documentation should be updated.

Ruby 2.7 compatibility

When I run tests which use this gem after upgrading Ruby 2.6.6 -> 2.7.2 I get a lot of these warnings in my output:

/Users/alec/.rbenv/versions/2.7.2/lib/ruby/gems/2.7.0/gems/avatax-20.9.0/lib/avatax/request.rb:31: warning: URI.escape is obsolete

Gem post-install links are incorrect

This gem includes a post-install message that has incorrect links. The developer site should probably be https://developer.avalara.com/api-reference/avatax/rest/v2/, and I could not find the developer blog. Does one exist? I'd be interested especially in the RSS feed.

Post-install message from avatax:
********************************************************************************

AvaTax REST API
------------------------------
Our developer site documents the AvaTax REST API.
(http://developer.avatax.com).
Blog
----------------------------
The Developer Blog is a great place to learn more about the API and AvaTax integrations
Subscribe to the RSS feed be notified of new posts:
(http://developer.avatax.com/blog).

********************************************************************************

Making the Gem Compatible for Jruby

Hi, Can we make the avatax gem compatible with jruby by removing the dependency on oj gem(not supported by jruby) and using gson gem instead which jruby supports.

Can no longer set custom SDK timeout after v20.1.1

Our application has a 15s timeout for web requests, so we previously lowered the read timeout for the Avalara SDK to 8s. Most requests for tax estimation took well under 8s already, and it's preferable for us to handle the timeout, trigger offline tax calculation, and do other request cleanup ourselves versus hitting the global application timeout hander where we have much less control.

Setting custom timeouts for an SDK is a common need and was possible using the connection_options config setting like so:

AvaTax.configure do |config|
  # ...
  config.connection_options = {
    request: {
      open_timeout: 3.seconds,
      timeout: 8.seconds
    }
  }
end

AvaTax-REST-V2-Ruby-SDK/lib/avatax/configuration.rb

Line 16 in eb7c20b

:connection_options,

These options ultimately get used to instantiate the Faraday request object in the AvaTax::Connection and control the request timeout. (Documentation: https://github.com/ankane/the-ultimate-guide-to-ruby-timeouts#faraday)

However, in #72, any custom timeout options are overridden in the request method, to what looks like 1200s. This means that clients can no longer set custom timeouts on that request, though it would seem like the connection_options setting was added to enable that type of use case.

Would it instead be possible to set the timeout in the default connection options and have the same effect?

AvaTax-REST-V2-Ruby-SDK/lib/avatax/configuration.rb

Line 32 in eb7c20b

DEFAULT_CONNECTION_OPTIONS = {}

Don't change default_options for Oj globally

In connection.rb, the Oj global default_options are changed here:

AvaTax-REST-V2-Ruby-SDK/lib/avatax/connection.rb

Line 23 in 7de81a1

Oj.default_options = {

This is problematic because it globally changes the options. This can lead to unexpected consequences since it is affecting behavior of an app outside of just the avatax API scope. For instance, if an app makes a request to avatax API, it changes the default options, and thus any other future times the app uses Oj to serialize JSON, decimals are converted to big decimals.

Could this be changed to not add default_options to Oj globally? One workaround would be to pass in bigdecimal_load: :bigdecimal as an option instead for the load methods.

Create an eCommerce token endpoint

Description

One of the routes in the REST API documentation is CreateECommerceToken. I can't fine this route in the source files of this gem. Is it unimplemented? Is it called something else? Is it undocumented?

Solution

Add or document ECommerceToken calls in lib/avatax/client/

Avatax::Request dropping querystring params on post

FYI, it looks like the options param passed to AvaTax::Request#request is effectively ignored in the case of PUT and POST requests. It might be more specific than that (say, limited to a specific Faraday adapter), but it's reproducible and pretty clear what's going on.

Context:

We noticed this after getting a "Please specify DocumentType parameter" response error despite specifying one in a refund_transaction call:

payload = {
  refundTransactionCode: transaction_code,
  refundDate: Date.today.to_s,
  refundType: 'Full'
}
resp = client.refund_transaction(company_code, transaction_code, payload, {useTaxDateOverride: true, documentType: 'SalesInvoice'})

That call fails unexpectedly with the error:

{
  "error": {
    "code": "DocumentCodeConflict",
    "message": "Please specify DocumentType parameter",
    "target": "HttpRequest",
    "details": [
      {
        "code": "DocumentCodeConflict",
        "number": 303,
        "message": "Please specify DocumentType parameter",
        "description": "This API applies to a single document, but multiple documents exist for company 'XXXXXXXXX' and code '15151515'.  Please provide the DocumentType parameter to distinguish between them.",
        "faultCode": "Client",
        "helpLink": "http://developer.avalara.com/avatax/errors/DocumentCodeConflict",
        "severity": "Error"
      }
    ]
  }
}

Diagnosis:

It looks like that call creates the following Faraday request object:

<struct Faraday::Request
method=:post,
path="/api/v2/companies/XXXXXXX/transactions/15151515/refund?useTaxDateOverride=true&documentType=SalesInvoice",
params={},
headers={"Accept"=>"application/json; charset=utf-8", "User-Agent"=>"AvaTax Ruby Gem 18.10.3", "X-Avalara-Client"=>"XXXXXXXXXXX", "Authorization"=>"Basic XXXXXXXX", "Content-Type"=>"application/json"},
body="{\"refundTransactionCode\":15151515,\"refundDate\":\"2019-02-04\",\"refundType\":\"Full\"}",
options=#<Faraday::RequestOptions (empty)
>

At some point, however, the params hash overwrites the params from the URL before it gets issued. This is reproducible by calling request.to_env(connection):

<Faraday::Env
@method=:post
@body="{\"refundTransactionCode\":15151515,\"refundDate\":\"2019-02-04\",\"refundType\":\"Full\"}"
@url=#<URI::HTTPS https://sandbox-rest.avatax.com/api/v2/companies/XXXXX/transactions/15151515/refund>
@request=#<Faraday::RequestOptions (empty)>
@request_headers={"Accept"=>"application/json; charset=utf-8", "User-Agent"=>"AvaTax Ruby Gem 18.10.3","X-Avalara-Client"=>"XXXXXXXXXXX", "Authorization"=>"Basic XXXXXXXX", "Content-Type"=>"application/json"}
@ssl=#<Faraday::SSLOptions (empty)>
>

(This happens here: https://github.com/lostisland/faraday/blob/e6311bd286de8df1a585b2d5a1eeb150f6d067bf/lib/faraday/connection.rb#L417)

Accordingly, the documentType is not longer anywhere in the request even though it was present in the original options hash.

Solution:

After some investigation, it looks like the request.path= call used in the PUT/POST case...

AvaTax-REST-V2-Ruby-SDK/lib/avatax/request.rb

Line 29 in 51144ef

request.path = ("#{URI.encode(path)}?#{URI.encode_www_form(options)}")

...should probably just be request.url, which correctly sets both request.path and request.params:

https://github.com/lostisland/faraday/blob/f08a985bd1dc380ed2d9839f1103318e2fad5f8b/lib/faraday/request.rb#L48

Note that after updating this locally, the querystring params are contained in the URL as we expect:

<Faraday::Env
@method=:post
@body="{\"refundTransactionCode\":15151515,\"refundDate\":\"2019-02-04\",\"refundType\":\"Full\"}"
@url=#<URI::HTTPS https://sandbox-rest.avatax.com/api/v2/companies/XXXXXXX/transactions/15151515/refund?documentType=SalesInvoice&useTaxDateOverride=true>
@request=#<Faraday::RequestOptions (empty)>
@request_headers={"Accept"=>"application/json; charset=utf-8", "User-Agent"=>"AvaTax Ruby Gem 18.10.3","X-Avalara-Client"=>"XXXXXXXXXXX", "Authorization"=>"Basic XXXXXXXX", "Content-Type"=>"application/json"}
@ssl=#<Faraday::SSLOptions (empty)>
>

I'll open up a PR for this change, though it's pretty fundamental and I'm therefore not confident from the test coverage alone. Would love a sanity check from someone more familiar with the this lib.

Thanks!

Ruby 2.2+ vs BigDecimal

After updating to avatax v17.12 we noticed tests failing that made use of JSON and BigDecimal, like so:

Failure:
Search::ProductSearchTest#test_facets [test/queries/search/product_search_test.rb:77]:
--- expected
+++ actual
@@ -1 +1 @@
-{{:to=>5.0}=>1, {:from=>5.0, :to=>9.99}=>2, {:from=>10.0}=>1}
+{{:to=>0.5e1}=>1, {:from=>0.5e1, :to=>0.999e1}=>2, {:from=>0.1e2}=>1}

(29 more lines...)

It seems to stem from this gem's use of the Oj library and this configuration that's applied when you call the AvaTax::API#connection method. Our solution was to just pull that configuration out, and everything worked as expected. But I was curious as to why it's included in the first place? Is it safe to do some kind of conditional check to make sure we're not in Ruby v2.2+ before applying this config?

Post install message is unnecessary

No other gem I've encountered (except famously httparty) makes use of post-install messages with bundler. People actively working on development that utilised your gem will know where to go for docs, and people who just have it pulled in by a bundle install don't care or need to see details about your blog and docs.

This information just dilutes any meaningful output from bundle with irrelevant noise from your company

AdapterName is not being sent in the header