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

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

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

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

こちらの記事、および、こちらのPOSTMANコレクションを参考にして、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ドキュメントの「出荷情報の作成」からリンクされている共通定義の記述をもとに、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ドキュメントの「出荷情報の作成」に記載されていますが、国内発送と海外発送で荷物の情報を指定するパラメータが違います。 国内発送の場合は、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ドキュメントの「出荷情報の作成」に記載されているcustomのパラメータを使って、関税（duty_paid　）や荷物の中身（content_type）についての指定を行います。インコタームズの指定も、duty_paidを使います。

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

5. 保険の情報を指定をする

APIドキュメントの「出荷情報の作成」からリンクされている共通定義の記述をもとに、setupのinsuranceを使って、保険金額を設定することもできます（必須ではありません）。

※UPSは対象外。

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

6. APIを実行する

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

DHLの例：

FedEXの例：

日本郵便の例：

その他の参考情報