Integrations

First-time workspace setup

Complete Getting Started — Recommended Setup Sequence step 12 (this tab — marketplace credentials and calendar feeds) after step 11 Emails, with Integration field capability and Tenant categories default for integrations aligned before bulk imports — full tab map: Recommended setup order. Finish steps 13–15 in Listings (Channels tab per unit), Bookings, and Tenants, then Onboarding a New Property — Step 7. Partner HTTP contracts: API Reference. Lockout catch-up: Getting Started. Workflow pairing after go-live: Account Settings — Setup sequence after go-live.

Finding your way in this guide

Skim What you see on this page and Page load and partial failures, then connect Booking Platforms and Other Providers. Calendar rules: Short-term (Airbnb / Booking.com) Configuration. Sync issues: Troubleshooting. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Integrations section cross-reference · Account Settings — Tab cross-reference.

Connect Vivin to external platforms and services. Once connected, data flows automatically between Vivin and these services.

Direct access

Open Account Settings > Settings > Integrations at platform.vivin.app/settings/integrations. Per-unit channel links and external listing IDs are configured from Listings > Channels. See Deep Links.

Pair with other Account Settings tabs

After platform cards are connected, use Integration field capabilities to see required partner payload fields, then link each unit on Listings → Channels. Pair invoicing providers with Payments, Invoicing & Utilities and set Tenant categories default for integrations before high-volume imports. Partner Bearer keys here are distinct from management JWTs — operator-only routes such as AI usage API require Management session sign-in. Section-to-doc pairing: Integrations section cross-reference. Hub tab matrix: Account Settings — Tab cross-reference.

For how connected channels appear when you manage availability and rates per unit, see the Sales module, especially Channel Manager and related views there.

What you see on this page

Without scrolling past the fold on a typical desktop width, expect roughly this vertical order:

Channel Manager — account-wide controls such as Short-term iCal Max Date and actions to push that date to many units at once (see below).
Booking platform cards — one block per connected marketplace (Airbnb, Booking.com, Vivin Booking Engine, etc.) with enable toggles, credentials or integration email fields, and optional Pricing Markup.
Other providers — Nuki, Hostkit, Invoice-xpress, and similar services you add with Add Integration.

Use Sales > Channel Manager when you need a consolidated operational view of channels; this Integrations page is where credentials and account-wide sync rules live.

Page load and partial failures

The Integrations tab loads in layers — account-wide platform cards from cached workspace settings, then a separate fetch for Other providers (Nuki, Hostkit, Invoice-xpress, and similar account connections).

Phase	What you see	If it fails
First paint	Settings form skeleton placeholders across the tab	Wait for the shared Account Settings bootstrap to finish, or refresh `/settings/integrations` after connectivity recovers
Booking platform cards + Channel Manager	Cards and toggles from account settings	Usually still render from the last successful settings payload; Save failures show an error toast with the server message
Other providers list	Connected provider cards, or skeleton rows while the connections API runs	On fetch failure the list clears to empty and Vivin shows an error toast — for example Failed to load integrations. — so you are not misled into thinking no Nuki / Hostkit / Invoice-xpress connections exist. Refresh `/settings/integrations` after connectivity recovers. Add Integration and per-card Delete failures also surface as toasts

Unlike directory modules such as Bookings or Sales that show an explicit Failed to load … card with Retry, Other providers failures use the global toast pattern (no inline Retry on the tab). See Glossary — Settings and profile load failures.

Account Settings — Integrations, Other providers list empty after connections fetch failure with error toast

When Remove connection fails (network or server error), the confirmation modal stays open and an error toast appears — for example Failed to remove connection — so you can retry or Cancel without losing context:

Account Settings — Integrations, Remove account connection modal with delete failure toast

Screenshots

Sales module (operational view) — Channel Manager lists each listing with per-channel connection status, sync controls, and availability context. Use it day to day alongside Account Settings > Integrations, where API keys, integration emails, pricing markups, and Short-term iCal Max Date are configured.

Sales — Channel Manager grid with per-listing integrations and channel status

Account Settings > Integrations — platform connection cards, API credentials, and account-wide sync options (including Short-term iCal Max Date) in the settings shell:

Account Settings — Integrations overview with platform cards and Short-term iCal Max Date

Platform integrations and booking channels — + Add for Nuki, Hostkit, Invoice-xpress, and similar providers; booking platform cards with enable toggles and per-channel options:

Account Settings — Integrations with Nuki and Invoice-xpress providers and booking platform cards

When Hostkit is connected, the Other providers list shows a Listing keys control on the Hostkit card (per-unit keys are managed in a modal — see Hostkit (invoicing) below).

Idealista and Coliving — mid-term marketplace cards with enable toggles, integration email, and optional pricing markup (same pattern as HousingAnywhere or Uniplaces):

Account Settings — Idealista and Coliving platform integration cards

Screenshot freshness

Idealista / Coliving cards — re-captured 2026-06-05 with expanded platform rows (enable toggle, integration email, pricing markup). Script: VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-docs-enrichment-batch.ts.

Other providers load/delete failure toasts — re-captured 2026-06-17 (#1735, #1734). Script: VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-settings-integrations-other-providers-failure-toasts.ts (local dev frontend with /api proxy — unset VITE_API_BASE_URL on npm run dev:frontend).

Booking Platforms

Pair with other Integrations sections

Enabling a platform card does not list units — link each unit on Listings → Channels and verify payloads against Integration field capabilities. Full pairing matrix: Integrations section cross-reference.

These integrations connect your units to external rental listing sites. When enabled, Vivin synchronizes availability calendars and (where supported) pricing.

Platform	What It Does
Airbnb	Two-way calendar sync. Bookings made on Airbnb are imported into Vivin; bookings in Vivin block Airbnb dates.
Booking.com	iCal calendar sync. Two-way sync — bookings made on Booking.com are imported into Vivin; bookings in Vivin block Booking.com dates. Add each unit's iCal URL from your Booking.com extranet (Availability > Export calendar) in the Channels tab.
Uniplaces	Calendar sync and booking import for the student rental platform.
Spotahome	Calendar sync for medium-term furnished rentals.
HousingAnywhere	Calendar sync for international student and expat housing.
Inlife	Integration for the Inlife student accommodation platform. After enablement, bulk migration uses + Create New → Listings → Inlife Import (structure only) or Inlife Full Import (Vivin internal — details + photos for full listing feeds). See Listings — Importing from Inlife and Create New Menu — Inlife Import.
Spacest	Calendar sync for the Spacest platform.
ErasmusLife Lisboa	Calendar sync and booking import for the ErasmusLife Lisboa student accommodation platform.
Idealista	Calendar sync and booking import for the Idealista marketplace. Configure integration email and optional Pricing Markup like other mid-term platforms.
Coliving	Calendar sync and booking import for the Coliving distribution channel. Configure integration email and optional Pricing Markup; bookings imported from Coliving appear with the Coliving platform badge in Vivin.
Channex	Channel-manager distribution: push availability and rate/restriction updates to Channex when your workspace has a Channex API connection and each unit is mapped to Channex property, room type, and rate plan UUIDs. Enable the platform card here and set optional Pricing Markup (no integration email on the card). Confirmed bookings can import from Channex when mappings match. Channex API credentials and per-unit UUID mapping are configured with your Vivin account team — not from the standard Add Integration dialog.
Edu Portugal	Calendar sync for the Edu Portugal student accommodation platform. Commission and calendar block can be configured; no integration email or markup.
Vivin Booking Engine	Enables the Vivin-hosted direct booking page where tenants can book directly without a third-party platform.
iCal	Export a standard iCal feed URL for each unit. Any platform that accepts iCal feeds (Airbnb, VRBO, Tripadvisor, etc.) can subscribe to this to receive availability updates. Per-unit URL: `{Core API host}/ical-integration/listings/{listingId}/iCal.ics` (copy via Copy iCal on a Sales > Channels row, from the unit integration wizard, or bulk-export VIVIN iCal column).

For each platform integration, you typically configure:

Integration Email or API Key — the credential that identifies your account on that platform
Pricing Markup — an optional percentage to add to your base Vivin price when syncing rates to that platform (e.g., +15% to cover platform fees)
Virtual IBAN (when provisioned) — some connected booking platforms show a platform-level virtual IBAN on the card with a copy control. Tenants paying through that channel can use it for bank transfers; Vivin matches inbound platform transfers separately from each booking’s tenant virtual IBAN on Contract Info (see Bookings — Virtual IBAN). The row appears only when Vivin has issued a non-empty VIBAN for that platform slug on your account.

Business Rule

Enabling a platform integration here does not automatically list your units on that platform. You still need to create the listing on the external platform and link each unit in Vivin to its corresponding external listing ID.

Channex (channel manager)

Channex is a channel-manager connection, not a single marketplace with one integration email. Operators typically:

Enable the Channex card under Booking platform cards and configure Pricing Markup if you mark up rates sent to connected OTAs.
Rely on Vivin to push availability and restrictions (ARI) to Channex for units that have a valid Channex mapping — Channex property, room type, and rate plan UUIDs from the Channex API.
Receive booking imports when Vivin processes a matching revision from Channex’s booking revisions feed — confirmed stays appear with the Channex platform badge like other channels.

Account-level Channex API keys and per-listing channexMapping UUID rows are maintained outside the self-serve Add Integration flow (your Vivin onboarding contact or internal admin tools). Unlike Airbnb or Idealista, you do not paste Channex UUIDs on the unit Channels tab yourself — ask Vivin support to verify mapping for affected units.

Direction	Mechanism	Operator action
Outbound (Vivin → Channex)	Scheduled ARI sync posts availability + minimal rate/restrictions for mapped units	Enable the platform card; keep listing rent and calendar data accurate in Vivin
Inbound (Channex → Vivin)	Vivin polls Channex’s booking revisions feed (not an HTTP webhook you configure on this page)	Enable the card; confirm mapping with support when imports are missing

Channex does not appear as a column on Sales > Channels. When a unit is mapped, a Channex row may appear in the unit Listings > Channels sidebar alongside other connected platforms — but UUID mapping itself is provisioned by Vivin, not typed into external listing ID fields like mid-term marketplaces. Bookings imported from Channex still show the Channex platform badge in Bookings and appear in Finance > Transactions when you filter by source platform.

Booking updates from Channex

Revisions with status modified are acknowledged on the Channex side but booking date or amount changes are not applied automatically in Vivin today — reconcile those in Bookings manually when a channel manager sends an amendment.

Short-term (Airbnb / Booking.com) Configuration

Pair with other Integrations sections

Short-term iCal Max Date pushes calendar horizons to many units at once — pair day-to-day sync status with Sales — Channel Manager before high-season turnover. Full pairing matrix: Integrations section cross-reference.

Airbnb and Booking.com use iCal feeds to sync availability. Vivin provides controls to limit how far ahead availability is exported to these platforms.

Short-term iCal Max Date

The Short-term iCal Max Date (in the Channel Manager section) limits how far ahead the iCal feed exports availability. Dates after this cutoff are blocked on the feed as a security lock, so external platforms will not show your unit as available beyond that date.

Account Settings — Channel Manager block with Short-term iCal Max Date and Save

Control	Location	Description
Short-term iCal Max Date	Channel Manager section	Account-wide default. Sets the last date availability is exported. Save after changing.
Apply to all listings	Airbnb / Booking.com platform cards	Copies the Short-term iCal Max Date to every unit's per-listing override. Use when you want all units to share the same cutoff.
Apply to selected listings	Airbnb platform card	Copies the date to only the selected units. Use when some units need a different cutoff.

On the Airbnb (and Booking.com) platform cards, Apply to all listings and Apply to selected listings copy the account-wide cutoff to per-unit overrides after you set Short-term iCal Max Date:

Account Settings — Airbnb platform card with Apply to all listings and Apply to selected listings

Walkthrough: Channel Manager short-term iCal cutoff, then Apply to all listings / Apply to selected listings on the Airbnb platform card (view-only tour — no Save or Apply clicks).

info

If a unit has no per-listing override, it uses the property-level override (if set), otherwise the account-level Short-term iCal Max Date. You can also set a per-unit date in the unit's edit view (Listings module) if you need different cutoffs per unit.

When to Use These Controls

Limit booking horizon — Prevent short-term platforms from accepting bookings too far in advance (e.g., only 6 months ahead).
Avoid double-bookings — Reduce risk when syncing with multiple channels by capping how far ahead availability is shared.
Per-unit control — Use "Apply to selected listings" or edit units individually when some units need a different cutoff than others.

Other Providers

Pair with other Integrations sections

Nuki, Hostkit, and Invoice-xpress pair with Payments, Invoicing & Utilities VAT series and Emails check-in codes — only one invoicing provider may be active per account. Full pairing matrix: Integrations section cross-reference.

Provider	What It Does
Nuki	Connects Vivin to Nuki smart locks. Once connected, Vivin can generate temporary access codes for tenants and automatically include them in check-in emails. Requires your Nuki API key.
Hostkit	Connects Vivin to Hostkit for Portuguese Fatura-Recibo invoicing. API keys are per listing (not a single account key on the add-integration dialog). After you add Hostkit, use Listing keys on the card to paste each unit’s key from Hostkit Properties → API key. See Hostkit (invoicing).
Invoice-xpress	Connects to the Invoice-xpress invoicing service for legally compliant invoice generation. Requires your Invoice-xpress API key and client ID. Once connected, Vivin generates and submits invoices automatically when payments are recorded.
Sage50c	Coming soon — Sage Accounting (Sage50c) as an additional invoicing connector. It appears in the Add Integration list as disabled with a Contact the VIVIN team to enable tooltip until your account is provisioned. When live, it will follow the same one invoicing provider at a time rule as Hostkit and Invoice-xpress.

To add a provider, click Add Integration in the Other providers section, select the provider from the list, enter the required credentials, and save. Sage50c is listed for visibility but cannot be added until Vivin enables it for your account.

One invoicing provider at a time

Hostkit, Invoice-xpress, and (when enabled) Sage50c are invoicing connections. The product allows only one active invoicing provider per account — if one is already configured, the others appear disabled in the Add Integration list until you remove the existing connection.

Removing a provider connection

Use this when you need to switch invoicing providers, rotate compromised API credentials, or disconnect smart-lock access.

Open Account Settings → Settings → Integrations.
In Other providers, locate the connection card (Nuki, Hostkit, Invoice-xpress, or Sage50c when connected).
Click the trash control on the card (or the remove action in the card menu, depending on layout).
Confirm in Remove account connection — the dialog names the connection and warns that the action cannot be undone and integrations using it may stop working.
Click Remove connection to delete the account connection via the API, or Cancel to keep it.

If the delete request fails (network or server error), Vivin shows an error toast — for example Failed to remove connection — and keeps the Remove account connection dialog open so you can retry or Cancel without losing context.

Account Settings — Integrations, Remove account connection confirmation for an Other providers card (example Hostkit connection)

Remove account connection modal capture refreshed 2026-06-22 02:14 UTC (VIVIN_DOCS_BASE_URL=http://localhost:5173 VIVIN_DOCS_RECORD_API=$VITE_API_BASE_URL npx tsx tools/capture-docs-enrichment-3005.ts).

Provider removed	Practical impact
Nuki	New check-in codes stop generating; existing codes may expire per Nuki rules. Resend flows on bookings fail until you reconnect.
Hostkit / Invoice-xpress / Sage50c	Automatic invoice creation stops; Finance see invoice links for past Hostkit documents may break for new payments until a provider is connected again. Per-listing Hostkit keys on the card are deleted with the connection.
Any	Add Integration re-enables competing invoicing types that were blocked while another invoicing connector was active.

Switching invoicing providers is remove first, then add — you cannot run two invoicing connectors in parallel. After removal, open Invoicing & Payments and confirm series / VAT settings match the new provider before recording chargeable payments.

Hostkit (invoicing)

Hostkit is aimed at operators who issue Fatura-Recibo (FR) documents from Hostkit when Vivin records chargeable payments.

1. Add Hostkit (account level)

Open Account Settings → Settings → Integrations.
In Other providers, click Add Integration and choose Hostkit.
The add dialog explains that keys are created in Hostkit under each property — it does not ask for an API key at this step. Save to create the connection card.

Official Hostkit key creation steps: Hostkit knowledge base — article 89.

2. Listing keys (per unit)

After Hostkit is saved, the Other providers section shows a Hostkit connection card (not a single account-wide API key field). The card subtitle explains that credentials are per listing; the primary action is Listing keys (wording may vary slightly by interface language).

On the Hostkit connection card, click Listing keys (tooltip: Manage Hostkit API keys per listing).
In the Hostkit API keys by listing modal, use Search by listing or property… when you manage keys across a large portfolio — Vivin searches server-side (debounced) over listing and property internal names instead of loading every unit up front.
Each row shows Property, Listing, Saved key (for example Configured (···1234) or Not set), and a New key field. Paste the full API key from the matching Hostkit property, then Save on that row. Keys are stored per listing — re-paste the full key when rotating credentials. After Save, the row updates in place so your scroll position is preserved (no full-table refresh).
The modal loads listings in chunks (about 20 rows per request). Scroll inside the table panel to fetch more — a Loading more… line appears while the next batch loads. The footer shows the server total (for example 142 listings). Changing search starts again from the first chunk for the new query.

Modal column (English UI)	Meaning
Listing / Property	Which unit the Hostkit property key belongs to
Saved key / New key	Current state vs the field where you paste a replacement
Configured (···suffix)	A key is on file; Vivin shows trailing digits only for security
Not set	No key saved yet — invoicing for that unit will fail until you paste one
Loading listings…	First chunk is still fetching (empty table)
No listings match…	Search returned zero rows — clear or broaden the search term
Could not load listings.	Hostkit-keys fetch failed — close and reopen the modal, or refresh Integrations

3. Invoice series on the Invoicing tab

After Hostkit is connected, open Payments, Invoicing & Utilities → Invoicing and set Hostkit invoice series to the exact series code from Hostkit Faturação → Séries (Vivin always requests document type FR on create). Vivin refuses to issue while the field is blank — save a non-empty series before your first Issue allocation. Use the same field when invoice creation fails with an invalid series error from Hostkit after a typo.

Account Settings — Invoicing tab with Hostkit invoice series field (see also Invoicing & Payments doc)

4. Finance and booking files

When invoicing runs through Hostkit, issued allocations can expose a Hostkit invoice link on Finance Transactions (transaction detail) and in booking file flows where the API returns a document URL. If a PDF is still generating in Hostkit, retry after a short wait or open the link in a desktop browser — server-side PDF fetch can lag Hostkit’s UI. See Finance — Hostkit invoice links for operator-facing detail.

5. Hostkit API pacing (bulk invoicing)

Hostkit enforces per-API-key rate limits. Vivin paces outbound Hostkit calls (per listing key and at account level) so large Issue allocation / Invoice selected batches are less likely to hit HTTP 429 responses. When Hostkit still returns 429, Vivin retries with backoff (honouring Retry-After when present) instead of failing the allocation immediately — safe because Hostkit rejected the request before processing it.

What you see	What it means
Bulk invoicing takes longer than usual on a big ledger selection	Normal — Vivin is spacing Hostkit requests to stay under the provider limit
Some rows stay Pending / Failed invoicing for a few minutes, then flip to Invoiced	Retries may still be in progress — refresh Transactions before re-running Issue allocation on the same row
Persistent Failed after several minutes with a Hostkit error toast	Check Listing keys, Hostkit invoice series, and Hostkit account health — see FAQ — Why is bulk Hostkit invoicing slow?

How Calendar Synchronization Works

Pair with other Integrations sections

Imported channel bookings appear in Bookings and block Sales availability — use Manual block hygiene when sync lag leaves suspicious gaps. Full pairing matrix: Integrations section cross-reference.

When a booking is created in Vivin (whether manually or imported from a platform), the system automatically blocks those dates on all connected external platforms. This prevents double-bookings across channels.

Similarly, when a booking is created directly on Airbnb or another platform, it is imported into Vivin and the dates are blocked across all other connected channels.

info

Calendar sync runs periodically. Newly created bookings may take a short time to propagate to all connected platforms. For immediate blocking, you can also add manual unavailability in the Listings module.

Troubleshooting

Pair with other Integrations sections

Sync symptoms often trace to Listings → Channels external IDs or Short-term iCal Max Date cutoffs — confirm unit mapping before filing support for duplicate imports. Full pairing matrix: Integrations section cross-reference.

Issue	Solution
Platform not appearing in Bookings filters	Ensure the platform is enabled in this Integrations page. Only connected platforms appear as filter options in the Bookings module.
Bookings not importing from a platform	Verify your API key or integration email is correct. Check that each unit is linked to its corresponding external listing ID in the unit's Channels tab.
Calendar dates not syncing	Confirm the iCal feed URL is correctly subscribed on the external platform. Check that the unit has no conflicting manual unavailability.
External calendar “stops” or looks fully blocked past a month	Often the Short-term iCal Max Date (Channel Manager section on this page): dates after the cutoff are sent to Airbnb / Booking.com iCal feeds as blocked on purpose. Move the date forward if you want a longer booking horizon on those platforms, then save and use Apply to all listings or per-listing overrides as needed. See Short-term (Airbnb / Booking.com) Configuration.
Booking.com iCal shows one multi-year “Unavailable” block	Some Hostify-hosted Booking.com iCal feeds export a single closed period spanning many months or years. Vivin ignores Hostify blocks longer than three months during import so they do not lock the unit calendar. Stale local rows from an earlier import are removed on the next sync. If availability still looks wrong, confirm the OTA calendar itself is open, re-save the unit Channels import URL, and check for genuine manual blocks in Listings.
Duplicate bookings appearing	This can happen if a booking was both imported automatically and created manually. Search by tenant name in Bookings to identify duplicates.
Channex enabled but no sync or imports	Confirm your account has a Channex API key and each unit has `channexMapping` UUIDs (property, room type, rate plan) provisioned by Vivin support — not self-serve external IDs on Listings > Channels. Enable the Channex platform card here; Channex is not a column on Sales > Channels. See Channex (channel manager) and Webhooks & notifications — Channex booking revisions.
Other providers list is empty after a blip	Check for a recent error toast (Failed to load integrations.). The list can look empty while platform cards above still render. Refresh `/settings/integrations` before re-adding a provider you already connected. See Page load and partial failures.
Bulk Hostkit invoicing is slow or some rows stay Pending	Vivin paces Hostkit API calls and retries HTTP 429 with backoff during Issue allocation / Invoice selected — large batches can take several minutes. Refresh Finance → Transactions before re-issuing the same allocation. Persistent failures: verify Listing keys and Hostkit invoice series. See Hostkit API pacing (bulk invoicing) and FAQ — Why is bulk Hostkit invoicing slow?.

Integrations section cross-reference

Use this table when one Integrations topic naturally leads into another Account Settings tab, operator module, API guide, or downstream workflow — each row links to the docs you should read before or after wiring marketplace connections.