> ## 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. # Magalu as a data source > Bring data from Magalu Marketplace to Nekt. Magalu (Magazine Luiza) is one of Brazil's largest retail and e-commerce platforms. The Magalu Seller API provides access to your marketplace seller data including orders, deliveries, delivery invoices (NF-e), product catalog (SKUs), pricing, and inventory. This connector enables you to extract and analyze your Magalu Marketplace operations data. ## Configuring Magalu 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 Magalu option from the list of connectors. Click **Next** and you'll be prompted to add your access. ### 1. Add account access You'll need to authorize Nekt to access your Magalu Seller data. Click on the `Magalu Authorization` button and log in with your Magalu account. Grant the necessary permissions for the seller account you want to extract data from. Make sure you're logged in with a Magalu account that has **seller access** and appropriate permissions to view orders, deliveries, and product catalog data. The following configurations are available: * **Start Date**: (Optional) Lower bound for incremental syncs (`updated_at` for Orders, `issued_at` for Deliveries invoices). If omitted, records are synced from the full history available in the API. Other streams are full-table extractions relative to the tap configuration. 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. 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**: you can choose between INCREMENTAL and FULL\_TABLE. * Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched. * Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog. 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), 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). Optionally, you can define some additional settings: * 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). * Determine when to execute an **Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync)**. This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while. 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. 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 Below you'll find all available data streams from Magalu and their corresponding fields: Product catalog stream containing all SKUs (Stock Keeping Units) from your Magalu seller portfolio. **Key Fields:** | Field | Type | Description | | :---------------- | :-------- | :---------------------------------------------------------------------------------------------------------------- | | `sku` | String | SKU identifier - unique code that identifies the product | | `title` | String | Product title or name | | `description` | String | Detailed product description | | `brand` | String | Brand name of the product | | `status` | String | Current status (e.g., 'active', 'inactive', 'pending', 'rejected') | | `active` | Boolean | Whether the SKU is currently active and available for sale | | `condition` | String | Product condition (e.g., 'new', 'used', 'refurbished') | | `type` | String | Product type classification | | `created_at` | Timestamp | When the SKU was created | | `updated_at` | Timestamp | When the SKU was last updated (the **skus** stream syncs as full table; this field is useful for change tracking) | | `creator` | String | User who created the SKU | | `updater` | String | User who last updated the SKU | | `attributes` | Array | Array of product attributes (name/value pairs for characteristics like Color, Size) | | `datasheet` | Array | Array of technical specifications (name/value pairs like Voltage, Power, Warranty) | | `extra_data` | Array | Array of additional custom data fields | | `identifiers` | Array | Array of product identifier objects (type, value) | | `has_ean` | Boolean | Whether the product has an EAN barcode | | `group` | Object | Product group information linking related SKUs/variants (id) | | `categories` | Array | Array of category classifications (categories, sub\_categories, product\_type, channel) | | `channels` | Array | Array of sales channels where product is available (id) | | `url_marketplace` | Array | Array of marketplace listing URLs (channel, url) | | `dimensions` | Array | Array of dimension sets (name, height, length, width, weight) | | `images` | Array | Array of product images (reference, type) | | `videos` | Array | Array of product videos (reference, type) | | `podcasts` | Array | Array of related podcasts (reference, type) | | `fulfillment` | Boolean | Whether the product uses fulfillment services | | `perishable` | Boolean | Whether the product is perishable | Orders stream containing all marketplace orders with customer, payment, and delivery information. **Key Fields:** | Field | Type | Description | | :---------------- | :-------- | :------------------------------------------------------------------------------------------------------ | | `id` | String | Unique identifier for the order | | `code` | String | Order code in the platform | | `status` | String | Order status (e.g., 'new', 'approved', 'cancelled', 'finished') | | `created_at` | Timestamp | When the order was created | | `updated_at` | Timestamp | When the order was last updated (replication key) | | `approved_at` | Timestamp | When the order was approved | | `purchased_at` | Timestamp | When the order was purchased | | `channel` | Object | Sales channel information (id, extras, marketplace) | | `customer` | Object | Customer details (name, email, document\_number, customer\_type, birth\_date, phones) | | `amounts` | Object | Order totals (currency, normalizer, total, commission, discount, freight, tax) | | `foreign_amounts` | Object | Foreign currency amounts (currency, normalizer, total, exchange\_rate) | | `deliveries` | Array | Array of order deliveries (id, code, status, purchased\_at, seller, amounts, items, shipping) | | `payments` | Array | Array of payment methods (amount, currency, method, brand, description, installments, normalizer, etc.) | Deliveries stream providing detailed shipping and fulfillment information for orders. **Key Fields:** | Field | Type | Description | | :------------- | :-------- | :----------------------------------------------------------------------------------------------- | | `id` | String | Unique identifier for the delivery | | `code` | String | Delivery code | | `status` | String | Delivery status | | `purchased_at` | Timestamp | When the order was purchased | | `order` | Object | Associated order information (id, code, channel) | | `seller` | Object | Seller details (id, name) | | `amounts` | Object | Delivery totals (currency, normalizer, total, freight, discount, tax) | | `items` | Array | Array of items in the delivery (quantity, sequencial, measure\_unit, info, unit\_price, amounts) | | `shipping` | Object | Shipping details (tracking, recipient, drop\_details, handling\_time, deadline, provider) | **Performance Impact:** This stream calls the invoices endpoint once per delivery row in **Deliveries**. Large delivery volumes increase API traffic and extraction time. Enable it only when you need NF-e (Nota Fiscal eletrônica) keys or XML payloads. Brazilian electronic invoice (NF-e) metadata and XML for each delivery. Child stream of **Deliveries**. **Key Fields:** | Field | Type | Description | | :------------ | :-------- | :--------------------------------------------------------------------------- | | `key` | String | NF-e access key (chave de acesso); primary key for this stream | | `delivery_id` | String | Parent delivery identifier (from context) | | `status` | String | Invoice status (e.g., approved) | | `issued_at` | Timestamp | When the invoice was issued (ISO 8601); replication key for incremental sync | | `xml` | String | Full NF-e XML content | **Performance Impact:** This stream requires an additional API request for each SKU in your catalog. If you have a large number of SKUs, selecting this stream will significantly increase extraction time. Only enable this stream if you need real-time pricing data per channel. Pricing information for each SKU per sales channel. This is a child stream of SKUs. **Key Fields:** | Field | Type | Description | | :----------- | :-------- | :------------------------------------------------------- | | `sku` | String | SKU identifier - unique code that identifies the product | | `channel_id` | String | Channel identifier where this price is valid | | `created_at` | Timestamp | When the price record was created | | `updated_at` | Timestamp | When the price was last updated | | `price` | Number | Current selling price of the product | | `list_price` | Number | List price or original price before discounts | | `currency` | String | Currency code (e.g., 'BRL') | | `normalizer` | Number | Price normalizer value used for price calculations | | `channel` | Object | Channel information (id) | **Performance Impact:** This stream requires an additional API request for each SKU in your catalog. If you have a large number of SKUs, selecting this stream will significantly increase extraction time. Only enable this stream if you need real-time stock levels per channel. Stock/inventory information for each SKU per sales channel. This is a child stream of SKUs. **Key Fields:** | Field | Type | Description | | :----------- | :-------- | :------------------------------------------------------- | | `sku` | String | SKU identifier - unique code that identifies the product | | `channel_id` | String | Channel identifier where this stock is available | | `created_at` | Timestamp | When the stock record was created | | `updated_at` | Timestamp | When the stock was last updated | | `quantity` | Number | Available quantity of the product in stock | | `type` | String | Type of stock (e.g., 'AVAILABLE') | # Data Model The following diagram illustrates the relationships between the core data streams in Magalu. The arrows indicate the join keys that link the different entities, providing a clear overview of the data structure. ```mermaid theme={null} graph TD; subgraph "Product Catalog" SKUs("SKUs"); Prices("Prices"); Stocks("Stocks"); end subgraph "Sales Data" Orders("Orders"); Deliveries("Deliveries"); DeliveriesInvoices("Deliveries invoices"); end SKUs -- "sku" --> Prices; SKUs -- "sku" --> Stocks; Orders -- "deliveries[].id" --> Deliveries; Orders -- "deliveries[].items[].info.sku" --> SKUs; Deliveries -- "items[].info.sku" --> SKUs; Deliveries -- "order.id" --> Orders; Deliveries -- "id" --> DeliveriesInvoices; ``` # Use Cases for Data Analysis This guide outlines valuable business intelligence use cases when consolidating Magalu Marketplace data, along with ready-to-use SQL queries that you can run on [Explorer](https://app.nekt.ai/explorer). ### 1. Order Status Overview Track the distribution of order statuses to understand your sales pipeline and identify potential bottlenecks. **Business Value:** * Monitor order fulfillment rates * Identify issues with specific order statuses * Track cancellation rates and reasons ```sql theme={null} WITH order_stats AS ( SELECT status, COUNT(*) AS order_count, SUM(amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1)) AS total_revenue, AVG(amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1)) AS avg_order_value FROM nekt_raw.magalu_orders WHERE DATE(created_at) >= CURRENT_DATE - INTERVAL '30' DAY GROUP BY status ), total AS ( SELECT SUM(order_count) AS total_orders FROM order_stats ) SELECT os.status, os.order_count, ROUND(os.order_count * 100.0 / t.total_orders, 2) AS percentage, ROUND(os.total_revenue, 2) AS total_revenue, ROUND(os.avg_order_value, 2) AS avg_order_value FROM order_stats os, total t ORDER BY os.order_count DESC ``` ```sql theme={null} WITH order_stats AS ( SELECT status, COUNT(*) AS order_count, SUM(amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1)) AS total_revenue, AVG(amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1)) AS avg_order_value FROM `nekt_raw.magalu_orders` WHERE DATE(created_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY) GROUP BY status ), total AS ( SELECT SUM(order_count) AS total_orders FROM order_stats ) SELECT os.status, os.order_count, ROUND(SAFE_DIVIDE(os.order_count * 100.0, t.total_orders), 2) AS percentage, ROUND(os.total_revenue, 2) AS total_revenue, ROUND(os.avg_order_value, 2) AS avg_order_value FROM order_stats os, total t ORDER BY os.order_count DESC ``` | status | order\_count | percentage | total\_revenue | avg\_order\_value | | --------- | ------------ | ---------- | -------------- | ----------------- | | finished | 1,245 | 62.25 | 892,340.50 | 716.74 | | approved | 456 | 22.80 | 312,450.00 | 685.20 | | new | 189 | 9.45 | 145,230.00 | 768.41 | | cancelled | 110 | 5.50 | 78,560.00 | 714.18 | ### 2. Top Selling Products Identify your best-performing products based on sales volume and revenue. **Business Value:** * Understand which products drive the most revenue * Optimize inventory for high-demand items * Inform marketing and promotional strategies ```sql theme={null} WITH item_sales AS ( SELECT i.info.sku AS sku, i.info.name AS product_name, SUM(i.quantity) AS total_quantity, SUM(i.amounts.total / COALESCE(NULLIF(i.amounts.normalizer, 0), 1)) AS total_revenue, COUNT(DISTINCT o.id) AS order_count FROM nekt_raw.magalu_orders o CROSS JOIN UNNEST(o.deliveries) AS t(d) CROSS JOIN UNNEST(d.items) AS t2(i) WHERE o.status NOT IN ('cancelled') AND DATE(o.created_at) >= CURRENT_DATE - INTERVAL '30' DAY GROUP BY i.info.sku, i.info.name ) SELECT sku, product_name, total_quantity, order_count, ROUND(total_revenue, 2) AS total_revenue, ROUND(total_revenue / NULLIF(total_quantity, 0), 2) AS avg_unit_price FROM item_sales ORDER BY total_revenue DESC LIMIT 20 ``` ```sql theme={null} WITH item_sales AS ( SELECT i.info.sku AS sku, i.info.name AS product_name, SUM(i.quantity) AS total_quantity, SUM(i.amounts.total / COALESCE(NULLIF(i.amounts.normalizer, 0), 1)) AS total_revenue, COUNT(DISTINCT o.id) AS order_count FROM `nekt_raw.magalu_orders` o, UNNEST(o.deliveries) AS d, UNNEST(d.items) AS i WHERE o.status NOT IN ('cancelled') AND DATE(o.created_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY) GROUP BY i.info.sku, i.info.name ) SELECT sku, product_name, total_quantity, order_count, ROUND(total_revenue, 2) AS total_revenue, ROUND(SAFE_DIVIDE(total_revenue, total_quantity), 2) AS avg_unit_price FROM item_sales ORDER BY total_revenue DESC LIMIT 20 ``` | sku | product\_name | total\_quantity | order\_count | total\_revenue | avg\_unit\_price | | --------- | ------------------------ | --------------- | ------------ | -------------- | ---------------- | | SKU-12345 | Smart TV 55" 4K Ultra HD | 234 | 230 | 467,532.00 | 1,998.00 | | SKU-67890 | Smartphone Galaxy S24 | 189 | 185 | 341,811.00 | 1,809.00 | | SKU-24680 | Notebook Gamer 16GB RAM | 78 | 75 | 312,000.00 | 4,000.00 | | SKU-13579 | Air Fryer Digital 5.5L | 456 | 420 | 228,456.00 | 501.00 | | SKU-11223 | Wireless Earbuds Pro | 892 | 845 | 178,400.00 | 200.00 | ### 3. Delivery Performance Analysis Monitor delivery times and shipping provider performance to optimize logistics. **Business Value:** * Track delivery success rates * Identify slow shipping providers * Optimize fulfillment processes ```sql theme={null} WITH delivery_metrics AS ( SELECT d.shipping.provider.name AS provider_name, d.status AS delivery_status, COUNT(*) AS delivery_count, AVG(d.shipping.deadline.value) AS avg_deadline_days, SUM(CASE WHEN d.status = 'delivered' THEN 1 ELSE 0 END) AS delivered_count, SUM(CASE WHEN d.status = 'cancelled' THEN 1 ELSE 0 END) AS cancelled_count FROM nekt_raw.magalu_deliveries d WHERE DATE(d.purchased_at) >= CURRENT_DATE - INTERVAL '30' DAY GROUP BY d.shipping.provider.name, d.status ) SELECT provider_name, SUM(delivery_count) AS total_deliveries, SUM(delivered_count) AS total_delivered, SUM(cancelled_count) AS total_cancelled, ROUND(SUM(delivered_count) * 100.0 / NULLIF(SUM(delivery_count), 0), 2) AS delivery_success_rate, ROUND(AVG(avg_deadline_days), 1) AS avg_deadline_days FROM delivery_metrics GROUP BY provider_name ORDER BY total_deliveries DESC ``` ```sql theme={null} WITH delivery_metrics AS ( SELECT d.shipping.provider.name AS provider_name, d.status AS delivery_status, COUNT(*) AS delivery_count, AVG(d.shipping.deadline.value) AS avg_deadline_days, SUM(CASE WHEN d.status = 'delivered' THEN 1 ELSE 0 END) AS delivered_count, SUM(CASE WHEN d.status = 'cancelled' THEN 1 ELSE 0 END) AS cancelled_count FROM `nekt_raw.magalu_deliveries` d WHERE DATE(d.purchased_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY) GROUP BY d.shipping.provider.name, d.status ) SELECT provider_name, SUM(delivery_count) AS total_deliveries, SUM(delivered_count) AS total_delivered, SUM(cancelled_count) AS total_cancelled, ROUND(SAFE_DIVIDE(SUM(delivered_count) * 100.0, SUM(delivery_count)), 2) AS delivery_success_rate, ROUND(AVG(avg_deadline_days), 1) AS avg_deadline_days FROM delivery_metrics GROUP BY provider_name ORDER BY total_deliveries DESC ``` | provider\_name | total\_deliveries | total\_delivered | total\_cancelled | delivery\_success\_rate | avg\_deadline\_days | | --------------- | ----------------- | ---------------- | ---------------- | ----------------------- | ------------------- | | Magalu Entregas | 1,456 | 1,389 | 42 | 95.40 | 3.2 | | Correios | 892 | 834 | 35 | 93.50 | 5.8 | | Jadlog | 456 | 421 | 18 | 92.32 | 4.5 | | Total Express | 234 | 218 | 8 | 93.16 | 4.1 | ## Implementation Notes ### Data normalization Magalu uses a normalizer pattern for monetary values. To get the actual value, divide by the normalizer: ```sql theme={null} -- Example: Get actual order total SELECT amounts.total / COALESCE(NULLIF(amounts.normalizer, 0), 1) AS actual_total FROM orders ``` Common normalizers: * `100` for values stored as cents * `1` for values already in the base currency unit ### Order status flow Orders in Magalu typically follow this status flow: 1. `new` - Order just placed 2. `approved` - Payment confirmed 3. `invoiced` - Invoice generated 4. `shipped` - Order dispatched 5. `delivered` - Order delivered to customer 6. `finished` - Order completed Orders can also be: * `cancelled` - Order was cancelled * `returned` - Customer returned the order ### Brazilian context This connector is designed for the Brazilian marketplace: * **Currency**: Values are in BRL (Brazilian Real) * **Documents**: Customer documents are CPF (individuals) or CNPJ (companies) * **Addresses**: Brazilian address format with CEP (postal code), state abbreviations * **Shipping**: Includes Brazilian carriers like Correios, Jadlog, and Magalu's own logistics ### Incremental sync and replication keys * **Orders** and **Deliveries invoices**: Incremental when configured. **Orders** uses `updated_at` and **Deliveries invoices** uses `issued_at` as the replication key (API requests include date filters from bookmark or **Start Date**). * **SKUs**, **Deliveries**, **Prices**, **Stocks**: Full table sync in the tap (no replication key on those streams). **Start Date** still applies where the shared client passes date filters only for streams that define a replication key. ### Child streams and API volume * **Prices** and **Stocks** are children of **SKUs**: one extra API request per SKU per stream when enabled. * **Deliveries invoices** is a child of **Deliveries**: one extra API request per delivery when enabled. Includes paginated extraction to safely fetch high volumes. Extraction time scales with SKU count (prices/stocks) and delivery count (invoices). Prefer off-peak schedules for large catalogs, and enable child streams only when you need that granularity. ### Nested data structures Magalu payloads are deeply nested. When querying: * Use `UNNEST` (or `CROSS JOIN UNNEST` in Athena) to flatten arrays * Access nested objects using dot notation (e.g., `customer.name`) * Handle NULL values in nested fields with `COALESCE` Example for accessing delivery items from nested orders: ```sql theme={null} -- AWS Athena SELECT d.items FROM orders o CROSS JOIN UNNEST(o.deliveries) AS t(d) -- GCP BigQuery SELECT i.* FROM orders o, UNNEST(o.deliveries) AS d, UNNEST(d.items) AS i ``` ## Skills for agents Magalu connector documentation as plain markdown, for use in AI agent contexts.