NAV Navbar
cURL
  • 概要
  • 認可
  • 出荷
  • 料金
  • 共通定義
  • エラー
  • 概要

    Ship&Co APIドキュメントへようこそ!このドキュメントではShip&CoのAPIの使い方について説明します。

    Ship&Coのアカウント登録はこちら

    APIの使い方はとても簡単です。以下の2ステップで完了です。

    1. 認可
    2. API コール

    認可

    全てのAPIコールに以下のHTTPヘッダーを追加してください

    curl "EACH_API_END_POINT" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    `YOUR_API_TOKEN_FROM_DASHBOARD`を取得したAPIトークンで置き換えてください

    Ship&Co APIは、APIダッシュボードから発行できるAPIトークンをHTTPヘッダーに指定することで認可され、利用できます。

    APIトークンの取得方法は以下です。

    1. Ship&Coダッシュボードにログインする
    2. [設定]メニューをクリックし、[API Settings]の[Token]に表示されているテキストをコピーする

    Dashboard

    コピーしたAPIトークンを以下のようにHTTPヘッダーに追加することでAPIを利用することができます。

    x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD

    出荷

    出荷情報の作成

    curl -v -X POST "https://app.shipandco.com/api/v1/shipments" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json" \
      -d '{
        "to_address": {
          "full_name": "John Doe",
          "company": "ACME",
          "email": "john@doe.io",
          "phone": "0901231234",
          "country": "PT",
          "address1": "Rua Maria Matos, 32",
          "address2": "",
          "province": "SETUBAL",
          "zip": "2820-344",
          "city": "CHARNECA DA CAPARICA"
        },
        "from_address": {
          "full_name": "Yamada Taro",
          "company": "World Company",
          "email": "ytaro@worldcompany.com",
          "phone": "08012341234",
          "country": "JP",
          "address1": "OSAKAFU",
          "address2": "OTECHO",
          "province": "OSAKA",
          "zip": "5670883",
          "city": "IBARAKI SHI"
        },
        "parcels": [
          {
            "weight": 200,
            "amount": 1,
            "width": 10,
            "height": 10,
            "depth": 10
          }
        ],
        "products": [
          {
            "name": "Basket ball",
            "quantity": 2,
            "price": 4850,
            "hs_code": "HS9988",
            "hs_description": "Sports ball",
            "origin_country": "JP"
          }
        ],
        "setup": {
          "carrier": "japanpost",
          "service": "ems",
          "currency": "JPY",
          "date": "2018-07-12",
          "insurance": 0,
          "ref_number": "",
          "delivery_note": "",
          "discount": 0,
          "signature": false,
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        }
      }'
    

    上記のリクエストは以下のようなレスポンスを返します。

    {
      "id": "API-XY7SCJGCXO",
      "state": "active",
      "created_at": "2018-10-10T15:50:10.868Z",
      "parcels": [
        {
          "weight": 200,
          "amount": 1,
          "width": 10,
          "height": 10,
          "depth": 10
        }
      ],
      "to_address": {
        "full_name": "John Doe",
        "company": "ACME",
        "address1": "Rua Maria Matos, 32",
        "country": "PT",
        "email": "john@doe.io",
        "phone": "0901231234",
        "address2": "",
        "city": "CHARNECA DA CAPARICA",
        "province": "SETUBAL",
        "zip": "2820-344"
      },
      "from_address": {
        "full_name": "Yamada Taro",
        "company": "World Company",
        "address1": "OSAKAFU",
        "country": "JP",
        "email": "ytaro@worldcompany.com",
        "phone": "08012341234",
        "address2": "OTECHO",
        "city": "IBARAKI SHI",
        "province": "OSAKA",
        "zip": "5670883"
      },
      "options": {
        "common": {
          "insurance": 0,
          "ref_number": "",
          "delivery_note": ""
        },
        "international": {
          "return_label": false,
          "signature": false,
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        },
        "japan": {
          "delivery_date": "2018-07-12",
          "shipment_type": "ems",
          "cash_on_delivery": false,
          "freight_on_delivery": false,
          "ahead_on_schedule": false,
          "care": {
            "fragile": false,
            "side_up": false,
            "valuable_goods": false
          },
          "package_number": "1",
          "pick_up": false
        }
      },
      "products": [],
      "delivery": {
        "carrier": "japanpost",
        "method": "ems",
        "tracking_numbers": ["EN022179102JP"],
        "label": "https://storage.googleapis.com/dev-shipandco/labels/201810/k3wWYYwk8Q8h46NcM/QFZT4vrm6bge73Bxg.pdf"
      }
    }
    

    指定した荷受人住所や荷物、製品情報、運送会社の情報を元に配送ラベル付きの出荷情報を作成します。

    リクエスト

    POST https://app.shipandco.com/api/v1/shipments

    項目 説明 必須情報
    to_address 荷受人住所です。 full_name, country, address1, city
    from_address 発送人住所です。 full_name, phone, country, address1, province
    parcels 荷物情報です。 国際の場合は最低1つの荷物情報が必要
    products 製品情報です。 name, quantity, price, hs_description, origin_country
    setup 設定情報です。
    詳細は運送業者とサービスを参照してください。
    料金の一覧を利用して最適な`service`を探すこともできます。
    carrier, service, currency

    レスポンス

    項目 説明
    id 出荷情報の一意のIDです。GETで利用できます。
    options 出荷情報のオプション情報です。
    delivery.carrier 指定した運送会社の名称です。
    delivery.tracking_numbers 出荷の追跡番号です。
    delivery.label 作成されたラベルのイメージ情報です。

    出荷情報の一覧

    curl -v -X GET "https://app.shipandco.com/api/v1/shipments?state=active&limit=2&page=1&created_after=2018-09-01T00:00:00.000Z&created_before=2018-09-30T00:00:00.000Z" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    上記のリクエストは以下のようなレスポンスを返します。

    {
      "shipments": [
        {
          "id": "API-H8TNUMIUBL",
          "state": "active",
          "created_at": "2018-09-24T15:37:33.995Z",
          "parcels": [
            {
              "weight": 200,
              "amount": 1,
              "width": 10,
              "height": 10,
              "depth": 10
            }
          ],
          "to_address": {
            "full_name": "John Doe",
            "company": "ACME",
            "address1": "Rua Maria Matos, 32",
            "country": "PT",
            "email": "john@doe.io",
            "phone": "0901231234",
            "address2": "",
            "city": "CHARNECA DA CAPARICA",
            "province": "SETUBAL",
            "zip": "2820-344"
          },
          "from_address": {
            "full_name": "Yamada Taro",
            "company": "World Company",
            "address1": "OSAKAFU",
            "country": "JP",
            "email": "ytaro@worldcompany.com",
            "phone": "08012341234",
            "address2": "OTECHO",
            "city": "IBARAKI SHI",
            "province": "OSAKA",
            "zip": "5670883"
          },
          "options": {
            "common": {
              "insurance": 0,
              "ref_number": "",
              "delivery_note": ""
            },
            "international": {
              "return_label": false,
              "signature": false,
              "duty_paid": false,
              "content_type": "MERCHANDISE"
            },
            "japan": {
              "delivery_date": "2018-07-12",
              "shipment_type": "ems",
              "cash_on_delivery": false,
              "freight_on_delivery": false,
              "ahead_on_schedule": false,
              "care": {
                "fragile": false,
                "side_up": false,
                "valuable_goods": false
              },
              "package_number": "1",
              "pick_up": false
            }
          },
          "products": [],
          "delivery": {
            "carrier": "japanpost",
            "method": "ems",
            "tracking_numbers": ["EN020057361JP"],
            "label": "https://storage.googleapis.com/dev-shipandco/labels/201809/k3wWYYwk8Q8h46NcM/undefined.pdf"
          }
        },
        {
          "id": "API-MIXKKUSCUD",
          "state": "active",
          "created_at": "2018-09-24T15:37:31.705Z",
          "parcels": [
            {
              "weight": 200,
              "amount": 1,
              "width": 10,
              "height": 10,
              "depth": 10
            }
          ],
          "to_address": {
            "full_name": "John Doe",
            "company": "ACME",
            "address1": "Rua Maria Matos, 32",
            "country": "PT",
            "email": "john@doe.io",
            "phone": "0901231234",
            "address2": "",
            "city": "CHARNECA DA CAPARICA",
            "province": "SETUBAL",
            "zip": "2820-344"
          },
          "from_address": {
            "full_name": "Yamada Taro",
            "company": "World Company",
            "address1": "OSAKAFU",
            "country": "JP",
            "email": "ytaro@worldcompany.com",
            "phone": "08012341234",
            "address2": "OTECHO",
            "city": "IBARAKI SHI",
            "province": "OSAKA",
            "zip": "5670883"
          },
          "options": {
            "common": {
              "insurance": 0,
              "ref_number": "",
              "delivery_note": ""
            },
            "international": {
              "return_label": false,
              "signature": false,
              "duty_paid": false,
              "content_type": "MERCHANDISE"
            },
            "japan": {
              "delivery_date": "2018-07-12",
              "shipment_type": "ems",
              "cash_on_delivery": false,
              "freight_on_delivery": false,
              "ahead_on_schedule": false,
              "care": {
                "fragile": false,
                "side_up": false,
                "valuable_goods": false
              },
              "package_number": "1",
              "pick_up": false
            }
          },
          "products": [],
          "delivery": {
            "carrier": "japanpost",
            "method": "ems",
            "tracking_numbers": ["EN021063567JP"],
            "label": "https://storage.googleapis.com/dev-shipandco/labels/201809/k3wWYYwk8Q8h46NcM/undefined.pdf"
          }
        }
      ],
      "count": 5,
      "pages": 3,
      "current_page": 1
    }
    

    作成した出荷情報を一覧表示します。

    リクエスト

    GET https://app.shipandco.com/api/v1/shipments

    項目 説明
    state 初期値 `active`, 指定可能な値: `active, avoided, any`

    その他の項目はGETパラメータを参照してください。

    レスポンス

    作成した出荷情報の配列です。出荷情報の詳細は出荷情報の作成を参照してください。

    その他の項目はGETレスポンスを参照してください。

    出荷情報の取得

    curl -v -X GET "https://app.shipandco.com/api/v1/shipments/API-H8TNUMIUBL" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json"
    

    上記のリクエストは以下のようなレスポンスを返します。

    {
      "id": "API-H8TNUMIUBL",
      "state": "active",
      "created_at": "2018-09-24T15:37:33.995Z",
      "parcels": [
        {
          "weight": 200,
          "amount": 1,
          "width": 10,
          "height": 10,
          "depth": 10
        }
      ],
      "to_address": {
        "full_name": "John Doe",
        "company": "ACME",
        "address1": "Rua Maria Matos, 32",
        "country": "PT",
        "email": "john@doe.io",
        "phone": "0901231234",
        "address2": "",
        "city": "CHARNECA DA CAPARICA",
        "province": "SETUBAL",
        "zip": "2820-344"
      },
      "from_address": {
        "full_name": "Yamada Taro",
        "company": "World Company",
        "address1": "OSAKAFU",
        "country": "JP",
        "email": "ytaro@worldcompany.com",
        "phone": "08012341234",
        "address2": "OTECHO",
        "city": "IBARAKI SHI",
        "province": "OSAKA",
        "zip": "5670883"
      },
      "options": {
        "common": {
          "insurance": 0,
          "ref_number": "",
          "delivery_note": ""
        },
        "international": {
          "return_label": false,
          "signature": false,
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        },
        "japan": {
          "delivery_date": "2018-07-12",
          "shipment_type": "ems",
          "cash_on_delivery": false,
          "freight_on_delivery": false,
          "ahead_on_schedule": false,
          "care": {
            "fragile": false,
            "side_up": false,
            "valuable_goods": false
          },
          "package_number": "1",
          "pick_up": false
        }
      },
      "products": [],
      "delivery": {
        "carrier": "japanpost",
        "method": "ems",
        "tracking_numbers": ["EN020057361JP"],
        "label": "https://storage.googleapis.com/dev-shipandco/labels/201809/k3wWYYwk8Q8h46NcM/undefined.pdf"
      }
    }
    

    出荷情報をIDで取得します。

    リクエスト

    GET https://app.shipandco.com/api/v1/shipments/:id

    レスポンス

    1つの出荷情報を返します。出荷情報の詳細は出荷情報の作成を参照してください。

    料金

    料金の一覧

    curl -v -X POST "https://app.shipandco.com/api/v1/rates" \
      -H "x-access-token: YOUR_API_TOKEN_FROM_DASHBOARD" \
      -H "Content-Type: application/json" \
      -d '{
        "to_address": {
          "full_name": "John Doe",
          "company": "ACME",
          "email": "john@doe.io",
          "phone": "0901231234",
          "country": "PT",
          "address1": "Rua Maria Matos, 32",
          "address2": "",
          "province": "SETUBAL",
          "zip": "2820-344",
          "city": "CHARNECA DA CAPARICA"
        },
        "from_address": {
          "full_name": "Yamada Taro",
          "company": "World Company",
          "email": "ytaro@worldcompany.com",
          "phone": "08012341234",
          "country": "JP",
          "address1": "OSAKAFU",
          "address2": "OTECHO",
          "province": "OSAKA",
          "zip": "5670883",
          "city": "IBARAKI SHI"
        },
        "parcels": [
          {
            "weight": 200,
            "amount": 1,
            "width": 10,
            "height": 10,
            "depth": 10
          }
        ],
        "products": [
          {
            "name": "Basket ball",
            "quantity": 2,
            "price": 4850,
            "hs_code": "HS9988",
            "hs_description": "Sports ball",
            "origin_country": "JP"
          }
        ],
        "setup": {
          "carrier": "japanpost",
          "service": "ems",
          "currency": "JPY",
          "date": "2018-07-12",
          "insurance": 0,
          "ref_number": "",
          "delivery_note": "",
          "discount": 0,
          "signature": false,
          "duty_paid": false,
          "content_type": "MERCHANDISE"
        }
      }'
    

    上記のリクエストは以下のようなレスポンスを返します。

    [
      {
        "carrier": "japanpost",
        "service": "ems",
        "currency": "JPY",
        "price": 2200,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "kakitome",
        "currency": "JPY",
        "price": 690,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "epacket",
        "currency": "JPY",
        "price": 785,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "sal",
        "currency": "JPY",
        "price": 280,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "epacketlight",
        "currency": "JPY",
        "price": 620,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "airparcel",
        "currency": "JPY",
        "price": 2500,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "salparcel",
        "currency": "JPY",
        "price": 2700,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "seaparcel",
        "currency": "JPY",
        "price": 1800,
        "surcharges": []
      },
      {
        "carrier": "japanpost",
        "service": "airmail",
        "currency": "JPY",
        "price": 420,
        "surcharges": []
      }
    ]
    

    作成する出荷情報を元に指定した運送業者のサービスごとの料金を一覧表示します。

    リクエスト

    POST https://app.shipandco.com/api/v1/rates

    `service`を除いた出荷情報の作成と同じです。詳細は、出荷情報の作成を参照してください。

    レスポンス

    各サービスの料金の配列です。

    共通定義

    運送業者とサービス

    運送業者 サービスの値 国際 / 国内
    日本郵便 japanpost ems, epacket, epacketlight, kakitome, airparcel, salparcel, seaparcel 国際
    UPS ups Saver, Worldwide Express, Worldwide Expedited, Worldwide Express Plus 国際
    DHL dhl EXPRESS WORLDWIDE, EXPRESS 12:00, EXPRESS 9:00, EXPRESS JUMBO 国際
    FedEx fedex International Economy, International First, International Priority 国際
    佐川急便 sagawa fresh, frozen, plane, regular 国内

    GETパラメータ

    項目 説明
    limit 初期値 `50`, 最大値 `250`
    page 初期値 `1`
    created_after 書式 `2018-09-20T00:00:00.000Z`
    created_before 初期値 `today` 書式 `2018-09-20T00:00:00.000Z`

    GETレスポンス

    項目 説明
    count データ数
    pages レスポンスのページ数(GETパラメータで指定可能)
    current_page レスポンスの現在ページ(GETパラメータで指定可能)

    エラー

    Ship&Co APIには以下のエラーコードがあります。

    正常時には200を返します。

    エラーコード 説明
    400 不正な入力または入力不足によるエラー
    403 APIトークンが未指定か間違っています
    404 指定されたデータが見つかりません
    500 内部エラー