Skip to content

Instantly share code, notes, and snippets.

@alChaCC

alChaCC/Easyship API - Shopmatic.md

Last active August 23, 2019 04:51
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save alChaCC/2aa4b32e0562e7ff4f1b723cd3cc7c63 to your computer and use it in GitHub Desktop.
Save alChaCC/2aa4b32e0562e7ff4f1b723cd3cc7c63 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
Easyship API - Shopmatic.md

Easyship Open API for Shopmatic

This documentation comes in addition to the main Easyship API documentation to offer additional functionality.

The API endpoints dedicated to Shopmatic can be used to create users and stores, create stores for existing users, get rates and get categories.

For any questions related to the Easyship API, please contact api-support@easyship.com

POST Create and link a new Shopmatic user

Note: After get Easyship Open API Access Token, please contact us to add scope shopmatic_admin.

Request

[POST] https://api.easyship.com/company/v1/create_shopmatic_user_and_store

This endpoint allows the Shopmatic admin to create a new company on Easyship, with a user, address, and API key, as well as linking his Shopmatic store and creating default settings.

Default settings for the store are:

  • incoterms: DDU
  • default category: the one specified in the request
  • excluded couriers: all couriers that don't provide a free pickup service

Example:

{
  "store": {
    "company_name": "My Store Inc.",
    "shopmatic_store_name": "mystore.goshopmatic.com",
    "email": "bob@test.com",
    "first_name": "Bob",
    "last_name": "Smith",
    "phone_number": "+852 1234 5678",
    "address_line_1": "1 Queen's Road Central",
    "address_line_2": "Central",
    "state": "Hong Kong",
    "postal_code": "0000",
    "city": "Hong Kong",
    "country_alpha2": "HK",
    "category": "fashion",
    "display_taxes": "show_with_amount",
    "label_callback_url": "https://api.goshopmatic.com/label_callback?store=mystore"
  }
}

Response

Example success:

// 201
{
  "company": {
    "easyship_company_id": "CHK00002", 
    "api_key": "13dddbebe7166749a0cde36688d3d13c9ffd95f3deaeaa01cefde85ea4931de6",
    "api_secret": "-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEAtLgb0bPFSV8yNevHOhh3fw7WZL0K2gp38TETPQGWoe9kfnm4\nXwKIX7w0K2kXnPdEHEJxqQjS/s7mt/j/RjmNApiO9rB0wmO3oGDIouXVJWMI0VA/\npj9Ykqj6lZ+LvNmTqfIObErDK4NGIbFuGAawHMAY3FCJMpoBmQtp+gPZ5PxU2E/k\ngfwmBn34cYcKk/pUn3xaTy+gti08qrW/PDisC+FA16ihqwjjg0VJkgwhgQt5bN6t\n8My6VdprFOFXJ3jd9hRipnr/01k58Aow5uXZnpJnl60FWV7o/hD3kKiZ0zCwZymP\nSs1QdCCXZYPkapoqDBqQ4LkwEzaa+eEQj3XNHQIDAQABAoIBACGKJceWiJ/kZgox\n1wjGL69KDqoll5T96mK+C+b/m3g0WL9MUdZ4Pt0drcT8vSApl99yyWtostgNiC5O\nrPnYhn4b2DSabSECprrCG5p380X8Ck/mh9mP2h1l9RO9x45mBwy8WsboXS5/L43j\nQx58Z0T+td51p/DXOkKwJpv7CP6BMdqdEQXA9btX6tCvP/V7M/8M5p+BUkUMoctI\n3GLR27Sr02L7g2XMaEzJaYc0sWZbF+xjoI4zQTlGKT3KOjKSTRjpJv07i4YL/L6/\nZ9zbQZKlb/Cv2y3v5AAd/xU6mmRJzrN9EJCnIqFw6kQboeYrCuUUT5iYMEwMtRIZ\nfkzxvJUCgYEA8J19MxLiLOi4gaoisADzE+NmXFAbeO8LMtp3WAZyH82foUIg6JkO\nMBMBr8lhjBpc4f3SC6AdEINmkAJbbJC9uuy1UG7BTTOtu9mywSn/sJ8SRc5MV0Ui\naVBC4pFgvF7nJT5sNicQtfT6AlWqLovPPCIdJBRuzyUGY54g8lp8n9sCgYEAwEY2\nG5nexwm912qCH1TZzShrU0sKRJAd9VtqrECcIEz/2VI+XVbENQCibxDKkB3+q9GP\nkkJ2TNgrW4ahyI8vfnu3g71NXyh9EPY9tCL0obpsMA3ezI9iJ2firumQ/elkGw3j\nVnOTcyWaecNNk5ExJ8q67AK+qwMsLC+vsUxbNGcCgYBF4OcQYyaOdlPHTHrgdJYj\nq4H5w0YHPB0berj4Nn8EX3pBoevewTyOl6aAv9J1lt5sv4M13x0xw4eQwS59/Bct\n5zrNDi1TV3PYP2Qbly/rwnbTERO4sJpKzYVvOVtHuaQVe+h/XZ8LyQamkOxosi/Q\nPfQKm2iG/jC5052r5L2WywKBgQCG13aQystSmQFbNmXFJVONrn/+LQ0pYkywSok3\n/iO//2Aaf7Qe73+wkB5ad9MnWPHGe7QNZbDjWWKm0HdbWRd8w7TCnhrJ1nJHV/mU\nAEPBvCStWrzaht/WNOPjuQenGmvLEWVStsE8qq14IUChcdygRGvsokwnUJVE87hq\nRdtclwKBgQDRK2/7Os3PHGm1CPkyjoqu5IeVyVvJanjEqzJ77/VNMQ9Y+RRK0g1x\nBRgzkoX9N6to0QPUBLXGSg3Siln7WMp4MiISY55gxAGJ0ucAtV4EyApru6SBFD1T\nxAG0pofB3n1KAg7vzRJJDCV9y6+izNswQbaaKemkl3fRwoXsaRe/sw==\n-----END RSA PRIVATE KEY-----\n",
    "token": "prod_123456789123456789123456789123456789123456789"
  }
}

Example error - user already exists:

// 401
{
  "status": "User already exists",
  "message": "email bob@test.com already exists",
  "errors": [
    "email bob@test.com already exists"
  ]
}

POST Link an existing Shopmatic user

Note: the Access Token included in the Headers must has the scope shopmatic_admin

Request

[POST] https://api.easyship.com/company/v1/create_shopmatic_store

This endpoint allows the Shopmatic admin to connect a Shopmatic store with an existing Easyship user and company, using the API key provided by the user. It also creates default settings for the store.

Default settings for the store are:

  • incoterms: DDU
  • default category: the one specified in the request
  • excluded couriers: all couriers that don't provide a free pickup service

Example:

{
  "store": {
    "shopmatic_store_name": "mystore.goshopmatic.com",
    "category": "fashion",
    "label_callback_url": "https://api.goshopmatic.com/label_callback?store=mystore",
    "access_token": "prod_123456789123456789123456789123456789123456789"
  }
}

Response

Example success:

// 201
{
  "company": {
    "easyship_company_id": "CHK00002"
  }
}

Example error - user's access_token not recognised:

// 404
{
  "status": "Access Token not found",
  "message": "Access Token not found",
  "errors": [
    "Access Token not found"
  ]
}

Example error - if shopmatic_store_name already linked

// 400
{
  "status": "Store already linked to Easyship", 
  "message": "Store already linked to Easyship",
  "errors": [
    "Store already linked to Easyship"
  ]
}

GET Shopmatic rates

Note: the Access Token included in the Headers must has the scope rate (customer's token)

Request

[POST] https://api.easyship.com/rate/v1/shopmatic

The Shopmatic Rates API allows you to request the top 3 shipping options (cheapest, fastest and best value for money) for a given order.

Example:

{ 
  "origin_country_alpha2": "SG",
  "destination_country_alpha2": "HK",
  "destination_postal_code": "12345",
  "destination_city": "Central",
  "destination_address_line_1": "line1",
  "destination_address_line_2": "line2",
  "destination_state": "Hong Kong",
  "is_insured": true,
  "items": [
    {
      "category": "watches",
      "actual_weight": 1.3,
      "length": 1,
      "width": 1,
      "height": 1,
      "declared_customs_value": 100,
      "declared_currency": "HKD"
    }
  ]
}

Response

Example:

// 200
{
  "rates": [
    {
      "courier_id": "e8c80815-1dcc-4496-ba32-0938c579978a",
      "courier_name": "DPEX Battery",
      "min_delivery_time": 3,
      "max_delivery_time": 5,
      "value_for_money_rank": 2,
      "delivery_time_rank": 4,
      "shipment_charge": 74.97,
      "fuel_surcharge": 8.9964,
      "remote_area_surcharge": 0,
      "shipment_charge_total": 83.9664,
      "warehouse_handling_fee": 0,
      "insurance_fee": 0,
      "ddp_handling_fee": 0,
      "import_tax_charge": 0,
      "import_duty_charge": 0,
      "total_charge": 83.97,
      "is_above_threshold": false,
      "effective_incoterms": "DDU",
      "estimated_import_tax": 0,
      "estimated_import_duty": 0,
      "courier_does_pickup": true,
      "courier_dropoff_url": null,
      "tracking_rating": 3,
      "payment_recipient": "Easyship",
      "courier_remarks": null,
      "currency": "HKD",
      "box": {
        "name": null,
        "length": 1,
        "width": 1,
        "height": 1
      },
      "minimum_pickup_fee": 0,
      "description": null,
      "full_description": null
    },
    {
      "courier_id": "43d6f8aa-6b9b-49dc-b053-47dd9817f317",
      "courier_name": "Aramex",
      "min_delivery_time": 4,
      "max_delivery_time": 5,
      "value_for_money_rank": 1,
      "delivery_time_rank": 5,
      "shipment_charge": 84.8925,
      "fuel_surcharge": 8.48925,
      "remote_area_surcharge": null,
      "shipment_charge_total": 93.38175,
      "warehouse_handling_fee": 0,
      "insurance_fee": 0,
      "ddp_handling_fee": 0,
      "import_tax_charge": 0,
      "import_duty_charge": 0,
      "total_charge": 93.38,
      "is_above_threshold": false,
      "effective_incoterms": "DDU",
      "estimated_import_tax": 0,
      "estimated_import_duty": 0,
      "courier_does_pickup": true,
      "courier_dropoff_url": null,
      "tracking_rating": 3,
      "payment_recipient": "Easyship",
      "courier_remarks": null,
      "currency": "HKD",
      "box": {
        "name": null,
        "length": 1,
        "width": 1,
        "height": 1
      },
      "minimum_pickup_fee": 0,
      "description": null,
      "full_description": null
    },
    {
      "courier_id": "b8d528a7-a2d4-4510-a7ac-11cbbb6542cd",
      "courier_name": "UPS Worldwide Saver",
      "min_delivery_time": 2,
      "max_delivery_time": 4,
      "value_for_money_rank": 3,
      "delivery_time_rank": 3,
      "shipment_charge": 111.51,
      "fuel_surcharge": 12.544875,
      "remote_area_surcharge": 0,
      "shipment_charge_total": 124.054875,
      "warehouse_handling_fee": 0,
      "insurance_fee": 0,
      "ddp_handling_fee": 0,
      "import_tax_charge": 0,
      "import_duty_charge": 0,
      "total_charge": 124.05,
      "is_above_threshold": false,
      "effective_incoterms": "DDU",
      "estimated_import_tax": 0,
      "estimated_import_duty": 0,
      "courier_does_pickup": true,
      "courier_dropoff_url": null,
      "tracking_rating": 3,
      "payment_recipient": "Easyship",
      "courier_remarks": null,
      "currency": "HKD",
      "box": {
        "name": null,
        "length": 1,
        "width": 1,
        "height": 1
      },
      "minimum_pickup_fee": 0,
      "description": null,
      "full_description": null
    }
  ]
}

GET Categories

With the Reference API, you are able to retrieve information that you may require to integrate with our service.

Note: the JWT Access Token included in the Headers must be generated with the scope reference.

Request

[GET] https://api.easyship.com/reference/v1/categories

Response

// 200
{
  "categories": [
    {
      "name": "Mobile Phones",
      "slug": "mobile_phones"
    },
    {
      "name": "Tablets",
      "slug": "tablets"
    },
    {
      "name": "Computers & Laptops",
      "slug": "computers_laptops"
    },
    {
      "name": "Cameras",
      "slug": "cameras"
    },
    {
      "name": "Accessory (no-battery)",
      "slug": "accessory_no_battery"
    },
    {
      "name": "Accessory (with battery)",
      "slug": "accessory_with_battery"
    },
    {
      "name": "Health & Beauty",
      "slug": "health_beauty"
    },
    {
      "name": "Fashion",
      "slug": "fashion"
    },
    {
      "name": "Watches",
      "slug": "watches"
    },
    {
      "name": "Home Appliances",
      "slug": "home_appliances"
    },
    {
      "name": "Home Decor",
      "slug": "home_decor"
    },
    {
      "name": "Toys",
      "slug": "toys"
    },
    {
      "name": "Sport & Leisure",
      "slug": "sport_leisure"
    },
    {
      "name": "Bags & Luggages",
      "slug": "bags_luggages"
    },
    {
      "name": "Audio Video",
      "slug": "audio_video"
    },
    {
      "name": "Documents",
      "slug": "documents"
    },
    {
      "name": "Jewelry",
      "slug": "jewelry"
    },
    {
      "name": "Dry Food & Supplements",
      "slug": "dry_food_supplements"
    },
    {
      "name": "Books & Collectibles",
      "slug": "books_collectibles"
    },
    {
      "name": "Pet Accessory",
      "slug": "pet_accessory"
    },
    {
      "name": "Gaming",
      "slug": "gaming"
    }
  ]
}
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment