> ## 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.

# TMTX as a data source

> Bring sales orders, returns, inventory, stock movements and transfers from TMTX to Nekt.

TMTX is a management system for sales, inventory and logistics. Its integration API gives read-only access to the sales orders, returns, inventory position, stock movements and transfers of the companies your integration token is authorized for. The Nekt connector extracts that data into your Catalog, so you can analyze sales, returns and stock together with the rest of your data.

## Before you start

You need the **integration token** that TMTX provides in its integration guide ("API TMTX - Guia de integração e acesso"). The token is read-only and decides which companies' data the connector can see. It does not expire on its own, but TMTX can revoke or replace it; if that happens, update it in the source configuration.

### Use two TMTX sources

Create the connector twice with the same token:

1. **Main source**: every stream except **Inventory history**. This is the source where the weekly full sync recommended below runs.
2. **Inventory history source**: only the **Inventory history** (`estoque_historico`) stream, running every few hours, with **no** Additional Full Sync.

Both sources use the same token and share TMTX's limit of 5 requests per second per IP, so stagger their schedules so that they never run at the same time (for example, the inventory history source at a different minute of the hour than the main source).

A full sync always applies to every stream of a source. On the inventory history table it replaces all the positions saved so far with the current one, and TMTX cannot send the old positions again. Keeping that stream in a source of its own is the only way to run full syncs on the other tables without losing the history.

## Configuring TMTX 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 TMTX option from the list of connectors.

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

### 1. Add account access

The following configuration is available:

* **API Token**: The integration token provided by TMTX. Paste only the token, without quotes and without the word `Bearer`.

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.

> 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 and changed 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.

> [!WARNING]
>
> Select the **Inventory history** (`estoque_historico`) stream only in its own source (see [Use two TMTX sources](#use-two-tmtx-sources)) and keep it as INCREMENTAL. TMTX only publishes the current inventory position, so this table is the only place where past positions are kept. Never schedule an Additional Full Sync on that source and never click **Full sync** on it: a full sync deletes the saved history for good and leaves only the current position. In FULL\_TABLE mode the table also keeps only the current position.

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. TMTX refreshes orders, returns and transfers about every 5 minutes, stock movements about every 15 minutes and the inventory position about once a day. Run the inventory history source every few hours, at times that do not overlap with the main source (both share TMTX's rate limit): each run first checks whether TMTX published a new position and only downloads it when it did, so frequent runs are cheap, while a single daily run can miss a publication.

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. On the **main source** we recommend a weekly full sync: records deleted in TMTX are not reported by its API, so they only leave your incremental tables on a full sync. On the **inventory history source**, leave it off: a full sync there deletes the saved history.

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 | Description |
| - | - | - |
| Orders (sales items) | `pedidos` | One row per sales-order item: product, quantity, value, freight, status, invoices and delivery dates. |
| Returns | `devolucoes` | One row per returned item, with the reason and the original document it refers to. |
| Inventory (current position) | `estoque` | Latest published inventory position per product and stock location: physical, reserved and available balance, and unit cost. |
| Inventory history | `estoque_historico` | Every published inventory position, accumulated from the first extraction on: one row per product, location and position date. |
| Stock movements | `movimentacoes` | One row per stock movement: entries, outflows, transfers, returns and adjustments. |
| Transfers | `transferencias` | One row per item of a transfer order between branches and distribution centers. |

Lists of invoices (`notas_fiscais`, `notas_devolucao`, `notas_venda_original`) are stored as JSON text, for example `json_extract_scalar(notas_fiscais, '$[0].numero')`.

## Fields by stream

> [accordion] Orders (sales items)
>
> Stream name: `pedidos`. One row per item of a sales order (Pedido Venda documents).
>
> **Sync Strategy:**
>
> * Incremental on `data_atualizacao` (the API's change marker)
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Stable identifier of the order item; unique within this endpoint (primary key). |
> | `id_pedido_item` | String | Identifier of the order item (same value as id). |
> | `contrato` | String | Internal identifier of the order (contract) in TMTX. |
> | `pedido_proprio` | String | Order number shown in TMTX. |
> | `pedido_omie` | String | Order number in Omie, when integrated; may be null. Not a global key across Omie accounts. |
> | `pedido_omie_id` | String | Internal identifier of the order integrated with Omie; may be null. |
> | `empresa_codigo` | String | Code of the company, within the set authorized for the token. |
> | `loja_codigo` | String | Code of the branch (store) of the sale. |
> | `loja_nome` | String | Name of the branch (store) of the sale. |
> | `vendedor_codigo` | String | Internal identifier of the salesperson; null when there is no active link. |
> | `vendedor_nome` | String | Name of the salesperson; null when there is no active link. |
> | `produto_codigo` | String | Integrated code of the product in TMTX. |
> | `produto_sku` | String | Commercial code (SKU) of the product. |
> | `produto_descricao` | String | Description of the product. |
> | `data_pedido` | Date | Order date; the field the API's period filter (data\_inicio/data\_fim) uses. |
> | `data_faturamento` | Date | First issue date among the active invoices; when there is none, the date recorded on the order. |
> | `data_remessa` | Date | Delivery date recorded on the item (or, when absent, on the order header). Informed date, not proof of physical delivery; may be null. |
> | `origem_data_remessa` | String | Where data\_remessa came from (CONTRATO\_ITEM.DATA\_ENTREGA or CONTRATO.DATA\_ENTREGA); null when absent. |
> | `quantidade` | Number | Quantity of the item in the source. |
> | `valor_venda` | Number | Total of the item as recorded in TMTX; on its own it is not the final total of the order. |
> | `valor_frete` | Number | Header freight apportioned to the item in proportion to the absolute value of the active items (cent adjustment on the last item). Do not add it again if your revenue rule already includes it. |
> | `status` | String | Status for consumption. Cancelled orders that are still active are kept. |
> | `status_origem` | String | Status description in the source system. |
> | `situacao_codigo` | String | Identifier of the status in the source system. |
> | `tipo_documento_codigo` | String | Code of the sales document type. |
> | `tipo_documento_descricao` | String | Description of the sales document type. |
> | `notas_fiscais` | String (JSON) | Active invoices of the item as a JSON array of objects with numero, serie, chave and data\_emissao; `[]` when there is no invoice. |
> | `data_previsao_entrega` | Date | Delivery forecast from the active, non-cancelled loading order (direct link first, then a linked transfer; the latest date when several apply). A plan, not proof of delivery. |
> | `origem_previsao_entrega` | String | Source of the delivery forecast: ordem\_carregamento or ordem\_carregamento\_transferencia\_vinculada; null when there is no forecast. |
> | `quantidade_entregue_origem` | Number | Delivered quantity (QTD\_ENTREGUE) recorded on the item in TMTX; does not tell when it was delivered. |
> | `data_atualizacao` | Timestamp | When the API last published a change to this order item; the API's incremental filter (atualizado\_desde) works on this field. |
> | `data_atualizacao_origem` | Timestamp | Informative change/insert date in the source system; not used as the sync marker. |
> | `excluido` | Boolean | Kept for compatibility; always false. Records deleted in the source (ATIVO=0) are not returned by the API at all, so they only disappear from the table after a full sync. |
> | `sincronizado_em` | Timestamp | When the TMTX API last synchronized this endpoint from the source system (meta.sincronizado\_em of the read that delivered this row). |

> [accordion] Returns
>
> Stream name: `devolucoes`. One row per returned item, with the reference to the original document (which can be a sale or a shipment/resale).
>
> **Sync Strategy:**
>
> * Incremental on `data_atualizacao` (the API's change marker)
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Stable identifier of the returned item; unique within this endpoint (primary key). |
> | `id_devolucao_item` | String | Identifier of the returned item (same value as id). |
> | `id_devolucao` | String | Identifier of the return contract. |
> | `data_devolucao` | Date | Return date; the field the API's period filter (data\_inicio/data\_fim) uses. |
> | `empresa_codigo` | String | Company of the return document. |
> | `loja_codigo` | String | Code of the branch of the original document referenced. |
> | `loja_nome` | String | Name of the branch of the original document referenced. |
> | `vendedor_codigo` | String | Internal identifier of the salesperson of the original document. |
> | `vendedor_nome` | String | Name of the salesperson of the original document. |
> | `motivo_codigo` | String | Code of the return reason. |
> | `motivo_descricao` | String | Description of the return reason. |
> | `contrato` | String | Identifier of the original document (not of the return). |
> | `pedido_proprio` | String | Number of the original document (not of the return). |
> | `pedido_omie` | String | Order number in Omie, when integrated; may be null. Not a global key across Omie accounts. |
> | `pedido_omie_id` | String | Internal identifier of the order integrated with Omie; may be null. |
> | `id_pedido_item` | String | Identifier of the original item referenced. |
> | `tipo_documento_original_codigo` | String | Code of the actual type of the original document (it may be a sale or a shipment/resale, which may not appear in pedidos). |
> | `tipo_documento_original_descricao` | String | Description of the actual type of the original document, as named in TMTX. |
> | `contrato_documento_original` | String | Explicit identifier of the original document referenced. |
> | `id_item_documento_original` | String | Explicit identifier of the original item referenced. |
> | `nf_devolucao` | String | Return invoice number when there is exactly one active invoice; null if none or several. |
> | `nf_venda_original` | String | Original sale invoice number when there is exactly one active invoice; null if none or several. |
> | `notas_devolucao` | String (JSON) | All active return invoices as a JSON array of objects with numero, serie, chave and data\_emissao. |
> | `notas_venda_original` | String (JSON) | All active invoices of the original sale as a JSON array of objects with numero, serie, chave and data\_emissao. |
> | `produto_codigo` | String | Integrated code of the returned product in TMTX. |
> | `produto_sku` | String | Commercial code (SKU) of the returned product. |
> | `produto_descricao` | String | Description of the returned product. |
> | `quantidade` | Number | Returned quantity recorded on the item. |
> | `valor_devolvido` | Number | Total returned value recorded on the item. |
> | `status` | String | Return status: aberta, finalizada or cancelada. |
> | `situacao_codigo` | String | Status identifier of the return document in the source system. |
> | `status_origem` | String | Status description of the return document in the source system. |
> | `data_atualizacao` | Timestamp | When the API last published a change to this returned item; the API's incremental filter (atualizado\_desde) works on this field. |
> | `data_atualizacao_origem` | Timestamp | Informative change/insert date in the source system; not used as the sync marker. |
> | `excluido` | Boolean | Kept for compatibility; always false. Records deleted in the source (ATIVO=0) are not returned by the API at all, so they only disappear from the table after a full sync. |
> | `sincronizado_em` | Timestamp | When the TMTX API last synchronized this endpoint from the source system (meta.sincronizado\_em of the read that delivered this row). |

> [accordion] Inventory (current position)
>
> Stream name: `estoque`. The latest published inventory position: one row per product and stock location. The table is replaced on every run.
>
> **Sync Strategy:**
>
> * Full table
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Opaque identifier of the balance: owner + installation + product. Unique within one position. |
> | `data_posicao` | Timestamp | When the published position was collected; the same for every row of one position. |
> | `local_codigo` | String | Owner + installation identity of the balance. |
> | `local_nome` | String | Description of the branch and stock location. |
> | `empresa_codigo` | String | Company linked to the branch of the balance. |
> | `loja_codigo` | String | Code of the branch. |
> | `loja_nome` | String | Name of the branch. |
> | `produto_codigo` | String | Integrated code of the product in TMTX. |
> | `produto_sku` | String | Commercial code (SKU) of the product. |
> | `produto_descricao` | String | Description of the product. |
> | `linha` | String | Product line. Reserved in the API contract and not mapped yet: always null in this version. |
> | `tamanho` | String | Product size. Reserved in the API contract and not mapped yet: always null in this version. |
> | `saldo_fisico` | Number | Sum of the active physical balances of this owner, location and product. |
> | `quantidade_reservada` | Number | Active reservations without a fulfillment date, linked to the active stock records. |
> | `saldo_disponivel` | Number | saldo\_fisico minus quantidade\_reservada; may be negative. |
> | `quantidade_em_transito` | Number | Quantity in transit. No validated source rule yet: always null in this version (null, not zero). |
> | `custo_unitario` | Number | Current accounting unit cost (accounting value / accounting quantity, or the registered average cost when the quantity is zero); may be null. Not the historical cost of each sale. |
> | `status_produto` | String | Product status (ativo); deleted products and inactive stock records are omitted. |
> | `data_atualizacao` | Timestamp | When the API last published a change to this balance; the API's incremental filter (atualizado\_desde) works on this field. |
> | `data_atualizacao_origem` | Timestamp | Informative change/insert date in the source system; not used as the sync marker. |
> | `excluido` | Boolean | Kept for compatibility; always false. Records deleted in the source (ATIVO=0) are not returned by the API at all, so they only disappear from the table after a full sync. |
> | `sincronizado_em` | Timestamp | When the TMTX API last synchronized this endpoint from the source system (meta.sincronizado\_em of the read that delivered this row). |

> [accordion] Inventory history
>
> Stream name: `estoque_historico`. Every published inventory position, accumulated: one row per product, stock location and position date.
>
> **Sync Strategy:**
>
> * Incremental on `data_posicao` (each new position is appended once)
> * Primary key(s): `id`, `data_posicao`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Opaque identifier of the balance: owner + installation + product. Unique within one position. |
> | `data_posicao` | Timestamp | When the published position was collected (part of the primary key: one row per balance per position). |
> | `local_codigo` | String | Owner + installation identity of the balance. |
> | `local_nome` | String | Description of the branch and stock location. |
> | `empresa_codigo` | String | Company linked to the branch of the balance. |
> | `loja_codigo` | String | Code of the branch. |
> | `loja_nome` | String | Name of the branch. |
> | `produto_codigo` | String | Integrated code of the product in TMTX. |
> | `produto_sku` | String | Commercial code (SKU) of the product. |
> | `produto_descricao` | String | Description of the product. |
> | `linha` | String | Product line. Reserved in the API contract and not mapped yet: always null in this version. |
> | `tamanho` | String | Product size. Reserved in the API contract and not mapped yet: always null in this version. |
> | `saldo_fisico` | Number | Sum of the active physical balances of this owner, location and product. |
> | `quantidade_reservada` | Number | Active reservations without a fulfillment date, linked to the active stock records. |
> | `saldo_disponivel` | Number | saldo\_fisico minus quantidade\_reservada; may be negative. |
> | `quantidade_em_transito` | Number | Quantity in transit. No validated source rule yet: always null in this version (null, not zero). |
> | `custo_unitario` | Number | Current accounting unit cost (accounting value / accounting quantity, or the registered average cost when the quantity is zero); may be null. Not the historical cost of each sale. |
> | `status_produto` | String | Product status (ativo); deleted products and inactive stock records are omitted. |
> | `data_atualizacao` | Timestamp | When the API last published a change to this balance; the API's incremental filter (atualizado\_desde) works on this field. |
> | `data_atualizacao_origem` | Timestamp | Informative change/insert date in the source system; not used as the sync marker. |
> | `excluido` | Boolean | Kept for compatibility; always false. Records deleted in the source (ATIVO=0) are not returned by the API at all, so they only disappear from the table after a full sync. |
> | `sincronizado_em` | Timestamp | When the TMTX API last synchronized this endpoint from the source system (meta.sincronizado\_em of the read that delivered this row). |

> [accordion] Stock movements
>
> Stream name: `movimentacoes`. One row per stock movement recorded in TMTX (entries, outflows, transfers, returns and adjustments).
>
> **Sync Strategy:**
>
> * Incremental on `data_atualizacao` (the API's change marker)
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Stable identifier of the movement; unique within this endpoint (primary key). |
> | `id_movimentacao` | String | Identifier of the movement (same value as id). |
> | `data_movimentacao` | Timestamp | Date of the movement in the source; the field the API's period filter (data\_inicio/data\_fim) uses. |
> | `local_codigo` | String | Owner + installation identity of the stock (same concept as in estoque). |
> | `local_nome` | String | Description of the branch and stock location. |
> | `empresa_codigo` | String | Company linked to the owner of the stock. |
> | `loja_codigo` | String | Branch linked to the owner of the stock. |
> | `produto_codigo` | String | Integrated code of the moved product in TMTX. |
> | `produto_sku` | String | Commercial code (SKU) of the moved product. |
> | `produto_descricao` | String | Description of the moved product. |
> | `tipo` | String | Movement class: entrada, saida, transferencia, devolucao or ajuste. |
> | `tipo_codigo` | String | Identifier of the movement type in the source. |
> | `tipo_descricao` | String | Detailed description of the movement type in the source. |
> | `quantidade` | Number | Moved quantity: negative for outflows, positive for inflows. A reversal can be a new movement with the opposite sign. |
> | `local_destino` | String | Destination location. Not mapped yet in this API version: always null (null means unavailable, not that there was no transfer). |
> | `documento` | String | Invoice number or, when absent, the linked contract number; null when there is no reference. |
> | `status` | String | Movement status (ativo). |
> | `data_atualizacao` | Timestamp | When the API last published a change to this movement; the API's incremental filter (atualizado\_desde) works on this field. |
> | `data_atualizacao_origem` | Timestamp | Informative change/insert date in the source system; not used as the sync marker. |
> | `excluido` | Boolean | Kept for compatibility; always false. Records deleted in the source (ATIVO=0) are not returned by the API at all, so they only disappear from the table after a full sync. |
> | `sincronizado_em` | Timestamp | When the TMTX API last synchronized this endpoint from the source system (meta.sincronizado\_em of the read that delivered this row). |

> [accordion] Transfers
>
> Stream name: `transferencias`. One row per item of a transfer order between branches and distribution centers. Not a stock posting nor a sale.
>
> **Sync Strategy:**
>
> * Incremental on `data_atualizacao` (the API's change marker)
> * Primary key(s): `id`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `id` | String | Stable identifier of the transfer item; unique within this endpoint (primary key). |
> | `id_transferencia_item` | String | Identifier of the transfer item (same value as id). |
> | `id_transferencia` | String | Identifier of the transfer order. |
> | `numero_transferencia` | String | Number of the transfer order. |
> | `pedido_omie` | String | Order number in Omie, when integrated; may be null. Not a global key across Omie accounts. |
> | `pedido_omie_id` | String | Internal identifier of the order integrated with Omie; may be null. |
> | `empresa_codigo` | String | Company of origin. |
> | `empresa_destino_codigo` | String | Destination company; depends on the active registration. |
> | `filial_origem_id` | String | Identifier of the origin branch (from the order). |
> | `filial_destino_id` | String | Identifier of the destination branch (from the branch linked to the active recipient). |
> | `loja_origem_codigo` | String | Code of the active origin branch. |
> | `loja_origem_nome` | String | Name of the active origin branch. |
> | `loja_destino_codigo` | String | Code of the active destination branch; null when it cannot be mapped. |
> | `loja_destino_nome` | String | Name of the active destination branch; null when it cannot be mapped. |
> | `origem_cd` | Boolean | Whether the origin is a distribution center, per registration; null when unavailable. |
> | `destino_cd` | Boolean | Whether the destination is a distribution center, per registration; null when unavailable. |
> | `instalacao_origem_codigo` | String | Code of the active installation informed on the item. |
> | `instalacao_origem_nome` | String | Name of the active installation informed on the item. |
> | `data_transferencia` | Date | Date of the transfer order; the field the API's period filter (data\_inicio/data\_fim) uses. |
> | `data_faturamento` | Date | First issue date of an active invoice, falling back to the billing date of the header. |
> | `data_entrega_informada` | Date | Delivery date recorded on the item or header; not proof of receipt. |
> | `origem_data_entrega` | String | Where data\_entrega\_informada came from. |
> | `produto_codigo` | String | Integrated code of the active product in TMTX. |
> | `produto_sku` | String | Commercial code (SKU) of the active product. |
> | `produto_descricao` | String | Description of the active product. |
> | `quantidade` | Number | Requested quantity; not sales revenue nor a stock debit/credit. |
> | `valor_total` | Number | Value of the item; not sales revenue. |
> | `status` | String | Status of the transfer order. Cancelled orders that are still active are kept. |
> | `status_origem` | String | Status description in the source system. |
> | `situacao_codigo` | String | Status identifier in the source system. |
> | `notas_fiscais` | String (JSON) | Active invoices of the order as a JSON array of objects with id, numero, serie, chave and data\_emissao. They are header references, not a per-item fiscal split. |
> | `tipo` | String | Record type (transferencia). |
> | `origem_registro` | String | Record origin (pedido\_transferencia). |
> | `tipo_documento_codigo` | String | Code of the transfer document type. |
> | `tipo_documento_descricao` | String | Description of the transfer document type. |
> | `data_previsao_entrega` | Date | Delivery forecast from the active, non-cancelled loading order (direct link first, then a linked transfer; the latest date when several apply). A plan, not proof of delivery. |
> | `origem_previsao_entrega` | String | Source of the delivery forecast: ordem\_carregamento or ordem\_carregamento\_transferencia\_vinculada; null when there is no forecast. |
> | `quantidade_entregue_origem` | Number | Delivered quantity (QTD\_ENTREGUE) recorded on the item in TMTX; does not tell when it was delivered. |
> | `data_atualizacao` | Timestamp | When the API last published a change to this transfer item; the API's incremental filter (atualizado\_desde) works on this field. |
> | `data_atualizacao_origem` | Timestamp | Informative change/insert date in the source system; not used as the sync marker. |
> | `excluido` | Boolean | Kept for compatibility; always false. Records deleted in the source (ATIVO=0) are not returned by the API at all, so they only disappear from the table after a full sync. |
> | `sincronizado_em` | Timestamp | When the TMTX API last synchronized this endpoint from the source system (meta.sincronizado\_em of the read that delivered this row). |

## Implementation Notes

### Data Quality Considerations

* **Deleted records**: records deleted in TMTX simply stop being returned by its API; there is no deletion notice, and the `excluido` column is always `false`. Incremental tables keep them until the next full sync (see the weekly full sync recommendation above). The **Inventory (current position)** table is replaced on every run, so deleted items leave it on the next run.
* **Inventory history**: TMTX keeps no past inventory positions, so the history starts on the first extraction and has one copy of each position published between your runs. Each run first reads a single record to check the position date; when it is the same as the last saved one, nothing is downloaded or added. When the table starts without a saved position (its first extraction, or a full sync), the run log warns that the table is replaced by the current position.
* **Empty inventory**: if TMTX returns an empty inventory position after an extraction that had rows, the inventory table fails for that run and keeps its previous content, because TMTX keeps the last published position available. An empty position is accepted, with a warning in the run log, only when there is no earlier extraction to compare with: the very first extraction, or a full sync of the source (which runs without the saved state). An accepted empty extraction does not reset that comparison, so the next regular runs are still protected. The inventory cost is the current accounting cost, not the historical cost of each sale.
* **Fields not available yet**: in the current TMTX API version, `linha`, `tamanho` and `quantidade_em_transito` (inventory) and `local_destino` (stock movements) are always empty. They are kept so they fill in automatically when TMTX starts sending them.
* **Freight**: `valor_frete` is the order's freight split across its items. Do not add it again if your revenue already includes freight.
* **Returns**: a return can point to a shipment or resale document that is not in the orders table. Use the identifiers on the return row (`contrato_documento_original`, `id_item_documento_original`, `pedido_omie`) instead of matching by product.
* **Delivery dates**: `data_remessa`, `data_entrega_informada` and `data_previsao_entrega` are informed or planned dates; TMTX does not confirm physical delivery.
* Identifiers and codes are text, and an `id` is only unique within its own table. `pedido_omie` must be matched within the right company/Omie account.
* Every row has `sincronizado_em`, the moment TMTX last refreshed that data from its own system.

### API Limits & Performance

* The connector reads 500 records per request and stays under TMTX's limit of 5 requests per second. When TMTX asks it to slow down or is temporarily unavailable, it waits and retries automatically.
* Each table is saved only after all of its pages were read and the record count matches the total reported by TMTX. If TMTX's read position expires during an extraction, the table is read again from the start (up to three times), so no record is duplicated or missed.
* Incremental extractions continue from the change marker TMTX returns at the end of each extraction. If an extraction fails, the next one starts again from the last successful point.

## Troubleshooting

| Error or symptom | What it means | What to do |
| :- | :- | :- |
| "TMTX rejected the access token" | The token is missing, wrong, revoked or was replaced (HTTP 401). | Check the token with TMTX and update it in the source configuration. |
| "TMTX denied this token access to ..." | The token is not authorized for that data (HTTP 403). The other tables continue. | Ask TMTX to authorize that endpoint for your token, or unselect the stream. |
| "The TMTX API asked us to slow down or is temporarily unavailable" | TMTX answered with a rate limit (429) or unavailability (503). | Nothing to do; the extraction retries on its own. If it fails, run it again later. |
| An extraction fails after many retries with TMTX unavailable | TMTX blocks reads when its data has not been refreshed for more than 24 hours (26 hours for inventory). | Contact TMTX to check their synchronization, then run the extraction again. |
| "did not deliver a complete, consistent read" | The pages returned by TMTX did not add up three times in a row. Nothing was saved for that table. | Run the extraction again later. If it keeps happening, contact support. |
| Deleted orders or movements still appear | TMTX does not report deletions. | Run a full sync of the main source. Never run it on the inventory history source. |
| "No saved inventory position was found" | The inventory history table started from scratch: its first extraction, or a full sync of its source. | On the first extraction, nothing to do. After a full sync, the earlier positions are lost; make sure the history source has no Additional Full Sync. |
| "TMTX returned an empty inventory position" (error) | TMTX sent no inventory rows although the previous extraction had them. The table was not changed. | Run again later. If it repeats, check the inventory publication with TMTX. |


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