📡 API Reference

Complete reference for all Ospite Facile API endpoints. All routes are under /api/.

Authentication
Dashboard
Bookings & Calendar
Properties
Compliance
Billing
Communication
Cleaning & Operations
Pricing & Revenue
Smart Locks & IoT
Documents & OCR
Notifications & Jobs
Guest Portal & Concierge
Co-Host Marketplace
GDPR
Admin & Monitoring
Public API (v1)
Import & Seeding

Authentication

`POST /api/auth/register`

Body:

{
  "email": "host@example.com",
  "password": "securePassword123",
  "name": "Mario Rossi",
  "role": "owner"
}

Response: 201 Created

{
  "success": true,
  "user": { "id": "...", "email": "...", "role": "owner", "planTier": "starter" }
}

Cookie set: ospite_session (30-day HttpOnly cookie with base64-encoded session)

`POST /api/auth/login`

Authenticate and create a session.

Body:

{
  "email": "host@example.com",
  "password": "securePassword123"
}

Response: 200 OK — Sets ospite_session cookie

`POST /api/auth/logout`

Destroy the current session.

Response: 200 OK — Clears ospite_session cookie

`GET /api/auth/csrf`

Get a CSRF token for form submissions.

Response: 200 OK

{
  "token": "csrf_..."
}

Dashboard

`GET /api/dashboard`

Main dashboard data with aggregated stats.

Auth: Required (owner, manager)

Response: 200 OK

{
  "properties": [...],
  "bookings": [...],
  "stats": {
    "totalProperties": 5,
    "activeBookings": 12,
    "monthlyRevenue": 8540.00,
    "occupancyRate": 0.78
  }
}

`GET /api/dashboard/overview`

Dashboard overview with operational data.

Auth: Required

Response: 200 OK — Properties, upcoming check-ins/outs, pending tasks, alerts

Bookings & Calendar

`GET /api/bookings`

List all bookings for the authenticated user's properties.

Auth: Required

Query params:

Param	Type	Description
`status`	string	Filter by status (confirmed, pending, canceled)
`propertyId`	string	Filter by property
`from`	string	Start date (ISO)
`to`	string	End date (ISO)

Response: 200 OK — Array of booking objects

`GET /api/calendar`

Calendar data with bookings and blocks.

Auth: Required

Query params: propertyId, month (YYYY-MM)

Response: 200 OK

`POST /api/calendar`

Create calendar blocks or manage availability.

Auth: Required

Body:

{
  "propertyId": "prop_123",
  "startDate": "2025-08-01",
  "endDate": "2025-08-05",
  "reason": "Personal use"
}

`GET /api/ical/[propertyId]`

Public iCal feed for a property. Used for channel sync with Airbnb/Booking.com.

Auth: None (public feed URL)

Response: 200 OK — text/calendar iCal format

`GET /api/lifecycle`

Get booking lifecycle state for active bookings.

Auth: Required

`POST /api/lifecycle`

Create a new lifecycle for a booking.

Auth: Required

Body:

{
  "bookingId": "book_123",
  "automationMode": "auto"
}

`PATCH /api/lifecycle`

Advance the lifecycle state machine (manual trigger or retry).

Body:

{
  "lifecycleId": "lc_123",
  "trigger": "manual"
}

Properties

`GET /api/properties`

List all properties for the authenticated user.

Auth: Required

Response: 200 OK

[
  {
    "id": "prop_123",
    "name": "Appartamento Centro Forlì",
    "address": "Via Garibaldi 42",
    "city": "Forlì",
    "province": "FC",
    "status": "active",
    "nightlyRate": 85.00
  }
]

Compliance

`GET /api/compliance/alloggiati`

List Alloggiati filings for the user's properties.

Auth: Required

Response: 200 OK — Array of filing records with status

`POST /api/compliance/alloggiati`

Submit guest data to the Questura via Alloggiati Web.

Auth: Required

Body:

{
  "bookingId": "book_123",
  "guests": [
    {
      "surname": "Smith",
      "name": "John",
      "sex": "M",
      "dateOfBirth": "1990-05-15",
      "citizenship": "US",
      "documentType": "passport",
      "documentNumber": "AB1234567"
    }
  ]
}

Response: 200 OK

{
  "success": true,
  "status": "accepted",
  "receiptId": "RCP-2025-0042"
}

`GET /api/compliance/istat`

List ISTAT reports for the user's properties.

Auth: Required

`POST /api/compliance/istat`

Submit ISTAT C/59 tourism statistics report.

Auth: Required

`GET /api/compliance-engine`

Run compliance checks across all properties.

Auth: Required

Response: 200 OK

{
  "score": 85,
  "checks": [
    { "name": "CIN Registration", "status": "pass", "severity": "critical" },
    { "name": "Fire Extinguisher", "status": "warning", "severity": "warning" }
  ],
  "recommendations": [...]
}

`POST /api/compliance-engine`

Trigger a compliance check for a specific property.

`GET /api/tax`

Get tourist tax calculations and rules.

Auth: Required

`POST /api/tax`

Calculate tourist tax for a booking.

Body:

{
  "municipality": "Forlì",
  "guests": 4,
  "childrenUnder14": 1,
  "nights": 5
}

Response: 200 OK

{
  "municipality": "Forlì",
  "ratePerPerson": 2.00,
  "taxableGuests": 3,
  "taxableNights": 5,
  "totalTax": 30.00,
  "breakdown": "3 ospiti × 5 notti × €2.00 = €30.00"
}

`GET /api/istat`

List ISTAT reporting data.

`POST /api/istat`

Submit ISTAT report data.

Billing

`GET /api/billing`

Get current billing/subscription status.

Auth: Required

Response: 200 OK

{
  "planTier": "host",
  "status": "active",
  "plan": {
    "name": "Host",
    "priceMonthly": 39,
    "propertyLimit": 10,
    "features": ["unlimited_channels", "cleaning_tasks", "dashboard_analytics"]
  }
}

`POST /api/billing`

Create or update a subscription.

`GET /api/billing/status`

Quick subscription status check.

`POST /api/billing/checkout`

Create a Stripe Checkout session.

Body:

{
  "planTier": "professional",
  "interval": "monthly"
}

Response: 200 OK

{
  "sessionId": "cs_...",
  "url": "https://checkout.stripe.com/..."
}

`POST /api/billing/portal`

Create a Stripe Customer Portal session for self-service billing management.

Response: 200 OK

{
  "url": "https://billing.stripe.com/..."
}

`POST /api/billing/webhook`

Stripe webhook receiver. Handles checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.paid, invoice.payment_failed.

Auth: Stripe webhook signature verification

Communication

`GET /api/communications`

List communication templates and rules.

Auth: Required

`POST /api/communications`

Send a message or create a communication rule.

Body:

{
  "trigger": "pre_arrival_48h",
  "channel": "email",
  "bookingId": "book_123",
  "language": "en"
}

Triggers: booking_confirmed, pre_arrival_48h, check_in_day, mid_stay, checkout_reminder, review_request

Channels: email, whatsapp, in_app

Cleaning & Operations

`GET /api/cleaning`

List cleaning tasks with status.

Auth: Required

`POST /api/cleaning`

Create or update a cleaning task.

`GET /api/maintenance`

List maintenance tickets.

`POST /api/maintenance`

Create a maintenance ticket.

`GET /api/inventory`

List inventory items and levels.

`POST /api/inventory`

Update inventory or log supply usage.

Pricing & Revenue

`GET /api/pricing`

Get pricing rules and suggestions for properties.

Auth: Required

`POST /api/pricing`

Create or update a pricing rule.

Body:

{
  "propertyId": "prop_123",
  "type": "weekend_uplift",
  "name": "Weekend +20%",
  "adjustment": 20,
  "isPercent": true,
  "conditions": { "daysOfWeek": [5, 6] },
  "priority": 10
}

Rule types: weekend_uplift, seasonal, event, last_minute, min_stay, high_demand, low_demand

`GET /api/analytics`

Revenue analytics and occupancy metrics.

`GET /api/revenue-intelligence`

Cross-property revenue intelligence: P&L, RevPAR, ADR, channel ROI, what-if scenarios.

`POST /api/revenue-intelligence`

Run a what-if revenue scenario.

`GET /api/owner-reports`

List owner reports and payout summaries.

`POST /api/owner-reports`

Generate an owner report for a period.

Smart Locks & IoT

`GET /api/smart-locks`

List smart locks and their status (battery, online, lock state).

Auth: Required

`POST /api/smart-locks`

Create access codes, lock/unlock, or register a new lock.

Body (create access code):

{
  "action": "create_code",
  "lockId": "lock_123",
  "bookingId": "book_123",
  "guestName": "John Smith",
  "validFrom": "2025-08-01T14:00:00Z",
  "validUntil": "2025-08-05T10:00:00Z"
}

Supported providers: Nuki, Yale, August, TTLock, Generic

Documents & OCR

`POST /api/documents`

Upload a guest document (passport, ID card).

Body: Multipart form data with document file.

`POST /api/documents/ocr`

Run OCR extraction on an uploaded document.

Response: 200 OK

{
  "extracted": {
    "surname": "SMITH",
    "name": "JOHN",
    "documentNumber": "AB1234567",
    "dateOfBirth": "1990-05-15",
    "expiryDate": "2030-05-15"
  },
  "confidence": 0.92
}

Notifications & Jobs

`GET /api/notifications`

List notifications for the authenticated user.

Auth: Required

`PATCH /api/notifications`

Mark notifications as read or dismissed.

`GET /api/jobs`

List background jobs with status.

`POST /api/jobs`

Create a background job.

Job types: ical_sync, lifecycle_advance, istat_report, alloggiati_submit, cleaning_auto, review_request, etc.

Guest Portal & Concierge

`POST /api/portal`

Authenticate a guest portal token.

`GET /api/concierge`

Get AI concierge conversations.

`POST /api/concierge`

Send a message to the AI concierge.

Body:

{
  "conversationId": "conv_123",
  "message": "Qual è la password del WiFi?",
  "language": "it"
}

Response: 200 OK

{
  "content": "La password del WiFi è...",
  "confidence": 0.95,
  "shouldEscalate": false,
  "matchedFaq": "wifi",
  "sources": ["knowledge_base"]
}

Co-Host Marketplace

`GET /api/cohost`

Browse co-host profiles and matches.

`POST /api/cohost`

Create a co-host profile or request a match.

Booking Sites

`GET /api/booking-site`

List direct booking site configurations.

`POST /api/booking-site`

Create or update a direct booking site.

GDPR

`GET /api/gdpr/export`

Export all personal data for the authenticated user (GDPR Art. 20 — data portability).

Auth: Required

Response: 200 OK — JSON with all user data, properties, bookings, communications, and subscription history.

`DELETE /api/gdpr/delete`

Delete all personal data and anonymize records (GDPR Art. 17 — right to erasure).

Auth: Required

Response: 200 OK

{
  "deleted": true,
  "anonymized": ["bookings", "communications", "documents"]
}

Retention policy:

Data Type	Retention	Reason
Guest documents	365 days	Operational compliance
Communication logs	90 days	Operational necessity
Job executions	90 days	Debug audit trail
Notifications	180 days	Support traceability
Billing/subscriptions	10 years	Italian fiscal obligations

Integrations

`GET /api/integrations`

List configured integration statuses (Stripe, Resend, Twilio, Alloggiati).

`PATCH /api/integrations`

Update integration configuration.

Admin & Monitoring

`GET /api/health`

Health check endpoint. Used by Docker, Vercel, and load balancers.

Response: 200 OK

{
  "status": "healthy",
  "database": { "provider": "turso", "region": "fra" },
  "version": "0.1.0",
  "uptime": 86400
}

`POST /api/health`

Extended health check with deeper diagnostics.

`GET /api/admin/metrics`

Aggregated application metrics (request volume, error rate, p95 latency).

Auth: Required (admin)

`GET /api/admin/alerts`

List recent alerts.

`POST /api/admin/alerts`

Create or acknowledge an alert.

`GET /api/moonshots`

Moonshot feature status and roadmap data (dev/internal).

Public API (v1)

`GET /api/v1/openapi`

OpenAPI 3.0 specification document for the public API.

`GET /api/v1/keys`

List API keys for the authenticated user.

`POST /api/v1/keys`

Create a new API key.

Body:

{
  "name": "My Integration",
  "permissions": ["properties:read", "bookings:read", "availability:read"],
  "rateLimit": 60
}

Permissions: properties:read, properties:write, bookings:read, bookings:write, availability:read, pricing:read, pricing:write, compliance:read, guests:read, webhooks:manage

`DELETE /api/v1/keys`

Revoke an API key.

`GET /api/v1/webhooks`

List webhook subscriptions.

`POST /api/v1/webhooks`

Create a webhook subscription.

Body:

{
  "url": "https://example.com/webhook",
  "events": ["booking.created", "guest.checked_in", "cleaning.completed"],
  "secret": "whsec_..."
}

Events: booking.created, booking.updated, booking.canceled, guest.checked_in, guest.checked_out, property.updated, cleaning.completed, review.received

`DELETE /api/v1/webhooks`

Delete a webhook subscription.

Import & Seeding

`POST /api/import/csv`

Import properties or bookings from CSV (Airbnb export format supported).

`PUT /api/import/csv`

Update existing records from CSV import.

`POST /api/seed`

Seed the database with demo data (development only).

`GET /api/onboarding`

Get onboarding state for the current user.

`POST /api/onboarding`

Create or advance onboarding flow.

`PUT /api/onboarding`

Update onboarding step data.

`GET /api/reviews`

List guest reviews with sentiment analysis.

`POST /api/reviews`

Create or respond to a review.

Error Responses

All endpoints return consistent error shapes:

{
  "error": "Descrizione dell'errore",
  "code": "VALIDATION_ERROR",
  "details": [...]
}

Status	Meaning
`400`	Validation error — invalid request body or params
`401`	Unauthorized — missing or expired session
`403`	Forbidden — insufficient role or plan tier
`404`	Not found
`429`	Rate limited
`500`	Internal server error

Rate Limiting

Default: configurable via RATE_LIMIT_WINDOW_MS and RATE_LIMIT_MAX_REQUESTS
Auth endpoints: separate limit via AUTH_RATE_LIMIT_MAX
API keys: per-key rate limits (default 60 req/min)

Authentication Methods

Method	Endpoints	Mechanism
Session cookie	All `/api/*` except public	`ospite_session` HttpOnly cookie
API key	`/api/v1/*`	`Authorization: Bearer <key>` header
Webhook signature	`/api/billing/webhook`	Stripe `stripe-signature` header
Portal token	`/api/portal`	One-time guest token in URL

FilesExpand file tree

API.md

Latest commit

History

API.md

File metadata and controls

📡 API Reference

Table of Contents

Authentication

POST /api/auth/register

POST /api/auth/login

POST /api/auth/logout

GET /api/auth/csrf

Dashboard

GET /api/dashboard

GET /api/dashboard/overview

Bookings & Calendar

GET /api/bookings

GET /api/calendar

POST /api/calendar

GET /api/ical/[propertyId]

GET /api/lifecycle

POST /api/lifecycle

PATCH /api/lifecycle

Properties

GET /api/properties

Compliance

GET /api/compliance/alloggiati

POST /api/compliance/alloggiati

GET /api/compliance/istat

POST /api/compliance/istat

GET /api/compliance-engine

POST /api/compliance-engine

GET /api/tax

POST /api/tax

GET /api/istat

POST /api/istat

Billing

GET /api/billing

POST /api/billing

GET /api/billing/status

POST /api/billing/checkout

POST /api/billing/portal

POST /api/billing/webhook

Communication

GET /api/communications

POST /api/communications

Cleaning & Operations

GET /api/cleaning

POST /api/cleaning

GET /api/maintenance

POST /api/maintenance

GET /api/inventory

POST /api/inventory

Pricing & Revenue

GET /api/pricing

POST /api/pricing

GET /api/analytics

GET /api/revenue-intelligence

POST /api/revenue-intelligence

GET /api/owner-reports

POST /api/owner-reports

Smart Locks & IoT

GET /api/smart-locks

POST /api/smart-locks

Documents & OCR

POST /api/documents

POST /api/documents/ocr

Notifications & Jobs

GET /api/notifications

PATCH /api/notifications

GET /api/jobs

POST /api/jobs

Guest Portal & Concierge

POST /api/portal

GET /api/concierge

POST /api/concierge

Co-Host Marketplace

GET /api/cohost

POST /api/cohost

`POST /api/auth/register`

`POST /api/auth/login`

`POST /api/auth/logout`

`GET /api/auth/csrf`

`GET /api/dashboard`

`GET /api/dashboard/overview`

`GET /api/bookings`

`GET /api/calendar`

`POST /api/calendar`

`GET /api/ical/[propertyId]`

`GET /api/lifecycle`

`POST /api/lifecycle`

`PATCH /api/lifecycle`

`GET /api/properties`

`GET /api/compliance/alloggiati`

`POST /api/compliance/alloggiati`

`GET /api/compliance/istat`

`POST /api/compliance/istat`

`GET /api/compliance-engine`

`POST /api/compliance-engine`

`GET /api/tax`

`POST /api/tax`

`GET /api/istat`

`POST /api/istat`

`GET /api/billing`

`POST /api/billing`

`GET /api/billing/status`

`POST /api/billing/checkout`

`POST /api/billing/portal`

`POST /api/billing/webhook`

`GET /api/communications`

`POST /api/communications`

`GET /api/cleaning`

`POST /api/cleaning`

`GET /api/maintenance`

`POST /api/maintenance`

`GET /api/inventory`

`POST /api/inventory`

`GET /api/pricing`

`POST /api/pricing`

`GET /api/analytics`

`GET /api/revenue-intelligence`

`POST /api/revenue-intelligence`

`GET /api/owner-reports`

`POST /api/owner-reports`

`GET /api/smart-locks`

`POST /api/smart-locks`

`POST /api/documents`

`POST /api/documents/ocr`

`GET /api/notifications`

`PATCH /api/notifications`

`GET /api/jobs`

`POST /api/jobs`

`POST /api/portal`

`GET /api/concierge`

`POST /api/concierge`

`GET /api/cohost`

`POST /api/cohost`

`GET /api/booking-site`

`POST /api/booking-site`

`GET /api/gdpr/export`

`DELETE /api/gdpr/delete`

`GET /api/integrations`

`PATCH /api/integrations`

`GET /api/health`

`POST /api/health`

`GET /api/admin/metrics`

`GET /api/admin/alerts`

`POST /api/admin/alerts`

`GET /api/moonshots`

`GET /api/v1/openapi`

`GET /api/v1/keys`

`POST /api/v1/keys`

`DELETE /api/v1/keys`

`GET /api/v1/webhooks`

`POST /api/v1/webhooks`

`DELETE /api/v1/webhooks`

`POST /api/import/csv`

`PUT /api/import/csv`

`POST /api/seed`