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

# Cloudfy as a data source

> Bring sales receipts, delivery orders, customers, financial titles, cash register sessions, purchases, stock and price history from Cloudfy to Nekt.

Cloudfy is a Brazilian management system (ERP and point of sale) for restaurants, bars and food service: sales receipts and tabs, delivery orders, digital menu, stock, purchases and finance. This connector reads your Cloudfy company through Cloudfy's query APIs and brings your sales receipts with their items and payments, delivery and pre-orders (including those from iFood and other platforms), customers, door entries and digital menu reviews, accounts payable and receivable, cash register sessions, bank balances, purchases, stock and price history.

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

> [!WARNING]
>
> Cloudfy allows only **7 requests per hour and 168 per day for each company and branch**, and does not support reading long history. Read [Request limit](#request-limit) before choosing the tables and the schedule.

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

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

### 1. Add account access

Cloudfy releases API access on request. Open a ticket with Cloudfy support asking for access to the **query APIs (APIs de consulta)** for your company and branch, and confirm when they send you the documentation. Cloudfy then sends the access data you will paste here.

The following configurations are available:

* **Account Key**: The AccKey of your Cloudfy API access.
* **Token Key**: The TokenKey of your Cloudfy API access.
* **User Login**: The Cloudfy user login (LoginUsr) the access was released for.
* **Company Code**: Your Cloudfy company code (CodEmpresa).
* **Branch Code**: Your Cloudfy branch code (CodFilial). To bring several branches, create one source per branch: each branch has its own request limit.
* **Start Date**: The first business day read by the date-based tables on the first sync. Cloudfy does not support reading long history, so keep it recent (for example, the last 30 days).
* **Requester Name** (advanced): The name sent to Cloudfy as the requester of each query. Default: INTEGRACAO BI.
* **Max Requests per Sync** (advanced): The most requests one sync may send, from 1 to 7. Lower it if other tools use the same Cloudfy access. Default: 7.
* **Days per Request** (advanced): How many days of data each request asks for in the date-based tables, from 1 to 366. Default: 31.
* **Lookback Days** (advanced): How many days before the last synced day are read again on every sync, to catch late changes such as receipts cancelled later, orders delivered later or payments recorded with an earlier date. It must be smaller than **Days per Request**, so it costs no extra request. Default: 28.
* **Financial Titles Future Days** (advanced): How many days after today are included when reading financial titles, so open payables and receivables appear before they fall due, from 0 to 366. Default: 60.

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

### 2. Select streams

Choose which data streams you want to sync. Each main table costs one Cloudfy request per sync (Financial Titles costs two: open and cancelled titles are separate queries); the tables of items, payments, status history and installments come with their main table at no extra cost. Select only the tables you need (see [Request limit](#request-limit)).

> 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**: keep **INCREMENTAL** for every Cloudfy table. Cloudfy cannot re-read long history, so FULL\_TABLE would replace your tables with only the period from the Start Date.

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 the request limit: when the selected tables need up to 7 requests, a sync every hour fits; with more tables, schedule a sync every 2 or 3 hours, or once a day.

> [!WARNING]
>
> Do not configure an **Additional Full Sync** for this source, and avoid running a manual Full sync: a Full sync re-reads every table from the Start Date, and Cloudfy does not keep long history available, so the tables would be replaced by that period only.

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.

## Request limit

Cloudfy counts every request to its query APIs: at most **7 per hour and 168 per day for each company and branch**. The connector works within that limit:

* Each main table costs **one request per sync** in normal operation (Financial Titles costs two). Tables of items, payments, history and installments are read together with their main table.
* Each sync sends at most 7 requests (or the **Max Requests per Sync** you set) and also counts the requests of the previous syncs. When a sync starts just before the previous sync's requests are one hour old, it waits for them (up to 15 minutes) instead of skipping tables; the log says so.
* When more tables are selected than requests are available, the tables synced longest ago go first, and the others **wait for the next sync** (their data is kept and nothing is lost). The sync log lists which tables were read and which wait.
* On the **first sync** (and on a Full sync), a table must read every period from the Start Date to today at once, one request per **Days per Request** days. A table that does not fit in the requests left is not read in that sync and is marked as failed in the log; it is read in a next sync. If a table needs more requests than one sync may send, move the Start Date closer to today or raise **Days per Request**.
* If Cloudfy refuses a request because the limit was reached or the credentials are wrong, the connector stops sending requests in that sync and the remaining tables are read in the next one. Other refusals (for example, a query not released for your branch) fail only that table, with Cloudfy's message in the log; if the same access refusal comes for two tables, the sync stops sending requests.
* If a request fails (Cloudfy unavailable) and no request is left for a retry, the table fails in that sync and is read again in the next one.

> [!NOTE]
>
> For the first sync with many tables, either select tables worth at most 7 requests and add the others later, or accept that some tables fail the first sync and load in the following ones. Select the item, payment, history and installment tables together with their main table: a table of this kind selected later only gets rows from then on (and from the last **Lookback Days**).

## Fields by stream

Column names follow Cloudfy's own field names (for example, `vlr_total` for VlrTotal). Codes such as statuses and payment types are kept as Cloudfy sends them; their meanings are in the field descriptions. Dates and times are the branch's local (Brazil) time.

### Sales

> [accordion] Sales Receipts
>
> Sales receipts (cupons de venda) of the POS, one row per receipt, read by business date (Cloudfy API CC870).
>
> Table: `sales_receipts` · Primary key: `nr_empresa`, `nr_filial`, `nr_caixa`, `data_movimento`, `nr_cupom` · Sync: Incremental by `data_movimento`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `nr_caixa` | Integer | Cash register number. |
> | `caixa` | String | Cash register description. |
> | `nr_cupom` | Integer | Receipt number. |
> | `data_movimento` | Date | Business (cash movement) date of the receipt; used as the incremental replication key. |
> | `nr_movimento` | Integer | Cash movement (register session) number. |
> | `hr_abertura` | String | Time the receipt was opened (HH:MM). |
> | `hr_fechamento` | String | Time the receipt was closed (HH:MM). |
> | `qtde_itens` | Integer | Total quantity of items on the receipt. |
> | `qtde_produtos` | Integer | Number of distinct products on the receipt. |
> | `vlr_sub_total_produtos` | Number | Sum of the item totals of the receipt. |
> | `vlr_descontos` | Number | Discounts applied to the receipt. |
> | `vlr_acrescimos` | Number | Surcharges applied to the receipt (e.g. service fee). |
> | `vlr_total` | Number | Receipt total. |
> | `vlr_pago` | Number | Amount paid. |
> | `tp_venda` | Integer | Sale type: 1 = cash (à vista), 2 = on credit (a prazo). |
> | `nr_cliente` | Integer | Customer code (credit sales). |
> | `nome_cliente` | String | Customer name. |
> | `cpfcnpj_cliente` | String | Customer CPF/CNPJ. |
> | `sit_venda_prazo` | Integer | Status of the credit-sale receivable: 0 = pending payment, 9 = settled (paid). |
> | `qtde_clientes` | Integer | Number of customers served on the receipt. |
> | `observacoes` | String | Notes. |
> | `chave_nfce_nfe` | String | NFC-e / NF-e access key. |
> | `serie_nfce_nfe` | Integer | NFC-e / NF-e series. |
> | `nr_nfce_nfe` | Integer | NFC-e / NF-e number. |
> | `situacao_cupom` | Integer | Receipt status: 1 = open, 8 = deleted, 9 = closed. |
> | `desc_situacao` | String | Description of the receipt status. |
> | `motivo_cancelamento_cupom` | String | Reason the receipt was cancelled. |
> | `cod_usuario_cancelamento` | Integer | Code of the user who cancelled the receipt. |
> | `nome_usuario_cancelamento` | String | Name of the user who cancelled the receipt. |
> | `setor` | String | Sector. |

> [accordion] Sales Receipt Items
>
> Items of each sales receipt, including cancelled and reversed items with their status.
>
> Table: `sales_receipt_items` · Primary key: `nr_empresa`, `nr_filial`, `nr_caixa`, `data_movimento`, `nr_cupom`, `nr_item` · Sync: Incremental by `data_movimento`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `nr_caixa` | Integer | Cash register number of the receipt. |
> | `data_movimento` | Date | Business date of the receipt; used as the incremental replication key. |
> | `nr_cupom` | Integer | Receipt number. |
> | `nr_item` | Integer | Item number within the receipt. |
> | `cod_produto` | Integer | Product code. |
> | `cod_ref_produto` | String | Product reference code. |
> | `cod_barras` | String | Barcode. |
> | `desc_produto` | String | Product description. |
> | `cod_grupo` | Integer | Product group code. |
> | `desc_grupo` | String | Product group. |
> | `unidade` | String | Unit of measure. |
> | `vlr_unitario` | Number | Unit sale price. |
> | `qtde` | Number | Quantity. |
> | `sub_total` | Number | Subtotal (unit price x quantity). |
> | `nr_promocao` | Integer | Promotion number. |
> | `desc_promocao` | String | Promotion description. |
> | `vlr_acrescimos` | Number | Surcharges on the item. |
> | `cod_tipo_desconto` | Integer | Discount type code. |
> | `desc_tipo_desconto` | String | Discount type description. |
> | `vlr_descontos` | Number | Discounts on the item. |
> | `cod_usuario_desconto` | Integer | Code of the user who authorized/applied the discount. |
> | `nome_usuario_desconto` | String | Name of the user who authorized/applied the discount. |
> | `vlr_total` | Number | Item total (subtotal + surcharges - discounts). |
> | `vlr_desc_cupom_rateio` | Number | Share of the receipt-level discount allocated to the item. |
> | `vlr_total_liq` | Number | Net item total on the receipt. |
> | `cod_usuario_vendedor` | Integer | Code of the selling user (waiter/seller). |
> | `nome_usuario_vendedor` | String | Name of the selling user (waiter/seller). |
> | `nr_mesa_comanda` | Integer | Table or tab (comanda) number. |
> | `data_hora_lancamento` | Datetime | Date and time the item was added to the tab (local). |
> | `cod_usuario_exclusao` | Integer | Code of the user who reversed/removed the item. |
> | `nome_usuario_exclusao` | String | Name of the user who reversed/removed the item. |
> | `motivo_exclusao` | String | Reason for the reversal/cancellation. |
> | `situacao_item` | Integer | Item status: 1 = open, 8 = reversed, 9 = closed. |
> | `desc_situacao_item` | String | Description of the item status. |
> | `vlr_custo_medio_unit` | Number | Average unit cost. |

> [accordion] Sales Receipt Payments
>
> Payments of each sales receipt, with card acquirer, fees and expected settlement.
>
> Table: `sales_receipt_payments` · Primary key: `nr_empresa`, `nr_filial`, `nr_caixa`, `data_movimento`, `nr_cupom`, `nr_seq_pagto` · Sync: Incremental by `data_movimento`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `nr_caixa` | Integer | Cash register number of the receipt. |
> | `data_movimento` | Date | Business date of the receipt; used as the incremental replication key. |
> | `nr_cupom` | Integer | Receipt number. |
> | `nr_seq_pagto` | Integer | Payment sequence number within the receipt. |
> | `tipo_pagto` | Integer | Payment type: 10 cash, 20 debit card, 21 credit card, 22 TEF, 30 check, 40 other, 50 advance, 60 online payment. |
> | `nr_parcelas` | Integer | Number of installments. |
> | `desc_forma_pagamento` | String | Payment method description. |
> | `cod_forma_pagamento` | Integer | Payment method code. |
> | `vlr_pago` | Number | Amount paid with this payment. |
> | `data_pagto` | Date | Actual payment date (can be the day after the business date for sales after midnight). |
> | `nr_adiquirente` | Integer | Card acquirer number. |
> | `nome_adiquirente` | String | Card acquirer network name. |
> | `cod_produto_cartao` | Integer | Card product code. |
> | `nome_produto_cartao` | String | Card product name. |
> | `taxa_adquirente` | Number | Fee rate charged by the acquirer. |
> | `vlr_tarifa_taxa` | Number | Transaction fee amount (rate-based). |
> | `vlr_tarifa_fixa` | Number | Fixed transaction fee amount. |
> | `vlr_tarifa_total` | Number | Total fee amount. |
> | `data_corte` | Date | Acquirer cut-off date. |
> | `data_prev_recebimento` | Date | Expected settlement date. |
> | `prazo_recebimento` | Integer | Settlement term in days. |
> | `nr_transacao_tef` | String | TEF transaction number. |
> | `nr_transacao_tef_host` | String | TEF host transaction number. |
> | `codigo_autorizacao` | String | Authorization code. |
> | `data_hora_autorizacao` | Datetime | Transaction date and time (local). |
> | `nr_cartao` | String | Customer card number (as masked by Cloudfy). |
> | `sit_tef` | Integer | TEF transaction status: 1 = pending, 2 = approved, 3 = cancelled. |

> [accordion] Sales Summary
>
> Sales per day and payment method, with card settlement details (Cloudfy API CC891).
>
> Table: `sales_summary` · Primary key: `summary_key` · Sync: Incremental by `data_venda`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `data_venda` | Date | Sales date; used as the incremental replication key. |
> | `cod_forma_pagto` | Integer | Payment method code. |
> | `forma_pagto` | String | Payment method. |
> | `qtd_vendas` | Integer | Number of transactions. |
> | `vlr_vendas` | Number | Sales amount. |
> | `summary_key` | String | Synthetic identifier of the row (hash of nr\_empresa, nr\_filial, data\_venda, cod\_forma\_pagto, forma\_pagto), because Cloudfy sends no identifier for it. |
> | `cartoes` | String (JSON) | Card sales of the day by acquirer and card product, with expected settlement, fees and reconciliation status (JSON array). |

> [accordion] Tab Reversals
>
> Items reversed (estornados) from tabs, with who reversed them and why (Cloudfy API CC885).
>
> Table: `comanda_reversals` · Primary key: `reversal_key` · Sync: Incremental by `data_estorno`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `data_estorno` | Date | Reversal date; used as the incremental replication key. |
> | `nr_comanda` | Integer | Tab (comanda) number. |
> | `nr_item` | Integer | Item number. |
> | `cod_ref_produto` | String | Product reference code. |
> | `produto` | String | Product description. |
> | `unidade` | String | Unit of measure. |
> | `qtde_prod` | Number | Quantity reversed. |
> | `vlr_total` | Number | Item total. |
> | `cod_usuario_vendedor` | Integer | Code of the selling user. |
> | `usuario_vendedor` | String | Selling user. |
> | `cod_usuario_estorno` | Integer | Code of the user responsible for the reversal. |
> | `usuario_estorno` | String | User responsible for the reversal. |
> | `justificativa` | String | Reversal justification. |
> | `data_hora_estorno` | Datetime | Reversal date and time (local). |
> | `reversal_key` | String | Synthetic identifier of the row (hash of nr\_empresa, nr\_filial, nr\_comanda, nr\_item, cod\_ref\_produto, data\_hora\_estorno), because Cloudfy sends no identifier for it. |

### Orders

> [accordion] Orders
>
> Delivery orders, pre-orders and event orders, including the ones from iFood, Rappi and other platforms, read by order date (Cloudfy API CC890).
>
> Table: `orders` · Primary key: `nr_empresa`, `nr_filial`, `origem`, `nr_pedido` · Sync: Incremental by `data_pedido`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `origem` | Integer | Order origin: 1 = back office, 2 = POS. |
> | `nr_pedido` | Integer | Order number (sequential per origin). |
> | `nr_ctrl_pedido` | Integer | Order control number used in operations. |
> | `tipo` | Integer | Order type: 1 = delivery, 2 = pre-order, 3 = event. |
> | `data_pedido` | Date | Order date; used as the incremental replication key. |
> | `hora_pedido` | String | Order time (HH:MM). |
> | `ind_retirada_balcao` | Integer | Counter pickup: 1 = yes, 0 = no. |
> | `nr_sistema_integrador` | Integer | System that created the order: 1 Cloudfy, 2 Cloudfy delivery app, 20 iFood, 21 Uber Eats, 22 James, 23 Rappi, 30 Neemo, 31 Shipp, 32 Epadoca, 33 MeuCardapio, 50 WooCommerce, 51 Magento, 80 other. |
> | `chave_pedido_sistema_integrador` | String | Order key in the originating system. |
> | `cod_cliente` | Integer | Customer code. |
> | `nome_cliente` | String | Customer name. |
> | `cpfcnpj_cliente` | String | Customer CPF/CNPJ. |
> | `fone_cliente` | String | Customer phone. |
> | `endereco` | String | Delivery address. |
> | `nr_endereco` | String | Address number. |
> | `complemento_endereco` | String | Address complement. |
> | `bairro` | String | Neighborhood. |
> | `cidade` | String | City. |
> | `estado` | String | State. |
> | `cep` | String | Postal code (CEP). |
> | `data_prev_entrega` | Date | Expected delivery date. |
> | `hora_prev_entrega` | String | Expected delivery time (HH:MM). |
> | `data_finalizacao` | Date | Completion date. |
> | `hora_finalizacao` | String | Completion time (HH:MM). |
> | `desconto_integracao` | Number | Discount granted by vouchers of the originating platform (e.g. iFood); already allocated to the items. |
> | `valor_total_produtos` | Number | Total of the products. |
> | `valor_taxa_entrega` | Number | Delivery fee. |
> | `custo_operador_logistico` | Number | Logistics operator cost. |
> | `status` | Integer | Order status: 100 quote, 110 pre-sale, 200 approved (in preparation), 230 dispatched, 240 delivered, 400 completed (invoiced), 500 cancelled, 501 denied. |
> | `latitude` | Number | Customer latitude. |
> | `longitude` | Number | Customer longitude. |
> | `distancia` | Number | Distance from the store in kilometers. |
> | `nr_filial_cupom` | Integer | Number of the branch where the receipt was issued. |
> | `filial_cupom` | String | Branch where the receipt was issued. |
> | `nr_caixa_cupom` | Integer | Number of the cash register that issued the receipt. |
> | `caixa_cupom` | String | Cash register that issued the receipt. |
> | `nr_cupom` | Integer | Receipt number. |

> [accordion] Order Items
>
> Products of each order, including add-ons.
>
> Table: `order_items` · Primary key: `nr_empresa`, `nr_filial`, `origem`, `nr_pedido`, `nr_item`, `nr_item_adicional` · Sync: Incremental by `data_pedido`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `origem` | Integer | Order origin: 1 = back office, 2 = POS. |
> | `nr_pedido` | Integer | Order number (sequential per origin). |
> | `data_pedido` | Date | Order date; used as the incremental replication key. |
> | `nr_item` | Integer | Item number. |
> | `nr_item_adicional` | Integer | Add-on sequence of the item (0 for the main product). |
> | `cod_ref` | String | Product reference code. |
> | `produto` | String | Product. |
> | `valor_unit_prod` | Number | Unit price. |
> | `quantidade` | Number | Quantity. |
> | `unidade_de_medida` | String | Unit of measure. |
> | `valor_sub_total` | Number | Subtotal. |
> | `valor_desconto` | Number | Discount. |
> | `valor_acrescimo` | Number | Surcharge. |
> | `valor_total` | Number | Total (subtotal + surcharge - discount). |
> | `observacoes` | String | Notes. |

> [accordion] Order Payments
>
> Payments of each order.
>
> Table: `order_payments` · Primary key: `nr_empresa`, `nr_filial`, `origem`, `nr_pedido`, `nr_parcela` · Sync: Incremental by `data_pedido`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `origem` | Integer | Order origin: 1 = back office, 2 = POS. |
> | `nr_pedido` | Integer | Order number (sequential per origin). |
> | `data_pedido` | Date | Order date; used as the incremental replication key. |
> | `nr_parcela` | Integer | Installment number. |
> | `forma_pagamento` | String | Payment method. |
> | `valor_pagamento` | Number | Payment amount. |
> | `situac_pag` | Integer | Payment status: 1 = paid in advance on another platform, 2 = to be paid through Cloudfy. |

> [accordion] Order Status History
>
> Status changes of each order (created, in preparation, dispatched, delivered...).
>
> Table: `order_status_history` · Primary key: `nr_empresa`, `nr_filial`, `origem`, `nr_pedido`, `seq` · Sync: Incremental by `data_pedido`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `origem` | Integer | Order origin: 1 = back office, 2 = POS. |
> | `nr_pedido` | Integer | Order number (sequential per origin). |
> | `data_pedido` | Date | Order date; used as the incremental replication key. |
> | `seq` | Integer | Position of the row within its parent (1-based). |
> | `data_evento` | Datetime | Event date and time (local). |
> | `descricao` | String | Event description. |
> | `status_evento` | Integer | Order status set by the event (see orders.status). |

### Customers

> [accordion] Customers
>
> Customers and their addresses, one row per customer address (Cloudfy API CC884). Read in full on every sync.
>
> Table: `customers` · Primary key: `nr_empresa`, `nr_cliente`, `seq_endereco` · Sync: Incremental by `snapshot_date`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_cliente` | Integer | Customer number. |
> | `cliente` | String | Customer name. |
> | `seq_endereco` | Integer | Address sequence number of the customer. |
> | `cpf_cnpj` | String | Customer CPF/CNPJ. |
> | `tp_pessoa` | String | Person type: PF = individual, PJ = company. |
> | `nr_tp_cliente` | Integer | Customer type number. |
> | `tp_cliente` | String | Customer type. |
> | `data_nascimento` | Date | Date of birth. |
> | `email` | String | Email. |
> | `telefone` | String | Phone. |
> | `celular` | String | Mobile phone. |
> | `nr_tp_endereco` | Integer | Address type number. |
> | `tp_endereco` | String | Address type. |
> | `logradouro` | String | Street. |
> | `numero` | String | Street number. |
> | `complemento` | String | Address complement. |
> | `bairro` | String | Neighborhood. |
> | `cidade` | String | City. |
> | `cep` | String | Postal code (CEP). |
> | `estado` | String | State (abbreviation). |
> | `snapshot_date` | Date | Day (Brazil time) on which this snapshot was read from Cloudfy; used as the incremental replication key. |

> [accordion] Door Entries
>
> Entrance (door) registrations of customers, with the tab given at the entrance and the amount purchased (Cloudfy API CC875).
>
> Table: `door_entries` · Primary key: `entry_key` · Sync: Incremental by `data_entrada`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `nr_mesa_comanda` | Integer | Table or tab (comanda) number given at the entrance. |
> | `nr_cliente` | Integer | Customer code. |
> | `nome_cliente` | String | Customer name. |
> | `email` | String | Customer email. |
> | `telefone` | String | Customer phone. |
> | `sexo` | String | Customer sex (M = male, F = female). |
> | `data_nascimento` | Date | Customer date of birth. |
> | `cpf_cnpj` | String | Customer CPF/CNPJ. |
> | `data_hora_entrada` | Datetime | Entrance date and time (local). |
> | `data_hora_saida` | Datetime | Exit date and time (local). |
> | `vlr_compras` | Number | Amount purchased during the visit. |
> | `entry_key` | String | Synthetic identifier of the row (hash of nr\_empresa, nr\_filial, nr\_mesa\_comanda, data\_hora\_entrada, nr\_cliente, cpf\_cnpj, nome\_cliente), because Cloudfy sends no identifier for it. |
> | `data_entrada` | Date | Day of the entrance; used as the incremental replication key. |

> [accordion] Digital Menu Reviews
>
> Ratings and comments left on the digital menu (Cloudfy API CC874).
>
> Table: `digital_menu_reviews` · Primary key: `review_key` · Sync: Incremental by `data`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `data` | Date | Date of the review; used as the incremental replication key. |
> | `nr_mesa_comanda` | Integer | Table or tab (comanda) number. |
> | `nome_cliente` | String | Customer name. |
> | `email` | String | Customer email. |
> | `avaliacao_comida` | Integer | Food rating (1 to 5). |
> | `avaliacao_bebida` | Integer | Drinks rating (1 to 5). |
> | `avaliacao_atendimento` | Integer | Service rating (1 to 5). |
> | `avaliacao_ambiente` | Integer | Ambience rating (1 to 5). |
> | `comentarios` | String | Comments. |
> | `review_key` | String | Synthetic identifier of the row (hash of nr\_empresa, nr\_filial, data, nr\_mesa\_comanda, nome\_cliente, email, avaliacao\_comida, avaliacao\_bebida, avaliacao\_atendimento, avaliacao\_ambiente, comentarios), because Cloudfy sends no identifier for it. |

### Finance

> [accordion] Financial Titles
>
> Accounts payable, accounts receivable and transfers, read by cash-flow date: the due date while open, the payment date once paid (Cloudfy API CC871).
>
> Table: `financial_titles` · Primary key: `title_key` · Sync: Incremental by `data`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `tipo_lancamento` | Integer | Entry type: 10 accounts payable, 20 accounts receivable, 30 transfer debit, 40 transfer credit. |
> | `conta_bancaria` | String | Bank account. |
> | `data` | Date | Cash-flow date: the due date while the title is open, the payment date once paid; used as the incremental replication key. |
> | `data_vencimento` | Date | Due date. |
> | `data_pagto` | Date | Payment/receipt date. |
> | `data_documento` | Date | Document date. |
> | `data_lancamento` | Date | Entry date. |
> | `descricao` | String | Title description. |
> | `nr_documento` | String | Document number. |
> | `cliente_fornecedor` | String | Customer/supplier name. |
> | `cpfcnpj` | String | Customer/supplier CPF/CNPJ. |
> | `tipo_de_documento` | String | Document type. |
> | `centro_de_custo` | String | Cost center. |
> | `vlr_lancamento` | Number | Entry amount. |
> | `vlr_descontos` | Number | Discounts. |
> | `vlr_acrescimos` | Number | Surcharges. |
> | `vlr_juros_mora` | Number | Late interest. |
> | `vlr_total` | Number | Total amount. |
> | `vlr_pago` | Number | Amount paid/received. |
> | `perc_acres_desc` | Number | Surcharge/discount percentage. |
> | `cod_situacao` | Integer | Title status: 10 pending payment/receipt, 80 cancelled, 85 deleted, 90 paid/received. |
> | `desc_situacao` | String | Description of the title status. |
> | `categoria` | String | Financial category. |
> | `observacoes` | String | Notes. |
> | `title_key` | String | Synthetic identifier of the row (hash of nr\_empresa, nr\_filial, tipo\_lancamento, nr\_documento, data\_documento, data\_lancamento, data\_vencimento, descricao, cpfcnpj, categoria, vlr\_lancamento), because Cloudfy sends no identifier for it. |

> [accordion] Cash Register Sessions
>
> Cash register sessions (movimentos de caixa) with opening and closing balances and totals per payment method (Cloudfy API CC888).
>
> Table: `cash_register_sessions` · Primary key: `nr_empresa`, `nr_filial`, `nr_caixa`, `data_movto`, `nr_movto` · Sync: Incremental by `data_movto`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `nr_caixa` | Integer | Cash register number. |
> | `caixa` | String | Cash register. |
> | `data_movto` | Date | Business date of the cash session; used as the incremental replication key. |
> | `nr_movto` | Integer | Cash session (movement) number. |
> | `data_abertura` | Datetime | Opening date and time (local). |
> | `data_fechamento` | Datetime | Closing date and time (local). |
> | `data_conciliamento` | Datetime | Reconciliation date and time (local). |
> | `nr_usr_resp_abertura` | Integer | Number of the operator who opened the register. |
> | `usr_resp_abertura` | String | Operator who opened the register. |
> | `nr_usr_resp_fechamento` | Integer | Number of the operator who closed the register. |
> | `usr_resp_fechamento` | String | Operator who closed the register. |
> | `nr_usr_resp_conciliacao` | Integer | Number of the operator who reconciled the register. |
> | `usr_resp_conciliacao` | String | Operator who reconciled the register. |
> | `saldo_inicial` | Number | Opening balance. |
> | `saldo_inicial_conc` | Number | Reconciled opening balance. |
> | `cred_vendas` | Number | Credits - sales. |
> | `cred_rec_vendas_prazo` | Number | Credits - receipts of credit sales. |
> | `cred_outros` | Number | Credits - other. |
> | `cred_outros_conc` | Number | Credits - other, reconciled. |
> | `cred_total` | Number | Credits - total. |
> | `deb_sangrias` | Number | Debits - cash withdrawals (sangrias). |
> | `deb_sangrias_conc` | Number | Debits - cash withdrawals, reconciled. |
> | `deb_outros` | Number | Debits - other. |
> | `deb_total` | Number | Debits - total. |
> | `saldo_final_calc` | Number | Calculated closing balance. |
> | `saldo_final_info` | Number | Closing balance informed by the operator. |
> | `dif_saldo_final` | Number | Closing balance difference (calculated - informed). |
> | `qtde_venda_vista` | Integer | Number of cash sales. |
> | `vlr_venda_vista` | Number | Total of cash sales. |
> | `qtde_venda_prazo` | Integer | Number of credit sales. |
> | `vlr_venda_prazo` | Number | Total of credit sales. |
> | `qtde_venda` | Integer | Number of sales. |
> | `vlr_venda` | Number | Total of sales (cash sales + receipts of credit sales). |
> | `qtde_rec_prazo` | Integer | Number of receipts of credit sales. |
> | `qtde_descontos` | Integer | Number of discounts. |
> | `vlr_descontos` | Number | Total of discounts. |
> | `qtde_acrescimos` | Integer | Number of surcharges. |
> | `vlr_acrescimos` | Number | Total of surcharges. |
> | `qtde_cancelamento_itens` | Integer | Number of removed items. |
> | `vlr_cancelamento_itens` | Number | Total of removed items. |
> | `qtde_cancelamento_cupom` | Integer | Number of cancelled receipts. |
> | `vlr_cancelamento_cupom` | Number | Total of cancelled receipts. |
> | `vlr_dinheiro_calc` | Number | Cash total, calculated. |
> | `vlr_dinheiro_info` | Number | Cash total, informed. |
> | `vlr_dinheiro_conc` | Number | Cash total, reconciled. |
> | `vlr_credito_calc` | Number | Credit card total, calculated. |
> | `vlr_credito_info` | Number | Credit card total, informed. |
> | `vlr_credito_conc` | Number | Credit card total, reconciled. |
> | `vlr_debito_calc` | Number | Debit card total, calculated. |
> | `vlr_debito_info` | Number | Debit card total, informed. |
> | `vlr_debito_conc` | Number | Debit card total, reconciled. |
> | `vlr_cheque_calc` | Number | Check total, calculated. |
> | `vlr_cheque_info` | Number | Check total, informed. |
> | `vlr_cheque_conc` | Number | Check total, reconciled. |
> | `vlr_outros_calc` | Number | Other payment methods total, calculated. |
> | `vlr_outros_info` | Number | Other payment methods total, informed. |
> | `vlr_outros_conc` | Number | Other payment methods total, reconciled. |
> | `vlr_online_calc` | Number | Online payments total, calculated. |
> | `vlr_online_info` | Number | Online payments total, informed. |
> | `vlr_online_conc` | Number | Online payments total, reconciled. |
> | `vlr_pix_calc` | Number | PIX total, calculated. |
> | `vlr_pix_info` | Number | PIX total, informed. |
> | `vlr_pix_conc` | Number | PIX total, reconciled. |
> | `vlr_gorjetas` | Number | Total tips / vouchers. |
> | `observacoes` | String | Notes. |
> | `cod_situacao` | Integer | Session status: 2 = closed, 3 = reconciled. |

> [accordion] Bank Balances
>
> Balance of each bank account on the day of each sync; a daily history builds up over time (Cloudfy API CC872).
>
> Table: `bank_balances` · Primary key: `balance_key` · Sync: Incremental by `snapshot_date`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `nr_conta` | Integer | Bank account number in Cloudfy. |
> | `conta_bancaria` | String | Bank account. |
> | `vlr_saldo` | Number | Account balance on the snapshot date. |
> | `snapshot_date` | Date | Reference day of the snapshot (Brazil time): the position at the end of that day, or at the time of the sync for today; used as the incremental replication key. |
> | `balance_key` | String | Synthetic identifier of the row (hash of snapshot\_date, nr\_empresa, nr\_filial, nr\_conta, conta\_bancaria), because Cloudfy sends no identifier for it. |

### Purchases and stock

> [accordion] Purchases
>
> Purchases (supplier invoices), read by purchase date (Cloudfy API CC892).
>
> Table: `purchases` · Primary key: `purchase_key` · Sync: Incremental by `data_compra`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `desc_compra` | String | Purchase description. |
> | `cod_fornecedor` | Integer | Supplier code. |
> | `fornecedor` | String | Supplier. |
> | `cpfcnpj_fornecedor` | String | Supplier CPF/CNPJ. |
> | `nr_doc` | String | Document number. |
> | `chave_nf` | String | Invoice (NF) access key. |
> | `data_compra` | Date | Purchase date; used as the incremental replication key. |
> | `vlr_total_itens` | Number | Total of the items. |
> | `vlr_frete` | Number | Freight. |
> | `vlr_impostos` | Number | Taxes. |
> | `vlr_descontos` | Number | Discounts. |
> | `vlr_out_despesas` | Number | Other expenses. |
> | `vlr_total` | Number | Purchase total. |
> | `integ_compra` | Integer | Stock integration status: 1 = not integrated, 2 = partially integrated, 3 = integrated. |
> | `purchase_key` | String | Synthetic identifier of the row (hash of nr\_empresa, nr\_filial, cod\_fornecedor, nr\_doc, chave\_nf, data\_compra, desc\_compra), because Cloudfy sends no identifier for it. |

> [accordion] Purchase Items
>
> Items of each purchase, with the product they were integrated into in stock.
>
> Table: `purchase_items` · Primary key: `purchase_key`, `nr_item` · Sync: Incremental by `data_compra`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `purchase_key` | String | Synthetic identifier of the purchase (see purchases.purchase\_key). |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `data_compra` | Date | Purchase date; used as the incremental replication key. |
> | `nr_item` | Integer | Item number in the purchase. |
> | `cod_barras` | String | Barcode. |
> | `und_medida_compra` | String | Unit of measure in the purchase. |
> | `item_compra` | String | Item description in the purchase. |
> | `cod_ref_integrado` | String | Reference code of the product the item was integrated into. |
> | `produto_integrado` | String | Product the item was integrated into. |
> | `und_medida_integrado` | String | Unit of measure of the integrated product. |
> | `qtd_integrada` | Number | Integrated (converted) quantity. |
> | `vlr_unit_integrado` | Number | Integrated (converted) unit value. |
> | `vlr_unit` | Number | Unit value of the item. |
> | `qtde` | Number | Quantity. |
> | `vlr_bruto` | Number | Gross value (quantity x unit value). |
> | `vlr_impostos` | Number | Taxes. |
> | `vlr_acres` | Number | Surcharges. |
> | `vlr_frete` | Number | Allocated freight. |
> | `vlr_desconto` | Number | Discount. |
> | `valor_total` | Number | Item total (gross + taxes + surcharges + freight - discount). |
> | `data_validade` | Date | Expiry date. |
> | `situacao` | Integer | Integration status of the item: 0 = not integrated, 1 = integrated. |

> [accordion] Purchase Installments
>
> Installments (payables) of each purchase.
>
> Table: `purchase_installments` · Primary key: `purchase_key`, `nr_parcela` · Sync: Incremental by `data_compra`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `purchase_key` | String | Synthetic identifier of the purchase (see purchases.purchase\_key). |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `data_compra` | Date | Purchase date; used as the incremental replication key. |
> | `nr_parcela` | Integer | Installment number. |
> | `data_venc` | Date | Due date. |
> | `nr_doc` | String | Document number. |
> | `nr_categoria_financeira` | Integer | Financial category number. |
> | `categoria_financeira` | String | Financial category. |
> | `nr_conta_bancaria` | Integer | Bank account number. |
> | `conta_bancaria` | String | Bank account. |
> | `nr_centro_custo` | Integer | Cost center number. |
> | `centro_custo` | String | Cost center. |
> | `nr_tipo_doc` | Integer | Document type number. |
> | `tipo_doc` | String | Document type. |
> | `vlr_acres` | Number | Surcharge. |
> | `vlr_desconto` | Number | Discount. |
> | `vlr_juros` | Number | Interest. |
> | `vlr_parcela` | Number | Installment amount. |
> | `vlr_total` | Number | Total (installment + surcharge + interest - discount). |
> | `situacao_pag` | Integer | Payment status: 10 = pending, 90 = paid. |
> | `situacao_integ_fin` | Integer | Integration with finance: 0 = not integrated, 1 = integrated. |

> [accordion] Stock Positions
>
> Stock balance per product and stock center on the day of each sync; a daily history builds up over time (Cloudfy API CC873).
>
> Table: `stock_positions` · Primary key: `snapshot_date`, `nr_empresa`, `nr_filial`, `nr_centro_estoque`, `cod_produto` · Sync: Incremental by `snapshot_date`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `nr_centro_estoque` | Integer | Stock center number. |
> | `centro_estoque` | String | Stock center. |
> | `cod_produto` | Integer | Product code. |
> | `cod_barras` | String | Barcode. |
> | `desc_produto` | String | Product description. |
> | `cod_grupo` | Integer | Product group code. |
> | `desc_grupo` | String | Product group. |
> | `unidade` | String | Unit of measure. |
> | `vlr_unitario` | Number | Product sale price. |
> | `saldo_estoque` | Number | Stock balance on the snapshot date. |
> | `vlr_custo_medio_unit` | Number | Average unit cost. |
> | `vlr_custo_medio_total` | Number | Average total cost. |
> | `situacao` | String | Product status (active or inactive). |
> | `snapshot_date` | Date | Reference day of the snapshot (Brazil time): the position at the end of that day, or at the time of the sync for today; used as the incremental replication key. |

> [accordion] Daily Stock Movements
>
> Stock entries and exits per day, product, stock center and reason (Cloudfy API CC886).
>
> Table: `daily_stock_movements` · Primary key: `nr_empresa`, `data`, `nr_filial`, `nr_centro_estoque`, `cod_ref_produto`, `motivo` · Sync: Incremental by `data`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `data` | Date | Movement date; used as the incremental replication key. |
> | `motivo` | Integer | Movement reason: 10 sale, 20 manual, 30 branch transfer, 40 inventory, 50 loss, 51 bonus, 60 purchase, 70 production, 80 load/migration, 90 balance update, 100 NF-e purchase, 110 customer return, 120 return to supplier. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `nr_centro_estoque` | Integer | Stock center number. |
> | `centro_estoque` | String | Stock center. |
> | `cod_ref_produto` | String | Product reference code. |
> | `produto` | String | Product. |
> | `unidade_medida` | String | Unit of measure. |
> | `qtde_saidas` | Number | Quantity out. |
> | `qtde_entradas` | Number | Quantity in. |
> | `qtde_movimento` | Number | Net quantity moved. |

> [accordion] Price History
>
> Product price changes, one row per change (Cloudfy API CC881).
>
> Table: `price_history` · Primary key: `price_change_key` · Sync: Incremental by `data`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `produto` | String | Product. |
> | `cod_ref_produto` | String | Product reference code. |
> | `cod_barras` | String | Barcode. |
> | `cod_grupo` | Integer | Product group code. |
> | `desc_grupo` | String | Product group. |
> | `unidade` | String | Unit of measure. |
> | `vlr_unitario` | Number | Current product sale price. |
> | `data` | Date | Date of the price change; used as the incremental replication key. |
> | `filial_alteracao` | String | Branch where the price changed. |
> | `novo_preco_vista` | Number | New cash (à vista) price. |
> | `novo_preco_prazo` | Number | New credit (a prazo) price. |
> | `usuario` | String | User who changed the price. |
> | `price_change_key` | String | Synthetic identifier of the row (hash of nr\_empresa, nr\_filial, cod\_ref\_produto, data, filial\_alteracao, novo\_preco\_vista, novo\_preco\_prazo, usuario), because Cloudfy sends no identifier for it. |

### Company

> [accordion] Branches
>
> Branches of the company (Cloudfy API CC882). Read in full on every sync.
>
> Table: `branches` · Primary key: `nr_empresa`, `nr_filial` · Sync: Incremental by `snapshot_date`
>
> | Field | Type | Description |
> | :- | :- | :- |
> | `nr_empresa` | Integer | Company number in Cloudfy. |
> | `empresa` | String | Company name. |
> | `nr_filial` | Integer | Branch number in Cloudfy. |
> | `filial` | String | Branch name. |
> | `cnpj_filial` | String | Branch CNPJ. |
> | `snapshot_date` | Date | Day (Brazil time) on which this snapshot was read from Cloudfy; used as the incremental replication key. |

## Implementation notes

* **Business dates, not change dates.** Cloudfy filters by business date (receipt, order, purchase date) and has no "changed since" filter. Each sync re-reads the last **Lookback Days** (28 by default), so receipts cancelled later, orders delivered later and payments recorded with an earlier date are updated within that period; changes older than that keep the previous values.
* **Financial titles** are read by cash-flow date: an open title appears on its due date and is read again on the day it is paid. Cancelled titles are read too (a separate query), so a title cancelled after being loaded gets its cancelled status when its due date falls within the period read. An overdue title cancelled more than **Lookback Days** after its due date keeps its last (open) status.
* **Rows without an identifier.** Some Cloudfy tables (financial titles, purchases, sales summary, reviews, door entries, reversals, price history, bank balances) have no identifier of their own; the connector builds one from the fields listed in the key column's description. If one of those fields changes (for example, a renegotiated due date), the row is loaded again as a new row.
* **Snapshots.** Bank balances and stock positions are read per day: each sync reads today, plus every day missed since the last sync, up to 7 days back. Days older than that are not read and stay missing (the sync log names them), so sync these tables at least once a week. A Full sync, or the FULL\_TABLE sync type, replaces these two tables with today's snapshot only, losing their daily history. Customers and branches are read in full on every sync.
* **Errors are never shown as empty tables.** When Cloudfy answers with an error, the table fails in the log with Cloudfy's message and keeps its data; only Cloudfy's "no records found" answers about the data itself (such as "Nenhum cupom encontrado" or "Não há registros para o período") count as an empty period.
* The connector's 15 main tables come with 7 tables of items, payments, history and installments. Not available: recipes (ficha técnica), DRE report, current-day order queue and cash withdrawals/supplies.


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