Ship&Co APIを使って、海外発送の送り状PDFを生成する

この記事では、[Ship&CoのAPI](https://developer.shipandco.com)を使って、DHL、UPS、FedEX、日本郵便EMSなどの海外発送用の送り状のPDFファイルを生成する方法を紹介します。

海外発送というと、難しくてハードルが高そうに聞こえますが、Ship&CoのAPIを使えば、以下の理由で国内発送同様に簡単にシステム連携ができます。

- 全ての運送会社に対して同じ構成のAPIで接続できるため、個別対応が必要でない
- 複雑な運送会社のAPIを１つのシンプルなAPIとしてデザインし直されている
- 海外の運送会社のAPIドキュメントは英語であるが、Ship&CoのAPIドキュメントは日本語で提供されている


# 1. shipment APIを呼び出す準備をする

[こちらの記事](https://qiita.com/shipandco/items/ffba21c1d0682bde1dc9)、および、[こちらのPOSTMANコレクション](https://documenter.getpostman.com/view/3269571/SW14TvyF?version=latest#47002eb0-da5d-4a21-a077-874a95e61e89)を参考にして、`https://app.shipandco.com/api/v1/shipments`に`POST`するリクエストJSONを作成します。

```
{
    "to_address": {
      "full_name": "John Doe",
      "company": "",
      "email": "",
      "phone": "0901231234",
      "country": "FR",
      "zip": "75002",
      "province": "",
      "city": "Paris",
      "address1": "12 Rue du 4 Septembre",
      "address2": ""
    },
    "from_address": {
      "full_name": "Yamada Taro",
      "company": "World Company",
      "email": "ytaro@worldcompany.com",
      "phone": "08012341234",
      "country": "JP",
      "zip": "6050012",
      "province": "KYOTO",
      "city": "KYOTO SHI",
      "address1": "HIGASHIYAMA KU",
      "address2": "SAIKAISHICHO"
    },
    "products": [
      {
        "name": "T-Shirt",
        "quantity": 2,
        "price": 2980,
        "hs_code": "1234.12",
        "origin_country": "JP"
      }
    ],
    "parcels": [
      {
        "weight": 2000,
        "amount": 1,
        "width": 10,
        "height": 10,
        "depth": 10
      }
    ],
    "customs": {
      "duty_paid": false,
      "content_type": "MERCHANDISE"
    },
    "setup": {
      "carrier": "dhl",
      "service": "dhl_express_worldwide",
      "currency": "JPY",
      "insurance": 0,
      "ref_number": "123-REF-3456",
      "delivery_note": "Leave the box at the door",
      "discount": 0,
      "signature": false,
      "test": true,
      "return_label": false
    }
}
```

※注意：テスト印刷（`"test": true,`）は、DHLとUPSのみ可能です。FedEXとEMSはできません。ただし、EMSについては、Ship&Coのダッシュボードから自由に日本郵便の国際アカウントを作成して、APIで印刷をすることができます。Ship&Coの14日間の無料トライアル期間中は、同じく無料で試すことができます。実際に荷物を日本郵便に持ち込まない限りは、配送料を請求されることもありません。

# 2. サービスの指定をする

[APIドキュメントの「出荷情報の作成」](https://developer.shipandco.com/#t-ship)からリンクされている[共通定義](https://developer.shipandco.com/#t-common_obj)の記述をもとに、`setup`の`carrier`と`service `を利用したいものに置き換えます。共通定義で「海外/国内」の項目が「海外」となっている運送会社が、海外発送向けのものです。上記の例は、DHL Express Worldwideのものですが、以下のように書き換え可能です。

UPS Saverの場合

```
"setup": {
  "carrier": "ups",
  "service": "ups_saver",
  ...
}
```

FedEX International Economyの場合

```
"setup": {
 "carrier": "fedex",
 "service": "fedex_international_economy",
  ...
}
```

日本郵便 EMSの場合

```
"setup": {
 "carrier": "japanpost",
 "service": "japanpost_ems",
  ...
}
```

# 3. 荷物の情報の指定をする

[APIドキュメントの「出荷情報の作成」](https://developer.shipandco.com/#t-ship)に記載されていますが、**国内発送と海外発送で荷物の情報を指定するパラメータが違います。** 国内発送の場合は、`setup`の`pack_size`、`pack_amount`などを使って指定しますが、海外発送の場合は、`parcels`を使います。`parcels`には、荷物のサイズを`width`、`height`、`depth`（単位はcm）を使って指定する方法と、運送会社が決めたサイズで指定する`package`を使う方法の２種類があります。重さは`weight`（単位はグラム）で指定します。

`width`、`height`、`depth`を使った指定

```
"parcels": [
  {
    "weight": 2000,
    "amount": 1,
    "width": 10,
    "height": 10,
    "depth": 10
  }
],
```

`package`を使った指定

```
"parcels": [
  {
    "weight": 200,
    "amount": 1,
    "package": "fedex_envelope"
  }
],
```

# 4. カスタム情報を指定をする
[APIドキュメントの「出荷情報の作成」](https://developer.shipandco.com/#t-ship)に記載されている`custom`のパラメータを使って、関税（`duty_paid`　）や荷物の中身（`content_type`）についての指定を行います。[インコタームズ](https://www.jetro.go.jp/world/qa/J-200309.html)の指定も、`duty_paid`を使います。

```
"customs": {
  "duty_paid": false, // = "DDU" in Incoterms
  "content_type": "MERCHANDISE"
},
```

# 5. 保険の情報を指定をする
[APIドキュメントの「出荷情報の作成」](https://developer.shipandco.com/#t-ship)からリンクされている[共通定義](https://developer.shipandco.com/#t-common_obj)の記述をもとに、`setup`の`insurance`を使って、保険金額を設定することもできます（必須ではありません）。

※UPSは対象外。

```
"setup": {
 ...
 "insurance": 1000,
  ...
}
```

# 6. APIを実行する

上記で作成したリクエストをもとに、APIを実行します。成功すると、下記のようなPDFがレスポンスにURLとして返されます。

DHLの例：![１.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/653449/661b9dfa-a3e3-18c5-088e-f1ec5433972e.png)

FedEXの例：![２.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/653449/f6b66c20-0a94-374e-6ff0-077a39878611.png)

日本郵便の例：![３.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/653449/32bdd54e-3d27-59c6-94ee-5f2cca6c7585.png)

# その他の参考情報

- 海外発送については、[Ship&Coのブログ](https://blog.shipandco.com/tag/shipping-tips-solutions/)に色々なTIPSがありますので、ぜひご参照ください。
- Ship&Coは、[DHLのペーパーレス取引（PLT）](https://support.shipandco.com/hc/ja/articles/360000274682)、[FedExの電子取引書類（ETD）](https://support.shipandco.com/hc/ja/articles/900000894566)といった、カスタムインボイスにも対応しています。