Pair this app to an online Porto instance on the first run and restart in remote mode (M6b)

POST

/api/desktop/v1/remote/pair

Shell / cURL

curl --request POST \
  --url https://example.com/api/desktop/v1/remote/pair \
  --header 'Content-Type: application/json' \
  --data '{ "first_run_token": "example", "link": "example", "url": "example", "code": "example", "fp": "example", "pin": "example", "name": "example" }'

Local mode, first run only (first-run token in the body; 409 first_run_done once the local instance has users or the app is already paired). The app calls pairDevice on the remote instance (kind: desktop) with the TLS policy of the payload (fp = pinned leaf, then its CA; no fp = system roots; http only in development), stores the device token in the OS secret store (never in the page or in desktop.json), sets the app PIN and restarts in remote mode (202).

Request Body^required

application/json

The porto://pair link, or url + code (+ fp); pin is the new app PIN.

object

first_run_token

required

string

<= 128 characters

link

Porto://pair?v=1&url=…&code=…&fp=…

string

<= 2048 characters

url

string

<= 512 characters

code

string

<= 16 characters

Leaf fingerprint (base64url) of a self-signed target

string

<= 128 characters

pin

required

string

>= 6 characters <= 12 characters /^[0-9]+$/

name

Device name shown on the online instance

string

<= 100 characters

Example ^generated

{
  "first_run_token": "example",
  "link": "example",
  "url": "example",
  "code": "example",
  "fp": "example",
  "pin": "example",
  "name": "example"
}

Responses

202

Paired; the app restarts in remote mode

400

Malformed request or validation failure

application/problem+json

object

type

required

string

Allowed values: bad_request validation_failed weak_password invalid_reset_token invalid_totp pairing_code_invalid invalid_scope invalid_webhook_url unknown_event_type unauthorized invalid_credentials totp_required forbidden csrf_failed totp_enrolment_required totp_required_by_policy not_found method_not_allowed conflict slug_taken already_member last_owner totp_already_enabled totp_not_enrolled endpoint_disabled idempotency_in_progress version_conflict unsupported_media_type idempotency_key_reused precondition_required rate_limited internal_error not_ready map_invalid map_not_empty map_not_georeferenced invalid_file file_too_large csv_invalid customer_anonymized customer_merged download_link_expired no_price promo_not_applicable price_list_invalid price_list_immutable price_list_overlap in_use resource_taken fit_blocked placement_invalid invalid_transition quote_expired hold_expired closure_active undo_unavailable release_invalid customer_required not_implemented renewal_exists proposal_closed signature_open invalid_signature otp_invalid otp_locked otp_rate_limited link_invalid template_invalid template_limits paper_scan_required insurance_required customer_email_missing shares_invalid table_incomplete table_active transfer_requirements mandate_overlap vessel_in_other_fleet vessel_not_in_fleet import_not_undoable provider_unknown code_taken charge_immutable charge_cancelled use_edit match_exceeds refund_exceeds already_reversed credit_insufficient not_deposit nothing_to_settle charge_exists no_termination_amount not_exported export_empty export_too_large charges_not_open release_not_resold cash_session_required cash_session_open cash_session_closed cash_insufficient register_in_use provider_disabled provider_refund_unsupported provider_error billing_item_missing first_run_token_invalid first_run_done lan_port_unavailable lan_no_address backup_in_progress restore_failed restore_backup_newer allocation_changed offline_not_allowed remote_unreachable remote_pin_mismatch peripheral_unavailable claim_expired app_pin_invalid invalid_period invalid_report_filter report_too_large unknown_indicator booking_unavailable booking_rules booking_busy consent_required text_outdated refund_changed price_changed cancellation_not_allowed nothing_due idempotency_mismatch storage_target_invalid storage_no_space area_exits_invalid pinned_invalid too_many_items scenario_window_invalid scenario_not_draft scenario_conflicts movement_not_pending element_invalid maintenance_conflicts task_already_done reading_charged consumption_frozen formula_invalid work_order_closed work_order_has_charges qualification_mismatch capacity_exceeded dependency_violation duration_too_long offline_time_out_of_range timer_already_running return_exceeds_issued nothing_to_bill equipment_slot_taken operator_busy equipment_out_of_service equipment_capacity_exceeded operator_not_enabled outside_lift_window ingest_unauthorized ingest_timestamp_out_of_range invalid_payload segment_overlap resource_has_sensor invalid_sensor_resource alert_stale alert_action_not_allowed profile_incomplete photo_invalid

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

field

required

string

code

required

string

message

string

retry_after_seconds

integer

issues

Map validation issues (map_invalid)

Array<object>

object

code

required

ValidateMap rule (m1-plan §2.3), e.g. berth_overlap

string

severity

required

string

Allowed values: error warning

element_type

required

string

refs

required

Array<string>

field

string

params

Numbers only (cm, counts)

object

key

additional properties

integer format: int64

price_list_issues

Price list validation issues (price_list_invalid)

Array<object>

object

code

required

Pricing.Validate issue code (m2-plan §4.8), e.g. period_overlap

string

severity

required

string

Allowed values: error warning

ref

required

object

kind

required

string

Allowed values: list settings period band rule item

Id of the row, or the client key of an unsaved one

string

field

string

params

Codes and integers as strings; never personal data

object

key

additional properties

string

details

Machine-readable details: no_price {item_id, contract_type, night, unit, category, band, reason}; price_list_overlap {conflicts: [{id, code, valid_from, valid_to}]}; in_use {references}; resource_taken ConflictDetail; fit_blocked FitResult; placement_invalid {reason, allocation_id?}; invalid_transition {from, action}; closure_active {closure_id, from_date, to_date}; release_invalid {reason}; allocation_changed {current_resource_id, current_resource_code} (null when the allocation is gone); remote_pin_mismatch {expected_fingerprint, presented_fingerprint}; scenario_conflicts {conflicts: [StorageScenarioConflict]}; maintenance_conflicts {conflicts: [MaintenanceConflict]}; storage_no_space {area_id, from, to}. Ids, codes, dates and integers only.

object

key

additional properties

any

Example

{
  "type": "bad_request",
  "issues": [
    {
      "severity": "error"
    }
  ],
  "price_list_issues": [
    {
      "severity": "error",
      "ref": {
        "kind": "list"
      }
    }
  ]
}

404

Not found (or not visible to the principal)

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

field

required

string

code

required

string

message

string

retry_after_seconds

integer

issues

Map validation issues (map_invalid)

Array<object>

object

code

required

ValidateMap rule (m1-plan §2.3), e.g. berth_overlap

string

severity

required

string

Allowed values: error warning

element_type

required

string

refs

required

Array<string>

field

string

params

Numbers only (cm, counts)

object

key

additional properties

integer format: int64

price_list_issues

Price list validation issues (price_list_invalid)

Array<object>

object

code

required

Pricing.Validate issue code (m2-plan §4.8), e.g. period_overlap

string

severity

required

string

Allowed values: error warning

ref

required

object

kind

required

string

Allowed values: list settings period band rule item

Id of the row, or the client key of an unsaved one

string

field

string

params

Codes and integers as strings; never personal data

object

key

additional properties

string

details

object

key

additional properties

any

Example

{
  "type": "bad_request",
  "issues": [
    {
      "severity": "error"
    }
  ],
  "price_list_issues": [
    {
      "severity": "error",
      "ref": {
        "kind": "list"
      }
    }
  ]
}

409

Conflict with the current state

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

field

required

string

code

required

string

message

string

retry_after_seconds

integer

issues

Map validation issues (map_invalid)

Array<object>

object

code

required

ValidateMap rule (m1-plan §2.3), e.g. berth_overlap

string

severity

required

string

Allowed values: error warning

element_type

required

string

refs

required

Array<string>

field

string

params

Numbers only (cm, counts)

object

key

additional properties

integer format: int64

price_list_issues

Price list validation issues (price_list_invalid)

Array<object>

object

code

required

Pricing.Validate issue code (m2-plan §4.8), e.g. period_overlap

string

severity

required

string

Allowed values: error warning

ref

required

object

kind

required

string

Allowed values: list settings period band rule item

Id of the row, or the client key of an unsaved one

string

field

string

params

Codes and integers as strings; never personal data

object

key

additional properties

string

details

object

key

additional properties

any

Example

{
  "type": "bad_request",
  "issues": [
    {
      "severity": "error"
    }
  ],
  "price_list_issues": [
    {
      "severity": "error",
      "ref": {
        "kind": "list"
      }
    }
  ]
}

422

Idempotency-Key reused with a different request

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

field

required

string

code

required

string

message

string

retry_after_seconds

integer

issues

Map validation issues (map_invalid)

Array<object>

object

code

required

ValidateMap rule (m1-plan §2.3), e.g. berth_overlap

string

severity

required

string

Allowed values: error warning

element_type

required

string

refs

required

Array<string>

field

string

params

Numbers only (cm, counts)

object

key

additional properties

integer format: int64

price_list_issues

Price list validation issues (price_list_invalid)

Array<object>

object

code

required

Pricing.Validate issue code (m2-plan §4.8), e.g. period_overlap

string

severity

required

string

Allowed values: error warning

ref

required

object

kind

required

string

Allowed values: list settings period band rule item

Id of the row, or the client key of an unsaved one

string

field

string

params

Codes and integers as strings; never personal data

object

key

additional properties

string

details

object

key

additional properties

any

Example

{
  "type": "bad_request",
  "issues": [
    {
      "severity": "error"
    }
  ],
  "price_list_issues": [
    {
      "severity": "error",
      "ref": {
        "kind": "list"
      }
    }
  ]
}

502

The payment provider failed (provider_error, details.code)

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

field

required

string

code

required

string

message

string

retry_after_seconds

integer

issues

Map validation issues (map_invalid)

Array<object>

object

code

required

ValidateMap rule (m1-plan §2.3), e.g. berth_overlap

string

severity

required

string

Allowed values: error warning

element_type

required

string

refs

required

Array<string>

field

string

params

Numbers only (cm, counts)

object

key

additional properties

integer format: int64

price_list_issues

Price list validation issues (price_list_invalid)

Array<object>

object

code

required

Pricing.Validate issue code (m2-plan §4.8), e.g. period_overlap

string

severity

required

string

Allowed values: error warning

ref

required

object

kind

required

string

Allowed values: list settings period band rule item

Id of the row, or the client key of an unsaved one

string

field

string

params

Codes and integers as strings; never personal data

object

key

additional properties

string

details

object

key

additional properties

any

Example

{
  "type": "bad_request",
  "issues": [
    {
      "severity": "error"
    }
  ],
  "price_list_issues": [
    {
      "severity": "error",
      "ref": {
        "kind": "list"
      }
    }
  ]
}

503

Not ready

application/problem+json

object

type

required

string

title

required

string

status

required

integer

detail

string

instance

string

request_id

string

errors

Array<object>

object

field

required

string

code

required

string

message

string

retry_after_seconds

integer

issues

Map validation issues (map_invalid)

Array<object>

object

code

required

ValidateMap rule (m1-plan §2.3), e.g. berth_overlap

string

severity

required

string

Allowed values: error warning

element_type

required

string

refs

required

Array<string>

field

string

params

Numbers only (cm, counts)

object

key

additional properties

integer format: int64

price_list_issues

Price list validation issues (price_list_invalid)

Array<object>

object

code

required

Pricing.Validate issue code (m2-plan §4.8), e.g. period_overlap

string

severity

required

string

Allowed values: error warning

ref

required

object

kind

required

string

Allowed values: list settings period band rule item

Id of the row, or the client key of an unsaved one

string

field

string

params

Codes and integers as strings; never personal data

object

key

additional properties

string

details

object

key

additional properties

any

Example

{
  "type": "bad_request",
  "issues": [
    {
      "severity": "error"
    }
  ],
  "price_list_issues": [
    {
      "severity": "error",
      "ref": {
        "kind": "list"
      }
    }
  ]
}

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

Pair this app to an online Porto instance on the first run and restart in remote mode (M6b)

Request Bodyrequired

Example generated

Responses

202

400

Example

404

Example

409

Example

422

Example

502

Example

503

Example

Request Body^required

Example ^generated