ContaAzul as a data source

Bring data from ContaAzul to Nekt.

ContaAzul is a financial management platform designed for small businesses in Brazil. It provides tools for invoicing, expense tracking, cash flow management, and integration with banks and accountants to simplify business finances. The ContaAzul API enables access to your financial data including payables, receivables, sales, products, services, and contacts.

Configuring ContaAzul as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the ContaAzul option from the list of connectors.

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

1. Add account access

You’ll need to authorize Nekt to access your ContaAzul data. Click on the ContaAzul Authorization button and log in with your ContaAzul account. Grant the necessary permissions for the company you want to extract data from.

The following configurations are available:

• Start Date: The earliest date from which records will be synced. Used as the starting point for incremental streams and as a date filter for financial events.

Make sure your ContaAzul account has the necessary permissions to access the data you want to extract. The connector requires access to financial, sales, product, and contact APIs depending on which streams you select.

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. You can select entire groups of streams or pick specific ones.

Tip: The stream can be found more easily by typing its name.

Select the streams and click Next.

3. Configure data streams

Customize how you want your data to appear in your catalog. Select the desired layer where the data will be placed, a folder to organize it inside the layer, a name for each table (which will effectively contain the fetched data) and the type of sync.

• Layer: choose between the existing layers on your catalog. This is where you will find your new extracted tables as the extraction runs successfully.
• Folder: a folder can be created inside the selected layer to group all tables being created from this new data source.
• Table name: we suggest a name, but feel free to customize it. You have the option to add a prefix to all tables at once and make this process faster!
• Sync Type: you can choose between INCREMENTAL and FULL_TABLE.
  • Incremental: every time the extraction happens, we’ll get only the new data - which is good if, for example, you want to keep every record ever fetched.
  • Full table: every time the extraction happens, we’ll get the current state of the data - which is good if, for example, you don’t want to have deleted data in your catalog.

Once you are done configuring, click Next.

4. Configure data source

Describe your data source for easy identification within your organization, not exceeding 140 characters.

To define your Trigger, consider how often you want data to be extracted from this source. This decision usually depends on how frequently you need the new table data updated (every day, once a week, or only at specific times).

Optionally, you can define some additional settings:

• Configure Delta Log Retention and determine for how long we should store old states of this table as it gets updated. Read more about this resource here.
• Determine when to execute an 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 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, you need at least one successful source run.

Streams and Fields

Below you’ll find all available data streams from ContaAzul and their corresponding fields:

Despesas (Payables)

Accounts payable / expense records with status, amounts, and due dates.

Field	Type	Description
id	String	Unique identifier
descricao	String	Description of the expense
data_vencimento	Date	Due date
status	String	Payment status
total	Number	Total amount
nao_pago	Number	Unpaid amount
pago	Number	Paid amount
data_criacao	DateTime	Creation date
data_alteracao	DateTime	Last modification date (replication key)

Receitas (Receivables)

Accounts receivable / revenue records with status, amounts, and due dates.

Field	Type	Description
id	String	Unique identifier
descricao	String	Description of the receivable
data_vencimento	Date	Due date
status	String	Payment status
total	Number	Total amount
nao_pago	Number	Unpaid amount
pago	Number	Paid amount
data_criacao	DateTime	Creation date
data_alteracao	DateTime	Last modification date (replication key)

Parcelas (Installments)

Detailed installment data for both payables (despesas) and receivables (receitas). Includes payment breakdowns, financial account info, billing requests, and attachments. This is a child stream fetched for each parent expense or receivable record.

Field	Type	Description
id	String	Installment identifier
evento	Object	Parent financial event with competence date, payment conditions, reference, apportionment details, and type
versao	Integer	Record version
referencia	String	Reference code
indice	Integer	Installment index
conciliado	Boolean	Whether the installment is reconciled
status	String	Installment status
valor_pago	Number	Amount paid
perda	Object	Loss details with date and value
nao_pago	Number	Unpaid amount
data_vencimento	String	Due date
data_pagamento_previsto	String	Expected payment date
descricao	String	Description
nota	String	Notes
conta_financeira	Object	Financial account details (bank, name, type, branch, number)
id_conta_financeira	String	Financial account ID
valor_composicao	Object	Value breakdown with penalty, interest, gross value, discount, fee, and net value
metodo_pagamento	String	Payment method
nsu	String	NSU (unique sequential number)
baixa_agendada	Boolean	Whether write-off is scheduled
baixas	Array	Array of write-off records with payment date, value composition, financial account, and attachments
anexos	Array	Array of attachments with name, description, type, and URL
solicitacoes_cobrancas	Array	Array of billing requests with status, values, due date, billing notifications, and payment details
fatura	Object	Invoice details with number, RPS, and invoice type
data_alteracao	String	Last modification date (replication key)
valor_total_liquido	Number	Total net value
renegociacao	Object	Renegotiation details with ID and value

Contas Financeiras (Financial Accounts)

Bank accounts and financial accounts registered in ContaAzul.

Field	Type	Description
id	String	Account identifier
banco	String	Bank name
codigo_banco	Integer	Bank code
nome	String	Account name
ativo	Boolean	Whether the account is active
tipo	String	Account type
conta_padrao	Boolean	Whether this is the default account
possui_config_boleto_bancario	Boolean	Whether boleto (bank slip) configuration is set up
agencia	String	Branch number
numero	String	Account number

Categorias (Categories)

Financial categories used to classify transactions.

Field	Type	Description
id	String	Category identifier
versao	Integer	Record version
nome	String	Category name
categoria_pai	String	Parent category ID
tipo	String	Category type
entrada_dre	String	Income statement (DRE) entry
considera_custo_dre	Boolean	Whether it’s considered a cost in the income statement

Categorias DRE (Income Statement Categories)

Hierarchical income statement (DRE) categories with sub-items and linked financial categories.

Field	Type	Description
id	String	Category identifier
descricao	String	Description
codigo	String	Category code
posicao	Integer	Position in the statement
indica_totalizador	Boolean	Whether this is a totalizer row
representa_soma_custo_medio	Boolean	Whether it represents average cost sum
subitens	Array	Array of sub-items with their own ID, description, code, position, and linked financial categories
categorias_financeiras	Array	Array of linked financial categories with ID, code, name, and active status

Centros de Custos (Cost Centers)

Cost centers used to allocate expenses and revenues.

Field	Type	Description
id	String	Cost center identifier
codigo	String	Cost center code
nome	String	Cost center name
ativo	Boolean	Whether it is active

Produtos (Products)

Product catalog with inventory, pricing, and variant information.

Field	Type	Description
id	String	Product identifier
id_legado	Integer	Legacy product ID
nome	String	Product name
codigo_sku	String	SKU code
codigo_ean	String	EAN barcode
tipo	String	Product type
status	String	Product status
estoque	Number	Current stock quantity
valor_venda	Number	Sale price
custo_medio	Number	Average cost
filhos	Array	Array of product variants/children with their own ID, name, SKU, stock, pricing, and parent reference
variacao	Integer	Variation identifier
nivel_estoque	String	Stock level indicator
estoque_minimo	Number	Minimum stock threshold
estoque_maximo	Number	Maximum stock threshold
movimentado	Boolean	Whether the product has had stock movement
id_pai	String	Parent product ID (for variants)
integracao_ecommerce_ativa	Boolean	Whether e-commerce integration is active

Servico (Services)

Service catalog with pricing and type information.

Field	Type	Description
id	String	Service identifier
id_servico	Integer	Legacy service ID
nome	String	Service name
codigo	String	Service code
descricao	String	Service description
preco	Number	Service price
custo	Number	Service cost
status	String	Service status
tipo_servico	String	Service type

Pessoas Lista (People List)

List of contacts (customers, suppliers, etc.) with basic information and address.

Field	Type	Description
uuid	String	Unique identifier
nome	String	Contact name
documento	String	Document number (CPF/CNPJ)
inscricao_estadual	String	State registration number
email	String	Email address
telefone	String	Phone number
ativo	Boolean	Whether the contact is active
id_legado	Integer	Legacy ID
uuid_legado	String	Legacy UUID
perfis	Array	Array of profile types (e.g. customer, supplier)
tipo_pessoa	String	Person type (individual or company)
endereco	Object	Address with zip code, street, number, complement, neighborhood, city, state, and country

Pessoas Detalhes (People Details)

Detailed contact information including financial summaries, multiple addresses, additional contacts, tax data, and custom fields. This is a child stream — one detail record is fetched per contact in the People List.

Field	Type	Description
uuid	String	Unique identifier
nome	String	Contact name
documento	String	Document number (CPF/CNPJ)
atrasos_recebimentos	Number	Overdue receivables amount
recebimentos_mes_atual	Number	Current month receivables
atrasos_pagamentos	Number	Overdue payables amount
pagamentos_mes_atual	Number	Current month payables
email	String	Email address
telefone_comercial	String	Business phone
celular	String	Mobile phone
criado_em	DateTime	Creation date
codigo	String	Contact code
perfis	Array	Array of profile types
pessoas_legado	Array	Array of legacy person records with ID, UUID, and profile
enderecos	Array	Array of addresses with zip code, street, number, complement, neighborhood, city, state, and country
observacoes_gerais	String	General notes
optante_simples_nacional	Boolean	Whether opted into Simples Nacional tax regime
orgao_publico	Boolean	Whether it is a public institution
nome_empresa	String	Company name
tipo_pessoa	String	Person type (individual or company)
lembretes_vencimento	Array	Array of due date reminders with email and status
informacoes_adicionais	Array	Array of custom fields with label, value, and type
outros_contatos	Array	Array of additional contacts with name, email, phone, and office
informacoes_fiscais	Array	Array of tax information with state registration, national registration, and SUFRAMA registration

Suppliers

Supplier records with contact information and address.

Field	Type	Description
id	String	Supplier identifier
name	String	Supplier name
company_name	String	Company name
email	String	Email address
business_phone	String	Business phone
mobile_phone	String	Mobile phone
person_type	String	Person type (NATURAL or LEGAL)
document	String	Document number (CPF/CNPJ)
identity_document	String	Identity document (RG)
state_registration_number	String	State registration number
state_registration_type	String	State registration type
city_registration_number	String	City registration number
date_of_birth	DateTime	Date of birth
notes	String	Notes
foreignId	String	Foreign/external ID
contactName	String	Contact person name
address	Object	Address with street, number, complement, zip code, neighborhood, city, and state

Vendas Lista (Sales List)

List of sales with summary information, customer data, and status.

Field	Type	Description
id	String	Sale identifier
total	Number	Total sale amount
id_legado	Integer	Legacy sale ID
data	String	Sale date
criado_em	DateTime	Creation date
data_alteracao	DateTime	Last modification date (replication key)
tipo	String	Sale type
itens	String	Items summary
condicao_pagamento	Boolean	Payment condition flag
numero	Integer	Sale number
cliente	Object	Customer info with ID, name, email, phone, address, city, state, country, and zip code
situacao	Object	Status with status code, description, and date
versao	Integer	Record version
status_email	Object	Email notification status with status and sent date

Vendas Detalhes (Sales Details)

Full sale details including customer, financial event, operation type, payment conditions, value breakdown, and pending status. This is a child stream — one detail record is fetched per sale in the Sales List.

Field	Type	Description
sales_id	String	Sale identifier (primary key)
data_alteracao_venda	DateTime	Sale last modification date (replication key)
data_alteracao	DateTime	Record modification date
cliente	Object	Customer with UUID, person type, document, and name
evento_financeiro	Object	Linked financial event with ID
notificacao	Object	Email notification with reference ID, recipient, sent date, opened date, and status
natureza_operacao	Object	Operation type with UUID, operation type, template, label, financial impact, and stock change
venda	Object	Detailed sale data with ID, status, legacy ID, negotiation type, sale number, category ID, commitment date, discount settings, value composition (gross, discount, freight, taxes, insurance, net), payment conditions (type, account, installments, card payment details), item counts, notes, and pending status

Vendas Itens (Sales Items)

Individual line items for each sale. This is a child stream — items are fetched per sale in the Sales List.

Field	Type	Description
sales_id	String	Parent sale identifier
id	String	Item record identifier
id_item	String	Product/service identifier
nome	String	Item name
descricao	String	Item description
tipo	String	Item type (product or service)
quantidade	Number	Quantity
valor	Number	Item value
data_alteracao_venda	DateTime	Sale last modification date (replication key)

Use Cases for Data Analysis

This guide outlines valuable business intelligence use cases when consolidating ContaAzul data, along with ready-to-use SQL queries that you can run on Explorer.

1. Cash Flow Overview

Analyze payables vs. receivables to understand your cash flow position.

Business Value:

• Monitor outstanding payables and receivables
• Identify overdue payments
• Track payment efficiency

SQL query

AWS

WITH payables AS (
   SELECT
      'PAYABLE' AS type,
      status,
      COUNT(*) AS record_count,
      SUM(total) AS total_amount,
      SUM(nao_pago) AS unpaid_amount,
      SUM(pago) AS paid_amount
   FROM
      nekt_raw.contaazul_despesas
   GROUP BY
      status
),
receivables AS (
   SELECT
      'RECEIVABLE' AS type,
      status,
      COUNT(*) AS record_count,
      SUM(total) AS total_amount,
      SUM(nao_pago) AS unpaid_amount,
      SUM(pago) AS paid_amount
   FROM
      nekt_raw.contaazul_receitas
   GROUP BY
      status
)
SELECT * FROM payables
UNION ALL
SELECT * FROM receivables
ORDER BY
   type, record_count DESC

GCP

WITH payables AS (
   SELECT
      'PAYABLE' AS type,
      status,
      COUNT(*) AS record_count,
      SUM(total) AS total_amount,
      SUM(nao_pago) AS unpaid_amount,
      SUM(pago) AS paid_amount
   FROM
      `nekt_raw.contaazul_despesas`
   GROUP BY
      status
),
receivables AS (
   SELECT
      'RECEIVABLE' AS type,
      status,
      COUNT(*) AS record_count,
      SUM(total) AS total_amount,
      SUM(nao_pago) AS unpaid_amount,
      SUM(pago) AS paid_amount
   FROM
      `nekt_raw.contaazul_receitas`
   GROUP BY
      status
)
SELECT * FROM payables
UNION ALL
SELECT * FROM receivables
ORDER BY
   type, record_count DESC

Sample Result

type	status	record_count	total_amount	unpaid_amount	paid_amount
PAYABLE	PAGO	456	234,567.89	0.00	234,567.89
PAYABLE	PENDENTE	89	45,230.00	45,230.00	0.00
PAYABLE	VENCIDO	12	8,900.00	8,900.00	0.00
RECEIVABLE	PAGO	780	567,890.12	0.00	567,890.12
RECEIVABLE	PENDENTE	134	98,450.00	98,450.00	0.00
RECEIVABLE	VENCIDO	23	15,670.00	15,670.00	0.00

2. Sales Performance by Customer

Analyze sales volume and revenue by customer to identify top accounts.

Business Value:

• Identify highest-value customers
• Track sales trends by customer
• Support customer segmentation

SQL query

AWS

SELECT
   v.cliente.nome AS customer_name,
   v.cliente.email AS customer_email,
   COUNT(*) AS total_sales,
   SUM(v.total) AS total_revenue,
   ROUND(AVG(v.total), 2) AS avg_sale_value,
   MIN(v.data) AS first_sale,
   MAX(v.data) AS last_sale
FROM
   nekt_raw.contaazul_vendas_lista v
WHERE
   v.situacao.status != 'CANCELADO'
GROUP BY
   v.cliente.nome, v.cliente.email
ORDER BY
   total_revenue DESC
LIMIT 20

GCP

SELECT
   v.cliente.nome AS customer_name,
   v.cliente.email AS customer_email,
   COUNT(*) AS total_sales,
   SUM(v.total) AS total_revenue,
   ROUND(AVG(v.total), 2) AS avg_sale_value,
   MIN(v.data) AS first_sale,
   MAX(v.data) AS last_sale
FROM
   `nekt_raw.contaazul_vendas_lista` v
WHERE
   v.situacao.status != 'CANCELADO'
GROUP BY
   v.cliente.nome, v.cliente.email
ORDER BY
   total_revenue DESC
LIMIT 20

Sample Result

customer_name	customer_email	total_sales	total_revenue	avg_sale_value	first_sale	last_sale
Empresa ABC Ltda	[e-mail]	45	123,456.78	2,743.48	2025-01-15	2026-03-08
Distribuidora XYZ	[e-mail]	32	89,234.50	2,788.58	2025-03-20	2026-03-10
Comércio Silva	[e-mail]	28	67,890.00	2,424.64	2025-02-01	2026-02-28
Tech Solutions SA	[e-mail]	19	45,670.00	2,403.68	2025-06-10	2026-03-05

3. Product Inventory Status

Monitor product stock levels and identify items that need replenishment.

Business Value:

• Identify low-stock products before they run out
• Track inventory turnover
• Optimize purchasing decisions

SQL query

AWS

SELECT
   nome AS product_name,
   codigo_sku AS sku,
   status,
   estoque AS current_stock,
   estoque_minimo AS min_stock,
   estoque_maximo AS max_stock,
   valor_venda AS sale_price,
   custo_medio AS avg_cost,
   CASE
      WHEN estoque <= estoque_minimo THEN 'CRITICAL'
      WHEN estoque <= estoque_minimo * 1.5 THEN 'LOW'
      ELSE 'OK'
   END AS stock_status
FROM
   nekt_raw.contaazul_produtos
WHERE
   status = 'ATIVO'
   AND estoque_minimo IS NOT NULL
ORDER BY
   estoque ASC

GCP

SELECT
   nome AS product_name,
   codigo_sku AS sku,
   status,
   estoque AS current_stock,
   estoque_minimo AS min_stock,
   estoque_maximo AS max_stock,
   valor_venda AS sale_price,
   custo_medio AS avg_cost,
   CASE
      WHEN estoque <= estoque_minimo THEN 'CRITICAL'
      WHEN estoque <= estoque_minimo * 1.5 THEN 'LOW'
      ELSE 'OK'
   END AS stock_status
FROM
   `nekt_raw.contaazul_produtos`
WHERE
   status = 'ATIVO'
   AND estoque_minimo IS NOT NULL
ORDER BY
   estoque ASC

Sample Result

product_name	sku	status	current_stock	min_stock	max_stock	sale_price	avg_cost	stock_status
Cabo USB-C 1m	SKU-001	ATIVO	5	10	100	29.90	12.50	CRITICAL
Carregador 20W	SKU-042	ATIVO	12	10	80	89.90	38.00	LOW
Película Protetora	SKU-103	ATIVO	8	15	200	19.90	5.20	CRITICAL
Mouse Sem Fio	SKU-078	ATIVO	45	20	150	79.90	32.00	OK

Implementation Notes

Parent-Child Streams

Several streams follow a parent-child pattern where a list endpoint provides summary records, and a detail endpoint is called for each individual record:

• Pessoas Lista → Pessoas Detalhes: The people list provides basic contact info; the detail stream fetches full contact data per person.
• Vendas Lista → Vendas Detalhes: The sales list provides summary data; the detail stream fetches full sale info per sale.
• Vendas Lista → Vendas Itens: Line items are fetched per sale from the sales list.
• Despesas → Parcelas: Installment details are fetched for each expense.
• Receitas → Parcelas: Installment details are fetched for each receivable.

Incremental Sync

The connector supports incremental sync for:

• Despesas: Uses data_alteracao as the replication key
• Receitas: Uses data_alteracao as the replication key
• Vendas Lista / Detalhes / Itens: Uses data_alteracao as the replication key

Streams without a replication key (Categorias, Categorias DRE, Centros de Custos, Contas Financeiras, Produtos, Pessoas, Servico, Suppliers) are always synced as full table.

Rate Limiting

The ContaAzul API enforces rate limits. The connector automatically handles 429 Too Many Requests responses by waiting 60 seconds before retrying. If you experience frequent rate limit errors, consider reducing the number of streams synced concurrently or adjusting your trigger frequency.

Authentication and Token Management

The connector automatically manages OAuth access token refresh to prevent authentication failures:

• Access tokens are refreshed proactively before expiration
• Refresh tokens are stored securely and rotated automatically
• Basic authentication headers are derived from your client ID and secret

Nested Data Structures

ContaAzul data contains nested structures. When querying:

• Use dot notation to access nested fields (e.g., cliente.nome in the sales list)
• Use UNNEST to flatten arrays (e.g., parcelas in sales details, filhos in products)

Example for product variants:

-- AWS Athena
SELECT p.nome, v.nome AS variant_name, v.estoque, v.valor_venda
FROM contaazul_produtos p
CROSS JOIN UNNEST(p.filhos) AS t(v)

-- GCP BigQuery
SELECT p.nome, v.nome AS variant_name, v.estoque, v.valor_venda
FROM `contaazul_produtos` p, UNNEST(p.filhos) AS v

Skills for agents

Download ContaAzul skills file

ContaAzul connector documentation as plain markdown, for use in AI agent contexts.