Reference

This chapter provides technical reference material for INTERA Integration Modules.

The reference section is intended for developers who already understand the main integration concepts and need precise information about schemas, fields, naming rules, supported structures, error handling, and API behavior.

The examples in this chapter are representative and may be extended as INTERA evolves. When building a production integration, always follow the contract supported by the INTERA version you are targeting.

YAML reference #

INTERA uses YAML to describe many configurable structures, including dashboards, widgets, role packages, mapping rules, Metrics, and integration-related configuration.

YAML is used because it is readable, versionable, and suitable for configuration that may be edited by developers, administrators, or visual editors.

A typical YAML document should be:

- readable by humans;
- stable in structure;
- easy to review in Git;
- explicit about IDs and references;
- careful with indentation;
- clear about time periods and Metric sources.

Example dashboard YAML:

dashboard:
  id: finance_overview
  name: Finance Overview
  pages:
    - id: main
      name: Main
      layout: Z
      widgets:
        - id: bank_balance
          type: metric_card
          size: half
          title: Bank Balance
          metric: finance.bank_balance

        - id: overdue_invoices
          type: metric_card
          size: half
          title: Overdue Invoices
          metric: finance.overdue_invoices

Example Metric reference in YAML:

metric:
  id: finance.overdue_invoices
  name: Overdue Invoices
  type: currency
  source:
    integration: example_accounting
    datasource: overdue_invoices
  time_context:
    type: due_date_range
    from: 2026-07-01
    to: 2026-07-31

Recommended YAML rules:

- Use stable technical IDs.
- Use clear display names.
- Avoid temporary names such as test, final, old, or new.
- Keep indentation consistent.
- Avoid hidden assumptions such as “current period” unless the period is defined.
- Prefer explicit references to integrations, DataSources, Assets, and Metrics.
- Keep role-package YAML understandable without reading integration code.

Common YAML mistakes:

- wrong indentation;
- duplicate IDs;
- missing required fields;
- inconsistent naming;
- unclear time context;
- references to DataSources that do not exist;
- references to Metrics that are not defined;
- using display names where technical IDs are required.

YAML should describe configuration, not hide business logic that belongs in an Integration Module or role package definition.

Manifest schema #

The manifest describes an Integration Module.

It allows INTERA to identify the module, display it in the integration catalog, understand its capabilities, and check compatibility.

A minimal manifest:

manifest: {
  id: "example_billing",
  name: "Example Billing",
  version: "1.0.0",
  kind: "direct_api",
  capabilities: ["datasource"],
  defaultCacheTtlSec: 300
}

Recommended manifest schema:

interface IntegrationManifest {
  id: string;
  name: string;
  version: string;
  kind: IntegrationKind;
  capabilities: IntegrationCapability[];
  defaultCacheTtlSec?: number;
  description?: string;
  vendor?: string;
  maintainer?: string;
  supportedInteraVersions?: string[];
  supportContact?: string;
}

Example kind values:

direct_api
readonly_api
sql
file
legacy
banking_api
external_feed

Example capabilities values:

datasource
entity_provider
sync
action

Field reference:

id
Unique technical identifier for the integration. Should remain stable across versions.

name
Human-readable integration name.

version
Integration Module version.

kind
General technical type of the integration.

capabilities
List of supported capabilities.

defaultCacheTtlSec
Default cache duration for DataSource results, in seconds.

description
Short description of what the integration provides.

vendor
External system vendor or integration author.

maintainer
Person, company, or team responsible for maintenance.

supportedInteraVersions
Compatible INTERA versions.

supportContact
Support contact or URL.

Manifest rules:

- The manifest must be present.
- The integration ID must be unique.
- The integration ID should not change between versions.
- The version must be updated when the integration changes.
- Capabilities must reflect actual supported functionality.
- Do not declare write-capable actions unless they are implemented and approved.

DataSource schema #

A DataSource is a named on-demand data endpoint exposed by an Integration Module.

It allows INTERA dashboards, Metrics, rules, and role packages to request structured data from an external system.

Example DataSource definition:

dataSources: [
  {
    id: "invoice_summary",
    name: "Invoice Summary",

    getData: async (params, context) => {
      return {
        generatedAt: new Date().toISOString(),
        totalOpen: 42,
        totalOverdue: 7,
        currency: "EUR"
      };
    }
  }
]

Recommended DataSource schema:

interface DataSource {
  id: string;
  name: string;
  description?: string;
  paramsSchema?: DataSourceParam[];
  cacheTtlSec?: number;

  getData(
    params: DataSourceParams,
    context: DataSourceContext
  ): Promise<unknown>;
}

Recommended parameter schema:

interface DataSourceParam {
  key: string;
  label: string;
  type: "string" | "number" | "boolean" | "date" | "datetime" | "select";
  required?: boolean;
  default?: unknown;
  options?: string[];
}

Recommended runtime params:

interface DataSourceParams {
  from?: string;
  to?: string;
  limit?: number;
  [key: string]: unknown;
}

Recommended runtime context:

interface DataSourceContext {
  userId?: string;
  roles?: string[];
  config?: Record<string, unknown>;
  instanceId?: string;
  timezone?: string;
}

Recommended response structure:

{
  "generatedAt": "2026-07-17T10:30:00Z",
  "period": {
    "from": "2026-07-01",
    "to": "2026-07-31"
  },
  "count": 2,
  "items": [
    {
      "customerId": "CUST-1001",
      "openInvoices": 3,
      "overdueAmount": 1200,
      "currency": "EUR"
    }
  ],
  "warnings": []
}

DataSource rules:

- Use stable DataSource IDs.
- Return predictable response shapes.
- Validate all runtime parameters.
- Avoid unrestricted raw database or API exposure.
- Include timestamps where possible.
- Include the time period used where relevant.
- Handle empty results safely.
- Return clear errors when data cannot be loaded.

KPI schema #

In INTERA, the public term is Metric. Older internal or technical references may still use the term KPI in schemas, code, or legacy documents. For public documentation, developers should treat KPI schema as the technical schema for defining or supplying Metrics.

A Metric is a measurable value used by INTERA dashboards, role packages, reconciliation rules, health scores, and pattern detection.

A Metric may be:

- supplied directly by an integration;
- calculated from a DataSource;
- derived from other Metrics;
- entered manually by a user;
- produced by reconciliation or pattern logic.

Example Metric definition:

metric:
  id: finance.monthly_revenue
  name: Monthly Revenue
  type: currency
  asset_type: customer
  source:
    integration: example_billing
    datasource: invoices
    field: total_amount
  aggregation:
    function: sum
    group_by: customer_id
  time_context:
    type: billing_period
    period: 2026-06

Recommended Metric schema:

interface MetricDefinition {
  id: string;
  name: string;
  type: MetricType;
  assetType?: string;
  source?: MetricSource;
  aggregation?: MetricAggregation;
  timeContext?: TimeContext;
  thresholds?: MetricThreshold[];
  display?: MetricDisplay;
}

Metric types:

number
currency
percentage
date
datetime
boolean
status
coordinates
text

Recommended Metric source schema:

interface MetricSource {
  integration: string;
  datasource: string;
  field?: string;
  filters?: Record<string, unknown>;
}

Recommended aggregation schema:

interface MetricAggregation {
  function: "sum" | "avg" | "min" | "max" | "count" | "latest";
  groupBy?: string;
}

Recommended threshold schema:

thresholds:
  - name: good
    condition: "value <= 1000"
  - name: warning
    condition: "value > 1000 and value <= 5000"
  - name: critical
    condition: "value > 5000"

Recommended Metric response shape:

{
  "metric": "finance.monthly_revenue",
  "asset": "customer:CUST-1001",
  "type": "currency",
  "value": 12500,
  "currency": "EUR",
  "period": {
    "type": "billing_period",
    "value": "2026-06"
  },
  "source": {
    "integration": "example_billing",
    "datasource": "invoices"
  },
  "generatedAt": "2026-07-17T10:30:00Z",
  "status": "valid"
}

Metric rules:

- Every Metric should have a stable technical ID.
- Every Metric should have a clear display name.
- Metric type must be explicit.
- Currency and unit must be explicit where relevant.
- Time context must be explicit.
- Asset relationship should be clear where applicable.
- The source DataSource should be traceable.
- Missing, delayed, invalid, or error values should be represented clearly.

Where possible, use the term Metric in user-facing documentation and interface text. Use KPI only where required by existing code or legacy schemas.

Error codes #

Integrations should report errors clearly and consistently.

Error codes allow INTERA to distinguish between configuration issues, authentication failures, temporary external system problems, invalid data, and internal integration errors.

Recommended error response shape:

{
  "code": "AUTH_INVALID_CREDENTIALS",
  "message": "The API key was rejected by the external system.",
  "source": "example_billing",
  "datasource": "invoices",
  "retryable": false,
  "details": {
    "statusCode": 401
  }
}

Recommended error fields:

code
Stable machine-readable error code.

message
Human-readable explanation.

source
Integration or external system involved.

datasource
DataSource involved, if applicable.

entityType
Entity type involved, if sync-related.

retryable
Whether retrying may solve the issue.

details
Optional safe technical context.

timestamp
When the error occurred.

Recommended error code categories:

CONFIG_MISSING_REQUIRED_FIELD
CONFIG_INVALID_VALUE
AUTH_MISSING_CREDENTIALS
AUTH_INVALID_CREDENTIALS
AUTH_EXPIRED
AUTH_FORBIDDEN
CONNECTION_UNREACHABLE
CONNECTION_TIMEOUT
RATE_LIMITED
EXTERNAL_SYSTEM_ERROR
DATASOURCE_NOT_FOUND
DATASOURCE_INVALID_PARAMS
DATASOURCE_EMPTY_RESPONSE
DATA_INVALID_FORMAT
DATA_MISSING_REQUIRED_FIELD
FILE_NOT_FOUND
FILE_INVALID_FORMAT
DATABASE_CONNECTION_FAILED
DATABASE_QUERY_FAILED
SYNC_FAILED
SYNC_PARTIAL_FAILURE
SYNC_DUPLICATE_KEY
SYNC_MISSING_KEY
METRIC_CALCULATION_FAILED
PERIOD_CONTEXT_MISSING
PERIOD_CONTEXT_INVALID
UNKNOWN_ERROR

Examples:

{
  "code": "CONFIG_MISSING_REQUIRED_FIELD",
  "message": "API Base URL is required for this Integration Instance.",
  "retryable": false
}

{
  "code": "CONNECTION_TIMEOUT",
  "message": "The external API did not respond within the configured timeout.",
  "retryable": true
}

{
  "code": "SYNC_PARTIAL_FAILURE",
  "message": "Customer sync completed with warnings. 14 records were skipped because they did not contain a stable customer ID.",
  "retryable": false
}

Error handling rules:

- Do not expose secrets in error messages.
- Use stable error codes.
- Make messages understandable to administrators.
- Mark retryable errors where possible.
- Distinguish temporary failures from configuration problems.
- Distinguish full sync failure from partial sync failure.
- Include enough safe context for troubleshooting.

---

API reference #

The API reference describes the main INTERA endpoints and behaviors used during integration development and testing.

The exact API surface may vary by INTERA version. This section should be treated as a developer reference and updated together with the backend API.

Common API areas include:

- authentication;
- integration catalog;
- Integration Instances;
- DataSource calls;
- entity sync;
- configuration;
- health checks;
- logs and diagnostics.

Example authentication flow:

POST /api/auth/login

Example request:

{
  "email": "developer@example.com",
  "password": "password"
}

Example response:

{
  "accessToken": "eyJ..."
}

Example list integrations:

GET /api/integrations

Example get integration details:

GET /api/integrations/{integrationId}

Example create Integration Instance:

POST /api/integration-instances

Example request:

{
  "integrationId": "example_billing",
  "name": "Example Billing - Test",
  "config": {
    "baseUrl": "https://api.example.test",
    "apiKey": "********"
  }
}

Example call DataSource:

GET /api/data/{integrationId}/{sourceId}

Example query:

GET /api/data/example_billing/invoice_summary?from=2026-07-01&to=2026-07-31

Example DataSource response:

{
  "generatedAt": "2026-07-17T10:30:00Z",
  "period": {
    "from": "2026-07-01",
    "to": "2026-07-31"
  },
  "totalOpen": 42,
  "totalOverdue": 7,
  "currency": "EUR"
}

Example run sync:

POST /api/integration-instances/{instanceId}/sync

Example request:

{
  "entityType": "customer",
  "mode": "dry_run"
}

Example response:

{
  "mode": "dry_run",
  "entityType": "customer",
  "summary": {
    "received": 1250,
    "wouldCreate": 43,
    "wouldUpdate": 1189,
    "wouldMarkInactive": 18,
    "wouldSkip": 0
  },
  "warnings": []
}

API usage rules:

- Use authentication for protected endpoints.
- Never expose access tokens in documentation, screenshots, or logs.
- Validate parameters before calling DataSources.
- Use trial environments for development testing.
- Use dry-run sync before real sync where supported.
- Check API responses and logs during integration development.