Facilitator Model

Getting started (Facilitator)

To extend our API to broader segment, we now introduce Facilitator Model integration. It’s a capability that enable Food API integration to POS (Point of Sales) or OFA (Online Food Aggregator) services. If you’re a POS players and want to integrate to GoFood, please follow these guidelines to ease your integration.

Prior to doing integration, you need to be a GoBiz Partners. If you’re not a GoBiz Partners and want to do integration with us, Please reach out to us using this form.

Prior to integration, there are some pre-requisite requirements

You need to get credential with this scopes

• openid
• offline
• partner:outlet:read ; partner:outlet:write
• gofood:catalog:read ; gofood:catalog:write
• gofood:order:read ; gofood:order:write
• gofood:outlet:write

How to obtain credential?

• Contact us via this form and register yourself as GoBiz Partners
• Our team will contact you to explore your inquiry and perform further assessment
• Once you’ve completed our assessment, you’ll be able to get the credential from our team

Authentication

GoBiz is using standard OAuth2.0 authentication for integration with all of our partners. To complete the authentication process, the client must authorize itself to Gojek OAuth2 server. Consult this section for better understanding on how to do authentication

Linking Outlet

1. Perform an auth mechanism to get auth code from your merchants, and exchange it to access token - see this step by step guideline

   1. Hit POST https://accounts.go-jek.com/oauth2/token to show GoBiz login page.

   2. From merchant point of view, this is the flow that they will get on their side

      1. User enters phone number
      2. System sends OTP to user phone number
      3. User inserts OTP
      4. System shows consent page to inform user what are data points that being accessible to partner
      5. User to click “Allow” or “Deny”

      

   3. When user click Allow, it means user successfully authenticates with system and authorizes the client to access information, system will generate an authorization code and redirect the user to redirect_uri with the code and the state that was originally sent by the client. On receiving this callback, client should verify the state parameter and ensure the value is same as the one sent by the client in previous step.

   4. The code returned in the previous step is one-time use only and is short-lived (no more than 2 minutes after receiving the redirection). Client should exchange this code to receive an access token.

2. Link outlet ; you need to link your outlet so you can enable webhook notifications. This is the process to associate between your POS ID to GoBiz ID, so order notification can be relayed to correct outlet ID. Use the access token and call PUT /integrations/partner/outlets/{outlet_id}/v1/link/gofood

Manage Menu / Catalog Update

Prior to making call on catalog update endpoint, please make sure you understand how GoFood Menu is being structured - see this section for details

Get existing Menu

This step can be useful for your merchant to fetch all existing menu on their GoFood, merchant later can utilize it to decide which menu they want to update.

Please mind that you can also hit update menu directly, without having to get existing menu.

Use [GET] https://api.partner-sandbox.gobiz.co.id/integrations/gofood/outlets/{outlet_id}/v2/catalog as the endpoint When you get success response, you will receive all current active menus & variant categories on your existing outlet See this section for request & response detail

Update Menu

Use this endpoint to update your GoFood menu, please note that this is an overwrite operation, it means that menu and variants will be shown based on its latest API call.

1. Use [PUT] https://api.partner-sandbox.gobiz.co.id/integrations/gofood/outlets/{outlet_id}/v1/catalog as the endpoint
2. When you get success response, you’ll see your menu being reflected on your testing account
3. See this section for request & response detail

Manage SKU promo

You can setup SKU Promo on your menu item using API. See this section to understand more on how to setup SKU Promo

Setup Webhook Notification (Facilitator)

In order to enable GoFood order relayed to your system, you need to subscribe to our webhooks. When you’re subscribing to an event (subscription is created) then a Gojek will trigger notification to the URL that you specified in the notification.

Learn more about it here

Handle Webhook Notification Error (Facilitator)

Sometimes webhook notifications might not be sent properly to you. So in order to compensate for this we are sending Error notification each time the order notification can’t be sent, we are sending this Order Webhook Error Event so that you can identify the problem and react accordingly. To get this information, please subscribe to this event. This is the case that usually happens and created error

• Missing Menu Mapping
  How to handle:
  When there are error notification sent containing error type “missing_menu_mapping” you can handle this with notification to merchant saying that they are missing their menu mapping and they need to resync the menu via API so that future order won’t have this problem anymore

Sample Response

Sample Response of Missing Menu mapping

{
  "body": {
    "error_type": "mapping_not_found",
    "mapping_not_found": {
      "items": [],
      "variants": [
        {
          "name": "Paha atas"
        },
        {
          "name": "Paha bawah"
        }
      ]
    },
    "order": {
      "number": "F-12345678"
    },
    "outlet": {
      "external_outlet_id": "external-outlet-id",
      "id": "G12345678"
    }
  },
  "header": {
    "event_type": "gofood.order.webhook_error",
    "event_id": "67235bd0-c963-4c32-aca1-27a52ec963e5",
    "version": 1,
    "timestamp": "2023-03-29T14:15:22Z"
  }
}

There are several field to be checked:

• Error Type: this is what makes the order notification can’t be sent. Currently only have "mapping_not_found". This error means that you need to resync your menu via API
• Items & Variants: this specify which item / variants that missing the mapping since it doesn’t have any external id inside
• Order Number: this specify which order number the error belongs to