> ## 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.
# Barte as a data source
> Bring data from Barte to Nekt.
Barte is a Brazilian payments platform for online billing, in-person card terminals, and recurring subscriptions. This connector extracts orders, charges, subscriptions, buyers, plans, payment links, and the account's financial statement from your Barte account into your Nekt Catalog.
## Configuring Barte as a Source
In the [Sources](https://app.nekt.ai/sources) tab, click the "Add source" button in the top-right corner, then select Barte from the list of connectors.
Click **Next** and add your access details.
### 1. Add account access
The following configuration fields are available:
* **API key**: Token used to authenticate against the Barte API, sent as the `X-Token-Api` header.
* If your account is a **seller** (vendedor), find it in the Barte seller portal under **Configurações » Integração**.
* If your account is a **payment intermediary** (intermediador), find each seller's key in the intermediary portal under **Vendedores » select the seller » Integração**.
* For details, check the [Barte authentication documentation](https://docs.barte.com/guias/seguranca/autenticacao).
* **Environment**: Which Barte environment to read from, `production` or `sandbox`. Keys are issued per environment and are not interchangeable.
* **Start date** (advanced): The earliest record date to sync. It bounds the first run of Charges and the date windows of the two Statement streams. Orders, Buyers, Plans, and Payment links have no date filter in the Barte API and are always read in full.
* **Requests per minute** (advanced): Maximum number of requests per minute the connector sends. Barte publishes no numeric quota but answers HTTP 429 when an account goes too fast, so this acts as a safety belt. Lower it if your account gets rate limited.
* **Window size (days)** (advanced): Days requested per call on the two Statement streams.
After configuring access, click **Next**.
### 2. Select streams
Choose which streams you want to sync. For faster extractions, select only the streams you need.
> Tip: You can search streams by name.
Select the streams and click **Next**.
### 3. Configure data streams
Customize how data should appear in your Catalog, including layer, table naming, and sync type.
* **Layer**: Select the destination layer where extracted tables will be created.
* **Table name**: Use the suggested name or customize it. You can also apply a prefix to all tables.
* **Sync Type**: Choose between `INCREMENTAL` and `FULL_TABLE`.
Only the **Charges** stream supports `INCREMENTAL` sync. Barte's other list endpoints have no creation-date filter, so every other stream reads in full on each run.
When you're done, click **Next**.
### 4. Configure data source
Add a clear description for this source so your team can identify it easily.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), choose how often data should be extracted (for example, daily, weekly, or at fixed times).
Optionally, configure additional settings:
* Delta Log Retention, which controls how long old table states are kept. Learn more [here](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Additional [Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync), to periodically complement incremental runs with a complete refresh.
When you are ready, click **Next** to finalize setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, trigger a run manually from the source actions.
To see data in the [Catalog](https://app.nekt.ai/catalog), at least one source run must complete successfully.
## Good to know
* **Orders vs. Charges.** An order (pedido) is the commercial intent — what was sold, to whom, for how much. A charge (cobrança) is an individual payment attempt against it. A one-off sale has a single charge; an instalment plan or a subscription cycle has several. Join them on `order_uuid`.
* **Incremental sync filters on creation, not update.** A charge whose status changes long after it was created — a late refund or a chargeback — is not picked up again by an incremental run. Schedule an [Additional Full Sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync) if you need those corrections reflected. The two Statement streams re-read their whole window on every run, so they already repair themselves.
* **Subscriptions come from charges.** Barte publishes no endpoint that lists subscriptions, so this connector reaches them through the charges they generated. A subscription that has never produced a charge is not available through the API, and on an incremental run you see the subscriptions billed inside the window.
* **Statement entries may not be available.** The `/report/statement` endpoint is documented under Barte's payment-intermediary section. If your key is a plain seller key and Barte refuses it, the connector skips that stream with a warning in the run log and continues; use **Statement with balance** instead.
* **Nested data is stored as JSON strings.** Fields such as `charges` and `refunds` are text columns containing JSON, so they can be parsed in a Query or Notebook without the table schema changing when Barte adds a field.
# Streams and Fields
Below are the currently available streams in the Barte connector and their main fields.
Orders (pedidos) created on the account, from the `/v2/orders` endpoint.
| Field | Type | Description |
| :--------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid` | String | Unique identifier of the order, used as the primary key. |
| `status` | String | Current status of the order: SENT, ABANDONED, PAID, CANCELED, LATE or PARTIALLY\_PAID. |
| `title` | String | Title of the order, shown to the buyer on the checkout and receipts. |
| `description` | String | Free-text description of what is being charged. |
| `value` | Number | Total amount of the order, in the account's currency. |
| `installments` | Integer | Number of instalments the order was split into (1 for a single payment). |
| `start_date` | Date | Date the order's billing starts. |
| `payment` | String | Payment method chosen for the order: CREDIT\_CARD, DEBIT\_CARD, PIX, BANK\_SLIP, CREDIT\_CARD\_EARLY\_SELLER or CREDIT\_CARD\_EARLY\_BUYER. |
| `customer_uuid` | String | Unique identifier of the buyer the order belongs to. |
| `customer_document` | String | Tax document of the buyer (CPF or CNPJ in Brazil). |
| `customer_type` | String | Type of the buyer's tax document: CPF, CNPJ or SSN. |
| `customer_document_country` | String | Country that issued the buyer's tax document. |
| `customer_name` | String | Full name of the buyer. |
| `customer_email` | String | Primary e-mail address of the buyer. |
| `customer_phone` | String | Phone number of the buyer. |
| `customer_alternative_email` | String | Secondary e-mail address of the buyer, when one was provided. |
| `idempotency_key` | String | Idempotency key sent when the order was created, used to avoid duplicate orders. |
| `charges` | String | Charges generated by this order (JSON array of objects). Each charge is also published as its own row in the charges stream. |
| `serial_number` | String | Serial number of the card terminal that processed the transaction, for in-person (POS) orders. |
| `terminal_id` | String | Logical identifier of the card terminal that processed the transaction, for in-person (POS) orders. |
| `origin_request` | String | Channel the order came from: API, PAYMENT\_LINK, POS, TAP\_TO\_PAY, ECOMMERCE or TEF. |
Individual payment attempts, from the `/v2/charges` endpoint. This is the only stream that supports `INCREMENTAL` sync.
| Field | Type | Description |
| :------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------- |
| `uuid` | String | Unique identifier of the charge, used as the primary key. |
| `title` | String | Title of the charge, shown to the buyer on the checkout and receipts. |
| `expiration_date` | Date | Date the charge expires and can no longer be paid. |
| `value` | Number | Amount actually charged, after any discount or interest. |
| `original_value` | Number | Amount of the charge before discounts, interest or fees were applied. |
| `payment_method` | String | Payment method used: CREDIT\_CARD, DEBIT\_CARD, PIX, BANK\_SLIP, CREDIT\_CARD\_EARLY\_SELLER or CREDIT\_CARD\_EARLY\_BUYER. |
| `status` | String | Current status of the charge: SENT, PENDING, AUTHORIZED, CAPTURED, PAID or CANCELED. |
| `installments` | Integer | Number of instalments this charge was split into. |
| `brand` | String | Card brand used on the transaction (null for Pix and bank slips). |
| `customer_document` | String | Tax document of the buyer (CPF or CNPJ in Brazil). |
| `customer_type` | String | Type of the buyer's tax document: CPF, CNPJ or SSN. |
| `customer_name` | String | Full name of the buyer. |
| `customer_email` | String | Primary e-mail address of the buyer. |
| `customer_phone` | String | Phone number of the buyer. |
| `authorization_code` | String | Authorisation code returned by the card issuer when the transaction was approved. |
| `authorization_nsu` | String | NSU (sequential transaction number) assigned by the acquirer. |
| `refunds` | String | Refunds issued against this charge (JSON array of objects with id, createdAt, amount and requestStatus). |
| `error_reason` | String | Reason the payment was declined, when it failed. |
| `created_at` | DateTime | Timestamp the charge was created, normalised to UTC and used as the incremental replication key. |
| `paid_date` | Date | Date the charge was actually paid. |
| `order_uuid` | String | Unique identifier of the order this charge belongs to. |
| `subscription_uuid` | String | Unique identifier of the subscription that generated this charge, when it came from recurring billing. |
Recurring billing agreements, from the the subscription detail endpoint endpoint. Barte has no endpoint that lists subscriptions, so they are reached through the charges they generated.
| Field | Type | Description |
| :------------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid` | String | Unique identifier of the subscription, used as the primary key. |
| `status` | String | Current status of the subscription: PENDING, ACTIVE, DEFAULTER or INACTIVE. |
| `start_date` | Date | Date the subscription's billing cycle starts. |
| `payment_method` | String | Payment method used for the recurring charges: CREDIT\_CARD, PIX or BANK\_SLIP. |
| `customer_uuid` | String | Unique identifier of the subscriber. |
| `customer_name` | String | Full name of the subscriber. |
| `customer_email` | String | Primary e-mail address of the subscriber. |
| `customer_document` | String | Tax document of the subscriber (CPF or CNPJ in Brazil). |
| `value` | String | Recurring amount and billing frequency of the subscription (JSON object with type — MONTHLY, SEMESTER or YEARLY — and valuePerMonth). |
| `additional_value` | String | One-off amount billed on top of the recurring value (JSON object with installments and value). |
| `charges` | String | Charges generated by this subscription (JSON array of objects). Each charge is also published as its own row in the charges stream. |
Customers registered on the account, from the `/v2/buyers` endpoint.
| Field | Type | Description |
| :------------------ | :----- | :------------------------------------------------------------ |
| `uuid` | String | Unique identifier of the buyer, used as the primary key. |
| `document` | String | Tax document of the buyer (CPF or CNPJ in Brazil). |
| `name` | String | Full name of the buyer. |
| `country_code` | String | Country code of the buyer's phone number. |
| `phone` | String | Phone number of the buyer. |
| `email` | String | Primary e-mail address of the buyer. |
| `alternative_email` | String | Secondary e-mail address of the buyer, when one was provided. |
Subscription plan catalogue, from the `/v2/plans` endpoint.
| Field | Type | Description |
| :----------------------- | :------ | :----------------------------------------------------------------------------------------------- |
| `uuid` | String | Unique identifier of the plan, used as the primary key. |
| `title` | String | Title of the plan, shown to subscribers. |
| `description` | String | Description of what the plan includes. |
| `active` | Boolean | Whether the plan is currently active and can be subscribed to. |
| `bullets` | String | Benefits listed on the plan (JSON array of objects). |
| `values` | String | Price of the plan per billing frequency (JSON array of objects with the charge type and amount). |
| `accept_payment_methods` | Array | Payment methods the plan accepts. |
Shareable checkout links, from the `/v2/payment-links` endpoint.
| Field | Type | Description |
| :----------- | :------- | :------------------------------------------------------------------------------------------------------------ |
| `uuid` | String | Unique identifier of the payment link, used as the primary key. |
| `link_type` | String | Kind of link: ORDER for a one-off charge, SUBSCRIPTION for recurring billing, FAST\_ORDER for quick checkout. |
| `created_at` | DateTime | Timestamp the link was created, normalised to UTC. |
| `title` | String | Title of the link, shown to the payer on the checkout page. |
| `value` | Number | Amount the link charges, in the account's currency. |
| `url` | String | Public checkout URL that is shared with the payer. |
| `processed` | Integer | Number of payments already collected through this link. |
The account's financial ledger, from the `/report/statement` endpoint. Only available to payment intermediary accounts; the stream is skipped when the key is not allowed to read it.
| Field | Type | Description |
| :----------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid` | String | Unique and stable identifier of the statement entry, used as the primary key. |
| `execution_date` | Date | Date the movement was posted to the account. |
| `charge_paid_date` | DateTime | Timestamp the underlying charge was paid, normalised to UTC. |
| `uuid_charge` | String | Unique identifier of the charge that produced this movement, linking to the charges stream. |
| `operacao` | String | Type of movement: CRÉDITO, ESTORNO, CHARGEBACK, TRANSFERÊNCIA, CORREÇÃO DÉBITO, CORREÇÃO CRÉDITO, CRÉDITO: DESCONTO DE TAXA, CRÉDITO: ANTECIPAÇÃO DE RECEITA or DÉBITO: ANTECIPAÇÃO DE RECEITA. |
| `payment_method` | String | Payment method of the underlying charge. |
| `entrada_bruta` | Number | Gross amount credited to the account by this movement, before fees. |
| `saida_bruta` | Number | Gross amount debited from the account by this movement, before fees. |
| `entrada_liquida` | Number | Net amount credited to the account by this movement, after fees. |
| `saida_liquida` | Number | Net amount debited from the account by this movement, after fees. |
| `taxa_operacao` | String | Fee applied to this movement. |
| `bandeira` | String | Card brand of the underlying charge (null for Pix and bank slips). |
The same movements plus the running account balance, from the `/report/statement_with_balance` endpoint.
| Field | Type | Description |
| :----------------------- | :------ | :-------------------------------------------------------------------------------- |
| `pedido` | String | Unique identifier of the order the entry refers to, linking to the orders stream. |
| `data_lancamento` | Date | Date the movement was posted to the account. |
| `metodo_pagamento` | String | Payment method used on the underlying transaction. |
| `bandeira` | String | Card brand of the underlying transaction (null for Pix and bank slips). |
| `parcelas_total` | Integer | Total number of instalments the order was split into. |
| `parcelas_lancamento` | String | Which instalment of the order this entry settles. |
| `descricao` | String | Description of the movement. |
| `valor_lancamento` | Number | Net amount of the entry, after fees. |
| `valor_bruto_lancamento` | Number | Gross amount of the entry, before fees. |
| `taxa_lancamento` | Number | Fee charged on this entry. |
| `saldo_conta` | Number | Balance of the account immediately after this entry was posted. |