chore: Merge master to develop (#3653)

2023-03-31 13:09:57 +02:00
parent b2e2eddcea
commit 809ab2e0eb
120 changed files with 2240 additions and 585 deletions
@@ -1,26 +1,85 @@
-# medusa-fulfillment-webshipper
+# Webshipper

-Adds Webshipper as a fulfilment provider in Medusa Commerce.
+Handle order fulfillments using Webshipper.

-On each new fulfillment an order is created in Webshipper. The plugin listens for shipment events and updated the shipment accordingly.
-A webhook listener is exposed at `/webshipper/shipments` to listen for shipment creations. You must create this webhook in Webshipper to have Medusa listen for shipment events.
+[Medusa Website](https://medusajs.com) | [Medusa Repository](https://github.com/medusajs/medusa)

-## Options
+## Features

-```
-  account: [your webshipper account] (required)
-  api_token: [a webshipper api token] (required)
-  order_channel_id: [the channel id to register orders on] (required)
-  webhook_secret: [the webhook secret used to listen for shipments] (required)
-  coo_countries: [an array of countries in which a Certificate of Origin will be attached] (default: "all")
-  delete_on_cancel [determines whether Webshipper orders are deleted when a Medusa fulfillment is canceled] (default: false)
-```
+- Webshipper can be used as a shipping option during checkouts and for handling order fulfillment.
+- Sync order details and updates with Webshipper.
+- Support for Webshipper webhooks.

-## Personal Customs Numbers
+---

-In countries like South Korea a personal customs number is required to clear customs. The Webshipper fulfillment plugin is able pass this information to Webshipper given that the number is stored in `order.shipping_address.metadata.personal_customs_no`.
+## Prerequisites

-### Modifications in checkout flow
+- [Medusa backend](https://docs.medusajs.com/development/backend/install)
+- [Webshipper Account](https://webshipper.com)
+
+---
+
+## How to Install
+
+1\. Run the following command in the directory of the Medusa backend:
+
+  ```bash
+  npm install medusa-fulfillment-webshipper
+  ```
+
+2\. Set the following environment variables in `.env`:
+
+  ```bash
+  WEBSHIPPER_ACCOUNT=<YOUR_WEBSHIPPER_ACCOUNT>
+  WEBSHIPPER_API_TOKEN=<YOUR_WEBSHIPPER_API_TOKEN>
+  WEBSHIPPER_ORDER_CHANNEL_ID=<YOUR_WEBSHIPPER_ORDER_CHANNEL_ID>
+  WEBSHIPPER_WEBHOOK_SECRET=<YOUR_WEBSHIPPER_WEBHOOK_SECRET>
+  WEBSHIPPER_COO_COUNTRIES=<WEBSHIPPER_COO_COUNTRIES>
+  WEBSHIPPER_DELETE_ON_CANCEL=<WEBSHIPPER_DELETE_ON_CANCEL>
+  ```
+
+3\. In `medusa-config.js` add the following at the end of the `plugins` array:
+
+  ```js
+  const plugins = [
+    // ...
+    {
+      resolve: `medusa-fulfillment-webshipper`,
+      options: {
+        account: process.env.WEBSHIPPER_ACCOUNT, // required
+        api_token: process.env.WEBSHIPPER_API_TOKEN, // required
+        order_channel_id: process.env.WEBSHIPPER_ORDER_CHANNEL_ID, // required, the channel id to register orders on
+        webhook_secret: process.env.WEBSHIPPER_WEBHOOK_SECRET, // required, the webhook secret used to listen for shipments
+        coo_countries: process.env.WEBSHIPPER_COO_COUNTRIES, // default: "all", an array of countries or a string of one country in which a Certificate of Origin will be attached
+        delete_on_cancel: process.env.WEBSHIPPER_DELETE_ON_CANCEL, // default: false, determines whether Webshipper orders are deleted when a Medusa fulfillment is canceled
+      },
+    },
+  ]
+  ```
+
+---
+
+## Test the Plugin
+
+1\. Run the following command in the directory of the Medusa backend to run the backend:
+
+  ```bash
+  npm run start
+  ```
+
+2\. Enable the fulfillment provider in the admin. You can refer to [this User Guide](https://docs.medusajs.com/user-guide/regions/providers) to learn how to do that. Alternatively, you can use the [Admin APIs](https://docs.medusajs.com/api/admin#tag/Region/operation/PostRegionsRegion).
+
+3\. Place an order using a storefront or the [Store APIs](https://docs.medusajs.com/api/store). You should be able to use the manual fulfillment provider during checkout.
+
+---
+
+## Additional Details
+
+### Personal Customs Numbers
+
+In countries like South Korea, a personal customs number is required to clear customs. The Webshipper fulfillment plugin is able pass this information to Webshipper given that the number is stored in `order.shipping_address.metadata.personal_customs_no`.
+
+#### Modifications in Checkout Flow

 To pass the information along you should dynamically show an input field to the customer when they are shopping from a region that requires a personal customs number, and make sure that the metadata field is set when updating the cart shipping address.

@@ -43,4 +102,4 @@ const onUpdateAddress = async () => {
      console.log("Good stuff - Webshipper will pass along the customs number")
    })
 }
-```
+```