> For the complete documentation index, see [llms.txt](https://docs.zaui.com/developer-api-documents/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zaui.com/developer-api-documents/databridge-integration-guide.md).

# DataBridge Integration Guide

A typical DataBridge integration consists of downloading a package, reading its manifest, loading the included datasets, and repeating that process for each subsequent package.

Zaui\
↓\
DataBridge package\
↓\
manifest.json\
↓\
Canonical CSV files\
↓\
Your data store\
↓\
Optional transformation\
↓\
D365 / BI / CRM / Data Warehouse

DataBridge provides the canonical Zaui export. Your organization is responsible for transforming that data into the structure required by its downstream systems.

***

## 1. Quick Start

A DataBridge integration follows eight steps.

### Step 1 — Get Access

Install and enable DataBridge for the Zaui organization.

The DataBridge app provides the customer-specific location required to access the organization's exports.

Treat the access information provided by DataBridge as configuration. Do not construct URLs from organization IDs, CDN paths, system IDs, or other Zaui values.

***

### Step 2 — Retrieve the Available Package

Use the DataBridge location provided by the app to discover the packages currently available for processing.

DataBridge produces two package types:

* **Bootstrap** — establishes the initial state of your destination.
* **Daily** — contains subsequent booking changes and the supporting records required to interpret them.

Process the bootstrap package before processing daily packages.

Do not search for, predict, or hard-code nightly filenames or CDN paths. Use the locations advertised by DataBridge.

***

### Step 3 — Read the Manifest

The manifest is the entry point for processing DataBridge exports.

It provides the information required to identify and validate the package, including:

* package ID;
* run ID;
* export type;
* schema version;
* export-period start and end;
* previous cursor;
* included files;
* record counts;
* file sizes and checksums;
* package metadata.

Always use the manifest rather than assuming which files a package contains.

***

### Step 4 — Extract and Read the Data Files

Download the package and safely extract it.

Process the CSV datasets listed by the manifest.

The current DataBridge schema contains:

```
organization.csvcustomers.csvbookings.csvbooking_items.csvtaxes.csvofferings.csvprice_codes.csvchannels.csvbooking_transactions.csvagents.csv
```

Use a standards-compliant CSV parser and identify fields by their documented header names rather than relying only on column position.

Before loading data, validate the package and its contents using the sizes and SHA-256 checksums supplied by DataBridge.

***

### Step 5 — Load the Canonical Datasets

Load the CSV datasets into staging tables or directly into your destination model.

DataBridge uses two main processing models:

| Dataset                    | Processing model               |
| -------------------------- | ------------------------------ |
| `organization.csv`         | Stable-key upsert              |
| `customers.csv`            | Stable-key upsert              |
| `bookings.csv`             | Stable-key upsert              |
| `offerings.csv`            | Stable-key upsert              |
| `price_codes.csv`          | Stable-key upsert              |
| `channels.csv`             | Stable-key upsert              |
| `agents.csv`               | Stable-key upsert              |
| `booking_items.csv`        | Complete child-set replacement |
| `taxes.csv`                | Complete child-set replacement |
| `booking_transactions.csv` | Complete child-set replacement |

Do not treat every row in every nightly package as a new record.

***

### Step 6 — Join the Datasets

Use the documented identifiers to connect DataBridge records.

The primary relationships are:

```
booking_items.bookingId    → bookings.bookingId
booking_items.customerId    → customers.customerId
booking_items.offeringId    → offerings.offeringId
booking_items.priceCodeId    → price_codes.priceCodeId
booking_items.channelId    → channels.channelId
taxes.bookingId    → bookings.bookingId
booking_transactions.bookingId    → bookings.bookingId
booking_transactions.lineItemId    → booking_items.lineItemId
booking_items.parentLineItemId    → booking_items.lineItemId
```

Identifiers should be treated as belonging to the exporting Zaui organization unless otherwise documented.

If exports from multiple Zaui organizations are combined, namespace tenant-scoped identifiers by organization.

***

### Step 7 — Process Each Nightly Package

After the bootstrap has been loaded, process daily packages in cursor order.

For each daily package, verify:

```
package.previousCursor == storedCursor
```

After the entire package has been successfully committed, store:

```
storedCursor = package.exportPeriod.end
```

For example:

```
Bootstrapend = 2026-08-01T06:00:00Z
        ↓
Daily 1previousCursor = 2026-08-01T06:00:00Zend            = 2026-08-02T06:00:00Z
        ↓
Daily 2previousCursor = 2026-08-02T06:00:00Zend            = 2026-08-03T06:00:00Z
```

If `previousCursor` does not match your stored cursor, stop processing. Do not skip forward to a newer package.

Advance the cursor only after the complete package has successfully committed.

***

### Step 8 — Transform Into Your Target Model

DataBridge provides standardized Zaui datasets. It does not prescribe the schema of your destination system.

After loading the canonical DataBridge data, transform it as required for your environment.

For example:

```
DataBridge    ↓Canonical Zaui datasets    ↓Your staging/data model    ↓Transformation    ↓D365Power BIData WarehouseCRMFinance Platform
```

Transformations such as aggregation, normalization, dimensional modelling, account mapping, or destination-specific field structures are the responsibility of the consuming system.

A simple implementation may look like:

```
package = download_next_package()
manifest = read_manifest(package)
validate(package, manifest)
for file in manifest.files:    rows = read_csv(file)    stage(rows)
apply_upserts()replace_booking_child_sets()
commit()
save_cursor(manifest.exportPeriod.end)
```

***

## 2. Data Model

DataBridge exports booking data together with the reference data required to interpret it.

### `organization.csv`

Describes the Zaui organization generating the export.

Primary key:

```
organizationId
```

Fields:

```
organizationIdorganizationNameaddressLine1cityregionpostalCodecountryCodetimeZonecurrencyCode
```

`timeZone` is the organization's IANA time zone.

***

### `customers.csv`

Contains exported customer profiles.

Primary key:

```
customerId
```

Fields:

```
customerIdstatusfirstNamelastNameemailphoneaddressLine1addressLine2cityregionpostalCodecountryCodesourceCreatedAt
```

Customer relationships are associated with booking items rather than directly with the booking header.

When customer personal data is configured as **Included**, approved contact and address fields may be populated.

When configured as **Redacted**, direct customer details are empty/null while stable identifiers and supported non-personal fields remain available.

***

### `bookings.csv`

Contains booking headers.

Primary key:

```
bookingId
```

Fields:

```
bookingIdbookingReferencebookingStatusbookedAtcancelledAtcurrencyCodesubtotalAmounttaxAmounttotalAmountbalanceDueAmountlastDateModifiedAt
```

`bookingReference` is the customer-facing booking reference.

***

### `booking_items.csv`

Contains sold booking lines and supported subordinate activity-option rows.

Fields:

```
lineItemIdparentLineItemIdbookingIdcustomerIdcustomerSequencepackageIdofferingIdcommissionedAgentIdchannelIdportalIdportalNameinternetBookedpriceCodeIditemStatusquantityseniorsadultsstudentschildreninfantstravelDatetravelTimeserviceStartAtcurrencyCodesubtotalAmounttaxAmountcancelledAtsourceCreatedAtlastDateModifiedAt
```

#### Customer attribution

`customerSequence = 1` identifies the purchaser or lead customer relationship.

Values of `2` and above represent additional guest-detail associations.

Passenger-type fields such as `adults`, `children`, `students`, `seniors`, and `infants` are aggregate sold quantities, not individual passenger records.

#### Offering attribution

`offeringId` uses a namespaced identifier:

```
<offeringType>:<sourceId>
```

Examples:

```
activity:501package:42pass:90gift_certificate:18
```

Supported prefixes include:

```
activityactivity_optionmerchandise_productpackagepassgift_certificate
```

#### Channel and portal attribution

* `channelId` identifies the booking channel and references `channels.csv.channelId`.
* `portalId` identifies the Zaui portal associated with the booking, where applicable.
* `portalName` provides the corresponding portal name.
* `internetBooked` indicates whether the booking was made through the internet booking flow.

***

### `taxes.csv`

Contains the current booking tax rows.

Fields:

```
bookingIdtaxNameamountlastDateModifiedAt
```

There is no independent row-level tax identifier.

Duplicate tax names may legitimately occur.

***

### `offerings.csv`

Contains offering definitions used to interpret sold booking items.

Primary key:

```
offeringId
```

Fields:

```
offeringIdofferingTypesellableFamilyactivitySubtypeofferingNamestatusbookableFrombookableTosourceCreatedAtsourceModifiedAt
```

DataBridge does not currently provide detailed enrichment for offering categories, departures, destinations, locations, journeys, routes, stops, or vehicles.

***

### `price_codes.csv`

Contains price-code definitions used to describe sold booking items.

Primary key:

```
priceCodeId
```

Fields:

```
priceCodeIdpriceCodeNamesourceCreatedAt
```

Price codes provide descriptive information about the sold line. They do not provide enough configuration to reconstruct Zaui's pricing engine.

***

### `channels.csv`

Contains booking-channel definitions.

Primary key:

```
channelId
```

Fields:

```
channelIdchannelNamechannelTypesourceCreatedAt
```

`channelId` is referenced by `booking_items.csv.channelId`.

***

### `booking_transactions.csv`

Contains financial transactions associated with bookings.

Fields:

```
transactionIdbookingIdlineItemIdresellerAgentIdresellerBookingReferenceresellerRateNameresellerRateresellerRateAmounttransactionMethodNameledgerEntrytransactionStatusamountcurrencyCodeprocessedAmountprocessedCurrencyCodeexchangeRateoccurredAt
```

Use `ledgerEntry` to determine debit or credit direction. Do not infer ledger direction solely from the sign of `amount`.

Where populated, `lineItemId` associates a transaction with a booking item.

For currency-converted transactions:

```
processedAmount = amount × exchangeRate
```

Preserve financial values using exact decimal storage.

***

### `agents.csv`

Contains agent reference data currently exposed by DataBridge.

Primary key:

```
agentId
```

Fields:

```
agentIdagentTypeagentNamestatussourceCreatedAt
```

The current dataset exposes employee agent records.

Commissioned seller and reseller agent records are not currently emitted through `agents.csv`, so consumers should not assume that all agent identifiers found in booking data can be resolved through this dataset.

***

## 3. Processing Rules

### Bootstrap vs. Daily Packages

A **bootstrap package** establishes the initial state of the destination.

It contains the full current-state reference dimensions required to begin processing DataBridge.

A **daily package** contains bookings that changed during the export period, their complete current booking child sets, and the reference records required to interpret those changes.

Process the bootstrap before any daily package.

***

### Dimension Records

The following datasets use referential closure:

```
customers.csvofferings.csvprice_codes.csvchannels.csv
```

On bootstrap, they contain their full current-state dimensions.

On daily packages, they contain only the rows required to resolve references from booking data changed in that package.

For example:

```
booking_items.channelId = 42
        ↓
channels.csv includes channelId = 42
```

The absence of a customer, offering, price code, or channel from a daily package does **not** indicate that the record was deleted.

`organization.csv` remains a single-row current-state snapshot.

`agents.csv` currently exposes employee agents on both bootstrap and daily runs and does not use the same daily referential-closure model.

***

### Stable-Key Upserts

Use the documented stable identifier when loading reference and booking-header datasets.

For example:

```
bookings.csvkey = bookingId
```

If booking `12345` already exists and appears again in a later package, update the existing booking.

Do not append another independent booking.

The same principle applies to organizations, customers, offerings, price codes, channels, and agents.

***

### Booking Child Records

These datasets represent complete current child sets for each emitted booking:

```
booking_items.csvtaxes.csvbooking_transactions.csv
```

When an emitted booking changes, replace its previously stored child sets with the rows contained in the new package.

Conceptually:

```
BEGIN
UPSERT booking
DELETE existing booking_itemsINSERT current booking_items
DELETE existing taxesINSERT current taxes
DELETE existing booking_transactionsINSERT current booking_transactions
COMMIT
```

This prevents stale child records from remaining after a booking changes.

#### Cancelled and removed items

A cancelled booking item remains part of the booking and may appear with:

```
itemStatus = cancelled
```

A previously stored item that is absent from the new complete child set has been removed.

Do not treat cancellation and removal as the same operation.

#### Legacy booking items

Some legacy booking items may have a null `lineItemId`.

When such a booking changes, rebuild its complete child set rather than attempting to match individual null-ID rows.

Do not create synthetic business identifiers unless required by your own destination design.

***

### Idempotency

Processing the same immutable package more than once must be safe.

Record at least:

```
packageIdsha256schemaVersionexportTypeexportPeriod.startexportPeriod.endprocessingResultprocessedAt
```

If the same package has already committed with the same package ID and checksum, treat it as already processed.

If the same package ID is observed with a different checksum, stop processing and investigate.

***

### Cursor Handling

The cursor represents the last package successfully committed to your destination.

Do not advance it when a package is merely:

* discovered;
* downloaded;
* extracted;
* staged;
* partially loaded.

Advance it only after the complete package has committed.

Package boundaries should be taken directly from the manifest.

Do not assume every reporting period is exactly 24 hours. Reporting periods may follow the organization's local time zone and can vary during daylight-saving transitions.

***

## 4. Reference

### Package Validation

Before loading a package, validate:

#### Package

* package ID;
* supported schema version;
* expected byte size;
* SHA-256 checksum.

#### Files

Use the package manifest to validate:

* filenames;
* dataset versions;
* file sizes;
* file checksums;
* record counts.

Do not load files merely because their names look familiar. Process the contents advertised by the manifest.

***

### CSV Data Types

DataBridge uses the following logical types.

**String** — UTF-8 text.

**ID** — stable string identifier whose scope depends on the field.

**Date**

```
YYYY-MM-DD
```

**Time**

```
HH:MM:SS
```

Time values represent organization-local wall-clock time unless otherwise documented.

**Timestamp** — ISO 8601 timestamp including the applicable UTC offset.

**Integer** — base-10 whole number.

**Decimal** — base-10 decimal value without a currency symbol.

**Boolean**

```
truefalse
```

**Enum** — value from the documented set supported by the schema version.

***

### Null Values

An empty CSV field represents null when the field is nullable.

For example:

```
customerId,email,phone12345,jane@example.com,
```

The empty `phone` value is null.

Do not automatically convert null values to `0`, `false`, `UNKNOWN`, `N/A`, or `REDACTED`.

***

### Financial Data

Use exact decimal or fixed-point storage for financial values.

Prefer:

```
DECIMAL / NUMERIC
```

rather than:

```
FLOAT / DOUBLE
```

Do not assume that:

* every booking total can be reconstructed from descriptive dimensions;
* an amount's sign identifies debit or credit direction;
* duplicate tax names should be collapsed;
* package grouping identifies a globally unique package sale;
* price-code names reproduce Zaui pricing.

Use the financial values exported by DataBridge as the source values for downstream reporting unless another reconciliation rule has been explicitly defined.

***

### Personal Data

DataBridge may contain approved personal data relating to purchasers and guests.

Depending on configuration:

**Included** — approved customer contact and address fields may be populated.

**Redacted** — direct customer details are omitted while stable identifiers and relationships remain available.

DataBridge does not export sensitive information such as:

* payment card data;
* authentication credentials;
* passwords or secrets;
* government identifiers;
* passport details;
* health information;
* birth dates;
* waiver data;
* unrestricted notes;
* person-level passenger records.

Changing the personal-data setting affects future packages. It does not alter packages already created, downloaded, or loaded into customer-controlled systems.

***

### Security

Treat DataBridge packages and downstream copies as potentially containing personal or commercially sensitive information.

Consumers should:

* use HTTPS;
* restrict access using least privilege;
* encrypt sensitive staging and destination storage at rest;
* keep personal data out of application logs;
* keep sensitive access information out of logs and monitoring systems;
* safely extract ZIP archives and prevent path traversal;
* remove temporary staging files after processing;
* apply appropriate downstream retention and privacy controls.

Downloaded DataBridge data becomes the responsibility of the organization operating the destination system.

***

### Retention

DataBridge packages are retained for **30 days**.

Process required packages before they expire.

Do not use DataBridge package storage as a long-term archive.

If a required package expires before it is processed, do not skip it and advance to a newer cursor. Stop processing and contact Zaui.

***

### Schema Version

The current DataBridge schema version is:

```
1.1.0
```

Consumers should inspect the schema version declared by each package before loading it.

Semantic versioning is used to communicate compatibility:

```
Major: 1.x.x → 2.x.xPotentially incompatible contract changes
Minor: 1.0.0 → 1.1.0Backward-compatible additions
Patch: 1.1.0 → 1.1.1Compatible corrections or clarifications
```

Consumers should identify CSV fields by header name rather than relying solely on column position.

***

### Error Handling

| Condition                                           | Recommended action                   |
| --------------------------------------------------- | ------------------------------------ |
| Package already committed with same ID and checksum | Treat as idempotent success          |
| Same package ID with different checksum             | Stop and investigate                 |
| Package download fails transiently                  | Retry with bounded backoff           |
| Package size or checksum fails                      | Discard staged file and retry        |
| Package manifest validation fails                   | Stop; do not load                    |
| CSV validation fails                                | Stop; do not advance cursor          |
| `previousCursor` does not match stored cursor       | Stop and refresh manifest            |
| Unsupported schema version                          | Stop before loading                  |
| Destination transaction fails                       | Roll back and retry the same package |
| Required package has expired                        | Stop and contact Zaui                |

Never manually advance the cursor to bypass an ingestion problem.

***

### Monitoring

A production integration should record enough information to determine what happened to each package.

At minimum, record:

* package ID;
* export type;
* export period;
* schema version;
* checksum;
* download and validation result;
* source and loaded record counts;
* previous cursor;
* committed cursor;
* processing result;
* errors;
* completion time.

Alert when there is:

* repeated retrieval failure;
* cursor discontinuity;
* an expired required package;
* checksum or file validation failure;
* unsupported schema version;
* repeated destination failure;
* absence of an expected nightly package.

***

### Data Not Included

The initial DataBridge release does not provide:

* real-time updates;
* individual passenger records or passenger personal details;
* payment card data;
* credentials or authentication secrets;
* standalone fee or discount datasets;
* offering-category enrichment;
* detailed departure, destination, location, journey, route, stop, or vehicle data;
* customer-requested historical rebuilds;
* long-term package archive storage.

Additional datasets may be introduced through future versioned releases.

***

### Production Checklist

Before enabling production ingestion:

* DataBridge is installed and enabled.
* The DataBridge location supplied by the app is stored as configuration.
* Bootstrap is processed before daily packages.
* The manifest is used to discover and validate package contents.
* Package sizes and SHA-256 checksums are validated.
* ZIP extraction prevents path traversal.
* Unsupported schema versions fail before destination changes.
* CSV files are parsed using a standards-compliant parser.
* Stable-key datasets use idempotent upserts.
* Booking child sets are replaced atomically.
* Financial values use exact decimal storage.
* Cursor continuity is validated for each daily package.
* The cursor advances only after the complete package commits.
* Package IDs and checksums are recorded durably.
* Missing or expired packages stop processing.
* Personal data is protected in staging and destination systems.
* Operational monitoring detects ingestion failures and missed exports.

***

## Integration Principle

A DataBridge integration should answer five questions clearly:

1. **What does DataBridge give me?**\
   A standardized package of canonical Zaui datasets.
2. **How do I retrieve it?**\
   Use the DataBridge access information provided by the app to discover and download the available package.
3. **What do I open first?**\
   The manifest. It describes the package and the files you should process.
4. **How are the datasets related?**\
   Join them using the documented booking, line-item, customer, offering, price-code, channel, and transaction identifiers.
5. **What do I do when the next nightly package arrives?**\
   Validate its cursor, load/upsert its data, replace the complete booking child sets, commit the package, and then advance your stored cursor.

**In short:**

Discover package\
↓\
Read manifest\
↓\
Validate files\
↓\
Load canonical datasets\
↓\
Join / Upsert\
↓\
Commit cursor\
↓\
Transform for D365 / BI / CRM / Warehouse\
↓\
Repeat with next nightly package

Treat the **manifest as the contract**, each **package as an immutable unit of work**, and the **committed cursor as the source of truth for ingestion progress**.