- Nexus: Plataforma de conciliação
  - [Nexus](/docs/nexus): Plataforma de ingestão, matching e webhooks para conciliação automatizada.
  - Guia de integração
    - [Visão geral](/docs/nexus/guia/visao-geral): O que é o Nexus e o fluxo recomendado de integração.
    - [Autenticação](/docs/nexus/guia/autenticacao): API key, segredos de webhook e assinatura de eventos.
    - [Fluxo de ingestão](/docs/nexus/guia/ingestao): Como criar data sources, selecionar dados, configurar datasets/fields e iniciar conciliações.
    - [Matching](/docs/nexus/guia/matching): Disparar e consultar execuções de matching, listar matches.
    - [Matching composicional](/docs/nexus/guia/matching-composicional): Como configurar e operar conciliações 1:N, N:1, parciais e por parcelas.
    - [Webhooks de saída](/docs/nexus/guia/webhooks-saida): Registrar endpoints, formato das entregas, assinatura HMAC e SLA.
    - [Erros e health checks](/docs/nexus/guia/erros): Envelope padrão de erros, códigos comuns e endpoints de health.
  - Referência da API
    - [Referência da API](/docs/nexus/api): Todos os endpoints da API do Nexus, gerados a partir do OpenAPI.
    - Api keys
      - [Create API key (tenant)](/docs/nexus/api/api-keys/apiKeys.create)
      - [Revoke API key (tenant)](/docs/nexus/api/api-keys/apiKeys.delete)
      - [List API keys (tenant)](/docs/nexus/api/api-keys/apiKeys.list)
      - [Rotate API key (tenant)](/docs/nexus/api/api-keys/apiKeys.rotate)
    - Billing
      - [Export billing events as CSV](/docs/nexus/api/billing/billing.exportCsv)
      - [Get billing usage for current tenant](/docs/nexus/api/billing/billing.usage)
    - Composite matches
      - [Get composite match with members](/docs/nexus/api/composite-matches/compositeMatches.get)
      - [List composite matches](/docs/nexus/api/composite-matches/compositeMatches.list)
    - Data sources
      - [List columns for a table](/docs/nexus/api/data-sources/dataSources.browse.columns)
      - [Preview rows from a table](/docs/nexus/api/data-sources/dataSources.browse.preview)
      - [List schemas (external data source)](/docs/nexus/api/data-sources/dataSources.browse.schemas)
      - [List tables for a schema](/docs/nexus/api/data-sources/dataSources.browse.tables)
      - [Create data source](/docs/nexus/api/data-sources/dataSources.create): Create a tenant data source. For `webhook` type the response includes `webhook_url`, `secret_plain` (returned only once), `status` and `listening_until`.
      - [Delete data source](/docs/nexus/api/data-sources/dataSources.delete)
      - [Delete a file from a data source](/docs/nexus/api/data-sources/dataSources.files.delete)
      - [Import an uploaded file into a dataset](/docs/nexus/api/data-sources/dataSources.files.import)
      - [List files of a data source](/docs/nexus/api/data-sources/dataSources.files.list)
      - [List records produced by a specific uploaded file](/docs/nexus/api/data-sources/dataSources.files.records): Returns the records ingested from this file, ordered by createdAt desc. The match is performed via the `fileId` field stamped into each record's `data`.
      - [Upload a file to a file-type data source (CSV/XLSX/Francesinha, up to 1GB)](/docs/nexus/api/data-sources/dataSources.files.upload): Allowed formats: CSV, XLSX (.xlsx), and Brazilian banking Francesinha (CNAB-style .txt/.fra). Returns the persisted file row (with parsed metadata where applicable).
      - [Get data source](/docs/nexus/api/data-sources/dataSources.get): Returns the data source. For `openi` and `openfinance` types the response also includes the connector `config` object so management clients can hydrate forms; sensitive fields may be present.
      - [Get inbound sample for webhook data source](/docs/nexus/api/data-sources/dataSources.inboundSample)
      - [Ingest rows from Postgres table into a dataset](/docs/nexus/api/data-sources/dataSources.ingest.postgres)
      - [List data sources (tenant)](/docs/nexus/api/data-sources/dataSources.list)
      - [Setup Openi reconciliation (server-to-server)](/docs/nexus/api/data-sources/dataSources.setupOpeni): Idempotent: ensures an Openi data source exists for the given company and that the `openi_invoices` and `openi_accounting_entries` datasets are present. Returns 201 when at least one resource was created, 200 otherwise.
      - [Trigger sync (OpenFinance/Openi)](/docs/nexus/api/data-sources/dataSources.sync)
      - [Test data source connectivity](/docs/nexus/api/data-sources/dataSources.test): Probe the configured connector. Postgres performs `SELECT 1`; OpenFinance fetches a small accounts page; Openi requests page 1 of invoices. Always returns 200; success is reflected in `ok`.
      - [Update data source](/docs/nexus/api/data-sources/dataSources.update)
      - [OpenFinance: list accounts (by itemId)](/docs/nexus/api/data-sources/openfinance.browse.accounts)
      - [OpenFinance: list account transactions (by itemId and accountId)](/docs/nexus/api/data-sources/openfinance.browse.accountTransactions)
      - [OpenFinance: list credit cards (by itemId)](/docs/nexus/api/data-sources/openfinance.browse.creditCards)
      - [OpenFinance: list credit card transactions (by itemId and cardId)](/docs/nexus/api/data-sources/openfinance.browse.creditCardTransactions)
      - [OpenFinance: list investments (by itemId)](/docs/nexus/api/data-sources/openfinance.browse.investments)
      - [OpenFinance: list investment transactions (by itemId and investmentId)](/docs/nexus/api/data-sources/openfinance.browse.investmentTransactions)
      - [OpenFinance: test connectivity (accounts list)](/docs/nexus/api/data-sources/openfinance.test)
      - [OpenFinance: rotate tenant webhook secret](/docs/nexus/api/data-sources/openfinance.webhook.rotate): Rotates the inbound webhook secret used by OpenFinance to deliver events. Optionally accepts a new `authorizationKey` and `baseUrl`. Verifies the new key with upstream before persisting; returns 502 when upstream rejects.
      - [Openi: list accounting entries (by companyId)](/docs/nexus/api/data-sources/openi.browse.accountingEntries)
      - [Openi: list invoices (by companyId)](/docs/nexus/api/data-sources/openi.browse.invoices)
      - [Setup Openi internal reconciliation](/docs/nexus/api/data-sources/openi.setupReconciliation): Server-to-server endpoint used by openi-business when a company enables auto-reconciliation. Provisions an `openi-internal` data source and the `openi_invoices`/`openi_accounting_entries` datasets. Idempotent.
      - [Openi: test connectivity (invoices page 1)](/docs/nexus/api/data-sources/openi.test)
    - Datasets
      - [Create dataset](/docs/nexus/api/datasets/datasets.create)
      - [Delete dataset](/docs/nexus/api/datasets/datasets.delete)
      - [Add field(s) to dataset](/docs/nexus/api/datasets/datasets.fields.create): Accepts either a single field input or an array of inputs. Returns the same shape (single object or array) as inserted. Fails 409 (`IDENTITY_EXISTS`) if any input has `isIdentity=true` and the dataset already has an identity field, and 400 (`INVALID_TRANSFORM_EXPR`) when `transform_expr` does not compile.
      - [Delete field](/docs/nexus/api/datasets/datasets.fields.delete)
      - [Bulk add fields from selected columns](/docs/nexus/api/datasets/datasets.fields.fromColumns)
      - [List fields of dataset](/docs/nexus/api/datasets/datasets.fields.list)
      - [Preview JSONata transform for a field](/docs/nexus/api/datasets/datasets.fields.previewJsonata): Always returns 200; failure is reflected in `ok=false` with `error` populated.
      - [Update field](/docs/nexus/api/datasets/datasets.fields.update)
      - [Get dataset](/docs/nexus/api/datasets/datasets.get)
      - [List datasets](/docs/nexus/api/datasets/datasets.list)
      - [Purge all records from a dataset](/docs/nexus/api/datasets/datasets.records.purge): Deletes every record under the dataset; the dataset itself and its fields are kept.
      - [Get one sample row for a dataset (most recent record)](/docs/nexus/api/datasets/datasets.sample)
      - [Update dataset](/docs/nexus/api/datasets/datasets.update)
    - Health
      - [Health check](/docs/nexus/api/health/health.liveness)
      - [Readiness check](/docs/nexus/api/health/health.ready): Checks connectivity to dependencies like database and queue.
    - Imports
      - [Create a file import (CSV/XLSX, up to 1GB) and enqueue processing. Francesinha (CNAB) uploads go through POST /v1/data-sources/{id}/files instead.](/docs/nexus/api/imports/imports.create)
      - [Get import details](/docs/nexus/api/imports/imports.get)
      - [List imports](/docs/nexus/api/imports/imports.list)
    - Inbound hooks
      - [Inbound webhook — first sample capture](/docs/nexus/api/inbound-hooks/webhookInbound.capture): Public endpoint to receive the first JSON payload for a webhook data source. Requires `X-Webhook-Secret` header. Only `application/json` content is accepted. Captures the first sample within a 5-minute window after creation, activates the data source, and auto-creates a dataset.
      - [OpenFinance inbound webhook](/docs/nexus/api/inbound-hooks/webhookInbound.openfinance): Receives OpenFinance webhook notifications. Requires `Authorization` header set to the tenant's stored secret. JSON body with `event` and `data` is expected.
      - [Openi inbound webhook](/docs/nexus/api/inbound-hooks/webhookInbound.openi): Receives Openi event notifications. Requires `X-Webhook-Signature` header carrying the HMAC of the configured secret. The body shape is `{ event, companyId, data: { entityId? | entityIds[]? } }`. Recognized events: `INVOICE_CREATED`, `INVOICE_UPDATED`, `ACCOUNTING_ENTRY_CREATED`, `ACCOUNTING_ENTRY_UPDATED`. Unknown events return `200 { ok: true, skipped: true }`.
    - Matches
      - [Export matches as CSV](/docs/nexus/api/matches/matches.exportCsv): Streams a CSV with header match.id,decision,left.dataset,right.dataset plus the requested left/right fields. At least one of leftFields or rightFields must be provided.
      - [Get match by id](/docs/nexus/api/matches/matches.get)
      - [List matches](/docs/nexus/api/matches/matches.list)
    - Matching jobs
      - [Cancel a running matching job](/docs/nexus/api/matching-jobs/matchingJobs.cancel): Sets the job status to cancelled. Only jobs with status `running` can be cancelled. Batches not yet processed will be skipped by the worker.
      - [Get left/right candidate base records used by a job](/docs/nexus/api/matching-jobs/matchingJobs.candidateBases): Returns the snapshot of records that were eligible for the job (capped at 10,000 per side). When the job's first rule set uses `jsonata-batch` with blocking enabled, the right (candidate) side is filtered to the same date/amount window automatic matching used. Useful for exporting reconciliation traces.
      - [Get matching job detail](/docs/nexus/api/matching-jobs/matchingJobs.get)
      - [List matching jobs](/docs/nexus/api/matching-jobs/matchingJobs.list)
      - [Purge all matching jobs and matches](/docs/nexus/api/matching-jobs/matchingJobs.purge): Deletes all matching jobs, their rule set progress records, and all match results for the tenant.
      - [Run matching job for a dataset](/docs/nexus/api/matching-jobs/matchingJobs.run)
    - Records
      - [Ingest a record and enqueue nexus job](/docs/nexus/api/records/records.create)
      - [Export records as CSV](/docs/nexus/api/records/records.exportCsv): Streams a CSV with header record.id,dataset,external_id plus the requested fields from record data. Filtering matches GET /v1/records. Arrays are joined with ';' and nested objects can be addressed with dot paths. Body is parsed leniently — an empty body is accepted but `dataset` and `fields` must be present once parsed.
      - [Get record details](/docs/nexus/api/records/records.get)
      - [List records (by dataset)](/docs/nexus/api/records/records.list)
    - Rule sets
      - [Create rule set](/docs/nexus/api/rule-sets/ruleSets.create): `jsonataExpr` is required when `engine = jsonata` (default). For `engine = jsonata-batch` the matcher expressions live inside `params.matchers` and `jsonataExpr` may be omitted. Field references inside `jsonataExpr` (`left.<key>`, `right.<key>`) are validated against the dataset's declared fields when `RULE_SETS_VALIDATE_FIELDS_STRICT=1`.
      - [Delete rule set](/docs/nexus/api/rule-sets/ruleSets.delete): Idempotent: returns 204 even when the rule set does not exist. Cascades a cleanup of `matches` and `matching_job_rule_sets` rows scoped to this rule set so the FK constraints can be satisfied.
      - [Create rule set from a template](/docs/nexus/api/rule-sets/ruleSets.fromTemplate): Instantiate a rule set from a template by mapping each `{{variable}}` placeholder to a concrete field path (alphanumeric, `_`, `.` only). Validates that all required variables are mapped, sanitizes values, and rejects unmapped placeholders remaining in the resolved expression or params.
      - [Get rule set](/docs/nexus/api/rule-sets/ruleSets.get)
      - [List rule sets](/docs/nexus/api/rule-sets/ruleSets.list)
      - [Preview JSONata evaluation with sample records](/docs/nexus/api/rule-sets/ruleSets.previewJsonata): Compiles and evaluates the expression against the supplied left/right records using a per-call sandbox, then computes a decision against the supplied thresholds. Always returns 200; failure is reflected in `ok=false` with `error`.
      - [Execute rule set on configured datasets](/docs/nexus/api/rule-sets/ruleSets.run): Queues a matching job for the rule set. When the left dataset has no records, returns 200 with `status=no_records` (no work enqueued). On success, returns 202 with `status=queued`, the produced `jobGroupId`, and the number of batches that were enqueued.
      - [Update rule set](/docs/nexus/api/rule-sets/ruleSets.update)
      - [Validate JSONata expression](/docs/nexus/api/rule-sets/ruleSets.validateJsonata): Always returns 200; failure is reflected in `ok=false` with `error` populated and (when available) `position`.
    - Rule templates
      - [Get rule template by id](/docs/nexus/api/rule-templates/ruleTemplates.get)
      - [List rule templates](/docs/nexus/api/rule-templates/ruleTemplates.list)
    - Webhook deliveries
      - [Purge deliveries older than 30 days](/docs/nexus/api/webhook-deliveries/webhookDeliveries.cleanup): Maintenance endpoint. Iterates a scoped DELETE in 5000-row batches until exhausted. Intended to be triggered by an external scheduler (e.g., EventBridge daily rule). Tenant scope is enforced upstream by `apiKeyAuth`; the underlying DELETE is global within the schema.
      - [Get webhook delivery detail](/docs/nexus/api/webhook-deliveries/webhookDeliveries.get): Full delivery row including the signed payload, the latest response body, and the next scheduled retry (when applicable).
      - [List webhook deliveries](/docs/nexus/api/webhook-deliveries/webhookDeliveries.list): Cursor-paginated list of webhook deliveries for the authenticated tenant. Use the returned `nextCursor` and `nextCursorId` together as the cursor for the next page.
      - [Resend a webhook delivery](/docs/nexus/api/webhook-deliveries/webhookDeliveries.resend): Re-enqueues an outbound delivery for the same webhook subscription with the original payload. Returns 400 (`WEBHOOK_INACTIVE`) if the target webhook is currently inactive.
    - Webhooks
      - [Create webhook](/docs/nexus/api/webhooks/webhooks.create)
      - [Delete webhook](/docs/nexus/api/webhooks/webhooks.delete)
      - [Get webhook](/docs/nexus/api/webhooks/webhooks.get)
      - [List webhooks](/docs/nexus/api/webhooks/webhooks.list)
      - [Enqueue a test webhook (synthetic event)](/docs/nexus/api/webhooks/webhooks.test): Enqueues a synthetic test.ping delivery for asynchronous processing by the webhook worker. Use the returned deliveryId to poll delivery status via GET /v1/webhook-deliveries/{id}. Headers on the HTTP POST to the webhook URL: X-Nexus-Event, X-Nexus-Id, X-Nexus-Timestamp, X-Nexus-Signature. The payload is { "event": "test.ping", "tenantId": "<uuid>", "test": true }.
      - [Update webhook](/docs/nexus/api/webhooks/webhooks.update): Partial update; only the fields supplied are persisted. Returns the updated webhook with its delivery tuning fields (`maxAttempts`, `baseBackoffMs`, `redactedFields`).