Skip to content
HallifyDevelopersSearch documentation
Open Hallify
Sections

Guest ordering

Prepare contact recovery from an owned preorder session

POST/public/preorders/manage/portal/prepare

Authorizes the current native READ SESSION, original verified birth, exact fulfillment and guest profile, source family, current presentation and actual Origin. All target fields are derived server-side; body and query must be absent or empty objects. No caller-selected contact is accepted. Returns only a private existing-contact reentry target for canonical Guest Portal code request and confirmation. No Portal bearer, proof or native grant is issued. The required idempotency key permanently binds the exact source and Origin to its encrypted original result; admitted replays return that same hint and deadline without creating another session or extending authority. A required Idempotency-Key makes retries with the same payload return the stored status and body; reusing the key with a different payload returns 409.

Authentication

Authorization: Bearer <HALLIFY_PREORDER_MANAGE_TOKEN>

Guest-owned capability for managing a preorder.

Connection guide

Parameters

idempotency-keyHeader · Required

Required idempotency key, up to 128 characters

string
Full definition
{
  "type": "string",
  "minLength": 1,
  "maxLength": 128,
  "example": "example"
}
originHeader · Required

Actual browser Origin, matching the original classified native presentation and its current continuation authority. Widget requests retain the isolated frame Origin; an embedding parent is never substituted.

string
Full definition
{
  "type": "string",
  "maxLength": 2048,
  "example": "example"
}

Responses

200Original private existing-contact recovery target, bounded by the admitted native maximum. Real OTP confirmation remains required before Portal access.
GuestNativePortalIngressResultDto
Full definition
{
  "$ref": "#/components/schemas/GuestNativePortalIngressResultDto"
}
Example response · 200 · application/json
{
  "reentryContext": {
    "hint": "gpr1_synthetic_recovery_context_example_not_a_runtime_credential_0000000000",
    "expiresAt": "2026-12-31T18:00:00.000Z"
  }
}
400The required idempotency key is empty or exceeds 128 characters, or the body/query is neither absent nor an empty object. Null, arrays, primitive values and supplied body/query fields are rejected.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 400 · application/json
{
  "statusCode": 400,
  "error": "errors:http.badRequest",
  "code": "HTTP_BAD_REQUEST",
  "message": "errors:http.badRequest",
  "translationKey": "errors:http.badRequest"
}
401Rejects a missing, malformed, expired, revoked, or invalid preorderManageToken credential at the owning domain boundary.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 401 · application/json
{
  "statusCode": 401,
  "error": "errors:http.unauthorized",
  "code": "HTTP_UNAUTHORIZED",
  "message": "errors:http.unauthorized",
  "translationKey": "errors:http.unauthorized"
}
402The original native ORDER lacks retained operational continuation admission. Error code: BILLING_OPERATION_NOT_ADMITTED. Preparing a Portal target never creates new commercial coverage.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 402 · application/json
{
  "statusCode": 402,
  "error": "errors:http.failure",
  "code": "HTTP_402",
  "message": "errors:http.failure",
  "translationKey": "errors:http.failure"
}
404The current native SESSION, READ scope, retained source birth, exact guest identity/profile, source family or current presentation is unavailable. Missing or mismatched Origin also fails closed. Error code: PREORDER_PUBLIC_RESOURCE_NOT_FOUND.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 404 · application/json
{
  "statusCode": 404,
  "error": "errors:http.notFound",
  "code": "HTTP_NOT_FOUND",
  "message": "errors:http.notFound",
  "translationKey": "errors:http.notFound"
}
409Idempotency key is already in progress or was reused with a different payload
IdempotencyConflictError
Full definition
{
  "$ref": "#/components/schemas/IdempotencyConflictError"
}
Example response · 409 · application/json
{
  "statusCode": 409,
  "error": "errors:http.conflict",
  "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
  "message": "errors:idempotency.inProgress",
  "translationKey": "errors:idempotency.inProgress"
}
429The native management rate limit was reached. Error code: RATE_LIMITED. Retry-After gives the remaining delay in whole seconds.

Response headers

Retry-After

Whole seconds the client must wait before retrying the rejected request.

integer
Full definition
{
  "type": "integer",
  "minimum": 1,
  "example": 60
}
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 429 · application/json
{
  "statusCode": 429,
  "error": "errors:http.tooManyRequests",
  "code": "HTTP_TOO_MANY_REQUESTS",
  "message": "errors:http.tooManyRequests",
  "translationKey": "errors:http.tooManyRequests"
}
503Current admission, retained evidence, encryption or original command state cannot be safely resolved. The same idempotency key must be retained when retrying.
TranslatedErrorDto
Full definition
{
  "$ref": "#/components/schemas/TranslatedErrorDto"
}
Example response · 503 · application/json
{
  "statusCode": 503,
  "error": "errors:http.serviceUnavailable",
  "code": "HTTP_SERVICE_UNAVAILABLE",
  "message": "errors:http.serviceUnavailable",
  "translationKey": "errors:http.serviceUnavailable"
}

Schemas

GuestNativePortalIngressResultDto

Private contact-code target prepared from the guest-owned native reservation, waitlist or preorder. It grants no Portal access until the existing real OTP workflow succeeds.

reentryContextRequired

Original bounded recovery target for the existing guest contact. Retain it privately and request and confirm a real code through the canonical Guest Portal reentry flow.

allOf
Full definition
{
  "readOnly": true,
  "description": "Original bounded recovery target for the existing guest contact. Retain it privately and request and confirm a real code through the canonical Guest Portal reentry flow.",
  "allOf": [
    {
      "$ref": "#/components/schemas/GuestPortalReentryContextDto"
    }
  ],
  "example": {
    "hint": "gpr1_synthetic_recovery_context_example_not_a_runtime_credential_0000000000",
    "expiresAt": "2026-12-31T18:00:00.000Z"
  }
}
Full definition
{
  "type": "object",
  "properties": {
    "reentryContext": {
      "readOnly": true,
      "description": "Original bounded recovery target for the existing guest contact. Retain it privately and request and confirm a real code through the canonical Guest Portal reentry flow.",
      "allOf": [
        {
          "$ref": "#/components/schemas/GuestPortalReentryContextDto"
        }
      ],
      "example": {
        "hint": "gpr1_synthetic_recovery_context_example_not_a_runtime_credential_0000000000",
        "expiresAt": "2026-12-31T18:00:00.000Z"
      }
    }
  },
  "description": "Private contact-code target prepared from the guest-owned native reservation, waitlist or preorder. It grants no Portal access until the existing real OTP workflow succeeds.",
  "required": [
    "reentryContext"
  ],
  "example": {
    "reentryContext": {
      "hint": "gpr1_synthetic_recovery_context_example_not_a_runtime_credential_0000000000",
      "expiresAt": "2026-12-31T18:00:00.000Z"
    }
  }
}
GuestPortalReentryContextDto

Non-reading recovery context for the original existing guest contact and portal scope. An unverified candidate still requires successful OTP confirmation. The context permits only the targeted reentry workflow, never portal, inbox or push access.

hintRequired

Opaque authenticated recovery hint. Store only as a recovery target; it is not a Guest Portal continuation or a push grant.

string
Full definition
{
  "type": "string",
  "description": "Opaque authenticated recovery hint. Store only as a recovery target; it is not a Guest Portal continuation or a push grant.",
  "minLength": 64,
  "maxLength": 2048,
  "pattern": "^gpr1_[A-Za-z0-9_-]+$",
  "example": "gpr1_synthetic_recovery_context_example_not_a_runtime_credential_0000000000",
  "readOnly": true
}
expiresAtRequired

Absolute recovery-target expiry. Current guest, original contact and portal scope remain authoritative before every code request and confirmation.

string · date-time
Full definition
{
  "type": "string",
  "description": "Absolute recovery-target expiry. Current guest, original contact and portal scope remain authoritative before every code request and confirmation.",
  "format": "date-time",
  "readOnly": true,
  "example": "2026-12-31T18:00:00.000Z"
}
Full definition
{
  "type": "object",
  "properties": {
    "hint": {
      "type": "string",
      "description": "Opaque authenticated recovery hint. Store only as a recovery target; it is not a Guest Portal continuation or a push grant.",
      "minLength": 64,
      "maxLength": 2048,
      "pattern": "^gpr1_[A-Za-z0-9_-]+$",
      "example": "gpr1_synthetic_recovery_context_example_not_a_runtime_credential_0000000000",
      "readOnly": true
    },
    "expiresAt": {
      "type": "string",
      "description": "Absolute recovery-target expiry. Current guest, original contact and portal scope remain authoritative before every code request and confirmation.",
      "format": "date-time",
      "readOnly": true,
      "example": "2026-12-31T18:00:00.000Z"
    }
  },
  "description": "Non-reading recovery context for the original existing guest contact and portal scope. An unverified candidate still requires successful OTP confirmation. The context permits only the targeted reentry workflow, never portal, inbox or push access.",
  "required": [
    "hint",
    "expiresAt"
  ],
  "example": {
    "hint": "gpr1_synthetic_recovery_context_example_not_a_runtime_credential_0000000000",
    "expiresAt": "2026-12-31T18:00:00.000Z"
  }
}
TranslatedErrorDto

Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.

statusCodeRequired

HTTP status code repeated from the response.

integer
Full definition
{
  "type": "integer",
  "description": "HTTP status code repeated from the response.",
  "example": 400
}
errorRequired

Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.

string
Full definition
{
  "type": "string",
  "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
  "example": "errors.request.invalid"
}
codeRequired

Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions.

string
Full definition
{
  "type": "string",
  "example": "HTTP_BAD_REQUEST",
  "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
}
messageRequired

Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application.

string
Full definition
{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
}
translationKeyRequired

Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback.

string
Full definition
{
  "type": "string",
  "example": "errors:http.badRequest",
  "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full definition
{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}
validationErrorsOptional

Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.

array
Full definition
{
  "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/ValidationErrorDto"
  },
  "example": [
    {
      "field": "email",
      "translationKey": "validation:isEmail",
      "code": "isEmail",
      "message": "validation:isEmail"
    }
  ]
}
detailsOptional

Optional domain-specific blocker or validation details

oneOf
Full definition
{
  "description": "Optional domain-specific blocker or validation details",
  "oneOf": [
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "example": [
    "example"
  ]
}
Full definition
{
  "type": "object",
  "properties": {
    "statusCode": {
      "type": "integer",
      "description": "HTTP status code repeated from the response.",
      "example": 400
    },
    "error": {
      "type": "string",
      "description": "Translation key for the HTTP category, such as errors:http.conflict. The specific cause is identified by code and translationKey.",
      "example": "errors.request.invalid"
    },
    "code": {
      "type": "string",
      "example": "HTTP_BAD_REQUEST",
      "description": "Stable machine-readable domain code, or an HTTP_* fallback when no domain code is provided. Branch on this field and the HTTP status; localized wording never controls retries or business decisions."
    },
    "message": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Translation key, identical to translationKey. The API does not return localized display text. Resolve the key and translationValues in the consuming application."
    },
    "translationKey": {
      "type": "string",
      "example": "errors:http.badRequest",
      "description": "Canonical translation key, identical to message. Status-specific errors:http.* keys cover unspecified failures. Public keys and EN/RU explanations are listed in Developers; unknown keys require a localized client fallback."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    },
    "validationErrors": {
      "description": "Field validation failures with translation keys and stable validator codes. Submitted values and raw validator text are not included.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ValidationErrorDto"
      },
      "example": [
        {
          "field": "email",
          "translationKey": "validation:isEmail",
          "code": "isEmail",
          "message": "validation:isEmail"
        }
      ]
    },
    "details": {
      "description": "Optional domain-specific blocker or validation details",
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": [
            "example"
          ]
        },
        {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/JsonValue"
          },
          "example": {
            "exampleKey": "example"
          }
        }
      ],
      "example": [
        "example"
      ]
    }
  },
  "required": [
    "statusCode",
    "error",
    "code",
    "message",
    "translationKey"
  ],
  "description": "Stable error envelope emitted by the global HTTP exception boundary. Domain-specific machine data, when present, is nested under details.",
  "example": {
    "statusCode": 400,
    "error": "errors:http.badRequest",
    "code": "HTTP_BAD_REQUEST",
    "message": "errors:http.badRequest",
    "translationKey": "errors:http.badRequest"
  }
}
ValidationErrorDto

Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.

fieldRequired

Public field path. Nested properties and array indices are separated by dots.

string
Full definition
{
  "type": "string",
  "example": "email",
  "description": "Public field path. Nested properties and array indices are separated by dots."
}
translationKeyRequired

Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog.

string
Full definition
{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
}
codeRequired

Stable validator identifier for this field failure. Custom validators may define additional identifiers.

string
Full definition
{
  "type": "string",
  "example": "isEmail",
  "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
}
messageRequired

Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included.

string
Full definition
{
  "type": "string",
  "example": "validation:isEmail",
  "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
}
translationValuesOptional

Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.

object
Full definition
{
  "type": "object",
  "additionalProperties": {
    "oneOf": [
      {
        "type": "string",
        "example": "example"
      },
      {
        "type": "number",
        "example": 0
      },
      {
        "type": "boolean",
        "example": true
      }
    ],
    "example": "example"
  },
  "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
  "example": {
    "exampleKey": "example"
  }
}
Full definition
{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "example": "email",
      "description": "Public field path. Nested properties and array indices are separated by dots."
    },
    "translationKey": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key for this validator, identical to message. Resolve it using a client dictionary; see the public Developers error catalog."
    },
    "code": {
      "type": "string",
      "example": "isEmail",
      "description": "Stable validator identifier for this field failure. Custom validators may define additional identifiers."
    },
    "message": {
      "type": "string",
      "example": "validation:isEmail",
      "description": "Translation key describing this field validation failure, identical to translationKey. Submitted values and validator prose are not included."
    },
    "translationValues": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "string",
            "example": "example"
          },
          {
            "type": "number",
            "example": 0
          },
          {
            "type": "boolean",
            "example": true
          }
        ],
        "example": "example"
      },
      "description": "Optional scalar values for placeholders in the translation. Treat values as data, escape them when rendering, and never use them as translation options.",
      "example": {
        "exampleKey": "example"
      }
    }
  },
  "required": [
    "field",
    "translationKey",
    "code",
    "message"
  ],
  "description": "Field validation failure with a field path, stable validator code and a translation key. Human-readable text belongs to the consuming application.",
  "example": {
    "field": "email",
    "translationKey": "validation:isEmail",
    "code": "isEmail",
    "message": "validation:isEmail"
  }
}
JsonValue

Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.

Full definition
{
  "oneOf": [
    {
      "type": "string",
      "nullable": true,
      "example": "example"
    },
    {
      "type": "number",
      "example": 0
    },
    {
      "type": "boolean",
      "example": true
    },
    {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": [
        "example"
      ]
    },
    {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/JsonValue"
      },
      "example": {
        "exampleKey": "example"
      }
    }
  ],
  "description": "Recursively JSON-safe value used only where the owning contract intentionally allows free-form structured data.",
  "example": "example"
}
IdempotencyConflictError

Idempotency key is already in progress or was reused with a different payload.

Full definition
{
  "example": {
    "statusCode": 409,
    "error": "errors:http.conflict",
    "code": "IDEMPOTENCY_REQUEST_IN_PROGRESS",
    "message": "errors:idempotency.inProgress",
    "translationKey": "errors:idempotency.inProgress"
  },
  "allOf": [
    {
      "$ref": "#/components/schemas/TranslatedErrorDto"
    },
    {
      "type": "object",
      "required": [
        "code"
      ],
      "properties": {
        "statusCode": {
          "type": "integer",
          "enum": [
            409
          ],
          "description": "HTTP 409 conflict status.",
          "example": 409
        },
        "code": {
          "type": "string",
          "enum": [
            "IDEMPOTENCY_REQUEST_NOT_READY",
            "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH",
            "IDEMPOTENCY_REQUEST_IN_PROGRESS",
            "IDEMPOTENCY_SCOPE_INCOMPLETE"
          ],
          "description": "Allowed code for idempotency conflict error: IDEMPOTENCY_REQUEST_NOT_READY, IDEMPOTENCY_KEY_PAYLOAD_MISMATCH, IDEMPOTENCY_REQUEST_IN_PROGRESS, IDEMPOTENCY_SCOPE_INCOMPLETE.",
          "example": "IDEMPOTENCY_REQUEST_NOT_READY"
        }
      },
      "example": {
        "code": "IDEMPOTENCY_REQUEST_NOT_READY"
      }
    }
  ],
  "description": "Idempotency key is already in progress or was reused with a different payload."
}

Hallify uses essential cookies and optional analytics.

Essential cookies keep sign-in, locale, and theme preferences working. Analytics is off until you choose to allow it.