> ## 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.
# Vindi as a data source
> Bring data from Vindi to Nekt.
Vindi is a Brazilian payment gateway that provides a complete solution for online sales, recurring billing, and financial management. It helps businesses of all sizes to process payments, manage subscriptions, and reduce churn.
## Configuring Vindi 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 Vindi option from the list of connectors.
Click **Next** and you'll be prompted to add your access.
### 1. Add account access
You'll need your Vindi API Token for this connection. You can find it in your Vindi account settings (more instructions [here](https://atendimento.vindi.com.br/hc/pt-br/articles/203020644-Introdu%C3%A7%C3%A3o-%C3%A0-API-de-Recorr%C3%AAncia-da-Vindi#:~:text=Seguran%C3%A7a%20e%20autentica%C3%A7%C3%A3o)).
Once you have it, add the account access and click **Next**.
### 2. Select streams
Choose which data streams you want to sync - you can select all streams or pick specific ones that matter most to you.
> 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 a name for each table (which will contain the fetched data) and the type of sync.
* **Table name**: we suggest a name, but feel free to customize it. You have the option to add a **prefix** and make this process faster!
* **Sync Type**: you can choose between INCREMENTAL and FULL\_TABLE.
* Incremental: every time the extraction happens, we'll get only the new data - which is good if, for example, you want to keep every record ever fetched.
* Full table: every time the extraction happens, we'll get the current state of the data - which is good if, for example, you don't want to have deleted data in your catalog.
Once you are done configuring, click **Next**.
### 4. Configure data source
Describe your data source for easy identification within your organization, not exceeding 140 characters.
To define your [Trigger](https://docs.nekt.com/runs/scheduling-and-triggers), consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).
Optionally, you can determine when to execute a [full sync](https://docs.nekt.com/get-started/core-concepts/types-of-sync#additional-full-sync). This will complement the incremental data extractions, ensuring that your data is completely synchronized with your source every once in a while.
Once you are ready, click **Next** to finalize the setup.
### 5. Check your new source
You can view your new source on the [Sources](https://app.nekt.ai/sources) page. If needed, manually trigger the source extraction by clicking on the arrow button. Once executed, your data will appear in your Catalog.
For you to be able to see it on your [Catalog](https://app.nekt.ai/catalog), you need at least one successful source run.
# Streams and Fields
Below you'll find all available data streams from Vindi and their corresponding fields:
Stream for managing account charges.
* `id`: Account charge ID
* `amount`: Charge amount
* `status`: Charge status
* `due_at`: Due date
* `paid_at`: Paid at
* `installments`: Number of installments
* `attempt_count`: Number of payment attempts
* `next_attempt`: Next attempt
* `print_url`: Print URL
* `created_at`: Charge creation timestamp
* `updated_at`: Charge last update timestamp
* `last_transaction`: Last transaction info
* `payment_method`: Payment method info
* `bill`: Bill info
* `customer`: Customer info
Stream for managing account periods.
* `id`: The account period's system ID
* `billing_at`: Billing date for the account period
* `cycle`: Current cycle number
* `start_at`: Account period start date
* `end_at`: Account period end date
* `duration`: Duration of the account period
* `subscription`: Subscription associated with the account period
* `created_at`: Account period creation timestamp
* `updated_at`: Account period last update timestamp
Stream for managing bills and their details.
* `id`: Bill ID
* `code`: Bill code
* `amount`: Bill amount
* `installments`: Number of installments
* `status`: Bill status
* `seen_at`: Datetime when bill was seen
* `billing_at`: Billing date
* `due_at`: Due date
* `url`: Bill URL
* `created_at`: Bill creation timestamp
* `updated_at`: Bill last update timestamp
* `bill_items`: List of bill items
* `charges`: List of charges
* `bill_affiliates`: List of bill affiliates
* `customer`: Customer info
* `period`: Period info
* `subscription`: Subscription info
* `metadata`: Custom metadata for the bill
* `payment_profile`: Payment profile info
* `payment_condition`: Payment condition info
Stream for managing customer information.
* `id`: The customer's system ID
* `name`: The customer's name
* `email`: The customer's email address
* `registry_code`: The customer's registry code
* `code`: The customer's code
* `notes`: Notes about the customer
* `status`: The customer's status (e.g., active)
* `created_at`: Customer creation timestamp
* `updated_at`: Customer last update timestamp
* `metadata`: Custom metadata for the customer
* `address`: Customer address
* `phones`: List of customer phone numbers
Stream for managing export batches.
* `id`: Export batch ID
* `status`: Status of the export batch
* `url`: URL to download the export batch
* `created_at`: Timestamp when the export batch was created
* `updated_at`: Timestamp when the export batch was last updated
* `payment_method`: Payment method associated with the export batch
Stream for managing import batches.
* `id`: Import batch ID
* `status`: Status of the import batch
* `batch_file_name`: Name of the batch file
* `batch_file_size`: Size of the batch file in bytes
* `batch_fingerprint`: Fingerprint of the batch file
* `url`: URL to download the import batch
* `created_at`: Timestamp when the import batch was created
* `updated_at`: Timestamp when the import batch was last updated
* `payment_method`: Payment method associated with the import batch
Stream for managing invoices.
* `id`: Invoice system ID
* `amount`: Invoice amount
* `status`: Invoice status
* `integration_invoice_id`: Integration invoice ID
* `integration_reference`: Integration reference
* `print_url`: URL to print the invoice
* `description`: Invoice description
* `settings`: Invoice settings (object/hash)
* `issued_at`: Invoice issued at
* `accrued_on`: Invoice accrued on
* `scheduled_at`: Invoice scheduled at
* `created_at`: Invoice creation timestamp
* `updated_at`: Invoice last update timestamp
* `bill`: Bill associated with the invoice
* `customer`: Customer associated with the invoice
Stream for managing merchant users.
* `id`: Merchant User ID
* `status`: Status of the merchant user
* `last_sign_in_at`: Timestamp of the last sign in
* `user`: User details
* `role`: Role details
Stream for managing messages.
* `id`: Message system ID
* `notification_type`: Type of notification
* `seen_at`: Timestamp when the message was seen
* `created_at`: Timestamp when the message was created
* `delivered_at`: Timestamp when the message was delivered
* `customer`: Customer associated with the message
* `charge`: Charge associated with the message
* `notification`: Notification details
Stream for managing notifications.
* `id`: Notification ID
* `status`: Status of the notification
* `notification_type`: Type of the notification
* `name`: Name of the notification
* `subject`: Subject of the notification
* `content`: Content of the notification
* `trigger_type`: Type of trigger for the notification
* `trigger_day`: Day of the trigger for the notification
* `bcc`: BCC email addresses for the notification
* `created_at`: Timestamp when the notification was created
* `updated_at`: Timestamp when the notification was last updated
Stream for managing payment methods.
* `id`: The payment method's system ID
* `public_name`: The public name of the payment method
* `name`: The internal name of the payment method
* `code`: The code of the payment method
* `type`: The type of the payment method
* `status`: The status of the payment method
* `settings`: Settings for the payment method
* `set_subscription_on_success`: Behavior for setting subscription on success
* `allow_as_alternative`: Whether this payment method is allowed as an alternative
* `payment_companies`: List of payment companies associated with this payment method
* `maximum_attempts`: Maximum number of attempts for this payment method
* `created_at`: Payment method creation timestamp
* `updated_at`: Payment method last update timestamp
Stream for managing customer payment profiles.
* `id`: Payment profile ID
* `status`: Payment profile status
* `holder_name`: Holder name
* `registry_code`: Registry code
* `bank_branch`: Bank branch
* `bank_account`: Bank account
* `card_expiration`: Card expiration
* `allow_as_fallback`: Allow as fallback
* `card_number_first_six`: Card number first six
* `card_number_last_four`: Card number last four
* `renewed_card`: Renewed card info
* `card_renewed_at`: Card renewed at
* `token`: Token
* `gateway_token`: Gateway token
* `type`: Payment profile type
* `created_at`: Payment profile creation timestamp
* `updated_at`: Payment profile last update timestamp
* `payment_company`: Payment company info
* `payment_method`: Payment method info
* `customer`: Customer info
Stream for managing subscription plans.
* `id`: The plan's system ID
* `name`: The plan's name
* `interval`: The interval type (e.g., days, months)
* `interval_count`: The number of intervals between billings
* `billing_trigger_type`: The billing trigger type
* `billing_trigger_day`: The day of the billing trigger
* `billing_cycles`: The number of billing cycles
* `code`: The plan's code
* `description`: The plan's description
* `status`: The plan's status
* `installments`: The number of installments
* `invoice_split`: Whether the invoice is split
* `interval_name`: The interval name
* `created_at`: Plan creation timestamp
* `updated_at`: Plan last update timestamp
* `plan_items`: List of plan items
* `metadata`: Custom metadata for the plan
Stream for managing products and their pricing.
* `id`: The product's system ID
* `name`: The product's name
* `code`: The product's code
* `unit`: The product's unit
* `status`: The product's status
* `description`: The product's description
* `invoice`: The invoice type
* `created_at`: Product creation timestamp
* `updated_at`: Product last update timestamp
* `pricing_schema`: Product pricing schema
* `metadata`: Custom metadata for the product
Stream for managing user roles.
* `id`: The role's system ID
* `name`: The role's name
* `base_role`: The role's base role in the system
Core stream for managing customer subscriptions.
* `id`: The subscription's system ID
* `status`: The subscription's status
* `start_at`: Subscription start date
* `end_at`: Subscription end date
* `next_billing_at`: Next billing date
* `overdue_since`: Date since subscription is overdue
* `code`: The subscription's code
* `cancel_at`: Scheduled cancellation date
* `interval`: Billing interval
* `interval_count`: Number of intervals per billing cycle
* `billing_trigger_type`: Billing trigger type
* `billing_trigger_day`: Billing trigger day
* `billing_cycles`: Number of billing cycles
* `installments`: Number of installments
* `created_at`: Subscription creation timestamp
* `updated_at`: Subscription last update timestamp
* `customer`: Customer associated with the subscription
* `plan`: Plan associated with the subscription
* `product_items`: List of product items in the subscription
* `payment_method`: Payment method used for the subscription
* `current_period`: Current billing period details
* `metadata`: Custom metadata for the subscription
* `payment_profile`: Payment profile details
* `invoice_split`: Whether the invoice is split
* `subscription_affiliates`: List of subscription affiliates
Stream for tracking payment transactions.
* `id`: Transaction ID
* `transaction_type`: Type of transaction
* `status`: Transaction status
* `amount`: Transaction amount
* `installments`: Number of installments
* `gateway_message`: Gateway message
* `gateway_response_code`: Gateway response code
* `gateway_authorization`: Gateway authorization
* `gateway_transaction_id`: Gateway transaction ID
* `gateway_response_fields`: Gateway response fields
* `fallback_type`: Fallback type
* `fraud_detector_score`: Fraud detector score
* `fraud_detector_status`: Fraud detector status
* `fraud_detector_id`: Fraud detector ID
* `created_at`: Transaction creation timestamp
* `updated_at`: Transaction last update timestamp
* `gateway`: Gateway info
* `payment_profile`: Payment profile info
* `charge`: Charge info
* `customer`: Customer info
* `payment_method`: Payment method info
## Data Model
The following diagram illustrates the relationships between the core data streams in Vindi. The arrows indicate the join keys that link the different entities, providing a clear overview of the data structure.
```mermaid theme={null}
graph TD;
subgraph "Core Entities"
Customers("Customers");
Subscriptions("Subscriptions");
Bills("Bills");
Transactions("Transactions");
end
subgraph "Product & Plan"
Products("Products");
Plans("Plans");
end
subgraph "Billing & Invoicing"
Invoices("Invoices");
AccountCharges("Account Charges");
PaymentMethods("Payment Methods");
PaymentProfiles("Payment Profiles");
end
Subscriptions -- "customer.id" --> Customers;
Subscriptions -- "plan.id" --> Plans;
Plans -- "plan_items.product.id" --> Products;
Bills -- "customer.id" --> Customers;
Bills -- "subscription.id" --> Subscriptions;
Transactions -- "customer.id" --> Customers;
Transactions -- "charge.id" --> AccountCharges;
Invoices -- "customer.id" --> Customers;
Invoices -- "bill.id" --> Bills;
AccountCharges -- "customer.id" --> Customers;
AccountCharges -- "bill.id" --> Bills;
AccountCharges -- "payment_method.id" --> PaymentMethods;
PaymentProfiles -- "customer.id" --> Customers;
PaymentProfiles -- "payment_method.id" --> PaymentMethods;
```
## Use Cases for Data Analysis
This guide outlines some business intelligence use cases when consolidating Vindi data, along with ready-to-use SQL queries that you can run on [Explorer](https://app.nekt.ai/explorer).
### 1. Monthly Recurring Revenue (MRR) and Churn Analysis
Track your MRR growth and identify churn patterns to improve customer retention.
**Business Value:**
* Monitor the health of your subscription business
* Identify drivers of churn and take corrective actions
* Forecast future revenue more accurately
```sql theme={null}
WITH mrr_cte AS (
SELECT
date_trunc('month', s.start_at) AS mrr_month,
SUM(p.price) AS mrr
FROM nekt_raw.vindi_subscriptions s
JOIN nekt_raw.vindi_plans pl ON s.plan.id = pl.id
JOIN UNNEST(pl.plan_items) AS t(pi)
JOIN nekt_raw.vindi_products p ON pi.product.id = p.id
WHERE s.status = 'active'
GROUP BY 1
),
churn_cte AS (
SELECT
date_trunc('month', s.end_at) AS churn_month,
COUNT(s.id) AS churned_subscriptions
FROM nekt_raw.vindi_subscriptions s
WHERE s.status = 'canceled'
GROUP BY 1
)
SELECT
m.mrr_month,
m.mrr,
c.churned_subscriptions
FROM mrr_cte m
LEFT JOIN churn_cte c ON m.mrr_month = c.churn_month
ORDER BY m.mrr_month;
```
### 2. Customer Lifetime Value (LTV) Analysis
Understand the total revenue generated by a customer over their entire lifecycle.
**Business Value:**
* Identify your most valuable customer segments
* Optimize marketing spend by focusing on high-LTV segments
* Improve customer retention strategies to maximize LTV
```sql theme={null}
WITH customer_revenue AS (
SELECT
c.id AS customer_id,
c.name AS customer_name,
SUM(b.amount) AS total_revenue
FROM nekt_raw.vindi_customers c
JOIN nekt_raw.vindi_bills b ON c.id = b.customer.id
WHERE b.status = 'paid'
GROUP BY 1, 2
)
SELECT
cr.customer_name,
cr.total_revenue
FROM customer_revenue cr
ORDER BY 2 DESC;
```
### 3. Payment Method Efficiency
Analyze the performance of different payment methods to reduce failures and improve revenue collection.
**Business Value:**
* Identify payment methods with high failure rates
* Optimize payment processing to increase successful transactions
* Reduce involuntary churn due to payment failures
```sql theme={null}
SELECT
pm.public_name AS payment_method,
t.status AS transaction_status,
COUNT(t.id) AS transaction_count,
SUM(t.amount) AS total_amount
FROM nekt_raw.vindi_transactions t
JOIN nekt_raw.vindi_payment_methods pm ON t.payment_method.id = pm.id
GROUP BY 1, 2
ORDER BY 1, 2;
```
## Skills for agents
Vindi connector documentation as plain markdown, for use in AI agent contexts.