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

# Operand as a data source

> Bring data from Operand to Nekt.

Operand is a Brazilian project-management and financial platform for creative and marketing agencies. It organizes projects, jobs and tasks, keeps client and supplier registrations, and runs a financial module (bills, boletos, invoices, cost centers). Nekt connects to Operand's Public API to extract this data.

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

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

### 1. Add account access

You'll need an Operand API token. It is generated inside Operand by the account owner (root) or an administrator, under **Avatar > Configurações > Módulos e Funções > API Operand > Gerar token**. The **API Operand** module must be contracted for the option to appear.

<Warning>
  Each Operand account has only one active token at a time. Generating a new token invalidates the previous one, which will break any integration still using it, so reuse the same token across your integrations.
</Warning>

The following configurations are available:

* **API Token**: The token generated in Operand. Used to sign in and read your account's data.

* **Start Date**: (Optional) The earliest creation date to sync for the incremental streams (projects and jobs). When left empty, the first sync fetches all available history.

* **Lookback Window (days)**: (Default: 90 days) Number of days re-scanned before the last sync point on each incremental run, so records created shortly before it are not missed. Operand only lets you filter projects and jobs by their creation date, so this window is also what lets recently created records be picked up again as they change.

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](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 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.

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.</Warning>

# 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                                                                                |
| -------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------ |
| Projects                   | `projects`                   | Projects registered in Operand. Incremental by creation date.                              |
| Jobs                       | `jobs`                       | Jobs registered in Operand. Incremental by creation date.                                  |
| Tasks                      | `tasks`                      | Tasks and subtasks belonging to each job.                                                  |
| Clients                    | `clients`                    | Client registrations.                                                                      |
| Vehicles                   | `vehicles`                   | Media vehicle registrations.                                                               |
| Providers                  | `providers`                  | Service provider registrations.                                                            |
| Suppliers                  | `suppliers`                  | Supplier registrations.                                                                    |
| Employees                  | `employees`                  | Employee (collaborator) registrations.                                                     |
| Departments                | `departments`                | Departments configured in the account.                                                     |
| Financial Bills            | `financial_bills`            | Financial bills/invoices (Faturas).                                                        |
| Financial Reports          | `financial_reports`          | Financial ledger entries (Lançamentos), joined with account, category, boleto and invoice. |
| Financial Billets          | `financial_billets`          | Boletos (bank slips).                                                                      |
| Financial NFe              | `financial_nfe`              | Service invoices (Notas Fiscais).                                                          |
| Financial Categories       | `financial_categories`       | Financial categories configuration.                                                        |
| Financial Cost Centers     | `financial_cost_centers`     | Cost centers configuration.                                                                |
| Financial Bank Accounts    | `financial_bank_accounts`    | Bank accounts configuration.                                                               |
| Financial Payment Methods  | `financial_payment_methods`  | Payment methods configuration.                                                             |
| Financial Invoice Statuses | `financial_invoice_statuses` | Invoice/document statuses configuration.                                                   |

## Fields by stream

Below you'll find the available data streams from Operand and their main fields. Nested objects and arrays of objects (for example `contacts`, `locality`, and the joined objects on financial reports) are delivered as JSON strings.

<AccordionGroup>
  <Accordion title="Projects">
    Projects registered in Operand. Replicated incrementally by `createdAt`.

    **Key Fields:**

    * `id` - Unique identifier of the project
    * `title` - Title of the project
    * `situation` - Lifecycle situation (active, archived)
    * `personId` / `personName` - Associated client/person
    * `statusId` - Status of the project
    * `budget` - Estimated budget (decimal string)
    * `createdAt` - Creation timestamp (replication key)
    * `updatedAt` - Last update timestamp

    **Other Fields:**

    * `requesterId`, `responsibleId`, `userUpdateSituationId` - Related users
    * `involvedIds`, `involvedProjectIds`, `favoriteForUserIds` - Related IDs
    * `documentsSituation`, `counters` - Status summary and counts (JSON objects)
    * `concludedAt`, `providedAt`, `maxDeadline` - Related dates
    * `totalEstimated`, `totalRealized`, `estimatedCost`, `filesCount`, `isPrivate`
  </Accordion>

  <Accordion title="Jobs">
    Jobs registered in Operand. Replicated incrementally by `createdAt`.

    **Key Fields:**

    * `id` - Unique identifier of the job
    * `title` - Title of the job
    * `situation` - Lifecycle situation (active, archived)
    * `projectId` / `projectTitle` - Parent project
    * `clientId` / `clientName` - Client the job belongs to
    * `statusId` / `statusName` - Status of the job
    * `createdAt` - Creation timestamp (replication key)
    * `updatedAt` - Last update timestamp

    **Other Fields:**

    * `responsibleId`, `jobResponsibleId`, `requesterId` - Related users
    * `openedTasks`, `closedTasks`, `canceledTasks` - Task counters
    * `estimated`, `estimatedTime`, `worked`, `workedTime` - Time tracking
    * `deadline`, `initialDate` - Related dates
    * `jsonInvolvedIds` - Involved users (JSON array)
    * `isDeleted`, `isShared`, `hasActiveApproval`, `isSubtaskBlocked`
  </Accordion>

  <Accordion title="Tasks">
    Tasks and subtasks belonging to each job.

    **Key Fields:**

    * `id` - Identifier of the job the task belongs to
    * `subtaskId` - Unique identifier of the task/subtask
    * `subtaskTitle` - Title of the task
    * `situation` - Lifecycle situation
    * `responsibleId` / `responsibleName` - User responsible for the task
    * `statusId` / `statusName` - Status of the task
    * `createdAt` / `updatedAt` - Creation and last update timestamps

    **Other Fields:**

    * `initialDate`, `deadline`, `finishedAt` - Related dates
    * `completed`, `orderId`, `allowDelay`, `workedTime`
    * `blocking`, `dependents` - Dependency lists (JSON arrays)
  </Accordion>

  <Accordion title="Clients">
    Client registrations.

    **Key Fields:**

    * `idClient` - Unique identifier of the client
    * `person` - Trade/display name
    * `nationalDocument` / `typeNationalDocument` - Document number and type (cpf/cnpj)
    * `company` - Whether the client is a company (PJ)
    * `situation` - Lifecycle situation (active, disabled)
    * `email`, `phone`, `phone2` - Contact details
    * `contacts` - List of contacts (JSON array)
    * `locality` - Full address breakdown (JSON object)
    * `totalJobs`, `lateJobs` - Job counters
  </Accordion>

  <Accordion title="Vehicles">
    Media vehicle registrations.

    **Key Fields:**

    * `idPerson` - Unique identifier of the vehicle registration
    * `person` - Trade/display name
    * `name`, `shortName`, `network` - Vehicle identification
    * `situation` - Lifecycle situation
    * `contacts` / `locality` - Contact and address (JSON)
    * `nationalDocument`, `email`, `phone`, `phone2`
  </Accordion>

  <Accordion title="Providers">
    Service provider registrations.

    **Key Fields:**

    * `idPerson` - Unique identifier of the provider registration
    * `person` - Trade/display name
    * `nationalDocument` / `typeNationalDocument` - Document number and type
    * `company` - Whether the provider is a company (PJ)
    * `situation` - Lifecycle situation
    * `contacts` / `locality` - Contact and address (JSON)
  </Accordion>

  <Accordion title="Suppliers">
    Supplier registrations.

    **Key Fields:**

    * `idPerson` - Unique identifier of the supplier registration
    * `person` - Trade/display name
    * `nationalDocument` / `typeNationalDocument` - Document number and type
    * `company` - Whether the supplier is a company (PJ)
    * `situation` - Lifecycle situation
    * `contacts` / `locality` - Contact and address (JSON)
  </Accordion>

  <Accordion title="Employees">
    Employee (collaborator) registrations.

    **Key Fields:**

    * `idPerson` - Unique identifier of the employee registration
    * `person` - Name of the employee
    * `occupation` - Job title/occupation
    * `nationalDocument`, `stateDocument` - Document numbers
    * `email`, `phone`, `phone2` - Contact details
    * `hiredDate`, `firedDate`, `birthdayDate` - Related dates
    * `grossSalary`, `hourlyRate` - Compensation
    * `benefits` - Benefits (JSON array)
  </Accordion>

  <Accordion title="Departments">
    Departments configured in the account.

    **Key Fields:**

    * `departmentId` - Unique identifier of the department
    * `title` - Name of the department
    * `situation` - Lifecycle situation
    * `createdDate` / `updatedDate` - Creation and last update timestamps
  </Accordion>

  <Accordion title="Financial Bills">
    Financial bills/invoices (Faturas).

    **Key Fields:**

    * `finBillId` - Unique identifier of the bill
    * `billTitle` - Title of the document
    * `billType` - Party type (client, supplier, transfer, ...)
    * `situation` / `statusId` - Situation and status
    * `value`, `discountValue`, `increaseValue`, `totalValue` - Amounts
    * `dueDate`, `paymentDate`, `accrualDate`, `billingDate` - Related dates
    * `createdDate` / `updatedDate` - Creation and last update timestamps

    **References:**

    * `finAccountId`, `finCategoryId`, `finCostCenterId`, `finPaymentMethodId`
    * `finBillGroupId`, `entPersonId`, `referrerClientId`, `userId`
    * `attachments`, `relatedDocuments` - JSON arrays
  </Accordion>

  <Accordion title="Financial Reports">
    Financial ledger entries (Lançamentos). Each record is a denormalized statement joining a bill with its related records. Joined parts are delivered as JSON strings.

    **Fields:**

    * `order` - Ordering/reference date of the entry
    * `finBills` - Bills that make up the entry (JSON array)
    * `billets`, `finAccounts`, `finCategories`, `finCostCenters` - Joined records (JSON)
    * `finNfe`, `finPaymentMethods`, `finReconciliation`, `finStatus` - Joined records (JSON)
    * `persons`, `referrerClient`, `relatedDocument`, `vehicleDetails` - Joined records (JSON)
  </Accordion>

  <Accordion title="Financial Billets">
    Boletos (bank slips).

    **Key Fields:**

    * `billetId` - Identifier of the boleto in Operand
    * `billet` - Identifier on the external platform
    * `finBillId` - Bill the boleto belongs to
    * `billetValue` - Value of the boleto
    * `situation` - Situation (active, settled, removed, ...)
    * `url` - URL to access the boleto
    * `fineForDelay`, `latePaymentInterest`, `instructions`, `description`
    * `createdDate` / `updatedDate` - Creation and last update timestamps
  </Accordion>

  <Accordion title="Financial NFe">
    Service invoices (Notas Fiscais).

    **Key Fields:**

    * `nfeId` - Identifier of the nota fiscal in Operand
    * `number` - Invoice number at the city hall
    * `situation` - Situation (waiting, issued, canceling)
    * `value`, `discount` - Amounts
    * `iss`, `ir`, `inss`, `pis`, `cofins`, `csll` - Tax fields
    * `companyNationalDocument`, `nationalDocument` - Documents
    * `issuedOn` - Issue timestamp
    * `urlPdf`, `urlXml` - Document URLs
  </Accordion>

  <Accordion title="Financial Categories">
    Financial categories configuration.

    **Fields:**

    * `finCategoryId` - Unique identifier of the category
    * `categoryName` - Name of the category
    * `path` - Hierarchical path (e.g. /1/2/)
    * `situation` - Lifecycle situation
  </Accordion>

  <Accordion title="Financial Cost Centers">
    Cost centers configuration.

    **Fields:**

    * `finCostCenterId` - Unique identifier of the cost center
    * `costCenter` - Name of the cost center
    * `situation` - Lifecycle situation
  </Accordion>

  <Accordion title="Financial Bank Accounts">
    Bank accounts configuration.

    **Fields:**

    * `finAccountId` - Unique identifier of the bank account
    * `accountName` - Display name
    * `bankCode`, `bankName` - Bank identification
    * `agency`, `account`, `operation`, `station` - Account identification
    * `situation` - Lifecycle situation
  </Accordion>

  <Accordion title="Financial Payment Methods">
    Payment methods configuration.

    **Fields:**

    * `finPaymentMethodId` - Unique identifier of the payment method
    * `paymentMethod` - Name of the payment method
    * `situation` - Lifecycle situation
  </Accordion>

  <Accordion title="Financial Invoice Statuses">
    Invoice/document statuses configuration.

    **Fields:**

    * `statusId` - Unique identifier of the status
    * `statusName` - Name of the status
    * `color` - Hex color
    * `order` - Display order
    * `typeDoc` - Document type the status applies to
    * `situation` - Lifecycle situation
  </Accordion>
</AccordionGroup>