> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mogo Gourmet as a data source

> Bring your Mogo Gourmet payments, menu, tables, tabs and cash registers to Nekt.

Mogo Gourmet is a point of sale (POS) and management system for restaurants, bars and food delivery. This connector reads your establishment's data through the Mogo API and brings every payment (your sales, with the items paid), the menu (products and product groups), tables and tabs, payment types, couriers and open cash registers.

> [!NOTE]
>
> The connector only reads data. It never creates, changes or deletes anything in Mogo.

## Before you start

Mogo opens its API to an establishment only after it approves the integration with Nekt. Ask Mogo support to enable the API integration with **Nekt** for your establishment, and to send you these three values:

* **Client Token** (Mogo may call it `tokenCliente`).
* **Software House Token** (Mogo may call it `token_sh`).
* **Database Name** (Mogo may call it `dbname`).

Mogo often sends the three values together, as a single "full token" text in the format `<Client Token>token_sh=<Software House Token>dbname=<Database Name>`, sometimes starting with `Token `. Split it into the three fields like this:

Full token sent by Mogo: `Token CLIENT_TOKENtoken_sh=SOFTWARE_HOUSE_TOKENdbname=DATABASE_NAME`

| Part of the full token | Field in Nekt |
| :- | :- |
| `Token ` at the start, if present | none (leave it out) |
| `CLIENT_TOKEN` (everything before `token_sh=`) | **Client Token** |
| `SOFTWARE_HOUSE_TOKEN` (between `token_sh=` and `dbname=`) | **Software House Token** |
| `DATABASE_NAME` (everything after `dbname=`) | **Database Name** |

Do not include the markers `token_sh=` and `dbname=` themselves in any field.

Mogo generates these values for each server, so each establishment has its own. Also check with Mogo where your Mogo runs:

* **In Mogo's cloud** (`app.mogogourmet.com.br`): nothing else is needed. In the source, choose **Mogo's cloud** in **Where Mogo Runs**.
* **On your establishment's own server** (on-premise; Mogo may call it an offline installation): choose **Establishment's own server** in **Where Mogo Runs**. You also need the **address of the Mogo API on that server, with its port**, for example `https://mogo.yourcompany.com.br:1690`. Ask Mogo support or your IT team for it.

> [!WARNING]
>
> If Mogo runs on your own server, the server must be reachable from the internet and its firewall must accept connections from Nekt's IP addresses: `34.24.209.97`, `34.74.81.117` and `34.138.230.39`. These are the addresses of Nekt Express. If your Nekt workspace runs on your own cloud account (GCP or AWS), ask Nekt support for the addresses to allow.

## Configuring Mogo Gourmet as a Source

In the [Sources](https://app.nekt.ai/sources) tab, click on the "Add source" button located on the top right of your screen. Then, select the Mogo Gourmet option from the list of connectors.

Click **Next** and you'll be prompted to add your access.

### 1. Add account access

The following configurations are available:

* **Client Token**: the integration token of your establishment, given by Mogo. If Mogo sent a single full token, see [how to split it](#before-you-start).
* **Software House Token**: the integration token Mogo generated for this establishment's integration with Nekt.
* **Database Name**: the name of your establishment's database in Mogo, given by Mogo together with the tokens.
* **Where Mogo Runs**: choose where your establishment's Mogo is installed (see [Before you start](#before-you-start)).
  * **Mogo's cloud (app.mogogourmet.com.br)**, the default: nothing else to fill in. The two fields below do not appear.
  * **Establishment's own server (on-premise)**: the **API Address** field appears, and the **Verify SSL Certificate** option appears in the advanced settings.
* **API Address** (only for the establishment's own server, required there): the address of the Mogo API on that server, with the port, for example `http://mogo.yourcompany.com.br:1690` or `https://mogo.yourcompany.com.br:1692`. Use only the address, without the database name, a path, user, password or parameters.
* **Start Date**: the earliest payment and order date synced. The other tables (products, tables, payment types and so on) are always read in full.
* **Verify SSL Certificate** (advanced, only for the establishment's own server, on by default): keep it on. Turn it off only when the API Address is `https` and that server uses a self-signed certificate. With it off, the connection stays encrypted, but the server's identity is not checked. Sources on Mogo's cloud always verify the certificate.

> [!NOTE]
>
> One source reads one establishment (one Mogo database). If you have more than one establishment, create one source for each, with its own tokens, Database Name and, on your own servers, its own API Address. On one server, each database usually has its own port.

> [!TIP]
>
> Prefer an `https` address. An `http` address works, but the tokens and your data travel between the Mogo server and Nekt without encryption, and each sync log shows a warning. If your server only answers `http`, ask your IT team or Mogo support to enable `https`.

Once you're done, click **Next**.

### 2. Select streams

Choose which data streams you want to sync. For faster extractions, select only the streams that are relevant to your analysis. You can select entire groups of streams or pick specific ones.

> Tip: The stream can be found more easily by typing its name.

**Orders** and **Product subgroups** are not selected by default (see [Available streams](#available-streams)). Select them only if they apply to your establishment.

Select the streams and click **Next**.

### 3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

* **Layer**: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
* **Folder**: a folder can be created inside the selected layer to group all tables being created from this new data source.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** to all tables at once and make this process faster!
* **Sync Type**: keep the suggested type. Payments and Orders are **Incremental**: each sync reads only the last days and merges them into the table. The other tables are **Full table**: Mogo gives no change date for them, so each sync reads them whole and replaces the table.

Once you are done configuring, click **Next**.

### 4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers.md), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times). Payments are read incrementally, so an hourly or daily sync works well.

Optionally, you can determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. A weekly full sync is recommended: it rebuilds the Payments table with Mogo's current report, which removes payments deleted or reversed in Mogo (see [Implementation Notes](#implementation-notes)).

Optionally, you can configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource [here](https://docs.nekt.com/get-started/core-concepts/resource-control).

Once you are ready, click **Next** to finalize the setup.

### 5. Check your new source

You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.

> [!WARNING]
>
> For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.

# Streams and Fields

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Sync | Description |
| - | - | - | - |
| Establishment | `establishment` | Full table | The establishment of the source, from its Mogo database. |
| Products | `products` | Full table | Products on the menu, with price, group and subgroup. |
| Product groups | `product_groups` | Full table | Groups that organize the products on the menu (for example, food and drinks). |
| Product subgroups | `product_subgroups` | Full table | Subgroups inside the product groups. **Not selected by default**: Mogo's API currently answers this table with an error. |
| Payment types | `payment_types` | Full table | Payment types accepted by the establishment and their card brands. |
| Couriers | `couriers` | Full table | Active delivery couriers. |
| Tables | `tables` | Full table | Tables of the restaurant and their situation when the sync ran. |
| Tabs | `tabs` | Full table | Every tab (comanda or card) and its situation when the sync ran. |
| Open cash registers | `open_cash_registers` | Full table | Cash registers open when the sync ran. |
| Orders | `orders` | Incremental | Orders created through Mogo's API or integrations only. **Not selected by default**: orders typed in the point of sale are not included. |
| Payments | `payments` | Incremental | Every payment from Mogo's payment report, with the items paid. This is the table of your sales. |

Use **Payments** for your sales. Join `payments.payment_type` with `payment_types.description`, and `products.group_id` with `product_groups.id`.

## Fields by stream

Fields marked String (JSON) hold a nested list as JSON text; use your warehouse's JSON functions to read them. Dates and times are the establishment's local date and time, as Mogo records them, with no time zone. Amounts are in BRL.

> [accordion] Establishment
>
> The establishment (restaurant) of the source, from its Mogo database.
>
> Table: `establishment` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Identifier of the establishment in its Mogo database. |
> | `trading_name` | String | Trading name (nome fantasia) of the establishment. |
> | `company_name` | String | Legal name (razão social) of the establishment. |
> | `active` | Boolean | Whether the establishment is active in Mogo. |

> [accordion] Products
>
> Products on the menu, with price, group and subgroup.
>
> Table: `products` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Identifier of the product. |
> | `description` | String | Name of the product as shown on the menu. |
> | `price` | Number | Sale price of the product, in BRL. |
> | `group_id` | Integer | Identifier of the product group (see `product_groups`). |
> | `subgroup_id` | Integer | Identifier of the product subgroup (see `product_subgroups`). |
> | `code` | String | Internal code of the product, when set. |
> | `barcode` | String | Barcode (EAN) of the product, when set. |
> | `display_order` | Integer | Position of the product in the menu. |
> | `available_to_waiters` | Boolean | Whether the product is sent to the waiter app. |
> | `opens_edit_on_add` | Boolean | Whether adding the product opens its edit screen automatically (to pick add-ons or notes). |
> | `sold_by_weight` | Boolean | Whether the product is weighed on a scale. |
> | `uses_flavors` | Boolean | Whether the product is assembled from flavors (for example, pizza). |
> | `prints_production_ticket_on_pos` | Boolean | Whether the production ticket is printed on the POS terminal. |
> | `no_service_fee` | Boolean | Whether the product is exempt from the service fee. |
> | `image_url` | String | URL of the product image, empty when there is none. |
> | `min_add_ons` | Integer | Minimum number of add-ons the customer must choose. |
> | `max_add_ons` | Integer | Maximum number of add-ons the customer may choose. |

> [accordion] Product groups
>
> Groups that organize the products on the menu.
>
> Table: `product_groups` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Identifier of the product group. |
> | `description` | String | Name of the product group. |
> | `display_order` | Integer | Position of the group in the menu. |

> [accordion] Product subgroups
>
> Subgroups inside the product groups. Not selected by default: Mogo's API currently answers this table with an error. If you select it, it shows as failed with Mogo's message until Mogo fixes it.
>
> Table: `product_subgroups` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Identifier of the product subgroup. |
> | `description` | String | Name of the product subgroup. |
> | `group_id` | Integer | Identifier of the product group the subgroup belongs to (0 when none). |

> [accordion] Payment types
>
> Payment types accepted by the establishment and the card brands of each one.
>
> Table: `payment_types` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Identifier of the payment type. |
> | `description` | String | Name of the payment type (for example, Dinheiro, PIX, Cartão Crédito). |
> | `prefix` | String | Short code of the payment type (for example, DIN, PIX, CRCR, CRDE). |
> | `card_brands` | String (JSON) | Card brands accepted for this payment type, as a list of objects with `Id` and `Description`. |

> [accordion] Couriers
>
> Active delivery couriers. The table is empty when the establishment has no active courier.
>
> Table: `couriers` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Identifier of the courier. |
> | `name` | String | Name of the courier. |

> [accordion] Tables
>
> Tables of the restaurant and their situation when the sync ran.
>
> Table: `tables` · Primary key: `id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Identifier of the table. |
> | `number` | String | Number or name of the table as shown in the POS. |
> | `status` | String | Situation of the table when the sync ran (for example, Disponivel, Ocupada). |
> | `status_title` | String | Status text the POS shows for the table. |
> | `in_payment` | Boolean | Whether the table was being paid when the sync ran. |
> | `seats` | Integer | Number of seats at the table. |
> | `opened_at_text` | String | When the table was opened, as Mogo shows it (empty when the table is free). |
> | `area` | String | Area (quadrant) of the restaurant the table belongs to. |
> | `inactivity_status` | Integer | Inactivity status code of the table, as Mogo reports it. |
> | `joined_table_id` | String | Table this one is joined to, when tables are combined. |
> | `joined_table_description` | String | Description of the joined table, when tables are combined. |

> [accordion] Tabs
>
> Every tab (comanda or card) of the establishment and its situation when the sync ran.
>
> Table: `tabs` · Primary key: `tab_id` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `tab_id` | String | Identifier of the tab (comanda or card), for example C0001. |
> | `status` | String | Situation of the tab when the sync ran (Disponivel, Ocupado, Cancelado). |

> [accordion] Open cash registers
>
> Cash registers that were open when the sync ran. The table is empty when no cash register is open. Mogo does not list cash registers open for more than 2 days.
>
> Table: `open_cash_registers` · Primary key: `cash_register`, `employee_id`, `opened_on` · Sync: Full table
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `cash_register` | String | Name of the open cash register. |
> | `employee_id` | Integer | Identifier of the employee who opened the cash register. |
> | `employee_name` | String | Name of the employee who opened the cash register. |
> | `opened_on` | Date | Date the cash register was opened (local date of the establishment). |

> [accordion] Orders
>
> Order headers (one row per order, without items), by order date. Not selected by default: Mogo's order search returns only orders created through Mogo's API or integrations, never orders typed in the point of sale. Select it only if your establishment takes orders through an integration. Use Payments for every sale.
>
> Table: `orders` · Primary key: `id` · Sync: Incremental (`order_date`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | Integer | Identifier of the order in Mogo. |
> | `order_number` | String | Order number shown in the POS and on receipts. |
> | `order_date` | Date | Local date of the order; used as the incremental replication key. |
> | `order_time` | String | Local time of the order (HH:MM:SS, establishment time, no time zone). |
> | `customer_name` | String | Name of the customer, when informed. |
> | `total_amount` | Number | Total amount of the order, in BRL. |
> | `status` | String | Status of the order (for example, Aberto, Pago, Cancelado). |
> | `delivery_status` | String | Delivery status (for example, Pendente, Entregando, Entregue). |
> | `order_type` | String | Type of order (for example, Entrega, Balcao, Mesa, Cartao). |

> [accordion] Payments
>
> Every payment from Mogo's payment report, by payment date, with the items paid. This is the table of your sales.
>
> Table: `payments` · Primary key: `payment_key` · Sync: Incremental (`payment_date`)
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `payment_key` | String | Key of the payment row, built by Nekt from the order, payment date and time, plus a sequence number when one order has several payments at the same second (Mogo sends no id for these rows). |
> | `order_id` | Integer | Identifier of the order the payment belongs to. |
> | `order_number` | String | Order number shown in the POS and on receipts. |
> | `payment_date` | Date | Local date of the payment; used as the incremental replication key. |
> | `payment_time` | String | Local time of the payment (HH:MM:SS, establishment time, no time zone). |
> | `cash_register_date` | Date | Opening date of the cash register session the payment belongs to, when Mogo informs it. |
> | `payment_type` | String | Payment type (see `payment_types.description`), for example Dinheiro, PIX, Cartão Crédito. |
> | `amount` | Number | Amount paid, without the service fee, in BRL. |
> | `service_fee` | Number | Service fee included in this payment, in BRL. |
> | `total_amount` | Number | Total of this payment (amount plus service fee), in BRL. |
> | `table` | String | Table the order was served at, empty when none. |
> | `tab` | String | Tab (comanda or card) of the order, empty when none. |
> | `customer_name` | String | Name of the customer, when informed (Mogo may append " - Inativo" to inactive customers). |
> | `user_name` | String | Mogo user who registered the payment, when informed. |
> | `paid_items_text` | String | Items paid, as Mogo sends them: `quantity\|description` pairs separated by `\|`. |
> | `paid_items` | String (JSON) | Items paid, read from `paid_items_text`, as a list of objects with `quantity` and `description`; empty when the text could not be split into pairs. |

## Implementation Notes

### Data Quality Considerations

* **Payments is the table of your sales.** Mogo's order search (the Orders table) returns only orders created through Mogo's API or integrations, so most establishments get no orders there. Every sale made in the point of sale is in Payments.
* **How payments and orders stay up to date.** They are read day by day, by the local date of the payment or order. Each sync reads the last 3 days again, so late payments and corrections are picked up. Orders still open are read again on the next syncs until they are closed, for up to 30 days.
* **Long first syncs are saved in steps of 30 days.** If a first sync over a long period stops with an error, the days already read are kept and the next sync continues from there.
* **Payments have no id in Mogo.** Nekt builds the `payment_key` column from the order and the payment date and time. A payment corrected in Mogo within the last 3 days (a different payment type, amount, table or tab) is updated in place.
* **A payment deleted or reversed in Mogo stays in the Payments table**, because Mogo's report gives no signal of removed payments. The same happens to the old row of a payment whose time was changed in Mogo. A full sync rebuilds the table with Mogo's current report; schedule a weekly **Additional Full Sync** to keep it in line.
* **Orders changed after 3 days are not updated** (for example, a paid order cancelled a week later), except orders still open. A full sync updates them.
* **Product subgroups** is not selected by default because Mogo's API currently answers it with an error. If you select it, it shows as failed with Mogo's message until Mogo fixes it. The other tables keep syncing.
* **Open cash registers**: Mogo does not list cash registers that have been open for more than 2 days. When that happens, the sync log shows Mogo's notice.
* **Permissions**: each table needs Mogo to allow it for your establishment's integration. If Mogo refuses one of them, that table is skipped and not updated, the other tables keep syncing, and the sync log says which table was skipped.
* **Full table tables are never half updated.** The connector reads all the data of a full table table before writing any of it. If Mogo fails while it is read, nothing of that table is sent and the sync shows it as failed. On GCP (BigQuery) the table keeps its previous content; on AWS, a full table table whose stream failed may be emptied by the load step until the next successful sync.

### API Limits & Performance

* Mogo does not publish a request limit. The connector waits a quarter of a second between requests and, when Mogo asks it to slow down, waits and tells you in the sync log.
* Payments and orders are read one day per request. The first sync makes one request per day since the Start Date for each of these tables (about 365 requests for one year), so choose a Start Date that keeps it manageable.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "Mogo rejected the credentials of this source" | Mogo refused the Client Token, the Software House Token or the Database Name, or the source reads from the wrong place: Mogo's cloud for an establishment whose Mogo runs on its own server, or another store's API Address. Mogo gives the same answer for any of them. | If Mogo runs on your own server, edit the source, choose **Establishment's own server** in **Where Mogo Runs** and enter that store's API Address: tokens generated on your own server never work on Mogo's cloud. Otherwise, check the three values with Mogo support. If they are correct, the integration with Nekt may not be approved yet for this establishment: ask Mogo support to confirm it. |
| "Could not connect to the Mogo API at ..." | Nekt could not reach the API Address. | Check the address (`http` or `https`, host and port) and that the Mogo server is on. On your own server, check that its firewall accepts connections from Nekt's IP addresses (see [Before you start](#before-you-start)). |
| "The Mogo server at ... presented a certificate that is not trusted" | The server's `https` certificate is self-signed, expired or issued for another name, so Nekt did not send the credentials. | Ask the server's administrator to install a valid certificate. Only for your establishment's own server with a self-signed certificate, you can turn off the advanced option **Verify SSL Certificate**. Never turn it off for Mogo's cloud. |
| "The Mogo API address of this source is not valid" | The API Address is not a web address Nekt can use: it has a path, user, password or parameters, or it is a local network address (such as `192.168.x.x` or `localhost`). | Use only the address of the Mogo API, for example `https://mogo.yourcompany.com.br:1690`. The server must be reachable from the internet. |
| "This source is set to read from the establishment's own Mogo server, but it has no API Address" | **Where Mogo Runs** is set to the establishment's own server and the API Address is empty. | Edit the source and enter the store's API Address with the port, or choose Mogo's cloud if that is where your Mogo runs. |
| "The Mogo API address of this source uses http, without encryption" | The source works, but the tokens and your data travel without encryption. | Enable `https` on the Mogo server and update the API Address. |
| "Certificate verification is off for this source" | The advanced option **Verify SSL Certificate** is off. | Keep it off only for your establishment's own server with a self-signed certificate. |
| "Mogo did not allow this source's integration to read ..." | Mogo refused one table for your establishment's integration. That table was skipped and not updated; the other tables loaded. | Ask Mogo support to enable that data for your establishment's integration with Nekt, or deselect the table. |
| "Mogo did not allow this source's integration to read any of the selected tables" | Mogo refused every selected table, so nothing was synced. | Ask Mogo support to confirm the API integration with Nekt is enabled for your establishment. |
| "Mogo returned an error while reading ... (Mogo said: '...')" | Mogo answered that table with an error message. Product subgroups currently fails like this. | Deselect the table, or ask Mogo support about the message. If it repeats on other tables, contact Nekt support. |
| "Mogo reported about the open cash registers" | Some cash registers have been open for more than 2 days, and Mogo does not list them. | No action needed. The table lists only the cash registers open for 2 days or less. |
| "This source has no Mogo Client Token" (or Software House Token, or Database Name) | A required value is empty in the source configuration. | Add the value Mogo gave for your establishment. |
| "The Start Date of this source is missing or not a valid date" or "...is in the future" | The Start Date cannot be used. | Set a past date in the source configuration. |
| "The Mogo API asked Nekt to slow down" | Mogo limited how fast the sync may read. | No action needed; the sync waits and continues. |
| "The Mogo API is answering with server errors right now" or "The Mogo API kept failing" | Mogo did not answer, or answered with errors, after several attempts. | Usually temporary; the next sync tries again. If it repeats, contact Nekt support. |
| "The Mogo API answered in an unexpected way" or "Some amounts ... could not be read" | The Mogo API changed or answered in an unexpected way. | Contact Nekt support. |

## Skills for agents

<Snippet file="agent-skills-intro.mdx" />

> [card] [Download Mogo Gourmet skills file](https://docs.nekt.com/sources/mogo-gourmet.md)
>
> Mogo Gourmet connector documentation as plain markdown, for use in AI agent contexts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.