Direct Integration Model

This section will cover on how to do Direct Integration. Direct Integration model is a host to host integration between GoBizAPI and your system.

By the end of this section, you should be able to obtain

1. App / Client ID
2. App / Client Secret
3. Partner ID
4. Outlet ID

note

Make sure you already obtained those 4 fields from GoBizDevPortal. You'll need them to start integrating with GoBizAPI.

Test Food Integration

In this section, we're going to explain how to do the integration using Postman - feel free to use other tools or doing curl directly from your terminal.

Get Access Token

To see how to do authentication for direct integration, please consult this section

Prepare your App ID & Secret that you have obtained from GoBiz Developer Portal and open your Postman application.

How to get access token using Postman

1. Use [POST][https://integration-goauth.gojekapi.com/oauth2/token](https://integration-goauth.gojekapi.com/oauth2/token) as the endpoint
2. On Authorization, choose Basic Auth type
3. Input your App ID on the Username
4. Input your Secret on the Password
5. On Headers, fill in Content-Type value: application/x-www-form-urlencoded
6. On Body, fill in grant_type value: client_credentials; fill in scope value: gofood:catalog:write gofood:catalog:read gofood:order:write gofood:order:read gofood:outlet:write promo:food_promo:read promo:food_promo:write for GoFood integration scopes.
7. Once you complete the configuration, click Send to receive your access_token. This access_token will be used upon performing API functions according to its purpose. The access_token that you receive will be expired in 3599 seconds, once it's expired you need to perform get access_token again

note

If you're not familiar with Postman and want to do curl instead, please refer to this API Reference

Setup Sync GoFood Menu

Prior to updating your GoFood menu. You'll need to familiarize yourself with the GoFood menu structure first.

Get your existing menu

1. Use [GET][https://api.partner-sandbox.gobiz.co.id/integrations/gofood/outlets/{outlet_id}/v2/catalog](https://api.partner-sandbox.gobiz.co.id/integrations/gofood/outlets/{outlet_id}/v2/catalog) as the endpoint

2. On authorization, choose Bearer Token Type and input your access_token value on Token

   

3. On Headers, fill in Content-Type value: application/json

   

4. Click Send, if you successfully perform the get menu activity, you will receive all current active menus & variant categories on your existing outlet

   

   

   

Update menu

1. Use [PUT] https://api.partner-sandbox.gobiz.co.id/integrations/gofood/outlets/{outlet_id}/v1/catalog as the endpoint

2. On authorization, choose Bearer Token Type and input your access_token value on Token

   

3. On Headers, fill in Content-Type value: application/json

   

4. On Body, fill in your menu structure according to your preference, follow this guideline menu-structure and sync-menu

   

5. Click Send, if the menu structure is correct, then you will receive success response from our system and your menu will be reflected on your testing account

   

Pro Tips

• Check these variables before sending the request

Variable	Description	Tips
external_id	Designated identifier to map Gojek item_id and Partner item_id i.e Cheese Burger on your system has ID B12345 where within Gojek system ID is eyJhbGciO	Use alphanumeric char, max 200 characters
menus.items.name	The name of the menu item to be shown in Gojek consumer app. Sample: "Refreshing Thai Green Tea"	Keep it simple but looks appealing to your customer
menus.items.internal_name	The name of the menu item to be shown in GoBiz app. Sample: "Iced Thai Green Tea".	Keep it simple and understandable for your cashier to identify it
in_stock	Setting menu item stock as available or not available. It's a boolean logic (true or false)
price	Menu item price, always inclusive of tax
image	Menu item image, max size 1 Mb with 1:1 aspect ratio	Make sure image URL is publicly accessible and content-type as image/png
How to use this rule? { "rules": { "selection": { "min_quantity": 1, "max_quantity": 2 }}}	min_quantity The minimum variant that the consumer can select. 0 means that the variant is optional. 1 or more means variant is mandatory, and consumer is required to pick one (or more) variant(s). max_quantity The maximum variant that the consumer can select

• Check if your menu category and menu items reflected correctly
• Check your menu items price - make sure it correctly reflected
• Check if all menu items has image. Image is critical for your menu item.
• Please make sure you only do menu update over API. Please refrain to update menu manually via GoBiz app once you're integrated via API ; updating menu manually via GoBiz post-API integration will make your order unrecognizable.

Setup Webhook Notification (Direct)

Webhooks notification is required for your GoFood order acceptance (GoFood orders flowing directly to your system). You are allowed to subscribe to multiple events (depending on your needs). When you're subscribing to an event (subscription is created) then a Gojek will trigger notification to the URL specified in the notification.

Learn more about notification subscriptions on our API Reference

Please follow this step-by-step instructions on how to subscribe to a webhook notification:

1. Use [POST][https://api.partner-sandbox.gobiz.co.id/integrations/partner/v1/notification-subscriptions](https://api.partner-sandbox.gobiz.co.id/integrations/partner/v1/notification-subscriptions) as the endpoint

2. On authorization, choose Bearer Token Type and input your access_token value on Token

   

3. On Headers, fill in Content-Type value: application/json

   

4. On body, fill:

   1. Event: "[choose an event that you would like to subscribe]" For a detailed notification event list, see this event list

   2. Url: "[fill in your webhook URL for receiving our notifications]"

   3. Active: true

      

5. Send the request, and once it's successful your event subscription is immediately active

   

Handle Webhook Notification Error (Direct)

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

Simulate GoFood Orders

We provide an API Simulator so you can simulate triggering an order on Sandbox without having to use consumer app, driver app and merchant app in Sandbox.

API Simulator will send a notification to your registered webhook URL, so you can see if an order successfully sent to your webhook URL.

Follow these instructions on how to simulate GoFood orders:

1. Fill in your

   1. App ID/Client ID
   2. Partner ID
   3. Outlet ID

   All of this fields can be obtained from GoBiz Developer Portal

   

2. Your menu set will be automatically reflected here - choose the menu, quantity, and order menu notes that you want to simulate

3. Choose the menu variant that you want to simulate

4. Choose the service type you want to simulate. GoFood is for driver delivery flow; GoFood pickup is for consumer self-pickup flow

5. Choose the notification subscription that you want to simulate, you can choose multiple notifications. Make sure that you have already set up the webhook notifications beforehand

6. Click create order to simulate the order. If it's successful, then our emulator provides a successful response and you could see the webhook notification on your registered endpoint.

How to read this response?

• This is the order body response that you will receive on your POS system.
• PIN is required to complete the order. As merchant you need to give the PIN to the driver (on delivery flow) or to consumer (on pickup flow).

Setup 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