Skip to main content
Aira is a Brazilian billing platform for usage-based and recurring pricing: it turns usage events into invoices, manages contracts and plans, and collects payments. The connector uses the Aira public API to extract your customers and their payment accounts and credit pools, your invoices with their line items, payments and discounts, your contracts with their plan instances and recurring discounts, and your metered resources. With it you can analyze revenue, billing and collection in your Lakehouse.

Configuring Aira as a Source

In the Sources tab, click on the “Add source” button located on the top right of your screen. Then, select the Aira option from the list of connectors. Click Next and you’ll be prompted to add your access.

1. Add account access

Aira gives access to your data through an API key. Keys are provisioned by the Aira team: request one from Aira support at contato@useaira.com, asking for read access to the data you want to extract (for example, invoices:read and contracts:read). The key is delivered only once, so store it safely. The connector only reads data: it never writes to Aira.
If your Aira key is restricted to a list of allowed IP addresses, ask Aira support to allow Nekt’s IP addresses for the key, or to remove the restriction.
The following configurations are available:
  • API Key: the Aira API key. Required.
  • Start Date (advanced): only invoices whose invoice date is on or after this date are extracted. Leave it empty to extract every invoice. Customers, contracts and resources are always extracted in full.
  • Lookback Days (advanced, default 7): on incremental syncs, invoices that are already paid or canceled are re-read only when their invoice date is at most this many days before the date of the previous sync. Invoices that are not paid or canceled yet are always re-read. See the Sync Type note below.
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.
Some streams make one request per record of another stream: payment accounts and credit pools per customer, invoice details and invoice discounts per refreshed invoice, contract details and recurring discounts per contract, and plan instances per plan instance. Invoice line items and invoice payments come from the invoice details response, with no extra request. Select only the streams you need.
Before reading any data, each sync checks once that the API key can read every selected stream. If it can’t, the sync stops right away and names the streams whose permission is missing, so you can ask Aira support for the permission or deselect them. 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: Aira does not expose when a record was last updated, so customers, invoices, contracts and resources are FULL_TABLE: each sync replaces the table with what Aira currently holds. Invoice details, line items, payments and discounts are INCREMENTAL by invoice date. Each incremental sync re-reads:
    • every invoice that is not paid or canceled yet;
    • every invoice that was not paid or canceled on the previous sync, so the sync in which an invoice gets paid or canceled reads it one more time;
    • every invoice dated up to Lookback Days before the date of the previous sync, which covers invoices created and paid between two syncs. An invoice imported or created with a past date that is already paid or canceled when it first appears is only read by a full sync: run a full sync after an import.
    The first sync, a full sync, and the first sync after you select one of these four streams read every invoice. Read more about Sync Types here.
The invoices table always has the current status and total of every invoice. Join it with the detail tables by invoice_id when you need the latest status of an invoice.
An incremental table never deletes rows: a discount or line item removed from an invoice in Aira stays in its table. Every row of the invoice detail, line item, payment and discount tables has a refreshed_at column: the start of the sync that last read that invoice, the same value for the whole sync. A row is current when its refreshed_at matches the invoice’s refreshed_at in invoice_details:
If you don’t sync invoice_details, keep the rows whose refreshed_at is the most recent one for their invoice_id in the same table.
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.
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.

Troubleshooting

  • “Aira rejected the API key”: the key does not exist, was deactivated or revoked, or has expired. Request a new key from Aira support and update it in the source configuration.
  • “The Aira API key is not allowed to read the data of the selected streams …”: the key does not have the read permission for that data. Ask Aira support to grant it, or deselect the streams listed in the message.
  • “Nekt’s address is not on that list”: the key is restricted to allowed IP addresses. Ask Aira support to allow Nekt’s IP addresses.
  • “N of M records were not found in Aira while reading”: those records were deleted in Aira during the sync and were skipped. If every record of a stream is not found (5 or more), the sync stops instead of loading an empty table. Contact Nekt support if it happens again.
  • Subsidiaries: subsidiaries (filiais) are rows of the customers table with type = 'subsidiary' and their organization in parent_customer_id. To check that they all arrived, compare SELECT count(*) FROM customers WHERE type = 'subsidiary' with the subsidiaries shown in Aira.

Streams and Fields

Below you’ll find all available data streams from Aira and their corresponding fields. API reference: Aira API.
Lists and nested objects are stored as JSON text. Every monetary amount is in cents, as Aira returns it (divide by 100 for reais). Discount amount values are cents when method is fixed and basis points (10000 = 100%) when method is percentage. Credit pool amounts are decimal text in the pool’s credit unit.

Customers

Every customer registered in Aira, including subsidiaries and archived customers.Table: customers · Primary key: id · Sync: Full table
Payment accounts of each customer: the legal entity (CNPJ/CPF, address, billing e-mails) that receives the invoices. Archived accounts are included.Table: customer_payment_accounts · Primary key: id · Sync: Full table
Prepaid credit pools of each customer, with the available balance and the automatic top-up settings.Table: customer_credit_pools · Primary key: id · Sync: Full table

Invoices

Every invoice, canceled ones included, with its current status and total. This is the table to use for the current status of an invoice.Table: invoices · Primary key: id · Sync: Full table
The full invoice: amounts breakdown, billed and issuing legal entities, payments, status history and generated files.Table: invoice_details · Primary key: id · Sync: Incremental
One row per invoice line item, grouped (one group per plan instance) or standalone. Read from the same response as Invoice Details, with no extra request.Table: invoice_line_items · Primary key: id · Sync: Incremental
Payment charges registered for each invoice at the payment provider (boleto, Pix, credit card). Read from the same response as Invoice Details.Table: invoice_payments · Primary key: id · Sync: Incremental
Discounts applied to each invoice, line item group or line item, inactive ones included. Refreshed for the same invoices as Invoice Details.Table: invoice_discounts · Primary key: id · Sync: Incremental

Contracts

Every contract, in all statuses, with the plan instances attached to it.Table: contracts · Primary key: id · Sync: Full table
The full contract: customer, contract number, issuing legal entity, billing schedule, payment settings, usage scope and allocations.Table: contract_details · Primary key: id · Sync: Full table
Recurring discounts configured on each contract.Table: contract_recurring_discounts · Primary key: id · Sync: Full table
Plan instances listed on each contract, with the plan and the charges (pricing) of the version in force.Table: plan_instances · Primary key: id · Sync: Full table

Usage

Metered resources: the usage metrics that turn the events you send to Aira into billable quantities.Table: resources · Primary key: id · Sync: Full table