> ## 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.
# Netshoes as a data source
> Bring data from the Grupo Netshoes marketplace to Nekt.
Netshoes is one of the largest sports and fashion e-commerce groups in Brazil, and runs the Netshoes and Zattini marketplaces. Its marketplace API lets a seller read the orders placed against their store, the products they have listed together with prices, stock and catalogue approval status, and the customer-service tickets raised about their sales.
## Configuring Netshoes 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 Netshoes option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
Netshoes authenticates every request with a pair of credentials: one that identifies the integration and one that identifies your store. Neither expires.
* **Client ID**: identifies the integration with Netshoes. Netshoes issues it once the integration passes its technical validation. If you are testing with sandbox credentials, this is the value generated in the Netshoes developer portal under **APPS**.
* **Access Token**: identifies your store. Request it from your Netshoes commercial contact. Sandbox tokens are shown in the developer portal under **Tokens Associados**.
A sandbox pair can only read sandbox data and a production pair can only read production data. Make sure the pair you paste matches the environment you select below, or every request will be rejected.
* **Environment**: `production` or `sandbox`. Use production unless Netshoes gave you sandbox credentials for testing.
* **Orders API version**: (Default: v1) which version of the Netshoes API your orders are read from. Netshoes documents orders on v1, which is the default. Only switch to v2 if a sync fails saying Netshoes asked your store to migrate.
The following optional settings are also available:
* **Initial sync date**: the earliest order date to read on the first sync. Later runs continue from where the previous one stopped. Leave it empty to read your full order history.
* **Seller ID**: only needed when the same credentials serve more than one store. The codes available to your credentials are listed in the `sellers` table.
* **Lookback window**: (Default: 7 days) how many days before the last sync the order tables re-read on every run. See [Keeping order status up to date](#keeping-order-status-up-to-date) below for why this matters.
* **Storefronts**: (Default: Netshoes and Zattini) which storefronts to read the department list for. A storefront your store is not listed on is skipped automatically.
* **Page size**: (Default: 50) records requested per page. Netshoes caps the order listing at 50.
* **Requests per minute**: (Default: 60) how fast this source is allowed to call the API. Netshoes limits how many calls a store may make per minute, and that allowance is shared with every other integration using the same credentials.
* **Base URL**: only needed if Netshoes told you to use a different address for your store.
Once you're done, click **Next**.
### 2. Select streams
Choose which data streams you want to sync.
The `product_prices`, `product_stocks`, `product_status` and `protocol_messages` streams read one record at a time — one API call per product, or per service ticket. On a large catalogue they take considerably longer than the others, so only select the ones you need.
> 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.
## How orders are organized
A Netshoes order is shipment-centric: the order itself carries the totals and the dates, while the customer, the invoice, the carrier and the products sold all belong to a **shipment**. One order can hold several shipments, each with its own status.
Nekt splits that into four tables you can join:
* `orders` — one row per order, with its totals, dates and overall status.
* `order_shippings` — one row per shipment, with the recipient, the delivery address, the invoice and the carrier. Join it to `orders` on `orderNumber`.
* `order_items` — one row per product sold, joined to a shipment by `orderNumber` and `shippingCode`.
* `order_devolution_items` — one row per product the customer returned or exchanged, joined the same way.
All four are filled from the same extraction, so selecting the detail tables costs no additional API calls.
## Keeping order status up to date
Netshoes only lets orders be filtered by **the date they were placed**. An order's status, however, keeps changing afterwards — it is approved, then invoiced, then shipped, then delivered, sometimes weeks later.
That means a plain incremental sync would capture each order once, with whatever status it had at the time, and never see it change again. The **lookback window** exists to prevent that: on every run the connector re-reads the orders placed in the last few days, so their current status replaces what was stored before.
The default of 7 days suits most stores. If your orders regularly take longer than a week to reach the customer, raise it so that deliveries are still within the window when they happen.
## Things to know
* **Orders and products come from different API versions.** Netshoes publishes two APIs: version 1 carries orders, service protocols and the catalogue reference tables, and version 2 carries products, prices and stock. The connector reads each from where it lives, so nothing is required of you beyond the credentials.
* **Catalogue tables change without notice.** Netshoes adds and removes brands, colours, sizes and departments on its own schedule, and a product listing is rejected when it names a value that does not exist. The `brands`, `colors`, `flavors`, `sizes`, `departments` and `product_types` tables are re-read in full on every run so they always reflect the current list.
* **Orders fulfilled by Magalu look different.** When a shipment's carrier is "Magalu Entregas - Fulfillment" (carrier code 906), Netshoes advances the order through invoicing, shipping and delivery automatically, and the seller cannot change those statuses. You can identify these shipments by `transport_carrierId` in `order_shippings`.
* **Rate limiting is expected on large stores.** Netshoes enforces a per-minute call limit and does not publish the number. When it throttles the connection, the sync waits and continues — you'll see a warning in the run log. If it happens on every run, lower **Requests per minute** in the source settings.
* **Not every table is available to every store.** If your credentials are not allowed to read part of the API, or your store is not listed on one of the storefronts, that table is simply not updated and a warning appears in the run log. The rest of the sync carries on.
## Available streams
| Stream | Slug | Sync | Replication key |
| -------------------- | ---------------------------- | ----------- | --------------- |
| Orders | `orders` | INCREMENTAL | `orderDate` |
| Order Shipments | `order_shippings` | FULL\_TABLE | — |
| Order Items | `order_items` | FULL\_TABLE | — |
| Order Returns | `order_devolution_items` | FULL\_TABLE | — |
| Cancellation Reasons | `order_cancellation_reasons` | FULL\_TABLE | — |
| Products | `products` | FULL\_TABLE | — |
| Product Prices | `product_prices` | FULL\_TABLE | — |
| Product Stock | `product_stocks` | FULL\_TABLE | — |
| Product Status | `product_status` | FULL\_TABLE | — |
| Brands | `brands` | FULL\_TABLE | — |
| Colors | `colors` | FULL\_TABLE | — |
| Flavors | `flavors` | FULL\_TABLE | — |
| Sizes | `sizes` | FULL\_TABLE | — |
| Sellers | `sellers` | FULL\_TABLE | — |
| Departments | `departments` | FULL\_TABLE | — |
| Product Types | `product_types` | FULL\_TABLE | — |
| Service Protocols | `protocols` | FULL\_TABLE | — |
| Protocol Messages | `protocol_messages` | FULL\_TABLE | — |
## Fields by stream
| Field | Type | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `orderNumber` | string | Order number as the customer and the Netshoes back office see it. Unique per order and the key of this table. |
| `originNumber` | string | Order number in the storefront that originated the sale, when it differs from the marketplace order number. |
| `businessUnit` | string | Storefront the order was placed on: Netshoes or Zattini. |
| `originSite` | string | Site the order came from, as Netshoes labels it (for example NETSHOES). |
| `orderType` | string | Nature of the order, such as Sale for a regular purchase. |
| `orderStatus` | string | Current status of the order as a whole (for example Approved, Invoiced, Shipped, Delivered, Canceled). Individual shipments carry their own status in the order\_shippings table. |
| `orderDate` | datetime | When the order was placed. Used as the incremental replication key, and the only date the listing can be filtered by. |
| `paymentDate` | datetime | When the payment was captured. |
| `agreedDate` | datetime | Delivery date promised to the customer at checkout. |
| `totalQuantity` | integer | Total number of units across every line of the order. |
| `totalGross` | number | Gross value of the order, before discounts and commission. |
| `totalCommission` | number | Commission Netshoes charges the seller for this order. |
| `totalDiscount` | number | Total discount applied to the order. |
| `totalFreight` | number | Freight charged on the order. |
| `totalNet` | number | Net value of the order after discounts and commission. |
| `devolutionRequested` | boolean | Whether a return has been requested for this order. |
| `exchangeRequested` | boolean | Whether an exchange has been requested for this order. |
| `payments` | string | Payments settling the order as returned by the API (JSON array of objects). |
| `paymentGatewayInfos` | string | Payment gateway records for the order, each with the amount settled and the gateway's registration number (JSON array of objects). |
| `shippings` | string | Shipments of this order exactly as the API returned them (JSON array of objects). The same data is available as rows in order\_shippings, order\_items and order\_devolution\_items. |
| Field | Type | Description |
| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `orderNumber` | string | Order this shipment belongs to. |
| `shippingCode` | string | Identifier of the shipment within the order. Together with the order number it is the key of this table. |
| `status` | string | Status of this shipment: approved, invoiced, shipped, delivered or canceled. A single order can hold shipments in different states. |
| `shippingEstimate` | datetime | Date the shipment is expected to reach the customer. |
| `deliveryTime` | integer | Delivery time quoted for this shipment, in days. |
| `freightAmount` | number | Freight charged for this shipment. |
| `country` | string | Destination country of the shipment. |
| `cancellationReason` | string | Why the shipment was cancelled, when it was. |
| `platformId` | string | Logistics platform handling the shipment, such as MAGALU\_ENTREGAS for orders fulfilled by Magalu. |
| `serviceId` | string | Identifier of the shipping service used. |
| `serviceName` | string | Name of the shipping service used, such as Normal. |
| `transport_carrier` | string | Carrier responsible for the shipment. 'Magalu Entregas - Fulfillment' means the order is fulfilled by Magalu and its status is advanced automatically rather than by the seller. |
| `transport_carrierId` | string | Carrier code. 906 identifies Magalu Entregas fulfillment. |
| `transport_trackingNumber` | string | Tracking code given by the carrier. |
| `transport_trackingLink` | string | URL where the customer can follow the shipment. |
| `transport_trackingShipDate` | datetime | Date the carrier registered the shipment for tracking. |
| `transport_deliveryDate` | datetime | Date the shipment was delivered to the customer. |
| `transport_shipDate` | datetime | Date the shipment left the seller. |
| `transport_deliveryService` | string | Delivery service chosen at checkout, such as Normal. |
| `transport_deliveryId` | string | Identifier of the delivery service chosen at checkout. |
| `invoice_accessKey` | string | Access key of the electronic invoice (NF-e) issued for this shipment. |
| `invoice_date` | datetime | Issue date of the invoice. |
| `invoice_shipDate` | datetime | Date the invoice records the goods as shipped. |
| `invoice_volume` | integer | Number of packages covered by the invoice. |
| `invoice_url` | string | URL of the invoice document, when the API returns one. |
| `invoiceErrors` | string | Errors and validation errors Netshoes recorded against the invoice (JSON object). Empty when the invoice was accepted. |
| `customer_document` | string | CPF or CNPJ of the customer who placed the order. |
| `customer_stateInscription` | string | State registration number, for business customers. |
| `customer_customerName` | string | Name of the customer who placed the order. |
| `customer_recipientName` | string | Name of the person the shipment is addressed to, which can differ from the buyer. |
| `customer_receiverName` | string | Name of whoever actually took delivery. |
| `customer_tradeName` | string | Trade name, for business customers. |
| `customer_cellPhone` | string | Mobile number registered for the delivery. |
| `customer_landLine` | string | Landline number registered for the delivery. |
| `address_street` | string | Street of the delivery address. |
| `address_number` | string | Street number of the delivery address. |
| `address_complement` | string | Address complement, such as an apartment or block. |
| `address_neighborhood` | string | Neighbourhood of the delivery address. |
| `address_city` | string | City of the delivery address. |
| `address_state` | string | State abbreviation of the delivery address. |
| `address_stateName` | string | Full state name of the delivery address. |
| `address_postalCode` | string | Postal code (CEP) of the delivery address. |
| `address_reference` | string | Free-text reference point for the delivery address. |
| `sender_supplierCnpj` | string | CNPJ of the seller shipping the goods. |
| `sender_sellerCode` | integer | Netshoes code of the seller shipping the goods. |
| `sender_sellerName` | string | Name of the seller shipping the goods. |
| `sender_supplierName` | string | Supplier name registered for the seller. |
| `exchangeOrders` | string | Orders generated by an exchange of this shipment (JSON array). |
| Field | Type | Description |
| ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `orderNumber` | string | Order this line belongs to. |
| `shippingCode` | string | Shipment this line was sent in. |
| `itemId` | integer | Identifier of the line within the shipment. |
| `sku` | string | Seller's SKU for the product sold on this line. |
| `name` | string | Product name as listed on the storefront. |
| `brand` | string | Brand of the product sold. |
| `ean` | string | EAN barcode of the product sold. |
| `manufacturerCode` | string | Manufacturer's reference for the product. |
| `quantity` | integer | Units of this product sold on the line. |
| `status` | string | Status of this individual line, which can differ from the shipment when only part of it was cancelled or returned. |
| `departmentName` | string | Netshoes department the product is catalogued under. |
| `departmentCode` | integer | Code of that department. |
| `color` | string | Colour variation sold. |
| `flavor` | string | Flavour variation sold, for products catalogued by flavour. |
| `size` | string | Size variation sold. |
| `grossUnitValue` | number | Gross price of a single unit. |
| `discountUnitValue` | number | Discount applied to a single unit. |
| `netUnitValue` | number | Net price of a single unit after discount. |
| `totalGross` | number | Gross value of the line. |
| `totalCommission` | number | Commission Netshoes charges on this line. |
| `totalDiscount` | number | Discount applied to the line. |
| `totalFreight` | number | Freight apportioned to the line. |
| `totalNet` | number | Net value of the line after discounts and commission. |
| Field | Type | Description |
| -------------------------- | -------- | ---------------------------------------------------------- |
| `orderNumber` | string | Order the returned line belongs to. |
| `shippingCode` | string | Shipment the returned line was sent in. |
| `itemId` | integer | Identifier of the returned line within the shipment. |
| `sku` | string | Seller's SKU for the returned product. |
| `name` | string | Product name as listed on the storefront. |
| `brand` | string | Brand of the returned product. |
| `ean` | string | EAN barcode of the returned product. |
| `manufacturerCode` | string | Manufacturer's reference for the product. |
| `quantity` | integer | Units returned. |
| `status` | string | Status of the return for this line. |
| `devolutionExchangeStatus` | string | Status of the exchange, when the return was opened as one. |
| `exchangeProcessCode` | integer | Code of the exchange process this return belongs to. |
| `checkInData` | datetime | When the returned goods were checked in at the warehouse. |
| `devolutionData` | datetime | When the return was registered. |
| `departmentName` | string | Netshoes department the product is catalogued under. |
| `departmentCode` | integer | Code of that department. |
| `color` | string | Colour variation returned. |
| `flavor` | string | Flavour variation returned. |
| `size` | string | Size variation returned. |
| `totalGross` | number | Gross value of the returned line. |
| Field | Type | Description |
| -------------- | ------- | ---------------------------------------------------------------------- |
| `code` | string | Code to send when cancelling a shipment for this reason. |
| `description` | string | What the reason means, in Netshoes' own wording. |
| `canBePenalty` | boolean | Whether cancelling for this reason can incur a penalty for the seller. |
| Field | Type | Description |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sku` | string | Seller's own code for this product variation. It is the key of the catalogue and Netshoes never changes it. |
| `productGroup` | string | Code grouping the size and colour variations of one model. Every SKU of the same model shares it, which is how the storefront offers them together. |
| `name` | string | Product title shown on the storefront, capped at 100 characters by Netshoes. |
| `description` | string | Product description shown on the storefront, capped at 3,000 characters and free of HTML. |
| `department` | string | Netshoes department the product is listed under. |
| `productType` | string | Product type within the department, which determines the attributes Netshoes requires. |
| `brand` | string | Brand of the product, taken from the brands table Netshoes maintains. |
| `color` | string | Colour of this variation, from the colours table. |
| `flavor` | string | Flavour of this variation, for products catalogued by flavour. |
| `size` | string | Size of this variation, from the sizes table. |
| `gender` | string | Audience the product is sold to, such as Masculino, Feminino or Unissex. |
| `manufacturerCode` | string | Manufacturer's own reference for the product. |
| `eanIsbn` | string | EAN or ISBN barcode of the variation. |
| `video` | string | URL of a product video, when one was registered. |
| `height` | number | Packed height of the product, in centimetres. |
| `width` | number | Packed width of the product, in centimetres. |
| `depth` | number | Packed depth of the product, in centimetres. |
| `weight` | number | Packed weight of the product, in grams. |
| `fulfillment_candidate` | boolean | Whether the seller offered this product to Magalu's fulfillment service. Orders for a fulfilled product move through their statuses automatically. |
| `images` | string | Images registered for the product (JSON array of objects, each with a url). |
| `attributes` | string | Attributes required by the product's department and type, as name and values (JSON array of objects). Which attributes apply varies by product type, so they are kept as JSON rather than columns. |
| Field | Type | Description |
| ----------- | ------ | ------------------------------------------------------- |
| `sku` | string | Product this price belongs to. |
| `listPrice` | number | Reference price shown struck through on the storefront. |
| `salePrice` | number | Price the customer actually pays. |
| Field | Type | Description |
| ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sku` | string | Product this stock position belongs to. |
| `available` | integer | Units available for sale. This is the whole of what the v2 stock resource returns — Netshoes does not expose reserved or total units on this endpoint. |
| Field | Type | Description |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sku` | string | Product this status belongs to. |
| `status` | string | Moderation status of the product. A product only reaches the storefront once Netshoes' catalogue team has released it. |
| `reviews` | string | Notes the catalogue team left while reviewing the product, each with a message and a date (JSON array of objects). This is where the reason for a rejected product is written. |
| Field | Type | Description |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| `code` | string | Netshoes code for the brand. This is the value a product listing must carry to claim it. |
| `name` | string | Name of the brand as Netshoes spells it. A product listing is rejected when its spelling does not match. |
| `externalCode` | string | Code the seller mapped to this brand, when one was registered with Netshoes. |
| Field | Type | Description |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `code` | string | Netshoes code for the colour. This is the value a product listing must carry to claim it. |
| `name` | string | Name of the colour as Netshoes spells it. A product listing is rejected when its spelling does not match. |
| `externalCode` | string | Code the seller mapped to this colour, when one was registered with Netshoes. |
| Field | Type | Description |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `code` | string | Netshoes code for the flavour. This is the value a product listing must carry to claim it. |
| `name` | string | Name of the flavour as Netshoes spells it. A product listing is rejected when its spelling does not match. |
| `externalCode` | string | Code the seller mapped to this flavour, when one was registered with Netshoes. |
| Field | Type | Description |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `code` | string | Netshoes code for the size. This is the value a product listing must carry to claim it. |
| `name` | string | Name of the size as Netshoes spells it. A product listing is rejected when its spelling does not match. |
| `externalCode` | string | Code the seller mapped to this size, when one was registered with Netshoes. |
| Field | Type | Description |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `code` | string | Netshoes code of the seller. This is the value to put in the 'Seller ID' setting when one set of credentials serves several sellers. |
| `name` | string | Registered name of the seller. |
| Field | Type | Description |
| -------------- | ------ | ----------------------------------------------------------------------------------------- |
| `businessUnit` | string | Storefront this department belongs to: netshoes or zattini. |
| `code` | string | Netshoes code of the department. Product types are listed per department using this code. |
| `name` | string | Name of the department as it appears on the storefront. |
| Field | Type | Description |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `departmentCode` | string | Department this product type belongs to. |
| `businessUnit` | string | Storefront the department belongs to. |
| `code` | string | Netshoes code of the product type. A product listing must pair it with the department it was read from. |
| `name` | string | Name of the product type as Netshoes spells it. |
| Field | Type | Description |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `protocolNumber` | string | Number identifying the service ticket. It is what the customer and Netshoes support both quote. |
| `orderNumber` | string | Order the ticket was raised about, linking it to the orders table. |
| `status` | string | Where the ticket stands — open, awaiting the seller, closed. |
| `type` | string | Kind of ticket, as Netshoes classifies it. |
| `cause` | string | Cause Netshoes recorded for the ticket. |
| `channel` | string | Channel the customer used to raise the ticket. |
| `initDate` | datetime | When the ticket was opened. |
| `lastMessageDate` | datetime | When the most recent message was added to the ticket. |
| `sla` | string | Service level the seller has to answer the ticket within. |
| `priority` | string | Priority Netshoes assigned to the ticket. |
| `responsible` | string | Who the ticket is currently waiting on. |
| Field | Type | Description |
| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `protocolNumber` | string | Ticket this message belongs to. |
| `messageDate` | datetime | When the message was written. Together with the ticket number it identifies the message. |
| `text` | string | Body of the message, in the words of whoever wrote it. The message carries no author of its own; who the ticket is waiting on is on the protocol itself. |