Compatibility

This plugin is compatible with versions >= 2.11.x of @medusajs/medusa.

Table of Contents

• Prerequisites
• Installation
• Configuration
  • Configuration Options
  • Environment Variables
  • Authentication

Prerequisites

• Node.js v20 or higher
• Medusa server v2.11.3 or higher
• SF-Express account and API credential

Installation

yarn add @gerbergpt/medusa-fulfillment-sfexpress

Configuration

Add the provider module in your medusa-config.ts file:

module.exports = defineConfig({
  projectConfig: {
    // ...
  },
  modules: [
    // ... other modules
    {
      key: Modules.FULFILLMENT,
      resolve: "@medusajs/fulfillment",
      options: {
        providers: [
          {
            id: "sf-express",
            resolve: "@gerbergpt/medusa-fulfillment-sfexpress/providers",
            options: {
              sandbox: process.env.SFEXPRESS_ENV === "sandbox",
              partner_id: process.env.SFEXPRESS_PARTNER_ID,
              secret_sandbox: process.env.SFEXPRESS_SECRET_SANDBOX,
              secret_production: process.env.SFEXPRESS_SECRET_PRODUCTION,
              // Origin ("ship from") is taken from the Medusa stock location that
              // fulfils the shipping option (Settings → Locations & Shipping),
              // not from static options. Only destination fallbacks remain.
              default_dest_province: "Guangdong Province",
              default_dest_city: "Guangzhou City",
              default_payment_terms: "1", // 1: Sender Pay; 2: Receiver Pay; 3: Sender Third-Party; 4: Receiver Third-Party
            },
          },
        ],
      },
    },
  ]
})

Environment Variables

Create or update your .env file with the following variables:

SFEXPRESS_ENV=sandbox | production
SFEXPRESS_PARTNER_ID=
SFEXPRESS_SECRET_SANDBOX=
SFEXPRESS_SECRET_PRODUCTION=
DEFAULT_DEST_PROVINCE=
DEFAULT_DEST_CITY=
DEFAULT_PAYMENT_TERMS=1

Configuration Options

• partner_id (required) – SF-Express partner/customer code.
• secret_sandbox / secret_production (required) – SF-Express checkword for the corresponding environment. Used to retrieve OAuth2 access tokens.
• sandbox – Use sandbox gateway when true.
• Origin address – taken automatically from the Medusa stock location that fulfils the shipping option (Settings → Locations & Shipping) via context.from_location; there is no static origin option. Put the district (区) in the location's address_2 if needed.
• default_dest_* – Destination fallbacks used when the customer's checkout address is incomplete.
• default_payment_terms – One of 1 | 2 | 3 | 4 (see SF docs). Defaults to 1.

Authentication

This plugin now authenticates with SF-Express using the OAuth2 token flow described in docs/sf-express/API.md. The provider exchanges partner_id and the environment-specific secret for an accessToken, caches it for its two-hour lifetime, and attaches it to all API calls. No message-digest signatures are required.

Development

1. Install Yarn

npm i -g yarn

2. Publish Alipay payment locally via yalc:

cd medusa-fulfillment-sfexpress
yarn install
npx medusa plugin:publish

3. Navigate to your Medusa backend application and install the plugin:

npx medusa plugin:add @gerbergpt/medusa-fulfillment-sfexpress

After installation, you should see an entry pointing to the local yalc package:

"dependencies": {
  ...,
  "@gerbergpt/medusa-fulfillment-sfexpress": "file:.yalc/@gerbergpt/medusa-fulfillment-sfexpress",
  ...
}

4. Configure your Medusa application (backend)

module.exports = defineConfig({
  modules: [
    {
      key: Modules.FULFILLMENT,
      resolve: "@medusajs/fulfillment",
      options: {
        providers: [
          {
            id: "sf-express",
            resolve: "@gerbergpt/medusa-fulfillment-sfexpress/providers",
            options: {
              sandbox: process.env.SFEXPRESS_ENV === "prod",
              partner_id: process.env.SFEXPRESS_PARTNER_ID,
              secret_sandbox: process.env.SFEXPRESS_SECRET_SANDBOX,
              secret_production: process.env.SFEXPRESS_SECRET_PRODUCTION,
              debug: false,
              // Origin comes from the fulfilling stock location's address.
              default_payment_terms: "1"
            },
          },
        ],
      },
    },
  ],
})

5. If you need to move the local npm package bridged by yalc, just run:

npx yalc remove @gerbergpt/medusa-fulfillment-sfexpress