DataBridge Integration Guide
DataBridge provides a standardized nightly export of Zaui data for customer-managed systems like data warehouses, finance platforms, CRM systems, reporting environments, & business intelligence tools.
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:
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:
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:
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:
After the entire package has been successfully committed, store:
For example:
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:
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:
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:
Fields:
timeZone is the organization's IANA time zone.
customers.csv
Contains exported customer profiles.
Primary key:
Fields:
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:
Fields:
bookingReference is the customer-facing booking reference.
booking_items.csv
Contains sold booking lines and supported subordinate activity-option rows.
Fields:
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:
Examples:
Supported prefixes include:
Channel and portal attribution
channelIdidentifies the booking channel and referenceschannels.csv.channelId.portalIdidentifies the Zaui portal associated with the booking, where applicable.portalNameprovides the corresponding portal name.internetBookedindicates whether the booking was made through the internet booking flow.
taxes.csv
Contains the current booking tax rows.
Fields:
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:
Fields:
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:
Fields:
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:
Fields:
channelId is referenced by booking_items.csv.channelId.
booking_transactions.csv
Contains financial transactions associated with bookings.
Fields:
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:
Preserve financial values using exact decimal storage.
agents.csv
Contains agent reference data currently exposed by DataBridge.
Primary key:
Fields:
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:
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:
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:
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:
When an emitted booking changes, replace its previously stored child sets with the rows contained in the new package.
Conceptually:
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:
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:
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
Time
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
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:
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:
rather than:
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:
Consumers should inspect the schema version declared by each package before loading it.
Semantic versioning is used to communicate compatibility:
Consumers should identify CSV fields by header name rather than relying solely on column position.
Error Handling
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:
What does DataBridge give me? A standardized package of canonical Zaui datasets.
How do I retrieve it? Use the DataBridge access information provided by the app to discover and download the available package.
What do I open first? The manifest. It describes the package and the files you should process.
How are the datasets related? Join them using the documented booking, line-item, customer, offering, price-code, channel, and transaction identifiers.
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.
Last updated