> ## 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.
# Lomadee as a data source
> Bring data from Lomadee to Nekt.
Lomadee is one of Latin America's largest affiliate networks: brands pay commission to affiliates for the orders their links and coupons generate. This connector reads either side of the network. As an **affiliate**, you bring your orders and commissions, your short links and their clicks, and the catalog of brands, campaigns and products you promote. As a **brand**, you bring the orders your affiliates generated and the affiliates of your program.
## Before you start
Lomadee has one API for each side of the network, and each side has its own key. Pick the side your Lomadee account is on and create the matching key.
### If you are an affiliate
In the Lomadee panel, open the **Chaves de API** page.
Click **Criar chave de API**, give it a name (for example *Nekt*) and select the permissions for the tables you want: **Pedidos**, **Marcas**, **Campanhas**, **Canais**, **Produtos** and **Encurtador (leitura)**.
The key is shown **only once**. Copy it before closing the window. A new key may show the status *Em análise* until Lomadee approves it.
A table whose permission the key does not have is skipped and reported in the run, and every other table still syncs. To add it later, create a new key with that permission and update the source.
### If you are a brand
In the Lomadee panel, go to **Configurações » Integrações**.
Under **Dados da integração por SDK**, copy the **Chave de API**.
If your brand panel has no **Dados da integração por SDK** section, your brand does not have API access enabled yet. Ask your Lomadee contact to enable the SDK integration for your brand, then copy the key.
## Configuring Lomadee as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click the "Add source" button in the top-right corner, then select Lomadee from the list of connectors.
Click **Next** and add your access details.
### 1. Add account access
The following configuration fields are available:
* **Account type**: **Affiliate** if you promote brands and earn commission, or **Brand** if you run an affiliate program on Lomadee. It decides which tables the source offers.
* **API key**: The key you copied in [Before you start](#before-you-start). An affiliate key does not work on a brand source, and the other way around.
* **Initial sync date** (advanced, affiliates only): The earliest order date read by the **Orders** table on the first run. Later runs continue from where the previous one stopped. Leave it empty to read your full order history.
* **Lookback window (days)** (advanced, affiliates only): How many days before the last synced order every run reads again, so status and commission changes are picked up while the brand validates an order. Defaults to 90.
* **Include expired campaigns** (advanced, affiliates only): Also read campaigns whose period has ended. By default only running and scheduled campaigns are read.
* **Product brand IDs** (advanced, affiliates only): Comma-separated ids of the brands whose products to read, taken from the `id` column of the **Brands** table. Leave it empty to read the whole catalog.
* **Requests per minute** (advanced): Maximum number of API calls per minute. Lomadee allows 60 per key; the default of 50 leaves room for other integrations that use the same key.
After configuring access, click **Next**.
### 2. Select streams
Choose which data streams you want to sync. For faster extractions, select only the ones relevant to your analysis.
> Tip: The stream can be found more easily by typing its name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how data should appear in your Catalog, including layer, table naming, and sync type.
* **Layer**: Select the destination layer where extracted tables will be created.
* **Folder**: A folder can be created inside the selected layer to group all tables from this source.
* **Table name**: Use the suggested name or customize it. You can also apply a prefix to all tables at once.
* **Sync Type**: Choose between `INCREMENTAL` and `FULL_TABLE`. See [Sync types](#sync-types): only the affiliate **Orders** table supports `INCREMENTAL`.
When you're done, click **Next**.
### 4. Configure data source
Add a clear description for this source so your team can identify it easily, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), choose how often data should be extracted (for example, daily, weekly, or at fixed times).
Optionally, configure additional settings:
* Delta Log Retention, which controls how long old table states are kept. Learn more [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync), to periodically complement incremental runs with a complete refresh.
When you are ready, click **Next** to finalize setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, trigger a run manually from the source actions.
To see data in the [Catalog](https://app.nekt.ai/catalog), at least one source run must complete successfully.
## Sync types
The affiliate **Orders** table is the only one that syncs incrementally. It is the only Lomadee listing that filters by date, so each run reads the orders created since the last one — plus the lookback window, because an order's status and commission keep changing for weeks while the brand validates it.
Every other table is read in full on every run. Lomadee offers no "modified since" filter on them, so a full read is what keeps the Catalog equal to Lomadee. That includes the brand **Orders** table, whose endpoint has no date filter at all.
## Good to know
* **Two sides, two sets of tables.** An affiliate source offers Orders, Brands, Campaigns, Channels, Products and Short links. A brand source offers Orders and Affiliates. Both have an Orders table, with different columns, because each side sees the order differently.
* **Order statuses change after the sale.** An affiliate order starts as `pending` and becomes `approved`, `rejected` or `repproved` once the brand validates it, and `commission_status` follows. The lookback window is what brings those updates in.
* **The full order is always kept.** Both Orders tables carry a `raw_payload` column with the complete record exactly as Lomadee returned it, including any field that has no column of its own.
* **Brand order values follow your integration.** Brand order values are stored exactly as your store's integration sent them to Lomadee. The Lomadee pixel sends them in cents — `157490` is R\$ 1.574,90 — so divide by 100 in a [Query](https://docs.nekt.com/queries/overview) if that is how your integration works.
* **Nested data is JSON text.** Order items, value breakdowns, product variants and similar lists are stored as JSON arrays. Parse them in a Query or Notebook when you need one row per item.
* **Products can be a large table.** It holds the catalog of every brand you can promote. Use **Product brand IDs** to limit it to the brands you work with.
* **A product id is unique per brand.** Two brands can use the same product id, so the key of the Products table is `organization_id` plus `id`.
* **Channels are capped at 20.** Lomadee returns at most 20 channels per account; if you have more, the run says so.
* **Short links include inactive ones.** The table holds both active and deactivated links, with their click counts; filter on `active` when you need only the live ones.
* **Rate limit.** Lomadee allows 60 requests per minute per key. The connector paces itself below it and waits automatically if Lomadee asks it to slow down, so a large first sync takes a while but loses no data.
# Streams and Fields
## Affiliate account
| Stream | Slug | Description |
| ----------- | ------------- | ----------------------------------------------------------------------------------- |
| Orders | `orders` | Orders your links and coupons generated, with their value, status and commission. |
| Brands | `brands` | Brands you can promote, with the commission they pay and their ratings. |
| Campaigns | `campaigns` | Offers and coupons the brands publish, with their period and links. |
| Channels | `channels` | Your own promotion channels, such as a blog or a push list. |
| Products | `products` | The product catalog of the brands you can promote, with variants, prices and stock. |
| Short links | `short_links` | Short links you generated, with their click counts. |
| Field | Type | Description |
| :------------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | String | Unique identifier of the order in the Lomadee network. |
| `order_id` | String | Identifier of the order in the brand's own store system. |
| `organization_id` | String | Identifier of the brand the order was placed with. |
| `status` | String | Status of the order: pending, approved, rejected or repproved. |
| `value` | Number | Total value of the order, exactly as reported by Lomadee. |
| `commission` | Number | Commission the affiliate earns on the order, exactly as reported by Lomadee. |
| `commission_status` | String | Status of the commission: pending while the brand validates the order, then approved, rejected or repproved. |
| `mdasc` | String | Custom tracking identifier the affiliate appended to the link (the mdasc parameter), used to attribute the order to a campaign or placement. |
| `items` | String | Items of the order, each with its id, name, quantity and price (JSON array of objects). |
| `created_at` | Date | Date and time the order was created, used as the incremental replication key. |
| `raw_payload` | String | The complete order record exactly as Lomadee returned it (JSON object), including any field that has no column of its own. |
| Field | Type | Description |
| :-------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------ |
| `id` | String | Unique identifier of the brand (its organization id). |
| `name` | String | Name of the brand. |
| `slug` | String | URL-friendly slug of the brand. |
| `logo` | String | URL of the brand's logo. |
| `site` | String | URL of the brand's website. |
| `segment` | String | Market segment the brand belongs to. |
| `network_active` | Boolean | Whether the brand is active on the Lomadee network. |
| `network_is_public` | Boolean | Whether the brand is public on the network or restricted to approved affiliates. |
| `is_exclusive` | Boolean | Whether the brand is exclusive to Lomadee. |
| `is_highlight` | Boolean | Whether Lomadee highlights the brand. |
| `is_favorite` | Boolean | Whether the affiliate marked the brand as a favourite. |
| `rating_approval` | Number | Approval rate of the brand, from 0 to 5. |
| `rating_commission` | Number | Commission rating of the brand, in percent. |
| `rating_conversion` | Number | Conversion rate of the brand, in percent. |
| `rating_popularity` | Number | Popularity index of the brand, from 0 to 100. |
| `rating_validation` | Number | Order validation rate of the brand, from 0 to 5. |
| `commission_value` | Number | Commission the brand pays the affiliate, in percent of the order value. |
| `commission_transfer` | String | Commission payment model, such as cpa (cost per action). |
| `channels` | String | The affiliate's channels for this brand, each with its short links or the restriction that blocks them (JSON array of objects). |
| `created_at` | Date | Date and time the brand joined the network. |
| Field | Type | Description |
| :---------------- | :------ | :----------------------------------------------------------------------------------------------------- |
| `id` | String | Unique identifier of the campaign (its operation id, used to generate links). |
| `name` | String | Name of the campaign. |
| `type` | String | Kind of campaign: PersonalCoupon, GenericCoupon or Offer. |
| `offer_type` | String | For offers, how the offer is delivered: Url or Spreadsheet. |
| `description` | String | Description of the campaign. |
| `code` | String | Coupon code of the campaign, when it is a coupon. |
| `url` | String | Landing page URL of the campaign. |
| `organization_id` | String | Identifier of the brand the campaign belongs to. |
| `is_highlight` | Boolean | Whether Lomadee highlights the campaign. |
| `status` | String | Status derived from the campaign period: onTime (running), scheduled (not started) or expired (ended). |
| `period_start_at` | Date | Start of the campaign period; empty for a permanent campaign. |
| `period_end_at` | Date | End of the campaign period; empty for a permanent campaign. |
| `categories` | String | Categories of the campaign (JSON array). |
| `channels` | String | The affiliate's channels for this campaign, each with its short links (JSON array of objects). |
| `media_kit` | String | Marketing material of the campaign, such as banner URLs (JSON object). |
| `created_at` | Date | Date and time the campaign was created. |
| Field | Type | Description |
| :----------- | :------ | :----------------------------------------------------- |
| `id` | String | Unique identifier of the channel. |
| `name` | String | Type of the channel, such as Blog or PushNotification. |
| `active` | Boolean | Whether the channel is active. |
| `created_at` | Date | Date and time the channel was created. |
| Field | Type | Description |
| :---------------- | :------ | :----------------------------------------------------------------------------------------------------- |
| `organization_id` | String | Identifier of the brand that sells the product. |
| `id` | String | Identifier of the product in the brand's catalog (unique per brand). |
| `object_id` | String | Internal Lomadee identifier of the catalog entry. |
| `name` | String | Name of the product. |
| `description` | String | Description of the product (HTML). |
| `url` | String | URL of the product page in the brand's store. |
| `available` | Boolean | Whether the product is available for sale. |
| `integration` | String | E-commerce platform the product was imported from, such as vtex. |
| `images` | String | Images of the product (JSON array of objects). |
| `options` | String | Variants of the product, each with its EAN, seller, prices in cents and stock (JSON array of objects). |
| `metadata` | String | Additional product data (JSON array). |
| `created_at` | Date | Date and time the product entered the catalog. |
| `updated_at` | Date | Date and time the product was last updated. |
| Field | Type | Description |
| :---------------- | :------ | :----------------------------------------------------------- |
| `url_code` | String | Unique code of the short link, the last part of its URL. |
| `short_url` | String | The short link itself. |
| `original_url` | String | The URL the short link redirects to. |
| `organization_id` | String | Identifier of the brand the link points to. |
| `link_type` | String | What the link points to: Coupon, Offer, BrandPage or Custom. |
| `active` | Boolean | Whether the short link is active. |
| `click_count` | Integer | Number of clicks the short link received. |
| `created_at` | Date | Date and time the short link was created. |
| `updated_at` | Date | Date and time the short link was last updated. |
## Brand account
| Stream | Slug | Description |
| ---------- | ------------ | ------------------------------------------------------------------------------ |
| Orders | `orders` | Orders attributed to your affiliates, with their value breakdown and customer. |
| Affiliates | `affiliates` | Affiliates of your program, with their invitation status and profile. |
| Field | Type | Description |
| :----------------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------- |
| `id` | String | Unique identifier of the order in Lomadee. |
| `order_id` | String | Identifier of the order in the brand's own store system. |
| `status` | String | Status of the order: Pending, Approved, Reproved or Canceled. |
| `value` | Number | Total value of the order as the brand's integration sent it; the Lomadee pixel sends values in cents (157490 is R\$ 1,574.90). |
| `items_value` | Number | Total value of the order's products, in the same unit as value (the Items sub- item). |
| `shipping_value` | Number | Shipping charged on the order, in the same unit as value (the Shipping sub-item). |
| `discounts_value` | Number | Discounts applied to the order, as a negative number in the same unit as value (the Discounts sub-item). |
| `coupon` | String | Coupon code used on the order, if any. |
| `affiliate_id` | String | Identifier of the affiliate the order is attributed to. |
| `channel_id` | String | Identifier of the affiliate channel the order came through. |
| `group` | String | Grouping label the brand attached to the order. |
| `customer_id` | String | Identifier of the customer in the brand's store. |
| `customer_email` | String | E-mail address of the customer. |
| `customer_first_name` | String | First name of the customer. |
| `customer_last_name` | String | Last name of the customer. |
| `customer_document_type` | String | Type of the customer's document, such as CPF or CNPJ. |
| `customer_document` | String | Document number of the customer. |
| `customer_phone` | String | Phone number of the customer. |
| `items` | String | Products of the order, each with its id, name, image, price, list price and quantity (JSON array of objects). |
| `sub_items` | String | Breakdown of the order value into Items, Shipping, Discounts and other entries (JSON array of objects). |
| `created_at` | Date | Date and time the order was registered in Lomadee. |
| `updated_at` | Date | Date and time the order was last updated. |
| `raw_payload` | String | The complete order record exactly as Lomadee returned it (JSON object), including any field that has no column of its own. |
| Field | Type | Description |
| :----------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | String | Unique identifier of the affiliate in the brand's program. |
| `user_organization_id` | String | Identifier of the link between the affiliate's user and the brand. |
| `invite_status` | String | Status of the affiliate's invitation: pendent, accept, need\_approval or rejected. |
| `active` | Boolean | Whether the affiliate is active in the program. |
| `user_id` | String | Identifier of the affiliate's Lomadee user. |
| `user_email` | String | E-mail address of the affiliate. |
| `user_username` | String | Username of the affiliate on Lomadee. |
| `user_trade_name` | String | Trade name of the affiliate, for a company. |
| `user_legal_name` | String | Legal name of the affiliate, for a company. |
| `user_document_type` | String | Type of the affiliate's document: cpf, cnpj, rg, passport or international. |
| `user_document` | String | Document number of the affiliate. |
| `user_phone` | String | Phone number of the affiliate. |
| `user_birth_date` | String | Birth date of the affiliate. |
| `user_position` | String | Job position the affiliate declared. |
| `user_avatar` | String | URL of the affiliate's profile picture. |
| `user_onboarding_status` | String | Whether the affiliate finished signing up: Completed or Pending. |
| `user_access_count` | Integer | Number of times the affiliate accessed the Lomadee panel. |
| `user_last_login_at` | Date | Date and time the affiliate last logged in to Lomadee. |
| `user_address` | String | Address of the affiliate (JSON object). |
| `user_categories` | String | Categories the affiliate promotes (JSON). |
| `clusters` | String | Affiliate groups of the brand's program the affiliate belongs to, each with its name and whether it is the default group (JSON array of objects). |
| `user_created_at` | Date | Date and time the affiliate's Lomadee user was created. |
| `user_updated_at` | Date | Date and time the affiliate's Lomadee user was last updated. |