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.
- 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.
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.
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.
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 If you don’t sync
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:invoice_details, keep the rows whose refreshed_at is the most recent one for their invoice_id in the same table.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.
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.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
customerstable withtype = 'subsidiary'and their organization inparent_customer_id. To check that they all arrived, compareSELECT 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
Customers
Customers
Every customer registered in Aira, including subsidiaries and archived customers.Table:
customers · Primary key: id · Sync: Full tableCustomer Payment Accounts
Customer Payment Accounts
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 tableCustomer Credit Pools
Customer Credit Pools
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 tableInvoices
Invoices
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 tableInvoice Details
Invoice Details
The full invoice: amounts breakdown, billed and issuing legal entities, payments, status history and generated files.Table:
invoice_details · Primary key: id · Sync: IncrementalInvoice Line Items
Invoice Line Items
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: IncrementalInvoice Payments
Invoice Payments
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: IncrementalInvoice Discounts
Invoice Discounts
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: IncrementalContracts
Contracts
Contracts
Every contract, in all statuses, with the plan instances attached to it.Table:
contracts · Primary key: id · Sync: Full tableContract Details
Contract Details
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 tableContract Recurring Discounts
Contract Recurring Discounts
Recurring discounts configured on each contract.Table:
contract_recurring_discounts · Primary key: id · Sync: Full tablePlan Instances
Plan Instances
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 tableUsage
Resources
Resources
Metered resources: the usage metrics that turn the events you send to Aira into billable quantities.Table:
resources · Primary key: id · Sync: Full table