> ## 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.

# Clara as a data source

> Bring your Clara corporate card transactions, cards, users, statements and digital account to Nekt.

Clara is a corporate card and spend management platform for companies in Brazil, Mexico and Colombia. This connector uses the Clara API to bring your company's card transactions, cards, users, billing statements, reimbursements, labels, groups and locations to the Catalog. For Brazilian accounts it also brings the Clara digital account: PIX, TED and bill movements, the available balance and the Pix payments made through Clara.

> [!NOTE]
>
> The connector only reads data. It never creates, changes, locks or pays anything in Clara.

## Prerequisites

Clara gives API access through an **API project** that your team creates in the Clara dashboard. API access starts on Clara's **Pro plan** (the Free plan only has a one-time trial of 500 calls). If you have never used the API, ask your Clara Customer Success Manager to enable it.

1. In the Clara dashboard, open **Integrations > Clara API > Project credentials** for your country:
   * Brazil: `brasil.clara.com/settings/integrations/clara-api`
   * Mexico: `app.clara.cc/settings/integrations/clara-api`
   * Colombia: `colombia.clara.com/settings/integrations/clara-api`
2. Click **Create project**, give it a name (for example "Nekt"), choose the **validity** (up to 360 days) and, under **Permissions to read**, select everything you want to extract: cards, transactions, users, billing statements, reimbursements and, in Brazil, the digital account. No write permission is needed.
3. Download the three files Clara offers: the **public key** (certificate), the **private key** and the **client credentials JSON** (with the Client ID and Client Secret).

> [!WARNING]
>
> Clara shows these files **only once**, when the project is created. Keep them in a safe place. If you lose them, create a new project.

> [!WARNING]
>
> Clara API projects expire at the end of the validity you chose (at most 360 days). Before that date, create a new project and update the four credentials in the source settings. Nekt warns you in the run log 30 days before the certificate expires, and the extraction stops with a clear message once it has expired.

## Configuring Clara 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 Clara option from the list of connectors.

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

### 1. Add account access

The following configurations are available:

* **Country**: the country of your Clara account (`brazil`, `mexico` or `colombia`). The project credentials only work in the country where they were created.
* **Environment**: `production` for your real data. `sandbox` is Clara's test environment, with separate credentials you request from Clara's integration team.
* **Client ID** and **Client Secret**: from the client credentials JSON file of your API project.
* **Certificate (public key file)**: open the public key file in a text editor and paste all of its content, from `-----BEGIN CERTIFICATE-----` to `-----END CERTIFICATE-----`.
* **Private key**: paste all of the content of the private key file, from `-----BEGIN ... PRIVATE KEY-----` to `-----END ... PRIVATE KEY-----`.
* **Start date**: the first day of transactions, digital account movements, Pix payments and reimbursements to extract.

Advanced settings:

* **Group company tax IDs**: only for Clara accounts that manage a group of companies (a holding). List the tax IDs (CNPJ in Brazil) of the companies to extract, one per item. Each company is read separately and identified in the `company_tax_identifier` column of every table. Leave it empty to extract the company of the API project.
* **Private key password**: only if your private key file is password-protected. The key Clara provides normally has no password.
* **Lookback days** (default 2): how many days before the last day read each run reads again. Clara can take up to 2 business days to confirm a card transaction, so this catches late changes.

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.

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

If your company does not use the Clara digital account, do not select **Digital Account Transactions**, **Digital Account Balance** and **Pix Payments**. They only exist for Brazilian accounts with a digital account. If you select them anyway, Nekt skips them on each run (their tables are not created or changed) and the run log shows a warning asking you to unselect 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**: 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/get-started/core-concepts/triggers), consider how often you want data to be extracted from this source. A daily trigger is a good fit: every request counts against your Clara plan's monthly API allowance (2,000 calls a month on the Pro plan), and each run tells you in its log how many requests it made.

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](https://docs.nekt.com/get-started/core-concepts/resource-control).
* Determine when to execute an **Additional [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. A full sync reads everything again since the start date, so it uses more of the monthly API allowance.

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.

> [!WARNING]
>
> 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

## Available streams

The table below lists every stream, its **slug** (the exact identifier to pass when creating the source via API) and a short description.

| Stream | Slug | Description |
| - | - | - |
| Transactions | `transactions` | Corporate card transactions: purchases, refunds, fees, credits and payments, with merchant, card, cardholder, statement and accounting data. |
| Cards | `cards` | Physical and virtual cards, with status, limit and cardholder. |
| Users | `users` | Clara users, with role, status, manager, location and groups. |
| Billing Statements | `billing_statements` | Monthly billing statements and their totals. |
| Reimbursements | `reimbursements` | Out-of-pocket expense reimbursements and their approval and payment status. |
| Digital Account Transactions | `digital_account_transactions` | Brazil only: PIX, TED, bill and transfer movements of the Clara digital account. |
| Digital Account Balance | `digital_account_balance` | Brazil only: available balance of the checking and collateral accounts, as of the last run. |
| Pix Payments | `pix_payments` | Brazil only: Pix payments made through Clara's payments API, with status and beneficiary. |
| Labels | `labels` | Labels used to classify transactions. |
| Groups | `groups` | Groups (teams or departments). |
| Locations | `locations` | Locations (cost centers or offices). |

Every table has a `company_tax_identifier` column: the tax ID of the group company the row belongs to when **Group company tax IDs** is set, and empty otherwise.

> [accordion] Transactions
>
> Corporate card transactions. Incremental by `last_update_date`: each run reads the transactions changed since a few days before the last run (see **Lookback days**), so status changes (for example from pre-authorized to authorized) are updated.
>
> **Identification:**
>
> * `uuid` - Unique identifier of the transaction (primary key, with `company_tax_identifier`)
> * `type` - PURCHASE, REFUND, FEE, CREDIT or PAYMENT
> * `transaction_label` - Label of the transaction as shown in Clara
> * `status` / `status_description` - NOTIFICATION, PRE\_AUTHORIZED, AUTHORIZED, REJECTED or SYSTEM\_TRANSACTION
> * `authorization_number` - Card network authorization number
> * `comment` - Comment added to the transaction
>
> **Amounts:**
>
> * `amount` / `currency` - Amount in the billing currency (decimal units, not cents)
> * `original_amount` / `original_currency` - Amount in the original currency of the purchase
>
> **Dates:**
>
> * `operation_date` - Purchase date
> * `accounting_date` - Accounting (posting) date
> * `last_update_date` - Date of the last change (replication key)
>
> **Merchant, card and cardholder:**
>
> * `merchant_name` / `merchant_category` / `merchant_category_code` / `merchant_mcc` - Merchant and its category
> * `card_uuid` / `card_last_four_digits` / `card_masked_pan` - Card used
> * `user_uuid` / `user_name` / `user_full_name` / `user_username` / `user_email` - Cardholder
>
> **Statement and accounting:**
>
> * `billing_statement_uuid` / `billing_statement_start_date` / `billing_statement_end_date` / `billing_statement_status` - Billing statement of the transaction. `billing_statement_status` is the status when the transaction last changed and is not updated when the statement closes: for the current status, join `billing_statement_uuid` with `uuid` in Billing Statements
> * `accounting_status` - NEEDS\_REVIEW, READY\_TO\_EXPORT or EXPORTED
> * `validation_status` / `validation_comment` - Expense validation, when present
> * `has_invoice` / `has_attachments` / `has_extracted_documents` - Whether the transaction has an invoice, receipts or extracted documents
> * `installment` / `installment_number` - Installment information, when the purchase is in installments
> * `labels` - Labels of the transaction (JSON)
> * `accounting_fields` - Accounting fields (JSON)
> * `bank_concept` - Bank concept, when present (JSON)

> [accordion] Cards
>
> Cards of the company. The table is replaced on every run with the current list.
>
> * `uuid` - Unique identifier of the card (primary key, with `company_tax_identifier`)
> * `alias` - Name given to the card
> * `status` / `status_description` - Card status (for example ACTIVE, LOCKED, CANCELLED)
> * `lock_code` - Who locked the card, when locked
> * `masked_pan` - Masked card number (the full number is never extracted)
> * `threshold` / `periodicity` - Spending limit and how often it resets (DAILY, WEEKLY or MONTHLY)
> * `type` - Card product and format (for example MASTER\_VIRTUAL, MASTER\_CORPORATE)
> * `user_uuid` / `user_name` / `user_full_name` / `user_username` / `user_email` - Cardholder

> [accordion] Users
>
> Clara users. The table is replaced on every run with the current list.
>
> * `uuid` - Unique identifier of the user (primary key, with `company_tax_identifier`)
> * `full_name` / `name` / `last_name` - Name of the user
> * `email` / `mobile_phone` - Contact
> * `tax_identifier` - Personal tax ID of the user (CPF in Brazil)
> * `role` - EMPLOYEE, MANAGER, COMPANY\_OWNER or BOOKKEEPER
> * `status` / `status_description` - Status of the user
> * `erp_id` - Identifier of the user in your ERP
> * `created_at` - When the user was created
> * `manager_uuid` / `manager_full_name` / `manager_email` - Manager of the user
> * `location_uuid` / `location_name` - Location (cost center) of the user
> * `groups` - Groups of the user (JSON)
> * `cards` - Cards of the user, with masked numbers only (JSON)

> [accordion] Billing Statements
>
> Monthly billing statements. The table is replaced on every run with the current list.
>
> * `uuid` - Unique identifier of the statement (primary key, with `company_tax_identifier`)
> * `status` - OPEN (current cycle) or CLOSED
> * `statement_start_date` / `statement_end_date` - Statement period
> * `statement_date` / `payment_limit_date` - Issue date and due date, when sent
> * `currency` / `total_amount` - Currency and total of the statement
> * `current_balance` / `required_payment` / `paid_amount` / `unpaid` - Payment information, when sent
> * `generated_at` - When the statement was generated

> [accordion] Reimbursements
>
> Out-of-pocket expense reimbursements. Incremental by `last_update_date`.
>
> * `uuid` - Unique identifier of the reimbursement (primary key, with `company_tax_identifier`)
> * `description` - Description of the expense
> * `status` / `status_comment` - PENDING, APPROVED, SENT\_TO\_PAY, PAYMENT\_IN\_PROGRESS, PAID, REJECTED, FINANCE\_REJECTED or CANCELLED, and the last comment
> * `amount` / `currency` - Amount of the expense
> * `request_creation_date` / `expense_date` / `final_approval_date` / `payment_date` - Lifecycle dates
> * `last_update_date` - Date of the last change (replication key)
> * `requester_uuid` / `requester_name` / `requester_email` - Employee who requested it
> * `merchant_name` / `merchant_description` / `merchant_category` / `merchant_category_code` / `merchant_country_code` - Merchant
> * `payment_method` / `payment_method_note` / `marked_as_paid_by` - How it was paid
> * `labels` / `groups` / `locations` - Classification (JSON)
> * `attachments` - Attached files, names only (JSON)

> [accordion] Digital Account Transactions
>
> Brazil only. Movements of the Clara digital account. Incremental by `transaction_date_time`.
>
> * `id` - Unique identifier of the movement (primary key, with `company_tax_identifier`)
> * `end_to_end_id` - PIX end-to-end identifier
> * `transaction_date_time` - Date and time of the movement, in UTC (replication key)
> * `transaction_date` - Date of the movement (legacy field)
> * `amount` - Amount in BRL
> * `method` - PIX, TED, Bill, Transfer or Undefined
> * `type` - Description of the movement (for example Transfer sent, Deposit in account, Reversal of sent transfer)
> * `description` / `digitable_line` - Description and digitable line, mostly for bills
> * `source_name` / `source_tax_id` / `source_institution` - Origin party
> * `beneficiary_name` / `beneficiary_tax_id` / `beneficiary_institution` - Destination party
> * `charges` - Bill fees: discount, fee, interest and total (JSON)
> * `original_transaction_id` / `original_transaction` - Original movement, when the row is a reversal

> [accordion] Digital Account Balance
>
> Brazil only. One row with the balance as of the last run. The table is replaced on every run.
>
> * `checking_account_available` - Available balance of the checking account in BRL
> * `checking_account_available_cents` - The same balance as Clara sends it, in cents
> * `collateral_account_available` - Available balance of the collateral account in BRL (0 when there is none)
> * `extracted_at` - When the balance was read

> [accordion] Pix Payments
>
> Brazil only. Pix payments made through Clara's payments API (accounts payable). Incremental by `creation_date`. Payments that are still scheduled or in process are followed on every run with one extra request for the whole list of open payments, plus one request for each payment whose status changed (up to 20 per run; the rest on the next run), until they reach a final status (PAID, FAILED or CANCELLED).
>
> * `external_id` - Identifier of the payment (primary key, with `company_tax_identifier`)
> * `status` - IN\_PROCESS, SCHEDULED, PAID, FAILED or CANCELLED
> * `amount` / `currency_code` / `payment_method` - Amount in BRL and method (PIX)
> * `description` - Description of the payment
> * `beneficiary_name` / `beneficiary_document_number` - Beneficiary and its CPF (masked) or CNPJ
> * `beneficiary_bank` / `beneficiary_bank_name` / `beneficiary_account_type` / `beneficiary_account_number` / `beneficiary_branch` - Beneficiary account, for payments made with bank details
> * `pix_end_to_end_id` - Pix end-to-end identifier, after settlement
> * `error_code` / `error_message` - Why a payment failed
> * `creation_date` - When the payment was created (replication key)
> * `payment_date` - Settlement date

> [accordion] Labels, Groups and Locations
>
> Reference lists. Each table is replaced on every run with the current list.
>
> * `uuid` - Unique identifier (primary key, with `company_tax_identifier`)
> * `name` - Name
> * `description` - Description, when set
> * `code` - Code, when set (locations use it to link ERP or HR systems)
> * `status` - Status (for example ACTIVE or INACTIVE)

## Limitations

* **API allowance**: every request, including authentication, counts against your Clara plan's monthly API allowance (2,000 calls a month on the Pro plan). A daily run of all tables for one company uses about 17 requests (around 510 a month) when each list fits in one page of 100 rows; larger lists add one request per 100 rows, and each company listed in **Group company tax IDs** costs the same again. The first run since an old start date uses more. You can follow the consumption in Clara under **Integrations > Clara API > API Insights**. If Clara keeps answering with its request-limit error (the monthly allowance used up, or another application using the same API project at the same time), the run stops the remaining tables at once with a message saying so, without spending more requests.
* **Receipts, invoices and extracted documents** of each transaction are not extracted: Clara serves them one transaction at a time, with download links that expire in 12 hours, which would use one request per transaction. The `has_attachments`, `has_invoice` and `has_extracted_documents` columns show which transactions have them.
* **CFDI invoices** (Mexico only), virtual card numbers for B2B purchases (VCN) and webhook settings are not extracted.
* **Full card numbers and CVV** are never extracted; only masked numbers.
* If Clara refuses a stream (missing permission in the API project), that stream fails and the run log names it; the other selected streams are still extracted. Add the read permission to the project in Clara, or unselect the stream.
* If most of what Clara returns for Transactions or Reimbursements is older than the requested dates (Clara stopped applying the date filter, which would make every run read the whole history), the stream stops with a message instead of spending the API allowance. A few older records are normal and are loaded. Contact Nekt support if you see the message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.