Overview

Marina and boatyard management system (Coste360 SRL).

Porto API 0.1.0

Single spec-first contract of Porto’s REST API (spec 27). M0 covers the platform foundations; M1 adds the harbour map (maps, elements, generators, berth groups, harbour settings) and the registry (customers, vessels, documents, deadlines). M2 adds items, classifications, price lists and the pricing tools (simulator, matrix, coverage, renewal). M3 adds occupancy, quotes, contracts and transits; M4 adds instalments, renewals, charter, rights and common charges, print templates and PDF, signatures, communications, the deadline engine, CSV imports and the customer magic-link pages. M5 adds charges from every origin, payments, refunds and credits, cash and corrispettivi, payment requests and reminders, optional online payments (Stripe with SEPA), the “da fatturare” export with invoice reconciliation, statements and the customer dashboard. M6a adds the desktop edition API (/api/desktop/v1, loopback only), browser pairing by QR with device sessions and the local-mode metadata. M6b adds the offline queue guarantees (x-porto-offline, Porto-Offline-Queued-At), the dock collectibles and the transit QR, the fiscal bridge claims of paired desktops, the desktop remote mode (pairing to an online instance, peripherals, kiosk) and the loopback bridge to local peripherals (/api/bridge/v1).

/api/admin/v1 — admin panel API (session cookie, API key or device token).
/api/device/v1 — paired devices (device token, spec 29).
/api/public/v1 — public marina pages (no authentication).
/api/desktop/v1 — desktop edition launcher (M6a): answers only on the loopback listener of porto-desktop, 404 everywhere else.
/api/bridge/v1 — local peripherals of the desktop app (M6b): loopback only like /api/desktop/v1; in remote mode it is served by the app’s local proxy, never by the online instance.

Conventions:

errors are application/problem+json (RFC 9457) with a stable type slug;
collections use cursor pagination (?cursor=&limit=, default 50, max 200);
Idempotency-Key is accepted on creating POSTs (24 h, per principal; 7 days on x-porto-offline operations);
x-porto-offline: true marks the only operations the offline queue may replay (M6b, spec 29.2); a replay carries Porto-Offline-Queued-At (the enqueue instant) and an Idempotency-Key; the header on any other operation is refused with 422 offline_not_allowed;
security schemes appPin and remoteCookie are checked by the desktop app’s remote proxy only (M6b): an operation whose alternatives are all of them answers 404 on a Porto server;
cookie-authenticated unsafe requests send X-CSRF-Token, equal to the porto_csrf cookie;
versioned resources return ETag: "<version>" and PATCH requires If-Match;
calendar dates are YYYY-MM-DD, instants RFC 3339 UTC, ids UUID strings; JSON names are snake_case;
lengths are integer centimetres (*_cm), angles rotation_dd in tenths of a degree, masses kg;
money is integer cents (*_cents), percentages integer basis points (*_bp, 1 % = 100), fractional quantities integer thousandths (*_milli); no number type is used anywhere;
x-porto-max-body-bytes on an operation sets its request body limit (default 1 MiB, hard cap 16 MiB); upload operations take a raw binary body with the declared content types;
x-porto-max-stream-bytes replaces it on the few operations that stream a large raw body to disk (desktop restore, at most 4 GiB): the 16 MiB hard cap does not apply to them.

Information

OpenAPI version: 3.1.0

Operations

Authentication

cookieAuth

Security scheme type: apiKey

Cookie parameter name: porto_session

csrfToken

Required together with cookieAuth on unsafe methods; equal to the porto_csrf cookie.

Security scheme type: apiKey

Header parameter name: X-CSRF-Token

apiKeyAuth

Security scheme type: http

Bearer format: po_live_<prefix>_<secret>

deviceAuth

Security scheme type: http

Bearer format: po_dev_<prefix>_<secret>

instanceToken

Token of the running desktop process (M6a), read by a second launch from the data folder; checked by the handler, not by the session middleware.

Security scheme type: apiKey

Header parameter name: Porto-Instance-Token

appPin

App PIN of a desktop in remote mode (M6b, 6 to 12 digits, Argon2id in desktop.json, 5 failures per 15 minutes): checked by the app’s remote proxy together with the porto_remote cookie, never sent upstream.

Security scheme type: apiKey

Header parameter name: Porto-App-Pin

remoteCookie

Per-launch cookie of the desktop remote proxy (M6b, HttpOnly, SameSite=Strict), obtained by the app window from a secret in the URL fragment; checked by the proxy only.

Security scheme type: apiKey

Cookie parameter name: porto_remote

sensorHmac

M12 ingestion (docs/sensor-protocol.md): Porto-Key (po_sns_ or po_gw_) plus Porto-Signature t=,v1=, timestamp tolerance 300 s. Checked by the ingest handler, never by the router.

Security scheme type: apiKey

Header parameter name: Porto-Signature

gatewayBearer

M12 ingestion by gateways that cannot sign (HTTPS only); checked by the ingest handler.

Security scheme type: http

Bearer format: po_gw_<kid>_<secret>

Porto è sviluppato da Coste360 SRL. Codice sorgente disponibile con licenza BSL 1.1; il marchio Porto è escluso dalla licenza.