Host functions

Shoppingate adds its own APIs on top of the standard Mini App ones — orders, payment, refunds, support tickets and the app language. These extended APIs must be declared in SGConf.js before ft.<name>(...) will work.

What goes in SGConf.js — and what does not

There are two kinds of APIs in a Mini App. Only the Shoppingate extended APIs need to be registered.

getUserInfo is not in SGConf.js and does not need to be — it ships with the runtime. See Permissions for how to call it.

Register only the APIs you actually call.

Step 1 — get your API list from the developer portal

Every API your Mini App can use is listed in the Shoppingate developer portal. Public APIs are available to every Mini App. Private APIs must be requested first and approved by an admin before your Mini App can call them. The full walkthrough is on the Dev portal → App Binding page.

In the developer portal, open:

Mini-Program  →  your Mini App  →  Information Details  →  App Binding
              →  API Configuration

API Configuration shows two lists:

• Public API — the APIs your Mini App can call right now.
• Restricted API — the APIs that need permission before use. Request them as shown in the next step.

Each row has the same columns:

• API name — the exact name to register, and to call as ft.<name>
• API category — e.g. user api, order apis, tickets apis
• Usable Range — Public or Private
• API Description — one line on what it does
• Action — Details opens the API and, for a restricted API, the request form

Click Details on the API in the Restricted API list. In API use application, write why your Mini App needs it, then click Application use.

Once an admin approves the request, the API moves to the Public API list. Its Usable Range still says Private — that is expected. It is now available to your Mini App, and you can register it in SGConf.js.

The portal gives you the name and a one-line description only. The parameters and the response for each API are in the API reference below. The extended APIs at the time of writing:

Step 2 — create SGConf.js

Create one file at the project root, exporting an extApi array — one entry per API, with its name, whether it is synchronous, and its parameters. This example registers every API in the list above:

// SGConf.js
module.exports = {
    extApi: [
        // user apis
        {
            name: 'getAppLang',
            sync: false,
            params: {}
        },
        // order apis
        {
            name: 'orderPayment',
            sync: false,
            params: {
                orderInfo: {},
                idempotencyKey: '',
                miniappId: '',
            }
        },
        {
            name: 'getUserOrder',
            sync: false,
            params: {
                orderId: '',
                miniappId: '',
            }
        },
        {
            name: 'getUserOrders',
            sync: false,
            params: {
                page: 1,
                perPage: 5,
                miniappId: '',
            },
        },
        {
            name: 'refundOrder',
            sync: false,
            params: {
                orderId: '',
                amount: 0.0,
                reason: '',
                miniappId: '',
            }
        },
        {
            name: 'getOrderRefunds',
            sync: false,
            params: {
                orderId: '',
                miniappId: '',
            }
        },
        // ticket apis
        {
            name: 'getTicketIssues',
            sync: false,
            params: {
                miniappId: '',
            }
        },
        {
            name: 'createTicket',
            sync: false,
            params: {
                issueId: 0,
                orderId: '',
                reason: '',
                affectedProducts: [],
                imageFilePath: '',
                miniappId: '',
            }
        },
        {
            name: 'getUserTickets',
            sync: false,
            params: {
                orderId: '',
                miniappId: '',
                page: 1,
                limit: 10,
            }
        },
    ]
}

Three rules for an entry:

• name must match the portal exactly. It is also the method name on ft.
• sync: false for all of these — they take success / fail callbacks.
• params declares the parameter names with placeholder values of the right type ('' string, 0 / 1 / 0.0 number, {} object, [] array). The values are not defaults; only the shape matters.

// app.js
App({
    globalData: {
        miniappId: '',
    },

    onLaunch() {
        const info = ft.getAccountInfoSync();
        this.globalData.miniappId = info && info.miniProgram && info.miniProgram.appId;
    },
})

Step 3 — how it is picked up

Nothing in your code imports SGConf.js. There is no require('./SGConf.js') anywhere, and the ft.* calls still work. The toolchain reads the file by name from the project root and registers the methods on the ft global.

So: put the file at the root, use the exact filename, and do not import it.

Step 4 — calling an API

Every extended API is a method on ft, with success and fail callbacks — the same shape as the built-in APIs. The parameters are the ones you declared in params.

// pages/bookings/bookings.js
const app = getApp()

ft.getUserOrders({
    page: 1,
    perPage: 10,
    miniappId: app.globalData.miniappId,
    success: (res) => {
        console.log(res.result, res.total, res.orders);
    },
    fail: (err) => console.log('getUserOrders fail', err),
});

import { useDidShow } from '@tarojs/taro'

useDidShow(() => {
    ft.getUserOrders({
        page: 1,
        perPage: 10,
        miniappId,
        success: (res) => setOrders(res.orders),
        fail: (err) => console.log('getUserOrders fail', err),
    })
})

const app = createApp({
    onShow() {
        ft.getUserOrders({
            page: 1,
            perPage: 10,
            miniappId,
            success: (res) => { store.orders = res.orders },
            fail: (err) => console.log('getUserOrders fail', err),
        })
    },
})

Step 5 — the response envelope

Extended APIs answer with a result field, not the errMsg string the built-in APIs use:

{ result: 'success', /* ...payload... */ }
{ result: 'failure', message: 'why it failed' }

Check result for the outcome and read message when it failed. The payload key differs per API — orders, order, refunds, tickets, issues, refundInfo — listed in the reference below.

API reference

Every API with its parameters, an example call and what it returns. The examples read miniappId from app.globalData, as set up in Step 2.

ft.getAppLang({
    success: (res) => {
        if (res.result === 'success') {
            console.log(res.language);   // 'en' or 'ar'
        }
    },
    fail: (err) => console.log('getAppLang fail', err),
});

{ result: 'success', language: 'en' }   // or 'ar'
{ result: 'failure', language: null }

ft.orderPayment({
    orderInfo: {
        vendor_order_ref: '1234567orderid',
        items: [ /* your items */ ],
        subtotal: '98.00',
        total_amount: '98.00',
        currency: 'SAR',
    },
    idempotencyKey: 'your-idempotency-key',
    miniappId: app.globalData.miniappId,
    success: (res) => {
        if (res.result !== 'success') {
            console.log('orderPayment failed', res.message);
            return;
        }
        console.log(res.status, res.order_id);
    },
    fail: (err) => console.log('orderPayment fail', err),
});

// failure
{ result: 'failure', message }

// success
{ result: 'success', status, order_id, message }

ft.getUserOrder({
    orderId: '1234567orderid',
    miniappId: app.globalData.miniappId,
    success: (res) => {
        if (res.result === 'success') {
            console.log(res.order);
        }
    },
    fail: (err) => console.log('getUserOrder fail', err),
});

{ result, order: { /* order */ } }

ft.getUserOrders({
    page: 1,
    perPage: 10,
    miniappId: app.globalData.miniappId,
    success: (res) => {
        if (res.result === 'success') {
            console.log(res.total, res.orders);
        }
    },
    fail: (err) => console.log('getUserOrders fail', err),
});

{ result, total, page, per_page, orders: [ /* order */ ] }

ft.refundOrder({
    orderId: '1234567orderid',
    amount: 25.0,
    reason: 'Item not available',
    miniappId: app.globalData.miniappId,
    success: (res) => {
        if (res.result === 'success') {
            console.log(res.refundInfo);
        }
    },
    fail: (err) => console.log('refundOrder fail', err),
});

{ result, refundInfo: { /* refund */ } }

ft.getOrderRefunds({
    orderId: '1234567orderid',
    miniappId: app.globalData.miniappId,
    success: (res) => {
        if (res.result === 'success') {
            console.log(res.refunds);
        }
    },
    fail: (err) => console.log('getOrderRefunds fail', err),
});

{ result, refunds: [ /* refund */ ] }

ft.getTicketIssues({
    miniappId: app.globalData.miniappId,
    success: (res) => {
        if (res.result === 'success') {
            console.log(res.issues);   // [ { id, name, code } ]
        }
    },
    fail: (err) => console.log('getTicketIssues fail', err),
});

{ result, issues: [ { id, name, code } ] }

ft.createTicket({
    issueId: 3,
    orderId: '1234567orderid',
    reason: 'The order arrived damaged',
    affectedProducts: [],
    imageFilePath: imagePath,   // from ft.chooseMedia
    miniappId: app.globalData.miniappId,
    success: (res) => {
        if (res.result !== 'success') {
            console.log('createTicket failed', res.message);
            return;
        }
        console.log(res.ticket);
    },
    fail: (err) => console.log('createTicket fail', err),
});

{ result, message, ticket: { /* ticket */ } }

ft.getUserTickets({
    orderId: '1234567orderid',
    miniappId: app.globalData.miniappId,
    page: 1,
    limit: 10,
    success: (res) => {
        if (res.result === 'success') {
            console.log(res.total, res.tickets);
        }
    },
    fail: (err) => console.log('getUserTickets fail', err),
});

{ result, total, page, limit, tickets: [ /* ticket */ ] }

The order object

Returned by getUserOrder (as order) and getUserOrders (in orders).

The refund object

Returned by refundOrder (as refundInfo) and getOrderRefunds (in refunds).

The ticket object

Returned by createTicket (as ticket) and getUserTickets (in tickets).