兔子运送胡萝卜

by Igor Petrov

通过伊戈尔·彼得罗夫(Igor Petrov)

我发现了一个API，可帮助您通过多种快递服务运送电子商务产品。这是使用方法。 (I discovered an API that helps you ship ecommerce products through multiple courier services. Here’s how to use it.)

The past few months have been super busy time: I’ve worked on development for different e-commerce projects, joined a startup, and co-organized another one — all while preparing for an ultra-marathon.

过去几个月一直很忙：我一直在为不同的电子商务项目进行开发，加入了一家初创公司，并共同组织了另一个项目-所有这些都是在准备超级马拉松的同时。

It so happened that I was working on some e-commerce projects that were in need of shipping features. These projects were already bootstrapped by someone else (not written by me from scratch) and they had the Shippo shipping service integrated into them. So this is how I met Shippo and started to work with it.

碰巧我正在从事一些需要运输功能的电子商务项目。这些项目已经被其他人引导(不是我从头开始写的)，并且有了Shippo 运输服务集成到其中。这就是我遇见七宝的方式并开始使用它。

I don’t know if Shippo is the only option for shipping features in web apps, but it’s quite popular and has a pretty good and simple API. In this article, we will uncover several common tasks you may need to solve with this service, along with Ruby.

我不知道Shippo是否是提供Web应用程序功能的唯一选择，但是它非常流行并且具有非常好的和简单的API。在本文中，我们将与Ruby一起揭示您可能需要使用此服务解决的一些常见任务。

从七宝开始 (Beginning with Shippo)

What you need first is to have a Shippo account and shippo gem bundled for your project:

您首先需要为您的项目捆绑一个shippo帐户和shippo gem：

gem 'shippo', git: 'https://github.com/goshippo/shippo-ruby-client'

Next, you need to configure it with the API token you should have (Shippo gives you test or live tokens). Just put this in config/initializers/shippo.rb:

接下来，您需要使用应有的API令牌对其进行配置(Shippo为您提供test或live令牌)。只需将其放在config/initializers/shippo.rb ：

Shippo::api_token = ENV['shippo_api_token']

For working with ENV , you might use something like dotenv or figaro or Heroku.

要使用ENV ，您可以使用dotenv或figaro或Heroku之类的工具 。

验证地址 (Validating addresses)

One cool feature Shippo has is allowing you to validate addresses. Let’s say you have address fields in your app’s users profiles, and you need to validate during sign up if the user’s address is correct. I came to a custom validator solution:

Shippo的一项很酷的功能是允许您验证地址。假设您在应用的用户个人资料中有地址字段，并且在注册期间需要验证用户的地址是否正确。我来到了一个自定义验证器解决方案：

class Profile < ApplicationRecord  validates_with ProfileAddressValidatorend

And the validator code utilizing Shippo::Address API will look like this:

使用Shippo::Address API的验证器代码如下所示：

创建装运/取货费率 (Creating a shipment/fetching rates)

The next popular task is to create a shipment in two steps. First, you are going to fetch shipping rates from different carriers (that you have set up in Shippo) and show them to your users so they can choose one. Second, based on the user’s choice, you’ll create a transaction (shipping label).

下一个流行的任务是分两步创建发货。首先，您将从不同的承运商(在Shippo中设置)中获取运费，并将其显示给用户，以便他们选择。其次，根据用户的选择，您将创建一个事务(装运标签)。

You may also offer a user interface for editing parcel sizes or just allow them to choose from pre-defined parcels/boxes.

您可能还提供了用于编辑宗地大小的用户界面，或仅允许他们从预定义宗地/盒子中进行选择。

Our first step might look like this:

我们的第一步可能看起来像这样：

Shippo::Shipment.create(  address_from: @address_from,  address_to: ADDRESS_TO,  parcels: parcels,  async: false)

In case you’re wrapping this into a service object, @address_from is something you want to pass into it. It should be like this (the same Hash for ADDRESS_TO which might be a constant, in case your users only send to one address):

如果将其包装到服务对象中，则@address_from是您想要传递给它的东西。应该是这样的(如果您的用户仅发送到一个地址，则ADDRESS_TO 哈希值可能是一个常数)：

{    :name => 'Apple',    :street1 => 'One Apple Park Way',    :city => 'Cupertino',    :state => 'CA',    :zip => '95014',    :country => 'US',    :phone => '+1 (408) 996–1010',    :email => 'tim@apple.com'  }

And finally, parcels is an array of such structures:

最后， parcels是这样结构的阵列：

{  length: 10, # or something coming from params  width: 10,  height: 10,  distance_unit: :in,  weight: 3,  mass_unit: :lb,}

After passing all these data and calling Shippo::Shipment.create you should get a shipment object which contains a rates attribute ( shipment.rates ).

传递Shippo::Shipment.create所有这些数据并调用Shippo::Shipment.create您应该获得一个包含rates属性( shipment.rates )的shipping对象。

根据所选费率创建货运标签(交易) (Create shipping label (transaction) based on selected rate)

We have a rate selected by the user, and we instantiated it (let’s say in a controller) in @selected_shipping_rate. Now just do this:

我们有一个由用户选择的费率，并在@selected_shipping_rate实例化了这个费率(例如在控制器中)。现在只需执行以下操作：

transaction = Shippo::Transaction.create(  rate: @selected_shipping_rate['object_id'],  label_file_type: "PDF",  metadata: @ticket.token.to_s, # pass any additional data if needed  async: false)

You should confirm whether it was successful or not by checking transaction["status"] . It should be SUCCESS or something from the available statuses. You may also be interested in transaction["tracking_number"] and transaction["label_url"] (the URL of the shipping label PDF file).

您应该通过检查transaction["status"]来确认是否成功。它应该是SUCCESS或可用状态中的某物。您可能也对transaction["tracking_number"]和transaction["label_url"] (货运标签PDF文件的URL) transaction["label_url"] 。

单一通话标签创建 (Single call label creation)

You might want to create a shipping label with a single Shippo API call. Well, you can do this! In this case, you’ll use a concrete shipping carrier, like FedEx.

您可能希望通过单个Shippo API调用来创建运输标签。好吧，你可以做到这一点！在这种情况下，您将使用像FedEx这样的混凝土运输公司。

So this API call looks like a combination of two calls we did previously: carrier_account is a Carrier object id — you can get it with https://goshippo.com/docs/reference/rb#carrier-accounts-list — and servicelevel_token is a corresponding token from this service levels enum:

因此，此API调用看起来像我们之前做过的两个调用的组合： carrier_account是一个Carrier对象carrier_account您可以通过https://goshippo.com/docs/reference/rb#carrier-accounts-list来获取它，而servicelevel_token是此服务级别枚举中的相应令牌：

运营商设置 (Carriers settings)

For working carriers, you need to pass all the required data. This depends on the concrete shipping provider. Shippo has very good description page about what’s needed. For example, for setting up FedEx you need to get from them at least the meter number and account number.

对于有效的运营商，您需要传递所有必需的数据。这取决于具体的运输提供商。七宝关于所需内容的说明页面非常好。例如，要设置FedEx，您需要至少从他们那里获得meter number和account number 。

One tricky thing about FedEx: their test server is not very stable (and that fact was confirmed by Shippo support). So, sometimes you’ll be able to create shipments and request rates, but sometimes you’ll get this response: “FedEx API did not respond. Please try again in a few minutes.”

关于FedEx的一件棘手的事情 ：他们的测试服务器不是很稳定(这一事实已得到Shippo支持的证实)。因此，有时您可以创建发货和请求费率，但有时您会收到以下响应：“ FedEx API没有响应。请在几分钟后再试一次。”

追踪货运 (Tracking shipments)

And finally, you might want to be like a “big brother” who is watching your shipments :-) Then you need to start tracking shipments so you’ll know when they have actually been sent and delivered.

最后，您可能想要像个“老大哥”一样监视着您的货物：-)然后您需要开始跟踪货物，以便知道何时实际发送和交付货物。

Shippo has a Shippo::Track API for such a purpose, and webhooks that you can receive via HTTP. First, you should register that you’re going to track some shipment.

七宝有一个Shippo::Track API可以达到此目的，并且您可以通过HTTP接收webhooks。首先，您应该注册要跟踪的货物。

@shipping_label is our own object that we store in the database: we saved it after the successful Shippo transaction (shipping label) creation.

@shipping_label是我们自己的对象，我们存储在数据库中：在成功创建Shippo事务(装运标签)后，我们将其保存了。

Second, you need to have a webhooks handler: in terms of Rails, you need to add a route and a controller.

其次，您需要一个webhooks处理程序：就Rails而言，您需要添加一条路由和一个控制器。

Shippo will then send you data about tracking status updates, so you can then update the status information in the database and have everything in sync.

然后，Shippo将向您发送有关跟踪状态更新的数据，以便您随后可以更新数据库中的状态信息并使所有内容保持同步。

# Shippo webhook in routes.rbpost '/shippo_webhook' => 'shippo#track_shipment'

Don’t forget to test this in development with your favorite development tunneling tool like ngrok or localtunnel . And of course, you need to login to your Shippo account and specify the URL that will receive webhooks and what types of webhooks they are.

不要忘了与像您喜欢的开发开道工具测试这个发展ngrok或localtunnel 。当然，您需要登录到Shippo帐户，并指定将接收Webhooks的URL以及它们是什么类型的Webhooks。

结论 (Conclusion)

Shippo is a great solution for pretty much anything when you need some shipping capabilities in your app. That’s why I would choose it for my next project.

当您需要在应用程序中提供某些传送功能时，Shippo是适用于几乎所有事物的出色解决方案。这就是为什么我会在下一个项目中选择它。

If there’s something competitive on the market, let me know in comments. I’d love to hear about something really cool for shipping tasks.

如果市场上有竞争产品，请在评论中让我知道。我很想听听关于运输任务非常酷的事情。

If you liked this post, please click on ✋ to spread the word.

如果您喜欢这篇文章，请单击 ✋ 以扩展单词。