Search by

justdev / lomnio-api-connector

kirilldorozhynskyi

Connects WordPress with the Lomnio API.

Package info

bitbucket.org/studiotem/lomnio-api-connector/

Homepage

Type:wordpress-plugin

pkg:composer/justdev/lomnio-api-connector

Statistics

Installs: 14

Dependents: 1

Suggesters: 0

0.2.0 2026-11-17 15:59 UTC

This package is auto-updated.

Last update: 2026-11-17 15:59:58 UTC


README

Lomnio website

WordPress plugin for syncing Lomnio project data, sending leads, and tracking visitor activity. Synced data is stored in local database tables for use in theme code.

Lomnio website · Lomnio API documentation · OpenAPI JSON

Installation

Recommended project install:

composer require justdev/lomnio-api-connector

Release packages include the vendor/ directory and Action Scheduler. Action Scheduler is a build-only Composer dependency so project-level Composer installs do not create a separate wp-content/plugins/action-scheduler plugin. At runtime the connector loads its bundled copy and therefore does not depend on WooCommerce, another Action Scheduler plugin, or a server-side Composer install. When several plugins bundle Action Scheduler, its version registry loads the newest available version.

Local plugin development install:

cd wp-content/plugins/lomnio-api-connector
composer install --optimize-autoloader

Do not use --no-dev when preparing the release: Action Scheduler is kept in require-dev intentionally so it is bundled during the plugin build without becoming a transitive dependency of consuming WordPress projects. Commit the resulting vendor/ directory with the release.

Activate the plugin in WordPress admin:

/wp-admin/plugins.php

Admin Pages

Endpoint management page:

/wp-admin/admin.php?page=lomnio-api-endpoints

This page allows admins to:

  • enable or disable endpoints;
  • set sync frequency;
  • configure which WP_ENV values may send Leads;
  • run all syncs manually;
  • run Project, Units, or Floors sync separately;
  • check Status, Message, and Fetched / Used At.

Lomnio Settings (including the Pages Settings section):

/wp-admin/admin.php?page=lomnio-api-pages

This page controls the universal Lomnio frontend layer:

  • Enable Lomnio pages turns the whole layer on or off;
  • floor and unit route slugs;
  • phase-aware routes;
  • theme templates used for floor and unit pages;
  • Inertia component names;
  • Floor Page and Unit Page settings custom post types;
  • flats home page used by breadcrumbs;
  • ACF cache TTL.

Detailed diagnostics are available under Lomnio API → Lomnio Logs:

/wp-admin/admin.php?page=lomnio-api-logs

The journal records outgoing Lomnio API requests and responses, incoming tracking proxy requests and webhooks, and endpoint synchronization outcomes (including skipped sends and local errors). Expand an entry to inspect HTTP status, headers, payload, and response. A shared request_id connects entries produced during the same WordPress request. Filter by source and level to find tracking warnings or errors. Tracking summaries include the API's created, duplicates, rejected, and ignored counts when present. Rejected events produce an error entry and mark the endpoint's delivery result as failed even with HTTP 201; ignored events produce a warning. Only events absent from all four response counters are classified as unaccounted for. Per-event rejection reasons cannot be inferred when the API does not return them.

Logs are stored in the private {$wpdb->prefix}lomnio_logs database table, with at most 1,000 entries retained for 7 days and 64 KiB of details per entry. Expired entries are removed on writes and when opening the journal. Oversized strings, collections, and entries are explicitly truncated. Authorization, cookies, signing secrets, email, and phone fields are redacted before storage; visitor/session identifiers are hashed. Viewing and clearing logs requires the plugin's management capability (by default manage_options); clearing uses a nonce-protected POST. Leads no longer create a public uploads log. On initialization, existing uploads/lomnio_leads_log.txt files are deleted without importing their contact data; failed removal is reported in the private journal and an administrator notice and retried on subsequent requests. Gravity Forms entry notes retain their existing behavior. Copies in backups or CDN caches must be handled separately when applicable.

Webhooks appear in the same journal with source webhook, event type and affected unit/floor ID in the summary. Each entry includes the processing result and retains the existing <pre> disclosures for all parsed parameters, raw body, headers, and parameters by source. There is no separate latest-webhook block. Opening the journal imports the previously saved webhook snapshot once and deletes the old snapshot only after a successful write; its original receipt time is preserved in the details and its unknown processing result is explicitly marked. New deliveries are recorded as history instead of overwriting that snapshot. Earlier webhook history cannot be reconstructed.

When Enable Lomnio pages is disabled, the plugin does not register rewrite rules, does not register route query vars, and does not route requests to theme templates.

Settings content is managed through two custom post types created by the plugin:

  • floor_settings
  • single_settings

Each post type allows one settings page per language. WPML translations are supported and should be used for localized content.

Theme templates should use the global facade:

$settings = \LomnioPages::settings();

$floor_slug = $settings['floor_slug'];
$unit_slug = $settings['unit_slug'];
$phase_query_var = $settings['phase_query_var'];

$floor = \LomnioPages::floor_number();
$unit_code = \LomnioPages::unit_id();
$phase = \LomnioPages::phase();

$floor_base_url = \LomnioPages::floor_base();
$phase_floor_base_url = \LomnioPages::floor_base( $phase );
$floor_url = \LomnioPages::floor_link( null, $floor );
$unit_url = \LomnioPages::unit_link( $unit_code );

$floor_fields = \LomnioPages::fields( 'floor' );
$unit_fields = \LomnioPages::fields( 'unit' );

$floor_component = \LomnioPages::component( 'floor' );
$unit_component = \LomnioPages::component( 'unit' );
$not_found_component = \LomnioPages::not_found_component();

$unit_seo = \LomnioPages::unit_seo( $unit );
$floor_seo = \LomnioPages::floor_seo( $floor );

unit_seo() and floor_seo() return title, h1, description, and canonical. They generate route-specific fallback metadata and replace title or description only when the matching Yoast field is explicitly filled on the translated Unit Page or Floor Page settings post.

LomnioPages::apartment_schema( $unit, $canonical ) returns script-safe Apartment JSON-LD for a normalized unit of type byt, or null for another type or missing identity. It includes the unit code, canonical URL and available room count, floor and interior area (MTK). Unknown fields, prices, outdoor area and unconfirmed amenities are omitted. The caller renders the returned JSON in an application/ld+json script and updates/removes it during client-side navigation.

Hidden API token settings page:

/wp-admin/admin.php?page=lomnio-api-connector

The page is available only to users with manage_options. The API token and webhook signing secret are stored encrypted in wp_options. The encryption key is stored in the same database so a full database export can be imported on a site with different WordPress salts. Anyone with access to the full export can recover the credentials.

Before exporting a database from an existing installation, update the plugin and open WordPress admin on the source site while it still uses its original salts. This upgrades both stored credentials automatically. If a database was already copied with the old encrypted values, export it again after this step.

You can paste either a raw token or the full header:

Authorization: Bearer YOUR_API_TOKEN

After saving a valid token, the plugin queues immediate Project, Units, and Floors sync when the endpoints are active.

Sync

The plugin uses Action Scheduler.

Project action hook:

lomnio_api_connector_sync_project

Units action hook:

lomnio_api_connector_sync_units

Floors action hook:

lomnio_api_connector_sync_floors

Default schedules:

  • Project: once per day;
  • Units: every 10 minutes.
  • Floors: every 10 minutes.

Available schedules include 5 minutes, 10 minutes, 30 minutes, hourly, twice daily, and daily.

External Sync Webhook

The standard WordPress REST API webhook receives external Lomnio data:

POST https://site.com/wp-json/lomnio/v1/webhook

Configure the Lomnio project signing secret on the plugin settings page. Every request must include X-Lomnio-Signature: sha256=...; the plugin verifies the HMAC-SHA256 signature over the raw body and returns HTTP 401 when it is invalid. Successfully completed delivery IDs from X-Lomnio-Delivery are deduplicated for seven days. A connection-scoped MySQL lock serializes each delivery; a parallel attempt gets HTTP 503. Completion is recorded only after successful processing, so a request killed before completion can be retried after its database connection closes. Processing exceptions and completion-storage failures return 5xx without acknowledging delivery. Legacy numeric claims are reprocessed once because the old format cannot distinguish success from an interrupted request. This provides at-least-once processing: a crash after a data write but before completion can repeat that write on retry. Recovery depends on the sender retrying the delivery.

webhook.test validates the integration without changing data. unit.*, floor.*, and project.* events upsert the complete snapshot from the matching unit, floor, or project payload field. When deleted is true, visible is false, or the event ends in .deleted, the matching local resource is removed. These snapshot events do not trigger a full pull synchronization.

units.bulk_updated triggers one synchronous full refresh through /v1/units?per_page=-1&detailed=true, using the configured API token and the existing atomic list synchronization. This compatibility handler does not depend on the unconfirmed ID-list payload format and does not fetch individual unit details. It refreshes all units accessible to the token, rather than only the changed IDs. Signature, event header, and delivery ID checks still apply. A busy units lock returns HTTP 503; API or storage failures return a server error and release the delivery claim so the sender can retry. Successful deliveries return status: synchronized; repeated deliveries are deduplicated. Large imports may require a longer webhook timeout because the full refresh completes before acknowledgment.

Unit events identify the resource with unit_id, floor events with floor_id, and project events with project_id. For create and update events, the ID must match the id inside the complete resource snapshot. Floor and unit snapshots use project.id as their local project relation.

For temporary integration debugging, the most recently received request is shown to administrators on the Lomnio API Endpoints page. The view includes headers, raw body, JSON, form, query, and file parameters and can be cleared from the same page. Raw bodies larger than 1 MB are truncated.

Leads

Leads are sent through:

/v1/leads

The endpoint is managed on the endpoint management page. If Leads is inactive, calls to the sender return a skipped result and do not send, note, or log anything.

Allowed environments are controlled per endpoint. By default, only production sends real API requests. If the current WP_ENV is not allowed, the sender records private diagnostics instead of sending. The All environments option allows real sending from every environment.

Use the global class when you do not want to import a namespace:

$result = \LomnioLeads::send(
	array(
		'name'    => sanitize_text_field( $_POST['input_10'] ?? '' ),
		'email'   => sanitize_email( $_POST['input_3'] ?? '' ),
		'phone'   => sanitize_text_field( $_POST['input_4'] ?? '' ),
		'message' => sanitize_textarea_field( $_POST['input_5'] ?? '' ),
	),
	array(
		'source'   => 'Contact form',
		'entry_id' => isset( $entry['id'] ) ? (int) $entry['id'] : 0,
	)
);

The sender records results in the private Lomnio Logs database journal. When GFAPI exists and entry_id is passed, it also writes the request result to the Gravity Forms entry notes. Other forms do not create files in the public uploads directory.

The sender returns either a result array or WP_Error.

Tracking

The plugin exposes a same-site browser proxy and keeps the Lomnio API token on the server:

POST /wp-json/lomnio/v1/tracking/events

Tracking uses the same API token configured under Lomnio API → API token settings → API Authorization as the other outgoing Lomnio API requests. The plugin sends it as the Authorization: Bearer <token> header; no separate tracking token is required.

The proxy accepts the official Lomnio batch shape with 1-50 events and forwards it to /v1/tracking/events/batch. Valid browser payloads always receive 202 Accepted, even when Lomnio rejects or cannot receive the batch. The real Lomnio status remains visible in the endpoint metadata and Lomnio Logs; browser validation errors (422) and the local rate limit (429) remain explicit. Lomnio authentication failures pause outbound tracking for five minutes. Tracking can be enabled, disabled, and restricted by WP_ENV on the Endpoints page. Consent behavior is configured under Lomnio API → Lomnio Settings → Tracking.

The plugin loads a build-free browser SDK:

window.LomnioTracking.track('gallery_browse', {
	unit_id: 1868,
	metadata: ['slide=2'],
});

window.LomnioTracking.setConsent(true);
window.LomnioTracking.setContext({ unit_id: 1868 });
window.LomnioTracking.flush();

For consent management, either call setConsent() or dispatch:

window.dispatchEvent(
	new CustomEvent('lomnio:consent', {
		detail: { granted: true },
	})
);

When Consent required is selected, the plugin also loads a OneTrust bridge after the SDK. It grants tracking when either C0002 or C0007 is active, rechecks on consent changes, and revokes tracking when neither group is active. Revocation clears the SDK visitor/session identity, UTM storage, and queued events.

Verify these default groups against the active OneTrust configuration before using the bridge on a site. If OneTrust is absent, the bridge never grants consent.

The plugin also loads a Cookiebot bridge in Consent required mode. It reads Cookiebot.consent.statistics and synchronizes existing consent as well as CookiebotOnConsentReady, CookiebotOnAccept, and CookiebotOnDecline events. This also supports Cookiebot loaded asynchronously through GTM. Necessary, preferences, or marketing consent alone does not enable Lomnio analytics. Revoking statistics consent clears the SDK identity and queued events. If Cookiebot is absent, this bridge does nothing. Other consent managers can use the event above. Configure only one consent manager per site. The bridge is not loaded in Always mode, and existing saved settings are not changed automatically. Theme-owned form attribution storage is separate and is not managed by this SDK bridge.

A Vue adapter that can be copied into the theme is provided at:

resources/vue/useLomnioTracking.js

Example:

import { useLomnioTracking } from '@/composables/useLomnioTracking';

const { track } = useLomnioTracking({
	unitId: () => props.unit?.id,
});

track('contact_form_open');
track('download', { metadata: ['type=floor_plan'] });

Attach the same anonymous visitor identity to a Vue/Inertia lead form at submit time:

const { withVisitorToken } = useLomnioTracking();

form.transform((data) => withVisitorToken(data)).post('/contact');

The resulting lead payload includes:

{
	"visitor_token": "123e4567-e89b-42d3-a456-426614174000"
}

When analytics consent has not been granted, withVisitorToken() leaves visitor_token out of the request.

The SDK automatically records initial/Inertia page views, unit views when unit context is configured, and time on page. Visitor and queued event data is created only after consent when Consent required is selected.

Tracking event ts values are sent as Unix timestamps in milliseconds. Queued legacy values in seconds are converted automatically before retrying.

Stored Data

Project data is stored in:

{$wpdb->prefix}lomnio_project

The table stores ProjectResource without the API data wrapper.

Units data is stored in:

{$wpdb->prefix}lomnio_units

Units sync uses one detailed list request:

/v1/units?per_page=-1&detailed=true

The plugin does not call:

/v1/units/{unit}

Each unit row stores the full UnitDetailResource in payload_json, plus separate columns for filtering and sorting: project_id, identifiers, status, type, layout, orientation, building, floor, phase, areas, pricing, floor plan, and bundle fields.

Legacy unit columns such as list_payload_json, detail_payload_json, list_hash, and detail_hash are not used. If lomnio_units was created by an older plugin version, recreate or migrate the table before running the current sync.

Floors data is stored in:

{$wpdb->prefix}lomnio_floors

Floors sync uses:

/v1/floors

Each floor row stores the full FloorResource in payload_json, plus separate columns for filtering and sorting: project_id, id, name, number, sort_order, building, availability, unit counts, facade_map_id, and floor_plan_url.

Local table relations:

lomnio_project.project_id = lomnio_units.project_id
lomnio_project.project_id = lomnio_floors.project_id
lomnio_floors.floor_id    = lomnio_units.floor_id

These are indexed local relation columns, not database-level foreign key constraints.

Theme Usage

Use global Lomnio classes in theme code. Do not instantiate repository classes directly unless you need low-level plugin internals.

Frontend routing and display helpers:

$settings = \LomnioPages::settings();

$floor_slug = $settings['floor_slug'];
$unit_slug = $settings['unit_slug'];
$phase_query_var = $settings['phase_query_var'];

$section['floor_link'] = \LomnioPages::floor_base();
$section['phase_floor_link'] = \LomnioPages::floor_base( \LomnioPages::phase() );

Project as object:

$section['project'] = \LomnioProject::get();

Project as array:

$project = \LomnioProject::to_array();

Project ID:

$project_id = \LomnioProject::id();

Project standards files (type: standards):

$standards = \LomnioProject::get_standards();

foreach ( $standards as $standard ) {
	$standard_url = $standard->url;
}

Units list:

$section['units'] = \LomnioUnits::get();

Each unit object contains url built from the unit code and without a phase/project segment.

Units with filters:

$section['units'] = \LomnioUnits::get(
	array(
		'status' => 'available',
		'floor'  => 2,
	)
);

Single unit by ID:

$section['unit'] = \LomnioUnits::find( 51 );

Single unit by code:

$section['unit'] = \LomnioUnits::find_by_code( 'A101' );

Similar units with full locally stored data:

$apartment_code = \LomnioPages::unit_id();
$section['similar_units'] = \LomnioUnits::get_similar( $apartment_code );

You can also pass an already loaded unit object:

$section['similar_units'] = \LomnioUnits::get_similar( $section['unit'] );

The returned objects follow the order of the current unit's similar_units IDs. Missing, deleted, or unpublished units are omitted.

Units by floor:

$section['units'] = \LomnioUnits::by_floor( 10 );

Floors list:

$section['floors'] = \LomnioFloors::get();

Available floors contain url built only from the floor number. Unavailable floors return url => null.

Floors with filters:

$section['floors'] = \LomnioFloors::get(
	array(
		'building_id'  => 1,
		'availability' => 'available',
	)
);

Single floor by ID:

$section['floor'] = \LomnioFloors::find( 10 );

Single floor by number:

$section['floor'] = \LomnioFloors::find_by_number( 2 );

Floors by project:

$section['floors'] = \LomnioFloors::by_project( 51 );

Available Unit Filters

\LomnioUnits::get() supports these filters:

  • id
  • project_id
  • unit_id
  • code
  • status
  • status_code
  • status_label
  • status_color
  • status_is_system
  • type
  • layout_type
  • orientation
  • floor
  • floor_number
  • floor_id
  • floor_name
  • building_id
  • building_name
  • phase_id
  • phase_name
  • room_count
  • area
  • area_floor
  • area_gross
  • area_building
  • area_land
  • price_without_vat
  • price_with_vat
  • discount_without_vat
  • discount_with_vat
  • discounted_price_without_vat
  • discounted_price_with_vat
  • price_per_sqm
  • vat_rate
  • pricing_hidden
  • pricing_display_text
  • floor_plan_url
  • bundle_id
  • bundle_name

Filter values can be scalar values or arrays:

$units = \LomnioUnits::get(
	array(
		'status' => array( 'available', 'reserved' ),
		'floor'  => array( 1, 2, 3 ),
	)
);

Available Floor Filters

\LomnioFloors::get() supports these filters:

  • id
  • project_id
  • floor_id
  • name
  • number
  • floor_number
  • sort_order
  • building_id
  • building_name
  • availability
  • status
  • units_count
  • available_units_count
  • facade_map_id
  • floor_plan_url

Filter values can be scalar values or arrays:

$floors = \LomnioFloors::get(
	array(
		'building_id'  => array( 1, 2 ),
		'availability' => array( 'available', 'unavailable' ),
	)
);

Direct Authorization Header

If plugin code needs the configured authorization header:

$headers = \LomnioApiConnector\Plugin::instance()
	->secret_storage()
	->get_authorization_headers();

The result is either a headers array or WP_Error.

Integration skill

For complete lead mapping, tracking, consent modes and verification, use the Lomnio integration skill. To audit an existing website after setup or a plugin update, use the Lomnio integration check skill for routes, SEO/JSON-LD, forms, consent and tracking, with separate local and live verification results. The complete API contract is published at Lomnio API documentation and OpenAPI JSON; the short lead example above is not the full field inventory.

Dynamic project SEO

Set Lomnio Settings → SEO location: the project locality and location phrase. The project name comes from the WordPress site title (get_bloginfo('name')). The theme calls LomnioPages::unit_seo( $unit ) or LomnioPages::floor_seo( $floor ) without hardcoded project values. Both methods return title, H1, description and canonical. Empty location settings preserve existing Yoast/generated defaults. Optional context arguments can override location and locality programmatically. Apartment-specific wording applies only to type byt; total area includes interior and outdoor spaces. Unknown features are not added.

LomnioPages::apartment_schema( $unit, $canonical ) includes the unit's floor plan, the stored project's address/coordinates and an ApartmentComplex relation to its public website. Empty address components and invalid coordinates/URLs are omitted. The lomnio_api_connector_apartment_schema_project filter receives the project array and unit object; a theme can fill missing location values from its own project map. Use residential project data, not a developer or sales office address. The schema uses accommodationFloorPlan with a FloorPlan object and marks its URL as an image only when the document MIME type identifies an image.

The unit_seo() context accepts an optional plain-text apartment_features sentence to append to generated apartment descriptions. Supply only confirmed features of the current project. Non-apartment routes and explicit Yoast description overrides retain their existing behavior.