Skip to main content

ACF Connector Specification — Xledger

1. Purpose​

ACF-XLEDGER defines how Xledger financial, operational and—where accessible—existing climate data enters the ZAYAZ canonical data environment.

Xledger publicly supports custom integrations through GraphQL, SOAP web services and file-based methods. Its GraphQL integration uses administrator-generated tokens; its SOAP services use account credentials and client certificates; file integration supports CSV, XML and other configured formats. Xledger also provides customer-specific test environments for integration development.

The connector therefore differs fundamentally from ACF-SIE.

SIE is primarily a standardized accounting payload.

Xledger is a live source platform.

ACF-XLEDGER consequently manages:

  • authentication;
  • source-schema discovery;
  • master-data retrieval;
  • transactional retrieval;
  • incremental synchronization;
  • multi-entity context;
  • schema drift;
  • source permissions;
  • existing ESG/climate information;
  • evidence provenance;
  • connection health.

2. Source-system capability versus API availability

Xledger contains broad ERP functionality, including general accounting, AP/AR, invoicing, purchasing, projects, inventory, fixed assets and financial dimensions. Xledger's own material confirms these application domains.

However:

Application functionality and API field availability are not the same thing.

The connector therefore does not hard-code the assumption that every Xledger ERP object is exposed through every customer's GraphQL permissions.

Before production activation, the API Hub creates a customer-specific capability profile.

Xledger environment
        ↓
Authentication
        ↓
Schema / capability discovery
        ↓
ACF-XLEDGER customer profile
        ↓
Approved canonical mappings
        ↓
Production synchronization

The resulting profile becomes the machine-readable authority for ZARA, FOGE, TrustGate and downstream computation engines.

3. Integration architecture

Preferred architecture — GraphQL​

XLEDGER
   │
   │ GraphQL
   ▼
ZAYAZ API HUB
   │
   ├── Authentication
   ├── Schema discovery
   ├── Query orchestration
   ├── Pagination
   ├── Incremental sync
   ├── Retry / monitoring
   │
   ▼
ACF-XLEDGER
   │
   ├── Validation
   ├── Mapping
   ├── Normalization
   ├── Entity resolution
   │
   ▼
ZAYAZ CANONICAL DATA MODEL
   │
   ├── FOGE
   ├── ZARA
   ├── TrustGate
   ├── DaVE
   ├── COSE
   └── Computation engines

GraphQL is the preferred production transport because Xledger identifies GraphQL as its primary modern integration approach and supports creation and modification of data through that interface. Authentication is token-based.

SOAP fallback​

SOAP provides an alternative integration path where required by an existing Xledger environment or customer implementation.

SOAP credentials and client certificates are stored independently of application data and are subject to rotation and least-privilege controls.

File integration​

CSV/XML can provide:

  • initial data loads;
  • migration;
  • reconciliation;
  • fallback;
  • customer-specific exchange.

File-derived records enter the same canonical validation and lineage process as API-derived records.

4. Customer-specific schema profile

Every Xledger connection produces a versioned schema profile.

Example:

customer_connector_profile:
  connector: ACF-XLEDGER
  tenant: ZAYAZ-TENANT-123

  available_entities:
    general_ledger: true
    suppliers: true
    supplier_invoices: true
    invoice_lines: true
    projects: true
    climate_activity: false

  permissions:
    read: true
    write: false

  sync:
    incremental: true

  schema_snapshot:
    version: "2026-08-20T08:42:00Z"

This profile prevents downstream engines from relying on generic Xledger assumptions.

FOGE asks:

Is invoice.line.quantity available for this specific tenant?

It does not ask:

Does Xledger generally have invoices?

That distinction is central to ACF.

5. Canonical data mapping

Xledger-specific objects map into source-independent ZAYAZ objects.

Examples:

Xledger account
      ↓
financial.account
Xledger transaction
      ↓
financial.transaction
Xledger supplier
      ↓
organization.supplier
Xledger supplier invoice
      ↓
procurement.invoice
Xledger project
      ↓
project.project
Xledger accounting dimension
      ↓
financial.dimension

Downstream ESG logic operates on canonical fields.

It does not contain connector-specific business logic unless an explicit source rule is required.

6. Data-domain treatment

General ledger and transactions​

Financial records support:

  • ESG expenditure screening;
  • account classification;
  • reconciliation;
  • financial-to-ESG linkage;
  • period analysis.

Each record retains the Xledger source identifier and legal-entity context.

Suppliers​

Supplier master information supports:

  • stable supplier resolution;
  • supplier spend;
  • supplier ESG profiling;
  • Scope 3 prioritization;
  • E-C-O™ Number matching;
  • supplier invitations;
  • supplier-specific evidence.

Supplier identity is not reconstructed from invoice text where a stable Xledger identifier is available.

Customers​

Customer records support:

  • customer-specific allocation;
  • sustainability-data requests;
  • downstream reporting relationships;
  • customer-specific Carbon Passport or product-data flows where applicable.

Invoices and invoice lines​

Invoice-level data provides a substantial data-quality improvement over general-ledger spend alone.

Where the customer schema exposes line-level information, ZAYAZ can use:

  • item/service description;
  • quantity;
  • unit;
  • supplier;
  • project;
  • accounting classification;
  • monetary value;

subject to validation and source availability.

Invoice-line availability is verified during connector activation.

Purchasing and goods receipt​

Xledger supports purchase-order, receiving and inventory processes at application level.

Where exposed through the authorized integration schema, this information can improve:

  • material-flow understanding;
  • quantity-based ESG calculation;
  • procurement classification;
  • product-level traceability;
  • project attribution.

Projects​

Xledger supports project accounting, project costs, time recording and project-level reporting.

Project identifiers can therefore become ESG allocation dimensions after semantic mapping.

Fixed assets​

Asset information can support:

  • capital-goods analysis;
  • asset-related energy or emissions allocation;
  • investment analysis;
  • depreciation/reconciliation context.

Multi-entity data​

Each source legal entity maps explicitly to a ZAYAZ organization entity.

Consolidation occurs only after entity mapping and does not destroy source-level lineage.

7. Existing Xledger ESG data

Xledger has its own carbon-accounting and ESG-reporting functionality, including Scope 1, 2 and 3 reporting, activity data, supplier/category analysis and ESRS-oriented functionality.

This requires a specific interoperability policy.

Principle​

Coexist, do not silently duplicate.

Where authorized Xledger ESG information is exposed to the connector, ZAYAZ registers it as externally originated sustainability data.

Example:

Xledger emission result
        ↓
calculation_origin = XLEDGER
        ↓
TrustGate
        ↓
ZAYAZ ESG data model

ZAYAZ does not silently replace that number with a separate ZAYAZ calculation.

If ZAYAZ performs an independent calculation for comparison:

Xledger result ─────┐
                    ├── Method comparison
ZAYAZ result ───────┘

both remain separately traceable.

This allows ZAYAZ to function as a broader ESG intelligence and assurance layer without corrupting the provenance of calculations performed inside Xledger.

8. ESG processing

Screening​

Transactions can be analyzed using combinations of:

  • account;
  • supplier;
  • invoice;
  • invoice line;
  • project;
  • financial dimension;
  • description;
  • prior classification.

Spend-based calculation​

Spend-based calculations can be generated where appropriate using approved factors and classifications.

Activity-based calculation​

When physical quantity and unit information are available, the calculation may be upgraded to activity-based treatment.

Example:

Invoice amount only
      ↓
Spend estimate

becomes:

Invoice quantity
+ activity unit
+ approved factor
      ↓
Activity-based result

The prior result remains in lineage.

Supplier-specific data​

Supplier-specific sustainability information can supersede generic estimates where it satisfies the applicable data-quality requirements.

9. Data-quality hierarchy

ACF-XLEDGER uses the common ACF hierarchy:

DQ1 — Accounting estimate General-ledger or spend-derived.

DQ2 — Invoice-level evidence Supplier/invoice attribution.

DQ3 — Activity data Physical quantity and unit.

DQ4 — Supplier-specific data Supplier/product-specific evidence.

DQ5 — Verified primary data Validated or verified primary evidence.

The connector records the data-quality level at datapoint level rather than assigning a single quality score to the whole Xledger integration.

10. Traceability

Minimum source lineage includes:

Xledger environment
      ↓
Legal entity
      ↓
Source entity/object
      ↓
Source record ID
      ↓
Retrieval event
      ↓
Canonical mapping
      ↓
Normalization
      ↓
Classification
      ↓
Enrichment
      ↓
Calculation
      ↓
Reported ESG datapoint

TrustGate additionally records:

  • connector version;
  • schema snapshot;
  • query/endpoint context;
  • retrieval time;
  • mapping version;
  • transformation version;
  • classification version;
  • calculation origin;
  • factor source;
  • manual overrides;
  • verification status.

11. Synchronization controls

Initial synchronization​

A full or scoped initial sync establishes:

  • organizations;
  • accounts;
  • suppliers;
  • customers;
  • dimensions;
  • relevant historical transactions;
  • applicable supporting objects.

Incremental synchronization​

Recurring operations use incremental retrieval where the customer Xledger schema supports reliable filtering or timestamps.

Late postings​

A transaction posted into an earlier reporting period generates a revalidation event.

Closed-period changes​

Changes to data already used in an ESG calculation or report are not silently overwritten.

They create:

  1. source-change event;
  2. affected-datapoint identification;
  3. recalculation assessment;
  4. new result version where required.

Schema drift​

Changes to Xledger source fields or permissions are compared against the registered schema snapshot.

Affected mappings are suspended rather than guessed.

12. Security and access

GraphQL credentials use customer-authorized Xledger tokens. SOAP integrations use the corresponding secured credential and certificate model described by Xledger.

ZAYAZ additionally requires:

  • encrypted credential storage;
  • least privilege;
  • tenant isolation;
  • legal-entity scoping;
  • encryption in transit;
  • encryption at rest;
  • audit logging;
  • credential rotation;
  • connection monitoring.

Xledger Norway publicly states ISO 27001 certification, ISAE 3402 alignment and Norwegian data storage for its Norwegian environment. These vendor-level controls are recorded as regional source metadata rather than generalized across every Xledger jurisdiction.

13. Engine behavior

ZARA​

ZARA can answer:

  • what Xledger data is connected;
  • whether a particular field is available;
  • where a datapoint originated;
  • whether a number came from Xledger or ZAYAZ;
  • what evidence supports it.

FOGE​

FOGE uses the customer connector profile before generating input requirements.

Example:

ESRS field requires energy kWh
        ↓
FOGE queries ACF-XLEDGER
        ↓
kWh available from Xledger?
      /       \
    yes        no
     ↓          ↓
prepopulate   request evidence

API Hub​

API Hub owns:

  • authentication;
  • schema discovery;
  • retrieval;
  • pagination;
  • retries;
  • synchronization;
  • health monitoring.

TrustGate​

TrustGate owns the evidential relationship between Xledger source records and resulting ESG data.

DaVE​

DaVE detects:

  • schema changes;
  • sync failures;
  • unexpected record-count changes;
  • source-method changes;
  • unexplained ESG variance.

COSE​

COSE can determine whether available Xledger data satisfies a regulatory evidence requirement or whether FOGE must request richer evidence.

14. Key guardrails

  1. No assumed API field availability.
  2. No silent supplier inference when a stable source ID is absent.
  3. No silent duplicate calculation of Xledger ESG results.
  4. No destruction of previous calculations after data-quality upgrades.
  5. No silent overwrite following closed-period accounting changes.
  6. No use of a source field after schema drift without mapping validation.
  7. No automatic regulatory completion where source evidence is insufficient.
  8. No mixing of legal entities without explicit organization mapping.

15. Canonical ACF principle

ACF-XLEDGER answers four machine-level questions:

What data can this specific Xledger environment provide?

How does that data map into ZAYAZ?

What is the provenance and quality of each resulting datapoint?

What additional evidence is required before ZAYAZ can make a stronger ESG claim?

The connector is therefore not merely an API integration.

It is a governed interpretation layer between Xledger and the wider ZAYAZ intelligence architecture.



Runtime Provider Extension​

The provider-specific runtime contract for this connector is maintained separately from the common ACF connector frontmatter.

It contains machine-actionable provider semantics that are intentionally not part of the common ACF schema, including authentication lifecycle, provider object revision semantics, change-capture constraints and provider-specific capability rules.

provider-extension.yamlGitHub ↗
schema_id: zayaz.acf.provider-extension.v1
extension_version: 1.0.0
connector_id: ACF-XLEDGER
provider:
  namespace: xledger.xledger
  name: Xledger
  product: Xledger
runtime:
  source_contract:
    primary_interface: graphql
    soap_supported: true
    file_import_supported: true
    schema_discovery_required: true
    customer_schema_snapshot_required: true
  source_identity:
    customer_environment_context_required: true
  capability_rules:
    discovered_schema_is_runtime_authority_for_available_entities_and_fields: true
    customer_permissions_material: true
  change_capture:
    native_webhook_support_must_not_be_assumed_without_customer_confirmation: true
    scheduled_query_supported: true
    reconciliation_required: true
  source_semantics:
    project:
      candidate_id_class: EBP
      automatic_resolution_allowed: false
    accounting_dimensions:
      candidate_id_class: EBU
      automatic_resolution_allowed: false
  evidence:
    invoice_documents_supported_when_exposed_by_customer_schema: true
  extensions:
    discovery_output:
      customer_connector_profile_versioned: true
      trustgate_registered: true
governance:
  status: active
  last_verified: 2026-08-30
  review_interval_days: 90
  change_control_required: true
  source_basis: connector_specification
GitHub RepoRequest for Change (RFC)
Last updated on by ZAYAZ