diff --git a/.changeset/contract-1-36.md b/.changeset/contract-1-36.md new file mode 100644 index 0000000..0b44633 --- /dev/null +++ b/.changeset/contract-1-36.md @@ -0,0 +1,20 @@ +--- +"@freeticket/cli": minor +--- + +Catch up with the B2B contract 1.36.0 (from 1.24.0). + +- **Lineup**: `ft artists search`, `ft events artists set|remove` and `ft events invitations list|resend|cancel`. `set` asks before removing anyone from the lineup or emailing `--invite` invitations, and prints `ARTIST_IDS_IGNORED` warnings. +- **Scheduling and presales**: `ft events schedule set|clear` and `ft presale-windows list|create|update|delete` (alias `presales`). +- **Box office and door**: `ft sales transfer`, `ft sales recipient set`, `ft sales abandon`, `ft sales intents` (checkout funnel), `ft tickets checkin-undo`, `ft event-dates courtesy-seats`, `ft event-dates access-close status|sign`, `ft reports live-attendance`, `ft master-qrs` (with `activate`/`deactivate`) and `ft ticket-templates` (with `instantiate`). +- **Access**: `ft events viewers list|add|remove`, `ft events validators list|add`, `ft staff access` (full replace, from flags or from `--data`, not both) and `ft staff resend-invite`. +- **Community**: `ft content-posts update|delete|pin|unpin`, `ft content-videos update|delete|publish|unpublish|set-series`, `ft content-series`, `ft content-lives create|update|delete|chat|reset-key`, `ft content-channels`, `ft content-meetups` (with `publish`, `cancel`, `rsvp`, `attendance`), `ft content-moderation`, `ft content-comments` and `ft content-members ban|unban`. +- **Workspace**: `ft products`, `ft organization update|analytics|profile`, `ft website get|set|publish|unpublish` and `ft merch catalog`. + +Confirmation: every operation the contract marks `x-ft-destructive` asks first, and so do `events viewers add`, `events validators add`, `events invitations resend`, `events artists set --invite`, `staff resend-invite`, `content-meetups publish`, `content-meetups rsvp`, `content-videos publish` (they email or notify people) and `website set` (a full replace). `--yes` skips the question; without a TTY they refuse. `content-moderation approve`, `tickets resend`, `content-posts create` and `products update` notify without asking, on purpose. Tests check that each gated command refuses without `--yes` and calls its operation with it, and that no `x-ft-destructive` operation of the contract is left without a gate. + +Master QR secrets: `ft master-qrs list` and `update` leave the secret `code` and `url` out, in the table and in `--json`, unless `--full`. `create` prints them, because you need them to print the QR. + +Flag validation: COP amounts, capacities and pages (`ticket-templates instantiate --price/--capacity`, `presale-windows --capacity`, `content-moderation --page`) take whole numbers only, `--limit` on `artists search` and `sales intents` an integer from 1 to 100, and `--active` (presale windows, `discounts list`) and `--attended` only `true` or `false`. `50.000`, `1,000`, `abc` or `yes` exit 1 before any request instead of being sent as 50, NaN/null or false. + +The buyer side of the merch store (place an order, look one up, pay it by card) and the buyer API (`/customer/*`) are left out on purpose: they need a buyer session or a Payment Brick token. diff --git a/README.md b/README.md index ca836f5..a1df0d8 100644 --- a/README.md +++ b/README.md @@ -95,15 +95,32 @@ ft sales list --status CONFIRMED --json | `ft events list` · `get ` | Workspace events (`--q` `--status` `--with-total`) | VIEWER | | `ft events create` · `update ` · `delete ` | Manage events (`--data `) | ADMIN | | `ft events publish ` · `cancel ` | Publish an event · cancel it and all its dates, keeping sales and tickets (no refunds; `--yes` skips the prompt) | ADMIN | +| `ft artists search ` | Find registered artists by name to get the ids a lineup takes (`--limit` `--cursor`) | VIEWER | +| `ft events artists set --artist ... [--invite ...]` | Replace the lineup, in order (unlisted artists are unlinked; asks before removing anyone or emailing `--invite` invitations, `--yes` skips it; ignored ids are shown as `ARTIST_IDS_IGNORED`) | ADMIN | +| `ft events artists remove ` | Unlink one artist (`--yes` skips the prompt) | ADMIN | +| `ft events invitations list ` · `resend ` · `cancel ` | Invitations sent to artists without an account: list, resend (renews 14 days, sends an email) and cancel; `resend` and `cancel` ask (`--yes`) | ADMIN | +| `ft events schedule set --publish-at ` \| `--sale-starts-at ` · `schedule clear ` | Schedule a DRAFT: publish later, or publish now and open sales later (exactly one flag) · cancel a pending `--publish-at` | ADMIN | +| `ft events viewers list ` · `add --email ` · `remove ` | Read-only viewers of an event's stats; `add` emails the link (and creates a VIEWER account if needed), both `add` and `remove` ask (`--yes`) | ADMIN | +| `ft events validators list ` · `add --name --email ` | Door staff of an event (additive; a new account gets an invitation email, so `add` asks, `--yes`) | ADMIN | | `ft event-dates list` · `create` · `update` · `delete` | Event dates | ADMIN | +| `ft event-dates courtesy-seats ` | Blocked seats of a numbered date that can be issued as courtesies | ADMIN | +| `ft event-dates access-close status ` · `sign ` | Live entry count · sign the access-close record (freezes the count and emails it; IRREVERSIBLE, `--yes`) | STAFF · ADMIN | +| `ft ticket-templates list` · `create` · `update ` · `delete ` · `instantiate --event-date [--name --price --capacity]` | Reusable ticket type templates; `instantiate` creates a ticket type on a date (`--price`/`--capacity` are whole numbers: `50000`, not `50.000`; `delete` asks, `--yes`) | ADMIN | +| `ft master-qrs list [--full]` · `create` · `update ` · `activate ` · `deactivate ` · `delete ` | Master box-office QRs. `code`/`url` are secret and never rotate: `list` and `update` leave them out, `--json` included, unless `--full`; `create` prints them (you need them to print the QR); `delete` asks, `--yes` | ADMIN | | `ft ticket-types list` · `get ` | Ticket types (`--event-date-id`) | VIEWER | | `ft ticket-types create` · `update ` · `delete ` | Manage ticket types (`--data `) | ADMIN | +| `ft presale-windows list ` · `create --plan --starts-at --ends-at [--capacity --active]` · `update ` · `delete ` | Membership presale windows (alias `presales`; one per plan; `--capacity` is a whole number or `none`, `--active` is `true`/`false`; `delete` asks, `--yes` skips) | ADMIN | | `ft sales list` · `get ` | Sales (filters: `--status` `--channel` `--event` `--event-date` `--reference` `--buyer` `--from` `--to`) | STAFF | | `ft sales create` | Create a sale/order — comps & programmatic sales (`--data `) | ADMIN | | `ft sales cancel ` · `refund ` | Cancel / refund a sale (`--data` for the `acknowledge_open_payment` / `acknowledge_manual` flags) | ADMIN | | `ft sales tickets ` · `attempts ` | Tickets/attendees of a sale · its payment attempt history (why it did not go through) | STAFF | +| `ft sales transfer --email ` | Transfer one ticket to a registered buyer; voids the old QR, once per ticket (`--yes`) | ADMIN | +| `ft sales recipient set --name --email ` | Correct a courtesy's recipient and resend (a new email voids the old QRs; `--yes`) | ADMIN | +| `ft sales abandon ` | Mark a PENDING sale whose payment never started as abandoned; releases its stock (terminal, `--yes`) | ADMIN | +| `ft sales intents --event [--event-date --only-abandoned --limit --cursor]` | Purchase intents: checkout funnel and abandoned journeys (personal data) | VIEWER | | `ft tickets access ` | Read a ticket's access status (no admit) | STAFF | | `ft tickets checkin ` | Admit a ticket at the door (idempotent) | STAFF | +| `ft tickets checkin-undo ` | Undo a check-in so the ticket is valid again (idempotent; `--yes`) | ADMIN | | `ft tickets resend ` | Resend the ticket's confirmation email (QR) | ADMIN | | `ft tickets reassign ` | Move a sold ticket to another date and/or type (`--data '{"eventDateId":"…"}'`; no price difference charged/refunded) | ADMIN | | `ft plans list` · `get ` | Membership plans | VIEWER | @@ -115,19 +132,38 @@ ft sales list --status CONFIRMED --json | `ft venues list` · `get ` | Venues | VIEWER | | `ft venues create` · `update ` · `delete ` | Manage venues (`--data `) | ADMIN | | `ft staff list` · `get ` · `create` · `set-role ` · `delete ` | Workspace staff (`--workspace-ids ` lists up to 25 workspaces in one call; `--data `) | ADMIN | +| `ft staff access --type admin\|validador\|personalizado\|lectura [--sections --validator-events --viewer-events --expires-at]` | FULL replace of a member's access in this workspace (or the whole body with `--data`, not both; asks, `--yes`) | ADMIN | +| `ft staff resend-invite ` | Email the invitation link again (asks, `--yes`) | ADMIN | | `ft reports summary` | KPIs (`--period 7d\|30d\|90d\|1y`) | VIEWER | | `ft reports by-event` · `timeseries` · `inventory` | Revenue/tickets by event, over time, and capacity/availability | VIEWER | | `ft reports export buyers\|attendees\|subscribers\|reconciliation` | Exports as CSV (filters `--event` `--event-date` `--from` `--to` `--status`) | ADMIN | | `ft reports reconciliation` · `financials` | CFO reconciliation (Mercado Pago vs sale vs Siigo invoice) · per-function P&L | ADMIN | +| `ft reports live-attendance [--scope all\|own\|partner:]` | Event dates happening right now, with check-in progress | VIEWER | | `ft settlements list` · `get ` · `document ` | Settlements paid to the organizer · signed download URL for the PDF, 5 min TTL (`--proof ` for a payment proof) | ADMIN | | `ft content-videos list` · `content-posts list\|create` · `content-lives list\|get\|playback-token` | Organization content; `content-posts create --data` publishes a post or article | ADMIN | +| `ft content-posts update ` · `delete ` · `pin ` · `unpin ` | Edit, delete (`--yes`) and pin community posts | ADMIN | +| `ft content-videos update ` · `delete ` · `publish ` · `unpublish ` · `set-series --series ` · `ft content-series list\|create\|update\|delete\|publish\|unpublish` | On-demand videos and video series (deletes and video `publish`, which notifies members, ask, `--yes`) | ADMIN | +| `ft content-lives create` · `update ` · `delete ` · `chat ` · `reset-key ` | Live streams: `create` and `reset-key` print the SECRET stream key once; `delete` and `reset-key` ask (`--yes`) | ADMIN | +| `ft content-channels list` · `create` · `update ` · `order ` · `archive ` | Community channels (`archive` has no undo, `--yes`) | ADMIN | +| `ft content-meetups list` · `get` · `create` · `update` · `publish ` · `cancel ` · `rsvp --approve\|--reject` · `attendance ` | Community meetups; `publish`, `cancel` and `rsvp` notify members, so they ask (`--yes`); `attendance --attended true\|false` | ADMIN | +| `ft content-moderation queue\|bans\|member-posts` · `approve --expected-updated-at ` · `reject ` · `remove ` · `ft content-comments hide\|unhide\|ignore-reports\|delete ` · `ft content-members ban --comment ` · `unban ` | Community moderation (`reject`, `remove`, `delete` and `ban` ask, `--yes`; `approve` does not: it is the reviewer's decision and is pinned to `--expected-updated-at`) | STAFF · ADMIN | +| `ft products list` · `get` · `create` · `update` · `delete` · `status --status DRAFT\|PUBLISHED` | Digital products and courses (`--data `; `delete` asks) | ADMIN | +| `ft organization update --data` · `analytics ` · `profile get\|update` · `ft website get\|set --data\|publish\|unpublish` | Workspace identity, profile, GA4 and public website (`website set` is a FULL replace, so it asks, `--yes`: start from `website get --json`) | ADMIN | +| `ft merch catalog` | Merch store settings and published products with live stock (needs an enterprise service key) | — | | `ft waitlist list [--city ]` · `waitlist create --data` | Per-city waitlist of an enterprise landing (export with personal data); `create` needs an enterprise service key | ADMIN | | `ft api-keys create ` · `list` · `revoke ` | Self-service API keys (the secret is shown once, never stored) | ADMIN | | `ft admin login` · `me` · `workspaces` · `users` · `plans` · `feature-flags` · `tokens` · `audit-log` | Superadmin, cross-tenant — needs a SUPER_ADMIN session, not an API key. Includes `admin workspaces plan ` (assisted plan assignment), `plan-show ` (current plan) and `delete ` (soft delete; suspend first) and `webTemplate` / `customDomain` on `update` | SUPER_ADMIN | > **Write operations** (`create`/`update`/`delete` and actions like `publish`, > `cancel`, `refund`) send a JSON body via `--data ` or -> `--data @file.json`. `delete` prompts for confirmation unless you pass `--yes`. +> `--data @file.json`. `delete` prompts for confirmation unless you pass `--yes`, and so do the +> commands that cannot be taken back or that email or notify people (each +> row says which). Without a TTY and without `--yes` they exit 1 before any +> write. Four notify without asking, on purpose: `tickets resend`, +> `content-posts create`, `products update` and `content-moderation approve`. +> Numeric flags take whole numbers only (`50000`, never +> `50.000` or `50,000`) and boolean flags only `true`/`false`: anything else +> exits 1 before any request. ### Common flags diff --git a/openapi.json b/openapi.json index 6c277ee..3592449 100644 --- a/openapi.json +++ b/openapi.json @@ -2,7 +2,7 @@ "openapi": "3.1.0", "info": { "title": "FreeTicket B2B API", - "version": "1.24.0", + "version": "1.36.0", "description": "FreeTicket B2B REST API for integrations, the `ft` CLI and the FreeTicket MCP server. Authentication is by API key (`Authorization: Bearer ` header or `x-api-key`); the active workspace is selected with the `X-Workspace-Id` header.\n\nScopes: each key is either `read` (GET/HEAD only) or `write` (additionally creates, edits, deletes, cancels, refunds and checks in). Self-service keys are issued as `read`. A `read` key calling a mutating method gets a 403. The machine-readable declaration lives at `/.well-known/oauth-protected-resource` (RFC 9728).\n\nGetting a key (self-serve, no sales contact): `ft login` runs the Device Authorization Grant (RFC 8628, `POST /auth/device/code` + `POST /auth/device/token`); the user approves the code at https://admin.appfreeticket.com/device and the CLI receives a key. New organizers can bootstrap headless with `POST /auth/signup` (verify-first, then `ft login`). With a key, `POST /api-keys` mints more (born `read` unless `write` is requested). There is no sandbox environment: test against a dedicated workspace with `read` keys.\n\n## Versioning and deprecation\n\n- **Path version.** The B2B API is versioned in the path (`/api/v1`). A breaking change ships under a new path (`/api/v2`); the previous version keeps running in parallel until its sunset date.\n- **Contract version.** `info.version` is the semantic version of this document. MINOR = additive (new endpoints, new optional fields, new enum values, new error codes; clients must ignore unknown fields). PATCH = documentation or fixes that do not change shapes. The public API (`/api/public`) is pre-1.0 and not versioned in the path: there, a MINOR bump may include a breaking change and PATCH never does.\n- **Deprecation signals.** A deprecated operation is marked `deprecated: true` in this document and its responses carry `Deprecation` (RFC 9745, e.g. `Deprecation: @1767225600`), `Sunset` (RFC 8594, an HTTP-date after which the operation may stop working) and `Link: ; rel=\"deprecation\"`.\n- **Timeline.** At least 6 months between the first `Deprecation` header and the `Sunset` date for `/api/v1`, and at least 90 days for `/api/public`. A path version is only retired after all its operations have sunset.\n- **Current status.** No operation is deprecated today.\n\n## Rate limits\n\n- **429 always carries `Retry-After`** (seconds). Wait at least that long before retrying the same request. The JSON error envelope comes with `error.retryable: true`; most rate-limited responses use `error.code: \"RATE_LIMITED\"`, and some return a more specific code (for example `TOO_MANY_REQUESTS` or `SEAT_BUDGET_EXHAUSTED`).\n- **RateLimit headers are sent where listed below.** Those endpoints answer every response, success or error, with the IETF RateLimit headers (draft-ietf-httpapi-ratelimit-headers): `RateLimit-Policy: \"\";q=;w=` and `RateLimit: \"\";r=;t=`. Other endpoints may answer 429 without them.\n- Counters are fixed windows kept per server instance: treat the numbers as pacing hints, not as a global account quota.\n\nEndpoints that send RateLimit headers today: `POST /auth/signup` (per client IP), `POST /customer/auth/request` and `POST /customer/auth/verify` (per client IP), and the buyer-session endpoints `GET /customer/orders/{id}`, `POST /customer/orders/{id}/payment`, `/payment/card`, `/payment/pse`, `/release`, `POST /customer/purchase-sessions` and `POST /customer/purchase-sessions/{id}/release`." }, "servers": [ @@ -19,85 +19,124 @@ } ], "paths": { - "/events/{id}/dates": { - "get": { - "operationId": "getEventsIdDates", + "/auth/device/code": { + "post": { + "operationId": "postAuthDeviceCode", "tags": [ - "events" + "auth" ], - "summary": "List an event's dates", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", - "security": [ - { - "apiKey": [] + "summary": "Start the Device Authorization Grant (RFC 8628)", + "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", + "security": [], + "responses": { + "200": { + "description": "Flow started: device_code (polled by the CLI) + user_code (approved by the user in the browser).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeviceCodeResponse" + } + } + } }, - { - "apiKeyHeader": [] - } - ], - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" + "429": { + "description": "Too many requests from the same IP (anti-flood).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } } }, - { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", - "schema": { - "type": "string" + "503": { + "description": "Could not generate a unique device_code/user_code after retrying (persistent collision).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } } } + } + } + }, + "/auth/device/token": { + "post": { + "operationId": "postAuthDeviceToken", + "tags": [ + "auth" ], + "summary": "CLI poll: exchanges the device_code for an API key once approved", + "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", + "security": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeviceTokenRequest" + } + } + } + }, "responses": { "200": { - "description": "OK", + "description": "Approved: delivers the ft_live_… API key exactly once and consumes the row.", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EventDate" - } - } - }, - "required": [ - "data" - ] + "$ref": "#/components/schemas/DeviceTokenResponse" } } } }, - "401": { - "description": "Missing or invalid credential.", + "400": { + "description": "RFC 8628 status: authorization_pending | slow_down | expired_token | access_denied | invalid_request.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/DeviceTokenError" } } } - }, - "403": { - "description": "Insufficient role or resource not accessible.", + } + } + } + }, + "/auth/signup": { + "post": { + "operationId": "postAuthSignup", + "tags": [ + "auth" + ], + "summary": "Headless sign-up: creates the unverified account and sends the email", + "description": "Public (no auth). Verify-first: no credential is issued. The optional `workspaceName` creates the first tenant in the same step (on the free Spark plan). Rate-limited per IP and per email.", + "security": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SignupRequest" + } + } + } + }, + "responses": { + "202": { + "description": "Account pending verification (or already existing: same shape, no enumeration). The email sent is used to verify AND set a password — it reuses the staff invitation (src/lib/staff-invite.ts). With that, the user can approve an `ft login` (Device Grant) from their browser.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/SignupResponse" } } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "422": { + "description": "Invalid body (email, name or workspaceName).", "content": { "application/json": { "schema": { @@ -106,8 +145,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "429": { + "description": "Too many attempts from the same IP or the same email.", "content": { "application/json": { "schema": { @@ -117,14 +156,16 @@ } } } - }, + } + }, + "/workspaces": { "post": { - "operationId": "postEventsIdDates", + "operationId": "postWorkspaces", "tags": [ - "events" + "me" ], - "summary": "Add a date to an event", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Create your own workspace/tenant (self-serve)", + "description": "Requires a valid API key — does NOT require an active workspace (`X-Workspace-Id` does not apply here: it is ignored if sent). The caller becomes ADMIN of the new workspace. If they already administer their own Organization (umbrella), another workspace is added there, subject to the plan quota (spark=1, star=3, icon=7); if they have no link at all, a new Organization is created on the free Spark plan. A user who is already a collaborator (staff) of someone else's workspace gets 409 `ALREADY_HAS_ACCESS`: ask an administrator to add them, instead of creating a tenant that would override their current access.", "security": [ { "apiKey": [] @@ -134,14 +175,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -157,7 +190,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EventDateCreate" + "$ref": "#/components/schemas/WorkspaceCreate" } } } @@ -171,7 +204,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EventDate" + "$ref": "#/components/schemas/WorkspaceAccess" } }, "required": [ @@ -211,8 +244,18 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -224,15 +267,14 @@ } } }, - "/customer/orders": { + "/me": { "get": { - "operationId": "getCustomerOrders", + "operationId": "getMe", "tags": [ - "customer", - "orders" + "me" ], - "summary": "The purchase the buyer left unfinished for this event date", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, results are additionally scoped to the workspace pinned to it; without a key, any of the buyer's own unfinished purchases is visible. Returns the PENDING sale whose inventory hold is STILL ALIVE that the buyer has for that event date —with its seats, its total and when it expires—, or `order: null` if there is none. This is what lets reloading the checkout, or coming back from signing in, RESUME the purchase instead of starting from scratch: the seats remain held in that person's name. If `paymentOpened` is true the payment is already open and `POST /customer/orders/{id}/payment` returns the SAME signed configuration; to discard it and pick other seats, use `POST /customer/orders/{id}/release`.", + "summary": "Authenticated user, role and accessible workspaces", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. `activeWorkspaceId` is `null` and `workspaces` is `[]` when the credential is valid but the user does not have any workspace yet (just registered via POST /auth/signup, before POST /workspaces).", "security": [ { "apiKey": [] @@ -242,15 +284,6 @@ } ], "parameters": [ - { - "name": "eventDateId", - "in": "query", - "required": false, - "description": "Required. The event date being queried.", - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -270,7 +303,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderCurrent" + "$ref": "#/components/schemas/Me" } }, "required": [ @@ -311,7 +344,7 @@ } }, "422": { - "description": "Operation error.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -321,15 +354,16 @@ } } } - }, - "post": { - "operationId": "postCustomerOrders", + } + }, + "/events": { + "get": { + "operationId": "getEvents", "tags": [ - "customer", - "orders" + "events" ], - "summary": "Create the ticket reservation (step 1 of the headless purchase)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the date and the ticket type must belong to the workspace pinned to it (anything else is 404); without a key, it is enough for the ticket type to exist and be on sale (same eligibility as the first-party checkout). Reserves inventory and creates the PENDING sale with the SAME rules as the first-party checkout (stock under lock, seats validated against seats.io, per-buyer limit, presale, memberships and virtual queue turn). The buyer email comes from the session, never from the body. Rejections carry a stable `reason` in `error.details.reason` (`sold_out`, `queue_turn_required`, `seats_not_held`, `members_only`, `members_only_withdrawn` — a members-only ticket whose artist withdrew the permission or left the lineup: it is no longer sold even to members —, …). With `pending_sale_in_progress` the inventory is taken by a half-paid purchase FROM THE SAME buyer: `error.details.pendingSaleId` and `pendingReference` identify it, and the right step is to reopen its payment with `POST /customer/orders/{pendingSaleId}/payment` (idempotent) instead of reserving again. If `free` is true the sale is already confirmed and `/payment` must NOT be called. Next step: `POST /customer/orders/{id}/payment`.", + "summary": "List workspace events", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Each event embeds `nextDate` (its next upcoming date, or null) and `artists` (the linked lineup, in the organizer's order), so rendering a catalog doesn't require `/events/{id}/dates` or one request per artist.", "security": [ { "apiKey": [] @@ -340,48 +374,95 @@ ], "parameters": [ { - "name": "X-Workspace-Id", - "in": "header", + "name": "limit", + "in": "query", "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "description": "1-100, default 20", "schema": { - "type": "string" + "type": "integer", + "default": 20 } }, { - "name": "X-Purchase-Session", - "in": "header", + "name": "cursor", + "in": "query", "required": false, - "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "description": "id of the last result from the previous page", "schema": { "type": "string" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerOrderCreateRequest" - } + }, + { + "name": "q", + "in": "query", + "required": false, + "description": "Search by name/description, case- and accent-insensitive", + "schema": { + "type": "string" } - } - }, - "responses": { - "201": { - "description": "OK", - "content": { - "application/json": { - "schema": { + }, + { + "name": "status", + "in": "query", + "required": false, + "description": "Filter by status (DRAFT | PUBLISHED | SOLD_OUT | CANCELLED | COMPLETED). Applied in the query, so `limit` only counts returned rows.", + "schema": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "SOLD_OUT", + "CANCELLED", + "COMPLETED" + ] + } + }, + { + "name": "withTotal", + "in": "query", + "required": false, + "description": "`1` to include `page.total` (count over the same filter). Opt-in: without it, the extra query is skipped.", + "schema": { + "type": "boolean" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderCreateResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/Event" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } } }, "required": [ - "data" + "data", + "page" ] } } @@ -417,16 +498,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -436,50 +507,16 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } - } - }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } - } - }, - "/customer/purchase-sessions/{id}": { - "get": { - "operationId": "getCustomerPurchaseSessionsId", + }, + "post": { + "operationId": "postEvents", "tags": [ - "customer", - "purchase-sessions" + "events" ], - "summary": "Purchase session status", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Returns the status of one of THE buyer's purchase sessions: `live` (this tab can create the order), `superseded` (another tab or device replaced it: stop offering the map and the payment), `expired` (the map clock ran out or it was released) or `converted` (it already created its order: `orderId`). A session whose `seatsDeadline` has passed is reported as `expired` immediately. Designed to be polled every ~10 s. Another buyer's session is 404.", + "summary": "Create an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -489,14 +526,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -507,8 +536,18 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -516,7 +555,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionStatus" + "$ref": "#/components/schemas/Event" } }, "required": [ @@ -556,6 +595,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -569,14 +618,14 @@ } } }, - "/events": { + "/events/{id}": { "get": { - "operationId": "getEvents", + "operationId": "getEventsId", "tags": [ "events" ], - "summary": "List workspace events", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Each event embeds `nextDate` (its next upcoming date, or null) and `artists` (the linked lineup, in the organizer's order), so rendering a catalog doesn't require `/events/{id}/dates` or one request per artist.", + "summary": "Get an event", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -587,58 +636,13 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, - "description": "id of the last result from the previous page", - "schema": { - "type": "string" - } - }, - { - "name": "q", - "in": "query", - "required": false, - "description": "Search by name/description, case- and accent-insensitive", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, - { - "name": "status", - "in": "query", - "required": false, - "description": "Filter by status (DRAFT | PUBLISHED | SOLD_OUT | CANCELLED | COMPLETED). Applied in the query, so `limit` only counts returned rows.", - "schema": { - "type": "string", - "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" - ] - } - }, - { - "name": "withTotal", - "in": "query", - "required": false, - "description": "`1` to include `page.total` (count over the same filter). Opt-in: without it, the extra query is skipped.", - "schema": { - "type": "boolean" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -658,24 +662,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Event" - } - }, - "page": { - "$ref": "#/components/schemas/Page" - }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" - } + "$ref": "#/components/schemas/Event" } }, "required": [ - "data", - "page" + "data" ] } } @@ -723,13 +714,13 @@ } } }, - "post": { - "operationId": "postEvents", + "patch": { + "operationId": "patchEventsId", "tags": [ "events" ], - "summary": "Create an event", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Update an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nAbsent fields are left untouched. Errors (`error.code`): 409 `SLUG_TAKEN`; 422 `PULEP_REQUIRED` (only evaluated when the request changes `genre` or `pulepCode`); 422 `GENRE_OTHER_WITHOUT_OTRO` (`genreOther` sent without `genre` while the stored genre is not \"otro\"); 422 `CLASSIFICATION_CONFLICT` (the resulting genre + audience, merged with the stored values, are incompatible, e.g. \"familiar\" with an 18+ audience). `genre`/`subgenre`/`audience` are validated against the stored classification (422 `CLASSIFICATION_CONFLICT`) and then saved as manual classification facets on a best-effort basis. Publication status, the external ticketing URL and the artist lineup have their own endpoints.", "security": [ { "apiKey": [] @@ -739,6 +730,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -754,13 +753,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EventCreate" + "$ref": "#/components/schemas/EventUpdate" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -829,30 +828,54 @@ } } } - } - }, - "/auth/device/code": { - "post": { - "operationId": "postAuthDeviceCode", + }, + "delete": { + "operationId": "deleteEventsId", "tags": [ - "auth" + "events" ], - "summary": "Start the Device Authorization Grant (RFC 8628)", - "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", - "security": [], - "responses": { + "summary": "Delete an event (soft delete)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nReturns 409 `EVENT_HAS_SALES` when the event has CONFIRMED or REFUNDED sales; cancel it with `POST /events/{id}/cancel` instead.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { "200": { - "description": "Flow started: device_code (polled by the CLI) + user_code (approved by the user in the browser).", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeviceCodeResponse" + "type": "object" } } } }, - "429": { - "description": "Too many requests from the same IP (anti-flood).", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -861,8 +884,8 @@ } } }, - "503": { - "description": "Could not generate a unique device_code/user_code after retrying (persistent collision).", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -870,85 +893,19 @@ } } } - } - } - } - }, - "/auth/device/token": { - "post": { - "operationId": "postAuthDeviceToken", - "tags": [ - "auth" - ], - "summary": "CLI poll: exchanges the device_code for an API key once approved", - "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", - "security": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeviceTokenRequest" - } - } - } - }, - "responses": { - "200": { - "description": "Approved: delivers the ft_live_… API key exactly once and consumes the row.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeviceTokenResponse" - } - } - } }, - "400": { - "description": "RFC 8628 status: authorization_pending | slow_down | expired_token | access_denied | invalid_request.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DeviceTokenError" - } - } - } - } - } - } - }, - "/auth/signup": { - "post": { - "operationId": "postAuthSignup", - "tags": [ - "auth" - ], - "summary": "Headless sign-up: creates the unverified account and sends the email", - "description": "Public (no auth). Verify-first: no credential is issued. The optional `workspaceName` creates the first tenant in the same step (on the free Spark plan). Rate-limited per IP and per email.", - "security": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SignupRequest" - } - } - } - }, - "responses": { - "202": { - "description": "Account pending verification (or already existing: same shape, no enumeration). The email sent is used to verify AND set a password — it reuses the staff invitation (src/lib/staff-invite.ts). With that, the user can approve an `ft login` (Device Grant) from their browser.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SignupResponse" + "$ref": "#/components/schemas/Error" } } } }, - "422": { - "description": "Invalid body (email, name or workspaceName).", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -957,8 +914,8 @@ } } }, - "429": { - "description": "Too many attempts from the same IP or the same email.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -970,14 +927,14 @@ } } }, - "/workspaces": { + "/events/{id}/publish": { "post": { - "operationId": "postWorkspaces", + "operationId": "postEventsIdPublish", "tags": [ - "me" + "events" ], - "summary": "Create your own workspace/tenant (self-serve)", - "description": "Requires a valid API key — does NOT require an active workspace (`X-Workspace-Id` does not apply here: it is ignored if sent). The caller becomes ADMIN of the new workspace. If they already administer their own Organization (umbrella), another workspace is added there, subject to the plan quota (spark=1, star=3, icon=7); if they have no link at all, a new Organization is created on the free Spark plan. A user who is already a collaborator (staff) of someone else's workspace gets 409 `ALREADY_HAS_ACCESS`: ask an administrator to add them, instead of creating a tenant that would override their current access.", + "summary": "Publish an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nPublishes the event and its dates (cancelled dates stay cancelled unless the whole event was `CANCELLED`). Requires at least one future date (409 `CONFLICT`).\n\nSeated (seats.io) events are validated first:\n- 409 `SEATSIO_INVALID`: a seated date has no ticket type mapped to a chart category, or maps a category missing from the chart.\n- 409 `SEAT_MAP_CATEGORIES_UNCOVERED`: a chart category with seats on sale has no ticket type on that date and is not fully blocked (booked). `error.details.zones[]` lists each one (`dateLabel`, `categoryKey`, `categoryLabel`, `seats`). Create its ticket type or block those seats, then retry.\n- 503 `SEAT_MAP_UNVERIFIABLE` (retryable): seats.io could not be reached to verify the map.\n\nPaid events (any ticket type with price > 0) require the workspace identity verification to be approved:\n- 409 `IDENTITY_VERIFICATION_REQUIRED`: the event stays `DRAFT` and is queued; it publishes automatically within ~5 minutes of the verification being approved.", "security": [ { "apiKey": [] @@ -987,6 +944,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -997,18 +962,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/WorkspaceCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -1016,7 +971,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/WorkspaceAccess" + "$ref": "#/components/schemas/Event" } }, "required": [ @@ -1067,7 +1022,17 @@ } }, "422": { - "description": "Operation error.", + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", "content": { "application/json": { "schema": { @@ -1079,14 +1044,14 @@ } } }, - "/me": { - "get": { - "operationId": "getMe", + "/events/{id}/cancel": { + "post": { + "operationId": "postEventsIdCancel", "tags": [ - "me" + "events" ], - "summary": "Authenticated user, role and accessible workspaces", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. `activeWorkspaceId` is `null` and `workspaces` is `[]` when the credential is valid but the user does not have any workspace yet (just registered via POST /auth/signup, before POST /workspaces).", + "summary": "Cancel an event (keeps the record and its sales)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nSets the event and ALL its dates to `CANCELLED` and turns off the waiting room. Unlike `DELETE /events/{id}`, it PRESERVES the record: sales, issued tickets and the audit trail for refunds remain. Idempotent: cancelling an already-cancelled event returns 200 with no changes. Does not trigger refunds — use `POST /sales/{id}/refund` for that.", "security": [ { "apiKey": [] @@ -1096,6 +1061,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -1115,7 +1088,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Me" + "$ref": "#/components/schemas/Event" } }, "required": [ @@ -1168,13 +1141,13 @@ } } }, - "/events/{id}": { + "/events/{id}/dates": { "get": { - "operationId": "getEventsId", + "operationId": "getEventsIdDates", "tags": [ "events" ], - "summary": "Get an event", + "summary": "List an event's dates", "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -1212,7 +1185,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Event" + "type": "array", + "items": { + "$ref": "#/components/schemas/EventDate" + } } }, "required": [ @@ -1264,12 +1240,12 @@ } } }, - "patch": { - "operationId": "patchEventsId", + "post": { + "operationId": "postEventsIdDates", "tags": [ "events" ], - "summary": "Update an event", + "summary": "Add a date to an event", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -1303,13 +1279,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EventUpdate" + "$ref": "#/components/schemas/EventDateCreate" } } } }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -1317,7 +1293,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Event" + "$ref": "#/components/schemas/EventDate" } }, "required": [ @@ -1368,14 +1344,16 @@ } } } - }, - "delete": { - "operationId": "deleteEventsId", + } + }, + "/events/{id}/dates/{dateId}": { + "patch": { + "operationId": "patchEventsIdDatesDateId", "tags": [ "events" ], - "summary": "Delete an event (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nReturns 409 `EVENT_HAS_SALES` when the event has CONFIRMED or REFUNDED sales; cancel it with `POST /events/{id}/cancel` instead.", + "summary": "Update an event date", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -1393,6 +1371,14 @@ "type": "string" } }, + { + "name": "dateId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -1403,13 +1389,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventDateUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EventDate" + } + }, + "required": [ + "data" + ] } } } @@ -1444,18 +1448,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "422": { - "description": "Request body/parameter validation failed.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -1465,16 +1459,14 @@ } } } - } - }, - "/events/{id}/publish": { - "post": { - "operationId": "postEventsIdPublish", + }, + "delete": { + "operationId": "deleteEventsIdDatesDateId", "tags": [ "events" ], - "summary": "Publish an event", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nPublishes the event and its dates (cancelled dates stay cancelled unless the whole event was `CANCELLED`). Requires at least one future date (409 `CONFLICT`).\n\nSeated (seats.io) events are validated first:\n- 409 `SEATSIO_INVALID`: a seated date has no ticket type mapped to a chart category, or maps a category missing from the chart.\n- 409 `SEAT_MAP_CATEGORIES_UNCOVERED`: a chart category with seats on sale has no ticket type on that date and is not fully blocked (booked). `error.details.zones[]` lists each one (`dateLabel`, `categoryKey`, `categoryLabel`, `seats`). Create its ticket type or block those seats, then retry.\n- 503 `SEAT_MAP_UNVERIFIABLE` (retryable): seats.io could not be reached to verify the map.\n\nPaid events (any ticket type with price > 0) require the workspace identity verification to be approved:\n- 409 `IDENTITY_VERIFICATION_REQUIRED`: the event stays `DRAFT` and is queued; it publishes automatically within ~5 minutes of the verification being approved.", + "summary": "Delete an event date", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -1492,6 +1484,14 @@ "type": "string" } }, + { + "name": "dateId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -1508,15 +1508,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Event" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -1570,28 +1562,18 @@ } } } - }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } } }, - "/events/{id}/cancel": { - "post": { - "operationId": "postEventsIdCancel", + "/events/{id}/artists": { + "put": { + "operationId": "putEventsIdArtists", "tags": [ "events" ], - "summary": "Cancel an event (keeps the record and its sales)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nSets the event and ALL its dates to `CANCELLED` and turns off the waiting room. Unlike `DELETE /events/{id}`, it PRESERVES the record: sales, issued tickets and the audit trail for refunds remain. Idempotent: cancelling an already-cancelled event returns 200 with no changes. Does not trigger refunds — use `POST /sales/{id}/refund` for that.", + "summary": "Replace the event lineup", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nReplaces the artists linked to the event with `artistIds`, in that order (the lineup order). Artists not in the list are unlinked (send the full lineup, not a diff); `[]` clears it. Ids come from `GET /artists?q=` (workspace ids of registered artists). Newly linked artists get a notification email.\n\n`inviteEmails` invites artists without an account: each email gets an invitation (only once per email and event) and is linked when it signs up. `inviteEmails` is additive: omitting it does not cancel existing invitations (use `DELETE /events/{id}/artist-invitations/{invitationId}`).\n\nIds that are not a registered artist (or the event's own workspace) are skipped and reported in `warnings[]` with code `ARTIST_IDS_IGNORED` (`ids`).\n\nLimits: up to 50 `artistIds` and 20 `inviteEmails` per request; 20 lineup changes per hour per API key and event (429 `RATE_LIMITED` with `Retry-After`).", "security": [ { "apiKey": [] @@ -1619,6 +1601,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventArtistsReplace" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -1629,6 +1621,12 @@ "properties": { "data": { "$ref": "#/components/schemas/Event" + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } } }, "required": [ @@ -1677,18 +1675,39 @@ } } } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } } } } }, - "/events/{id}/dates/{dateId}": { - "patch": { - "operationId": "patchEventsIdDatesDateId", + "/events/{id}/artists/{organizationId}": { + "delete": { + "operationId": "deleteEventsIdArtistsOrganizationId", "tags": [ "events" ], - "summary": "Update an event date", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Unlink an artist from an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nRemoves one artist from the event lineup. Allowed for the workspace that owns the event, or for the artist itself (`organizationId` equal to the active workspace) to remove itself from an event it was linked to. 404 `EVENT_NOT_FOUND` when the event is not owned by the workspace; 404 `ARTIST_NOT_LINKED` when the artist is not in its lineup (when unlinking itself, the artist always gets `ARTIST_NOT_LINKED`).", "security": [ { "apiKey": [] @@ -1707,7 +1726,7 @@ } }, { - "name": "dateId", + "name": "organizationId", "in": "path", "required": true, "schema": { @@ -1724,16 +1743,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EventDateUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -1743,7 +1752,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/EventDate" + "$ref": "#/components/schemas/EventArtistUnlink" } }, "required": [ @@ -1794,14 +1803,16 @@ } } } - }, - "delete": { - "operationId": "deleteEventsIdDatesDateId", + } + }, + "/events/{id}/artist-invitations": { + "get": { + "operationId": "getEventsIdArtistInvitations", "tags": [ "events" ], - "summary": "Delete an event date", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List artist invitations of an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nPending and expired invitations sent to artists without an account (via `inviteEmails` in `PUT /events/{id}/artists`), newest first. Accepted invitations are not listed: they are already linked artists. Invitations expire 14 days after being sent.", "security": [ { "apiKey": [] @@ -1819,14 +1830,6 @@ "type": "string" } }, - { - "name": "dateId", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -1843,7 +1846,18 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtistInvitation" + } + } + }, + "required": [ + "data" + ] } } } @@ -1878,16 +1892,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -1901,14 +1905,14 @@ } } }, - "/ticket-types": { - "get": { - "operationId": "getTicketTypes", + "/events/{id}/artist-invitations/{invitationId}": { + "delete": { + "operationId": "deleteEventsIdArtistInvitationsInvitationId", "tags": [ - "ticket-types" + "events" ], - "summary": "List workspace ticket types", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Cancel an artist invitation", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nCancels a pending or expired invitation; its link stops working. 409 `INVITATION_ACCEPTED` when the artist already accepted it (unlink the artist with `DELETE /events/{id}/artists/{organizationId}` instead).", "security": [ { "apiKey": [] @@ -1919,28 +1923,17 @@ ], "parameters": [ { - "name": "eventDateId", - "in": "query", - "required": false, - "description": "filter by event date", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "invitationId", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -1964,18 +1957,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TicketType" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/ArtistInvitationDeleted" } }, "required": [ - "data", - "page" + "data" ] } } @@ -2011,6 +1997,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -2022,14 +2018,16 @@ } } } - }, + } + }, + "/events/{id}/artist-invitations/{invitationId}/resend": { "post": { - "operationId": "postTicketTypes", + "operationId": "postEventsIdArtistInvitationsInvitationIdResend", "tags": [ - "ticket-types" + "events" ], - "summary": "Create a ticket type", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Resend an artist invitation", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nResends the invitation email and renews its expiry to 14 days from now (status back to `PENDING`, same link). Works on expired invitations too. 409 `INVITATION_ACCEPTED` when already accepted. 502 `EMAIL_NOT_SENT` when the email provider failed (the expiry was renewed; retry). Rate limited: 3 resends per hour per API key and invitation (429 `RATE_LIMITED` with `Retry-After`).", "security": [ { "apiKey": [] @@ -2039,6 +2037,22 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "invitationId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -2049,18 +2063,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TicketTypeCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -2068,7 +2072,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketType" + "$ref": "#/components/schemas/ArtistInvitation" } }, "required": [ @@ -2108,6 +2112,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -2117,20 +2131,51 @@ } } } - } - } - } - }, - "/ticket-types/{id}": { - "get": { - "operationId": "getTicketTypesId", - "tags": [ - "ticket-types" - ], - "summary": "Get a ticket type", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", - "security": [ - { + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/artists": { + "get": { + "operationId": "getArtists", + "tags": [ + "artists" + ], + "summary": "Search registered artists", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.\n\nSearches artist workspaces registered on FreeTicket by name (case-insensitive, `q` of 2+ characters). Returns public brand data only. Use the `id` in `PUT /events/{id}/artists`; for artists without an account use `inviteEmails` there.", + "security": [ + { "apiKey": [] }, { @@ -2139,9 +2184,28 @@ ], "parameters": [ { - "name": "id", - "in": "path", + "name": "q", + "in": "query", "required": true, + "description": "Name to search, 2-100 characters", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, "schema": { "type": "string" } @@ -2165,11 +2229,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketType" + "type": "array", + "items": { + "$ref": "#/components/schemas/ArtistSummary" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -2216,14 +2287,16 @@ } } } - }, - "patch": { - "operationId": "patchTicketTypesId", + } + }, + "/events/{id}/viewers": { + "get": { + "operationId": "getEventsIdViewers", "tags": [ - "ticket-types" + "events" ], - "summary": "Update a ticket type", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List read-only viewers of an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nPeople with read-only access to this event's statistics (they see only `/stats`, nothing else of the workspace), newest first. Only events owned by the active workspace (an event where the workspace is just a linked artist is 404). A key restricted by `event_scope` gets 403 `EVENT_SCOPE_FORBIDDEN` for events outside its scope.", "security": [ { "apiKey": [] @@ -2251,16 +2324,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TicketTypeUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -2270,7 +2333,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketType" + "type": "array", + "items": { + "$ref": "#/components/schemas/EventViewer" + } } }, "required": [ @@ -2310,16 +2376,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -2332,13 +2388,13 @@ } } }, - "delete": { - "operationId": "deleteTicketTypesId", + "post": { + "operationId": "postEventsIdViewers", "tags": [ - "ticket-types" + "events" ], - "summary": "Delete a ticket type (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Grant read-only access to an event's statistics", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nGives the owner of `email` read-only access to this event's statistics and emails them the link. If no account exists for that email, a read-only (`VIEWER`) account is created with no access to the rest of the workspace, and a second email lets them set a password. The response does not say whether an account already existed (`newAccount` is deprecated and never sent). Idempotent per event and person: 201 when the access is new, 200 when it already existed (the notice email is sent again). 502 `EMAIL_NOT_SENT` when the email provider failed (the access WAS granted; retry to resend). Rate limited: 10 invitations per 10 minutes per API key (429 `RATE_LIMITED` with `Retry-After`).", "security": [ { "apiKey": [] @@ -2366,13 +2422,49 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventViewerInvite" + } + } + } + }, "responses": { "200": { + "description": "The person already had access.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EventViewerInviteResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "201": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EventViewerInviteResult" + } + }, + "required": [ + "data" + ] } } } @@ -2407,8 +2499,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -2417,8 +2509,29 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", "content": { "application/json": { "schema": { @@ -2430,14 +2543,14 @@ } } }, - "/sales": { - "get": { - "operationId": "getSales", + "/events/{id}/viewers/{viewerId}": { + "delete": { + "operationId": "deleteEventsIdViewersViewerId", "tags": [ - "sales" + "events" ], - "summary": "List workspace sales", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Revoke a read-only viewer of an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nDESTRUCTIVE: removes this person's read-only access to the event's statistics. Their account is kept (it may have access to other events). `viewerId` is the access id returned by `GET /events/{id}/viewers`, not the user id. An access of another event or workspace is 404.", "security": [ { "apiKey": [] @@ -2446,106 +2559,117 @@ "apiKeyHeader": [] } ], + "x-ft-destructive": true, "parameters": [ { - "name": "status", - "in": "query", - "required": false, - "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED", - "schema": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - } - }, - { - "name": "channel", - "in": "query", - "required": false, - "description": "WEB|MOBILE|POS|ADMIN", - "schema": { - "type": "string", - "enum": [ - "WEB", - "MOBILE", - "POS", - "ADMIN" - ] - } - }, - { - "name": "event", - "in": "query", - "required": false, - "description": "event id", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, { - "name": "eventDate", - "in": "query", - "required": false, - "description": "event date id", + "name": "viewerId", + "in": "path", + "required": true, "schema": { "type": "string" } }, { - "name": "reference", - "in": "query", + "name": "X-Workspace-Id", + "in": "header", "required": false, - "description": "sale reference/code (partial match)", + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/EventViewerRevoke" + } + }, + "required": [ + "data" + ] + } + } + } }, - { - "name": "buyer", - "in": "query", - "required": false, - "description": "buyer name or email (partial match)", - "schema": { - "type": "string" + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } } }, - { - "name": "from", - "in": "query", - "required": false, - "description": "start date (ISO 8601, applied to created_at)", - "schema": { - "type": "string" + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } } }, - { - "name": "to", - "in": "query", - "required": false, - "description": "end date (ISO 8601, applied to created_at)", - "schema": { - "type": "string" + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } } }, - { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } } + } + } + } + }, + "/events/{id}/validators": { + "get": { + "operationId": "getEventsIdValidators", + "tags": [ + "events" + ], + "summary": "List the ticket validators of an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nDoor staff who can validate tickets for this event: those assigned to it plus those with no events assigned (`allEvents: true`, they validate every event of the workspace). Includes inactive validators (`isActive: false`). `userId` and `name` are only returned for members of the active workspace. Only events owned by the active workspace. A key restricted by `event_scope` gets 403 `EVENT_SCOPE_FORBIDDEN` for events outside its scope.", + "security": [ + { + "apiKey": [] }, { - "name": "cursor", - "in": "query", - "required": false, + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -2571,37 +2695,17 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Sale" - } - }, - "page": { - "$ref": "#/components/schemas/Page" - }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" + "$ref": "#/components/schemas/EventValidator" } } }, "required": [ - "data", - "page" + "data" ] } } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -2645,12 +2749,12 @@ } }, "post": { - "operationId": "postSales", + "operationId": "postEventsIdValidators", "tags": [ - "sales" + "events" ], - "summary": "Create a sale/order (complimentary tickets and programmatic sales)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nAccepts `Idempotency-Key`: retrying with the same key returns the sale created on the first attempt (a 201 response with the `Idempotent-Replay: true` header) instead of issuing another one. Recommended for any client that retries on its own.", + "summary": "Add a ticket validator to an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nAssigns door staff to this event. If no account exists for `email`, a `STAFF` account is created in the workspace and an invitation email is sent so they can set a password (`invited: true`). If the person is already a validator of this workspace, they are reactivated and this event is added to their list (assignments are additive: existing events are never removed; a validator with no events assigned already validates every event of the workspace, so nothing is added and they keep `allEvents: true`). `userId` and `name` are only returned when the person is a member of the active workspace (otherwise only the `email` sent is echoed). 409 `VALIDATOR_OTHER_WORKSPACE` when that person cannot be assigned as a validator of this workspace (the message is intentionally generic). To remove a validator, change their access with `PUT /staff/{id}/access` or revoke it with `DELETE /staff/{id}`. Rate limited: 10 per 10 minutes per API key (429 `RATE_LIMITED` with `Retry-After`).", "security": [ { "apiKey": [] @@ -2661,19 +2765,18 @@ ], "parameters": [ { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, { - "name": "Idempotency-Key", + "name": "X-Workspace-Id", "in": "header", "required": false, - "description": "Client-chosen idempotency key (max. 255 characters). Retrying with the SAME key returns the resource created by the first attempt instead of creating another one. Unique per workspace.", + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } @@ -2684,7 +2787,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SaleCreate" + "$ref": "#/components/schemas/EventValidatorCreate" } } } @@ -2698,7 +2801,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SaleDetail" + "$ref": "#/components/schemas/EventValidatorCreateResult" } }, "required": [ @@ -2758,27 +2861,38 @@ } } }, - "502": { - "description": "The external provider failed to complete the operation.", + "429": { + "description": "Too many requests: rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } } } } }, - "/sales/{id}": { + "/ticket-types": { "get": { - "operationId": "getSalesId", + "operationId": "getTicketTypes", "tags": [ - "sales" + "ticket-types" ], - "summary": "Get a sale with its items", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List workspace ticket types", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -2789,9 +2903,28 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "eventDateId", + "in": "query", + "required": false, + "description": "filter by event date", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, "schema": { "type": "string" } @@ -2815,11 +2948,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SaleDetail" + "type": "array", + "items": { + "$ref": "#/components/schemas/TicketType" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -2866,16 +3006,14 @@ } } } - } - }, - "/sales/{id}/cancel": { + }, "post": { - "operationId": "postSalesIdCancel", + "operationId": "postTicketTypes", "tags": [ - "sales" + "ticket-types" ], - "summary": "Cancel a sale (blocked if someone already checked in or the payment is still open)", - "description": "Marks the sale as CANCELLED, releases its inventory and frees the associated numbered seats. IMPORTANT: a sale with tickets already used at the door is NOT cancelled: it responds 409 SALE_ALREADY_CHECKED_IN, because returning that inventory would put it back on sale with the person already inside. If the money must be returned, use POST /sales/{id}/refund. IMPORTANT: a PENDING sale charged through Bold has a payment link that may still be live — the Bold API never marks its links as expired —, so cancelling it could leave the buyer charged without a ticket. Before cancelling, the actual payment status is re-read: if Bold reports it approved, it responds 409 SALE_PAID_AT_GATEWAY and the sale is NOT cancelled under any circumstances (that sale gets confirmed or refunded). If the payment is still open or its status cannot be read, it responds 409 OPEN_PAYMENT_CONFIRMATION_REQUIRED: check the Bold dashboard and repeat the call with {\"acknowledge_open_payment\": true} to explicitly accept the risk. A sale charged with a Bold card terminal (counter sale) that still has a terminal charge in progress, or an approved charge not yet delivered, responds 409 TERMINAL_CHARGE_IN_PROGRESS and is not cancelled (the acknowledgement does not override it). Sales from other gateways and sales with no payment started are cancelled without that step.", + "summary": "Create a ticket type", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -2885,14 +3023,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -2908,13 +3038,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SaleCancelRequest" + "$ref": "#/components/schemas/TicketTypeCreate" } } } }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -2922,7 +3052,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Sale" + "$ref": "#/components/schemas/TicketType" } }, "required": [ @@ -2962,16 +3092,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -2985,14 +3105,14 @@ } } }, - "/sales/{id}/refund": { - "post": { - "operationId": "postSalesIdRefund", + "/ticket-types/{id}": { + "get": { + "operationId": "getTicketTypesId", "tags": [ - "sales" + "ticket-types" ], - "summary": "Refund a sale (moving the funds depends on the payment gateway)", - "description": "Marks the sale as REFUNDED and releases the associated numbered seats. IMPORTANT: whether the money goes back to the buyer depends on the payment gateway and the payment method used. Sales charged through MercadoPago are fully refunded against the MercadoPago API (stable idempotency key per sale, so retries never refund twice) and marked only once MercadoPago confirms. A 503 GATEWAY_REFUND_PENDING means MercadoPago did not answer clearly: the sale stays CONFIRMED and repeating the same call is safe. Sales charged through Wompi by CARD are voided against the payment gateway before being marked. In every other case this endpoint does NOT trigger the actual refund: the money is NOT returned automatically and a 200 only confirms the accounting status change. Those refunds must be handled separately in the payment gateway's dashboard. PARTIAL REFUND BY TICKET: send `items` with the ids of the sale items to refund (the `id` field of GET /sales/{id}/tickets). Each item refunds its prorated share of the sale total (by item subtotal; shares always add up to the exact total). The refunded tickets are invalidated at the door and their quota returns to stock; when no live item remains the sale becomes REFUNDED. Only MercadoPago (or uncharged / cash sales) support partial refunds: Wompi and Bold answer 409 GATEWAY_REFUND_NOT_SUPPORTED. Items already checked in answer 409 ITEM_ALREADY_CHECKED_IN — also for a FULL refund (no `items`, or all of them): a sale with any checked-in ticket is never refunded whole; refund the unused tickets by item; items from another sale answer 422 ITEM_NOT_IN_SALE; a refund already in flight over the same items answers 409 REFUND_IN_PROGRESS (retry exactly the same items). `block_seats: true` (also valid for a full refund) keeps the refunded numbered seats OUT of sale: seats.io moves them from booked straight to a blocked status, never through free. The `refund` object in the response reports the refunded amount and what happened to the seats. Wompi payment methods without API refunds (PSE, Nequi, Bancolombia transfer) respond 409: return the money in the Wompi dashboard and repeat the call with {\"acknowledge_manual\": true} to reflect the accounting status. A 502 means the gateway rejected the void and the sale remains CONFIRMED.", + "summary": "Get a ticket type", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -3020,16 +3140,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SaleRefundRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -3039,7 +3149,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SaleRefundResult" + "$ref": "#/components/schemas/TicketType" } }, "required": [ @@ -3079,38 +3189,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { - "description": "Operation error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "502": { - "description": "The external provider failed to complete the operation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -3120,16 +3200,14 @@ } } } - } - }, - "/membership-plans": { - "get": { - "operationId": "getMembershipPlans", + }, + "patch": { + "operationId": "patchTicketTypesId", "tags": [ - "membership-plans" + "ticket-types" ], - "summary": "List the workspace's membership plans", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Update a ticket type", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -3140,19 +3218,9 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -3167,6 +3235,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketTypeUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -3176,18 +3254,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MembershipPlan" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/TicketType" } }, "required": [ - "data", - "page" + "data" ] } } @@ -3223,6 +3294,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -3235,12 +3316,12 @@ } } }, - "post": { - "operationId": "postMembershipPlans", + "delete": { + "operationId": "deleteTicketTypesId", "tags": [ - "membership-plans" + "ticket-types" ], - "summary": "Create a membership plan", + "summary": "Delete a ticket type (soft delete)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3251,6 +3332,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -3261,31 +3350,13 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/MembershipPlanCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/MembershipPlan" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -3320,6 +3391,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -3333,13 +3414,13 @@ } } }, - "/membership-plans/{id}": { + "/sales": { "get": { - "operationId": "getMembershipPlansId", + "operationId": "getSales", "tags": [ - "membership-plans" + "sales" ], - "summary": "Get a membership plan", + "summary": "List workspace sales", "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3351,9 +3432,104 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "status", + "in": "query", + "required": false, + "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED", + "schema": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + } + }, + { + "name": "channel", + "in": "query", + "required": false, + "description": "WEB|MOBILE|POS|ADMIN", + "schema": { + "type": "string", + "enum": [ + "WEB", + "MOBILE", + "POS", + "ADMIN" + ] + } + }, + { + "name": "event", + "in": "query", + "required": false, + "description": "event id", + "schema": { + "type": "string" + } + }, + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "event date id", + "schema": { + "type": "string" + } + }, + { + "name": "reference", + "in": "query", + "required": false, + "description": "sale reference/code (partial match)", + "schema": { + "type": "string" + } + }, + { + "name": "buyer", + "in": "query", + "required": false, + "description": "buyer name or email (partial match)", + "schema": { + "type": "string" + } + }, + { + "name": "from", + "in": "query", + "required": false, + "description": "start date (ISO 8601, applied to created_at)", + "schema": { + "type": "string" + } + }, + { + "name": "to", + "in": "query", + "required": false, + "description": "end date (ISO 8601, applied to created_at)", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, "schema": { "type": "string" } @@ -3377,18 +3553,41 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/MembershipPlan" + "type": "array", + "items": { + "$ref": "#/components/schemas/Sale" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } } }, "required": [ - "data" + "data", + "page" ] } } } }, - "401": { - "description": "Missing or invalid credential.", + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -3429,13 +3628,13 @@ } } }, - "patch": { - "operationId": "patchMembershipPlansId", + "post": { + "operationId": "postSales", "tags": [ - "membership-plans" + "sales" ], - "summary": "Update a membership plan", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Create a sale/order (complimentary tickets and programmatic sales)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nAccepts `Idempotency-Key`: retrying with the same key returns the sale created on the first attempt (a 201 response with the `Idempotent-Replay: true` header) instead of issuing another one. Recommended for any client that retries on its own.\n\n`comp: true` issues complimentary tickets at price 0. The sale is flagged as a courtesy, like the ones issued from the dashboard: reports count it apart from paid sales, and `PATCH /sales/{id}/recipient` can correct its recipient.", "security": [ { "apiKey": [] @@ -3446,18 +3645,19 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } }, { - "name": "X-Workspace-Id", + "name": "Idempotency-Key", "in": "header", "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "description": "Client-chosen idempotency key (max. 255 characters). Retrying with the SAME key returns the resource created by the first attempt instead of creating another one. Unique per workspace.", "schema": { "type": "string" } @@ -3468,13 +3668,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MembershipPlanUpdate" + "$ref": "#/components/schemas/SaleCreate" } } } }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -3482,7 +3682,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/MembershipPlan" + "$ref": "#/components/schemas/SaleDetail" } }, "required": [ @@ -3522,6 +3722,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -3531,16 +3741,28 @@ } } } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } - }, - "delete": { - "operationId": "deleteMembershipPlansId", + } + }, + "/sales/{id}": { + "get": { + "operationId": "getSalesId", "tags": [ - "membership-plans" + "sales" ], - "summary": "Delete a membership plan (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Get a sale with its items", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -3574,7 +3796,15 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/SaleDetail" + } + }, + "required": [ + "data" + ] } } } @@ -3609,16 +3839,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -3632,14 +3852,14 @@ } } }, - "/venues": { - "get": { - "operationId": "getVenues", + "/sales/{id}/cancel": { + "post": { + "operationId": "postSalesIdCancel", "tags": [ - "venues" + "sales" ], - "summary": "List workspace venues", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Cancel a sale (blocked if someone already checked in or the payment is still open)", + "description": "Marks the sale as CANCELLED, releases its inventory and frees the associated numbered seats. IMPORTANT: a sale with tickets already used at the door is NOT cancelled: it responds 409 SALE_ALREADY_CHECKED_IN, because returning that inventory would put it back on sale with the person already inside. If the money must be returned, use POST /sales/{id}/refund. IMPORTANT: a PENDING sale charged through Bold has a payment link that may still be live — the Bold API never marks its links as expired —, so cancelling it could leave the buyer charged without a ticket. Before cancelling, the actual payment status is re-read: if Bold reports it approved, it responds 409 SALE_PAID_AT_GATEWAY and the sale is NOT cancelled under any circumstances (that sale gets confirmed or refunded). If the payment is still open or its status cannot be read, it responds 409 OPEN_PAYMENT_CONFIRMATION_REQUIRED: check the Bold dashboard and repeat the call with {\"acknowledge_open_payment\": true} to explicitly accept the risk. A sale charged with a Bold card terminal (counter sale) that still has a terminal charge in progress, or an approved charge not yet delivered, responds 409 TERMINAL_CHARGE_IN_PROGRESS and is not cancelled (the acknowledgement does not override it). Sales from other gateways and sales with no payment started are cancelled without that step.", "security": [ { "apiKey": [] @@ -3650,19 +3870,9 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -3677,6 +3887,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SaleCancelRequest" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -3686,18 +3906,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Venue" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/Sale" } }, "required": [ - "data", - "page" + "data" ] } } @@ -3733,6 +3946,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -3744,14 +3967,16 @@ } } } - }, + } + }, + "/sales/{id}/refund": { "post": { - "operationId": "postVenues", + "operationId": "postSalesIdRefund", "tags": [ - "venues" + "sales" ], - "summary": "Create a venue", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Refund a sale (moving the funds depends on the payment gateway)", + "description": "Marks the sale as REFUNDED and releases the associated numbered seats. IMPORTANT: whether the money goes back to the buyer depends on the payment gateway and the payment method used. Sales charged through MercadoPago are fully refunded against the MercadoPago API (stable idempotency key per sale, so retries never refund twice) and marked only once MercadoPago confirms. A 503 GATEWAY_REFUND_PENDING means MercadoPago did not answer clearly: the sale stays CONFIRMED and repeating the same call is safe. Sales charged through Wompi by CARD are voided against the payment gateway before being marked. In every other case this endpoint does NOT trigger the actual refund: the money is NOT returned automatically and a 200 only confirms the accounting status change. Those refunds must be handled separately in the payment gateway's dashboard. PARTIAL REFUND BY TICKET: send `items` with the ids of the sale items to refund (the `id` field of GET /sales/{id}/tickets). Each item refunds its prorated share of the sale total (by item subtotal; shares always add up to the exact total). The refunded tickets are invalidated at the door and their quota returns to stock; when no live item remains the sale becomes REFUNDED. Only MercadoPago (or uncharged / cash sales) support partial refunds: Wompi and Bold answer 409 GATEWAY_REFUND_NOT_SUPPORTED. Items already checked in answer 409 ITEM_ALREADY_CHECKED_IN — also for a FULL refund (no `items`, or all of them): a sale with any checked-in ticket is never refunded whole; refund the unused tickets by item; items from another sale answer 422 ITEM_NOT_IN_SALE; a refund already in flight over the same items answers 409 REFUND_IN_PROGRESS (retry exactly the same items). `block_seats: true` (also valid for a full refund) keeps the refunded numbered seats OUT of sale: seats.io moves them from booked straight to a blocked status, never through free. The `refund` object in the response reports the refunded amount and what happened to the seats. Wompi payment methods without API refunds (PSE, Nequi, Bancolombia transfer) respond 409: return the money in the Wompi dashboard and repeat the call with {\"acknowledge_manual\": true} to reflect the accounting status. A 502 means the gateway rejected the void and the sale remains CONFIRMED.", "security": [ { "apiKey": [] @@ -3761,6 +3986,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -3776,13 +4009,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/VenueCreate" + "$ref": "#/components/schemas/SaleRefundRequest" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -3790,7 +4023,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Venue" + "$ref": "#/components/schemas/SaleRefundResult" } }, "required": [ @@ -3830,8 +4063,38 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", "content": { "application/json": { "schema": { @@ -3843,14 +4106,14 @@ } } }, - "/venues/{id}": { - "get": { - "operationId": "getVenuesId", + "/sales/{id}/items/{itemId}/transfer": { + "post": { + "operationId": "postSalesIdItemsItemIdTransfer", "tags": [ - "venues" + "sales" ], - "summary": "Get a venue", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Transfer one ticket of a sale to another person (destructive)", + "description": "DESTRUCTIVE: changes the ticket holder and voids the previous QR code (the ticket code is rotated and any installed Apple Wallet pass stops working). The new holder receives the ticket by email and the buyer is notified. Same rules as the dashboard and the buyer: the recipient must already have a verified FreeTicket buyer account (the holder name comes from that account), each ticket can be transferred only once (no staff override) and only until the show starts. 422 RECIPIENT_NOT_REGISTERED / SELF_TRANSFER: fix the recipient. 409 NOT_CONFIRMED, ALREADY_TRANSFERRED, CHECKED_IN, REFUNDED, ADDON, PRESALE_NOT_TRANSFERABLE, MULTI_QUANTITY, EVENT_STARTED or CONFLICT (the ticket changed in flight; re-read and retry). Not idempotent: a retry after success answers 409 ALREADY_TRANSFERRED. Minimum role: `ADMIN`.", "security": [ { "apiKey": [] @@ -3859,6 +4122,7 @@ "apiKeyHeader": [] } ], + "x-ft-destructive": true, "parameters": [ { "name": "id", @@ -3868,6 +4132,14 @@ "type": "string" } }, + { + "name": "itemId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -3878,6 +4150,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SaleItemTransferRequest" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -3887,7 +4169,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Venue" + "$ref": "#/components/schemas/SaleItemTransfer" } }, "required": [ @@ -3927,6 +4209,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -3938,14 +4230,16 @@ } } } - }, + } + }, + "/sales/{id}/recipient": { "patch": { - "operationId": "patchVenuesId", + "operationId": "patchSalesIdRecipient", "tags": [ - "venues" + "sales" ], - "summary": "Update a venue", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Correct the recipient of a courtesy sale and resend its tickets", + "description": "DESTRUCTIVE when the email changes (previous QR codes are voided). Only for courtesy sales issued from the dashboard (confirmed, `is_courtesy`); any other sale answers 404. Updates the recipient's name and email and resends the tickets to the corrected address. When the email changes, the ticket codes of the non-transferred tickets are rotated, so the QR codes sent to the wrong address stop working (`ticketCodesRotated: true`). Minimum role: `ADMIN`.", "security": [ { "apiKey": [] @@ -3954,6 +4248,7 @@ "apiKeyHeader": [] } ], + "x-ft-destructive": true, "parameters": [ { "name": "id", @@ -3978,7 +4273,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/VenueUpdate" + "$ref": "#/components/schemas/CourtesyRecipientUpdate" } } } @@ -3992,7 +4287,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Venue" + "$ref": "#/components/schemas/CourtesyRecipient" } }, "required": [ @@ -4043,14 +4338,16 @@ } } } - }, - "delete": { - "operationId": "deleteVenuesId", - "tags": [ - "venues" + } + }, + "/event-dates/{id}/courtesy-seats": { + "get": { + "operationId": "getEventDatesIdCourtesySeats", + "tags": [ + "events" ], - "summary": "Delete a venue (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List blocked seats that can be issued as courtesies", + "description": "For a numbered (seats.io) event date: the seats that are booked on the map without an order (blocked from sale by the event wizard or by hand) and are not claimed by any live sale, grouped by numbered ticket type (matched by seats.io category). These are the seats the dashboard offers when issuing a courtesy. A date without a seat map, or without numbered ticket types, returns `ticketTypes: []`. 503 SEATSIO_UNAVAILABLE (retryable) when seats.io could not be read. Minimum role: `ADMIN`.", "security": [ { "apiKey": [] @@ -4084,7 +4381,15 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CourtesySeats" + } + }, + "required": [ + "data" + ] } } } @@ -4128,18 +4433,28 @@ } } } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/staff": { + "/membership-plans": { "get": { - "operationId": "getStaff", + "operationId": "getMembershipPlans", "tags": [ - "staff" + "membership-plans" ], - "summary": "List staff with access to the workspace", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. With `?workspaceIds=`, cursor pagination is still per user: `limit` counts people, not rows.", + "summary": "List the workspace's membership plans", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4167,15 +4482,6 @@ "type": "string" } }, - { - "name": "workspaceIds", - "in": "query", - "required": false, - "description": "Comma-separated workspace ids (max. 25). Returns the staff of all of them in a single call, with each row tagged with `workspaceId`/`workspaceName` (one row per person and workspace). Always intersected with the workspaces the credential can already manage: it never widens its scope. Without the parameter, the workspace from the `X-Workspace-Id` header is listed.", - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -4197,7 +4503,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/StaffUser" + "$ref": "#/components/schemas/MembershipPlan" } }, "page": { @@ -4255,11 +4561,11 @@ } }, "post": { - "operationId": "postStaff", + "operationId": "postMembershipPlans", "tags": [ - "staff" + "membership-plans" ], - "summary": "Create a staff user in the workspace", + "summary": "Create a membership plan", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4285,7 +4591,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StaffCreate" + "$ref": "#/components/schemas/MembershipPlanCreate" } } } @@ -4299,7 +4605,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StaffUser" + "$ref": "#/components/schemas/MembershipPlan" } }, "required": [ @@ -4339,16 +4645,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -4358,39 +4654,18 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } - } } } } }, - "/staff/{id}": { + "/membership-plans/{id}": { "get": { - "operationId": "getStaffId", + "operationId": "getMembershipPlansId", "tags": [ - "staff" + "membership-plans" ], - "summary": "Get a staff member", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Get a membership plan", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4427,7 +4702,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StaffUser" + "$ref": "#/components/schemas/MembershipPlan" } }, "required": [ @@ -4479,13 +4754,13 @@ } } }, - "delete": { - "operationId": "deleteStaffId", + "patch": { + "operationId": "patchMembershipPlansId", "tags": [ - "staff" + "membership-plans" ], - "summary": "Revoke a staff member's access to this workspace", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nRevokes access to THIS workspace: granted sections, ticket validation permissions, read-only events, membership, and the home workspace if it was this one. Terminates live sessions and invalidates the invitation QR code. It does NOT delete the account or its history: the person may belong to other workspaces. An `ADMIN` cannot revoke another admin (403) or themselves (409).", + "summary": "Update a membership plan", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4513,13 +4788,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MembershipPlanUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MembershipPlan" + } + }, + "required": [ + "data" + ] } } } @@ -4554,16 +4847,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -4575,15 +4858,13 @@ } } } - } - }, - "/staff/{id}/role": { - "patch": { - "operationId": "patchStaffIdRole", + }, + "delete": { + "operationId": "deleteMembershipPlansId", "tags": [ - "staff" + "membership-plans" ], - "summary": "Change a staff user's role", + "summary": "Delete a membership plan (soft delete)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4612,31 +4893,13 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/RoleUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/StaffUser" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -4694,13 +4957,13 @@ } } }, - "/reports/summary": { + "/venues": { "get": { - "operationId": "getReportsSummary", + "operationId": "getVenues", "tags": [ - "reports" + "venues" ], - "summary": "Workspace KPIs (revenue, tickets, sales, memberships)", + "summary": "List workspace venues", "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4712,19 +4975,21 @@ ], "parameters": [ { - "name": "period", + "name": "limit", "in": "query", "required": false, - "description": "7d | 30d (default) | 90d | 1y", + "description": "1-100, default 20", "schema": { - "type": "string", - "enum": [ - "7d", - "30d", - "90d", - "1y" - ], - "default": "30d" + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" } }, { @@ -4746,11 +5011,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ReportSummary" + "type": "array", + "items": { + "$ref": "#/components/schemas/Venue" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -4797,16 +5069,14 @@ } } } - } - }, - "/reports/inventory": { - "get": { - "operationId": "getReportsInventory", + }, + "post": { + "operationId": "postVenues", "tags": [ - "reports" + "venues" ], - "summary": "Inventory aggregated by event/date/ticket type (capacity, sold, available)", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Create a venue", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4817,78 +5087,27 @@ ], "parameters": [ { - "name": "eventId", - "in": "query", + "name": "X-Workspace-Id", + "in": "header", "required": false, - "description": "Filter by event", + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } - }, - { - "name": "eventDateId", - "in": "query", - "required": false, - "description": "Filter by event date", - "schema": { - "type": "string" - } - }, - { - "name": "from", - "in": "query", - "required": false, - "description": "Event date start ≥ (ISO 8601)", - "schema": { - "type": "string" - } - }, - { - "name": "to", - "in": "query", - "required": false, - "description": "Event date start ≤ (ISO 8601)", - "schema": { - "type": "string" - } - }, - { - "name": "includeDrafts", - "in": "query", - "required": false, - "description": "Include DRAFT events/dates (default false)", - "schema": { - "type": "boolean", - "default": false - } - }, - { - "name": "groupBy", - "in": "query", - "required": false, - "description": "event | date | ticketType (default)", - "schema": { - "type": "string", - "enum": [ - "event", - "date", - "ticketType" - ], - "default": "ticketType" - } - }, - { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", - "schema": { - "type": "string" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VenueCreate" + } } } - ], + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -4896,16 +5115,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InventoryRow" - } - }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" - } + "$ref": "#/components/schemas/Venue" } }, "required": [ @@ -4958,14 +5168,14 @@ } } }, - "/reports/reconciliation": { + "/venues/{id}": { "get": { - "operationId": "getReportsReconciliation", + "operationId": "getVenuesId", "tags": [ - "reports" + "venues" ], - "summary": "CFO financial reconciliation (MP ↔ sale ↔ Siigo invoice)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Get a venue", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4976,86 +5186,13 @@ ], "parameters": [ { - "name": "date_from", - "in": "query", - "required": true, - "description": "ISO 8601 (start, on Sale.created_at)", - "schema": { - "type": "string" - } - }, - { - "name": "date_to", - "in": "query", + "name": "id", + "in": "path", "required": true, - "description": "ISO 8601 (end)", - "schema": { - "type": "string" - } - }, - { - "name": "match_status", - "in": "query", - "required": false, - "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", - "schema": { - "type": "string", - "enum": [ - "OK", - "MISSING_INVOICE", - "MISSING_CUFE", - "AMOUNT_MISMATCH", - "MISSING_PAYMENT" - ] - } - }, - { - "name": "provider", - "in": "query", - "required": false, - "description": "Filter by payment_provider (e.g. mercadopago)", - "schema": { - "type": "string" - } - }, - { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by event id", - "schema": { - "type": "string" - } - }, - { - "name": "eventDate", - "in": "query", - "required": false, - "description": "Filter by event date id (takes precedence over `event`)", "schema": { "type": "string" } }, - { - "name": "page", - "in": "query", - "required": false, - "description": "1-based page (default 1)", - "schema": { - "type": "integer", - "default": 1 - } - }, - { - "name": "page_size", - "in": "query", - "required": false, - "description": "Page size 1..500 (default 100)", - "schema": { - "type": "integer", - "default": 100 - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -5075,10 +5212,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ReconciliationRow" - } + "$ref": "#/components/schemas/Venue" } }, "required": [ @@ -5129,15 +5263,13 @@ } } } - } - }, - "/reports/exports/reconciliation": { - "get": { - "operationId": "getReportsExportsReconciliation", + }, + "patch": { + "operationId": "patchVenuesId", "tags": [ - "reports" + "venues" ], - "summary": "CSV export of the CFO financial reconciliation", + "summary": "Update a venue", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -5149,62 +5281,9 @@ ], "parameters": [ { - "name": "date_from", - "in": "query", - "required": true, - "description": "ISO 8601 (start, on Sale.created_at)", - "schema": { - "type": "string" - } - }, - { - "name": "date_to", - "in": "query", + "name": "id", + "in": "path", "required": true, - "description": "ISO 8601 (end)", - "schema": { - "type": "string" - } - }, - { - "name": "match_status", - "in": "query", - "required": false, - "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", - "schema": { - "type": "string", - "enum": [ - "OK", - "MISSING_INVOICE", - "MISSING_CUFE", - "AMOUNT_MISMATCH", - "MISSING_PAYMENT" - ] - } - }, - { - "name": "provider", - "in": "query", - "required": false, - "description": "Filter by payment_provider (e.g. mercadopago)", - "schema": { - "type": "string" - } - }, - { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by event id", - "schema": { - "type": "string" - } - }, - { - "name": "eventDate", - "in": "query", - "required": false, - "description": "Filter by event date id (takes precedence over `event`)", "schema": { "type": "string" } @@ -5219,13 +5298,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VenueUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Venue" + } + }, + "required": [ + "data" + ] } } } @@ -5271,15 +5368,13 @@ } } } - } - }, - "/reports/exports/attendees": { - "get": { - "operationId": "getReportsExportsAttendees", + }, + "delete": { + "operationId": "deleteVenuesId", "tags": [ - "reports" + "venues" ], - "summary": "Export attendees per ticket, with filters (max 5000)", + "summary": "Delete a venue (soft delete)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -5291,57 +5386,13 @@ ], "parameters": [ { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by Event.id", - "schema": { - "type": "string" - } - }, - { - "name": "eventDate", - "in": "query", - "required": false, - "description": "Filter by EventDate.id", - "schema": { - "type": "string" - } - }, - { - "name": "from", - "in": "query", - "required": false, - "description": "ISO 8601 — from (on Sale.created_at)", - "schema": { - "type": "string" - } - }, - { - "name": "to", - "in": "query", - "required": false, - "description": "ISO 8601 — to (on Sale.created_at)", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, - { - "name": "status", - "in": "query", - "required": false, - "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", - "schema": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -5358,22 +5409,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExportAttendee" - } - }, - "page": { - "$ref": "#/components/schemas/Page" - } - }, - "required": [ - "data", - "page" - ] + "type": "object" } } } @@ -5421,14 +5457,14 @@ } } }, - "/reports/exports/buyers": { + "/staff": { "get": { - "operationId": "getReportsExportsBuyers", + "operationId": "getStaff", "tags": [ - "reports" + "staff" ], - "summary": "Export buyers, with filters (max 5000)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List staff with access to the workspace", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. With `?workspaceIds=`, cursor pagination is still per user: `limit` counts people, not rows.", "security": [ { "apiKey": [] @@ -5439,57 +5475,32 @@ ], "parameters": [ { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by Event.id", - "schema": { - "type": "string" - } - }, - { - "name": "eventDate", + "name": "limit", "in": "query", "required": false, - "description": "Filter by EventDate.id", + "description": "1-100, default 20", "schema": { - "type": "string" + "type": "integer", + "default": 20 } }, { - "name": "from", + "name": "cursor", "in": "query", "required": false, - "description": "ISO 8601 — from (on Sale.created_at)", "schema": { "type": "string" } }, { - "name": "to", + "name": "workspaceIds", "in": "query", "required": false, - "description": "ISO 8601 — to (on Sale.created_at)", + "description": "Comma-separated workspace ids (max. 25). Returns the staff of all of them in a single call, with each row tagged with `workspaceId`/`workspaceName` (one row per person and workspace). Always intersected with the workspaces the credential can already manage: it never widens its scope. Without the parameter, the workspace from the `X-Workspace-Id` header is listed.", "schema": { "type": "string" } }, - { - "name": "status", - "in": "query", - "required": false, - "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", - "schema": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -5511,7 +5522,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ExportBuyer" + "$ref": "#/components/schemas/StaffUser" } }, "page": { @@ -5567,15 +5578,13 @@ } } } - } - }, - "/reports/exports/subscribers": { - "get": { - "operationId": "getReportsExportsSubscribers", + }, + "post": { + "operationId": "postStaff", "tags": [ - "reports" + "staff" ], - "summary": "Export subscribers (max 5000)", + "summary": "Create a staff user in the workspace", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -5596,8 +5605,18 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StaffCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -5605,10 +5624,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExportSubscriber" - } + "$ref": "#/components/schemas/StaffUser" } }, "required": [ @@ -5648,6 +5664,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -5657,18 +5683,39 @@ } } } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } } } } }, - "/reports/by-event": { + "/staff/{id}": { "get": { - "operationId": "getReportsByEvent", + "operationId": "getStaffId", "tags": [ - "reports" + "staff" ], - "summary": "Sales KPIs per workspace event", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Get a staff member", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5679,39 +5726,13 @@ ], "parameters": [ { - "name": "from", - "in": "query", - "required": false, - "description": "ISO 8601, filters Sale.created_at (gte)", - "schema": { - "type": "string" - } - }, - { - "name": "to", - "in": "query", - "required": false, - "description": "ISO 8601, filters Sale.created_at (lte)", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, - { - "name": "status", - "in": "query", - "required": false, - "description": "PENDING|CONFIRMED (default)|ABANDONED|CANCELLED|REFUNDED", - "schema": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -5731,10 +5752,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ReportByEventRow" - } + "$ref": "#/components/schemas/StaffUser" } }, "required": [ @@ -5744,16 +5762,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -5795,16 +5803,14 @@ } } } - } - }, - "/reports/timeseries": { - "get": { - "operationId": "getReportsTimeseries", + }, + "delete": { + "operationId": "deleteStaffId", "tags": [ - "reports" + "staff" ], - "summary": "Time series of CONFIRMED sales per bucket (day|week|month)", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Revoke a staff member's access to this workspace", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nRevokes access to THIS workspace: granted sections, ticket validation permissions, read-only events, membership, and the home workspace if it was this one. Terminates live sessions and invalidates the invitation QR code. It does NOT delete the account or its history: the person may belong to other workspaces. An `ADMIN` cannot revoke another admin (403) or themselves (409).", "security": [ { "apiKey": [] @@ -5815,42 +5821,9 @@ ], "parameters": [ { - "name": "interval", - "in": "query", + "name": "id", + "in": "path", "required": true, - "description": "day | week | month", - "schema": { - "type": "string", - "enum": [ - "day", - "week", - "month" - ] - } - }, - { - "name": "from", - "in": "query", - "required": false, - "description": "ISO 8601, filters Sale.created_at (gte)", - "schema": { - "type": "string" - } - }, - { - "name": "to", - "in": "query", - "required": false, - "description": "ISO 8601, filters Sale.created_at (lte)", - "schema": { - "type": "string" - } - }, - { - "name": "event", - "in": "query", - "required": false, - "description": "Workspace event ID (optional)", "schema": { "type": "string" } @@ -5871,24 +5844,13 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ReportTimeseriesRow" - } - } - }, - "required": [ - "data" - ] + "type": "object" } } } }, - "400": { - "description": "Bad request: malformed parameters.", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -5897,8 +5859,8 @@ } } }, - "401": { - "description": "Missing or invalid credential.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -5907,8 +5869,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -5917,8 +5879,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -5940,14 +5902,14 @@ } } }, - "/reports/financials": { - "get": { - "operationId": "getReportsFinancials", + "/staff/{id}/role": { + "patch": { + "operationId": "patchStaffIdRole", "tags": [ - "reports" + "staff" ], - "summary": "Financial statement per event date: gross, costs, and net payable", - "description": "One row per event date (event_date) with the financial breakdown of its confirmed sales — gross collected, platform fee + VAT (IVA), face value, payment gateway fee (actual for MercadoPago, rate-estimated for Wompi or Bold), 4x1000 tax, and net payable — plus the status of the associated settlement. If wompiSalesWithoutRate > 0, the gateway fee for some Wompi or Bold sales could not be estimated and the net amount is overstated.", + "summary": "Change a staff user's role", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5958,27 +5920,13 @@ ], "parameters": [ { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by event id", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } }, - { - "name": "past", - "in": "query", - "required": false, - "description": "true = only event dates that already took place (settleable); false = upcoming ones", - "schema": { - "type": "string", - "enum": [ - "true", - "false" - ] - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -5989,6 +5937,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -5998,16 +5956,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ReportFinancialsRow" - } - }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" - } + "$ref": "#/components/schemas/StaffUser" } }, "required": [ @@ -6017,8 +5966,8 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -6027,8 +5976,8 @@ } } }, - "401": { - "description": "Missing or invalid credential.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -6037,8 +5986,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -6047,8 +5996,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -6070,14 +6019,14 @@ } } }, - "/settlements": { - "get": { - "operationId": "getSettlements", + "/staff/{id}/resend-invite": { + "post": { + "operationId": "postStaffIdResendInvite", "tags": [ - "settlements" + "staff" ], - "summary": "Workspace settlements (payouts to the organizer)", - "description": "Lists the settlements visible to the organization (SENT, AWAITING_PAYMENT, PAID) with their standard id, amount, event/event date, and payment proofs. Download the files with `GET /settlements/{id}/document` (PDF) and `GET /settlements/{id}/proofs/{fileName}` (bank transfer proofs).", + "summary": "Resend a staff member's invitation email", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nEmails the staff member their invitation link again (to set a password and enter the panel). The link is the same persistent one already shared, so previously shared links and QR codes keep working; the link itself is never returned by the API. An `ADMIN` can only target users whose home workspace is the active one (otherwise 404). 409 `NO_EMAIL` for quick-access accounts without an email address (share their QR from the panel). 502 `EMAIL_NOT_SENT` when the email provider failed (retry). Rate limited: 3 resends per hour per API key and user (429 `RATE_LIMITED` with `Retry-After`). Keys restricted by `event_scope` get 403.", "security": [ { "apiKey": [] @@ -6088,43 +6037,9 @@ ], "parameters": [ { - "name": "event", - "in": "query", - "required": false, - "description": "Filter by event id", - "schema": { - "type": "string" - } - }, - { - "name": "status", - "in": "query", - "required": false, - "description": "SENT|AWAITING_PAYMENT|PAID", - "schema": { - "type": "string", - "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" - ] - } - }, - { - "name": "limit", - "in": "query", - "required": false, - "description": "1..100 (default 20)", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, - "description": "Id of the last row of the previous page", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -6148,25 +6063,18 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Settlement" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/StaffInviteResend" } }, "required": [ - "data", - "page" + "data" ] } } } }, - "400": { - "description": "Bad request: malformed parameters.", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -6175,8 +6083,8 @@ } } }, - "401": { - "description": "Missing or invalid credential.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -6185,8 +6093,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -6195,8 +6103,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -6214,18 +6122,49 @@ } } } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/settlements/{id}": { - "get": { - "operationId": "getSettlementsId", + "/staff/{id}/access": { + "put": { + "operationId": "putStaffIdAccess", "tags": [ - "settlements" + "staff" ], - "summary": "Get a settlement", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nThe same resource the list returns, by id. Only settlements already sent to the organizer (`SENT`, `AWAITING_PAYMENT`, `PAID`): internal master statuses are not exposed. Download the files with `GET /settlements/{id}/document` and `GET /settlements/{id}/proofs/{fileName}`.", + "summary": "Replace a staff member's access in this workspace", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nDESTRUCTIVE (full replace): sets what the user can do in the active workspace and removes whatever is not in the body. `accessType`: `admin` (role `ADMIN`, everything; only a `SUPER_ADMIN` can grant it, otherwise 403 `ADMIN_REQUIRES_SUPER_ADMIN`), `validador` (role `STAFF`, ticket validation only; `validatorEventIds` limits which events, empty = all events of the workspace), `personalizado` (role `STAFF`, only the listed `sections`; including `validar` also enables validation, limited by `validatorEventIds`) or `lectura` (role `VIEWER`, read-only statistics of `viewerEventIds`). `expiresAt` (`YYYY-MM-DD`, end of that day in the workspace timezone; null = permanent). `expiresAt` in the past is rejected (422). Event ids must belong to the workspace (422 `INVALID_EVENTS`). Nobody can change their own access (409 `SELF_ACCESS`). Only a `SUPER_ADMIN` can change the access of a user whose global role is `SUPER_ADMIN`, `ADMIN` or `MINCULTURA`, or who is an `OWNER`/`ADMIN` of the organization that owns the workspace (403 `TARGET_ROLE_FORBIDDEN`). 409 `VALIDATOR_OTHER_WORKSPACE` when the access enables ticket validation and the user cannot be assigned as a validator of this workspace (nothing is written). An `ADMIN` can only target users whose home workspace is the active one (otherwise 404). Note: the role is the user's global role. Keys restricted by `event_scope` get 403.", "security": [ { "apiKey": [] @@ -6234,6 +6173,7 @@ "apiKeyHeader": [] } ], + "x-ft-destructive": true, "parameters": [ { "name": "id", @@ -6253,6 +6193,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StaffAccessUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -6262,7 +6212,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Settlement" + "$ref": "#/components/schemas/StaffAccess" } }, "required": [ @@ -6302,90 +6252,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/settlements/{id}/document": { - "get": { - "operationId": "getSettlementsIdDocument", - "tags": [ - "settlements" - ], - "summary": "Download a settlement PDF", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Files live in a private bucket, so the response is a **302** to a signed URL valid for 5 minutes (the client must follow the redirect; the `storage_path` is never exposed). Only settlements visible to the organization (SENT, AWAITING_PAYMENT, PAID) and within the key's `event_scope`.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } - ], - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", - "schema": { - "type": "string" - } - } - ], - "responses": { - "302": { - "description": "Redirect to the signed URL (5 min TTL) of the PDF, with Content-Disposition: attachment." - }, - "401": { - "description": "Invalid or missing credential.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "403": { - "description": "Insufficient role (< ADMIN).", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "404": { - "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no document yet.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "502": { - "description": "Could not sign the storage URL.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -6394,8 +6262,8 @@ } } }, - "503": { - "description": "Storage is not configured.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -6407,14 +6275,14 @@ } } }, - "/settlements/{id}/proofs/{fileName}": { + "/reports/summary": { "get": { - "operationId": "getSettlementsIdProofsFileName", + "operationId": "getReportsSummary", "tags": [ - "settlements" + "reports" ], - "summary": "Download a settlement payment proof", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. `fileName` is the same value returned in `paymentProofs[].fileName` by `GET /settlements` (URL-encoded). Like `/document`, it responds with a **302** to a signed URL, valid for 5 minutes, in the private bucket.", + "summary": "Workspace KPIs (revenue, tickets, sales, memberships)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -6425,19 +6293,19 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "fileName", - "in": "path", - "required": true, + "name": "period", + "in": "query", + "required": false, + "description": "7d | 30d (default) | 90d | 1y", "schema": { - "type": "string" + "type": "string", + "enum": [ + "7d", + "30d", + "90d", + "1y" + ], + "default": "30d" } }, { @@ -6451,21 +6319,26 @@ } ], "responses": { - "302": { - "description": "Redirect to the signed URL (5 min TTL) of the payment proof, with Content-Disposition: attachment." - }, - "401": { - "description": "Invalid or missing credential.", + "200": { + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ReportSummary" + } + }, + "required": [ + "data" + ] } } } }, - "403": { - "description": "Insufficient role (< ADMIN).", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -6474,8 +6347,8 @@ } } }, - "404": { - "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no payment proof with that name.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -6484,8 +6357,8 @@ } } }, - "502": { - "description": "Could not sign the storage URL.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -6494,8 +6367,8 @@ } } }, - "503": { - "description": "Storage is not configured.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -6507,14 +6380,14 @@ } } }, - "/discounts": { + "/reports/inventory": { "get": { - "operationId": "getDiscounts", + "operationId": "getReportsInventory", "tags": [ - "discounts" + "reports" ], - "summary": "List workspace discount codes", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Inventory aggregated by event/date/ticket type (capacity, sold, available)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -6525,41 +6398,66 @@ ], "parameters": [ { - "name": "event", + "name": "eventId", "in": "query", "required": false, - "description": "event id to filter by", + "description": "Filter by event", "schema": { "type": "string" } }, { - "name": "active", + "name": "eventDateId", "in": "query", "required": false, - "description": "true|false", + "description": "Filter by event date", "schema": { - "type": "boolean" + "type": "string" } }, { - "name": "limit", + "name": "from", "in": "query", "required": false, - "description": "1-100, default 20", + "description": "Event date start ≥ (ISO 8601)", "schema": { - "type": "integer", - "default": 20 + "type": "string" } }, { - "name": "cursor", + "name": "to", "in": "query", "required": false, + "description": "Event date start ≤ (ISO 8601)", "schema": { "type": "string" } }, + { + "name": "includeDrafts", + "in": "query", + "required": false, + "description": "Include DRAFT events/dates (default false)", + "schema": { + "type": "boolean", + "default": false + } + }, + { + "name": "groupBy", + "in": "query", + "required": false, + "description": "event | date | ticketType (default)", + "schema": { + "type": "string", + "enum": [ + "event", + "date", + "ticketType" + ], + "default": "ticketType" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -6581,16 +6479,18 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Discount" + "$ref": "#/components/schemas/InventoryRow" } }, - "page": { - "$ref": "#/components/schemas/Page" + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } } }, "required": [ - "data", - "page" + "data" ] } } @@ -6637,13 +6537,15 @@ } } } - }, - "post": { - "operationId": "postDiscounts", + } + }, + "/reports/reconciliation": { + "get": { + "operationId": "getReportsReconciliation", "tags": [ - "discounts" + "reports" ], - "summary": "Create a discount code", + "summary": "CFO financial reconciliation (MP ↔ sale ↔ Siigo invoice)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -6655,120 +6557,84 @@ ], "parameters": [ { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "name": "date_from", + "in": "query", + "required": true, + "description": "ISO 8601 (start, on Sale.created_at)", "schema": { "type": "string" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DiscountCreate" - } - } - } - }, - "responses": { - "201": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Discount" - } - }, - "required": [ - "data" - ] - } - } + }, + { + "name": "date_to", + "in": "query", + "required": true, + "description": "ISO 8601 (end)", + "schema": { + "type": "string" } }, - "401": { - "description": "Missing or invalid credential.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } + { + "name": "match_status", + "in": "query", + "required": false, + "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", + "schema": { + "type": "string", + "enum": [ + "OK", + "MISSING_INVOICE", + "MISSING_CUFE", + "AMOUNT_MISMATCH", + "MISSING_PAYMENT" + ] } }, - "403": { - "description": "Insufficient role or resource not accessible.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } + { + "name": "provider", + "in": "query", + "required": false, + "description": "Filter by payment_provider (e.g. mercadopago)", + "schema": { + "type": "string" } }, - "404": { - "description": "Resource does not exist or is out of scope.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } + { + "name": "event", + "in": "query", + "required": false, + "description": "Filter by event id", + "schema": { + "type": "string" } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "Filter by event date id (takes precedence over `event`)", + "schema": { + "type": "string" } }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/discounts/{id}": { - "patch": { - "operationId": "patchDiscountsId", - "tags": [ - "discounts" - ], - "summary": "Update a discount code", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", - "security": [ { - "apiKey": [] + "name": "page", + "in": "query", + "required": false, + "description": "1-based page (default 1)", + "schema": { + "type": "integer", + "default": 1 + } }, { - "apiKeyHeader": [] - } - ], - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, + "name": "page_size", + "in": "query", + "required": false, + "description": "Page size 1..500 (default 100)", "schema": { - "type": "string" + "type": "integer", + "default": 100 } }, { @@ -6781,16 +6647,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DiscountUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -6800,7 +6656,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Discount" + "type": "array", + "items": { + "$ref": "#/components/schemas/ReconciliationRow" + } } }, "required": [ @@ -6851,13 +6710,15 @@ } } } - }, - "delete": { - "operationId": "deleteDiscountsId", + } + }, + "/reports/exports/reconciliation": { + "get": { + "operationId": "getReportsExportsReconciliation", "tags": [ - "discounts" + "reports" ], - "summary": "Delete a discount code (soft delete)", + "summary": "CSV export of the CFO financial reconciliation", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -6869,9 +6730,62 @@ ], "parameters": [ { - "name": "id", - "in": "path", + "name": "date_from", + "in": "query", + "required": true, + "description": "ISO 8601 (start, on Sale.created_at)", + "schema": { + "type": "string" + } + }, + { + "name": "date_to", + "in": "query", "required": true, + "description": "ISO 8601 (end)", + "schema": { + "type": "string" + } + }, + { + "name": "match_status", + "in": "query", + "required": false, + "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", + "schema": { + "type": "string", + "enum": [ + "OK", + "MISSING_INVOICE", + "MISSING_CUFE", + "AMOUNT_MISMATCH", + "MISSING_PAYMENT" + ] + } + }, + { + "name": "provider", + "in": "query", + "required": false, + "description": "Filter by payment_provider (e.g. mercadopago)", + "schema": { + "type": "string" + } + }, + { + "name": "event", + "in": "query", + "required": false, + "description": "Filter by event id", + "schema": { + "type": "string" + } + }, + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "Filter by event date id (takes precedence over `event`)", "schema": { "type": "string" } @@ -6940,13 +6854,13 @@ } } }, - "/webhooks": { + "/reports/exports/attendees": { "get": { - "operationId": "getWebhooks", + "operationId": "getReportsExportsAttendees", "tags": [ - "webhooks" + "reports" ], - "summary": "List workspace webhooks", + "summary": "Export attendees per ticket, with filters (max 5000)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -6958,48 +6872,82 @@ ], "parameters": [ { - "name": "limit", + "name": "event", "in": "query", "required": false, - "description": "1-100, default 20", + "description": "Filter by Event.id", "schema": { - "type": "integer", - "default": 20 + "type": "string" } }, { - "name": "cursor", + "name": "eventDate", "in": "query", "required": false, + "description": "Filter by EventDate.id", "schema": { "type": "string" } }, { - "name": "X-Workspace-Id", - "in": "header", + "name": "from", + "in": "query", "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "description": "ISO 8601 — from (on Sale.created_at)", "schema": { "type": "string" } - } - ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Webhook" - } - }, - "page": { + }, + { + "name": "to", + "in": "query", + "required": false, + "description": "ISO 8601 — to (on Sale.created_at)", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", + "schema": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExportAttendee" + } + }, + "page": { "$ref": "#/components/schemas/Page" } }, @@ -7052,13 +7000,15 @@ } } } - }, - "post": { - "operationId": "postWebhooks", + } + }, + "/reports/exports/buyers": { + "get": { + "operationId": "getReportsExportsBuyers", "tags": [ - "webhooks" + "reports" ], - "summary": "Create a webhook (returns the signingSecret only once)", + "summary": "Export buyers, with filters (max 5000)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7069,6 +7019,58 @@ } ], "parameters": [ + { + "name": "event", + "in": "query", + "required": false, + "description": "Filter by Event.id", + "schema": { + "type": "string" + } + }, + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "Filter by EventDate.id", + "schema": { + "type": "string" + } + }, + { + "name": "from", + "in": "query", + "required": false, + "description": "ISO 8601 — from (on Sale.created_at)", + "schema": { + "type": "string" + } + }, + { + "name": "to", + "in": "query", + "required": false, + "description": "ISO 8601 — to (on Sale.created_at)", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", + "schema": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -7079,18 +7081,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/WebhookCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -7098,11 +7090,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/WebhookCreated" + "type": "array", + "items": { + "$ref": "#/components/schemas/ExportBuyer" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -7151,13 +7150,13 @@ } } }, - "/webhooks/{id}": { - "delete": { - "operationId": "deleteWebhooksId", + "/reports/exports/subscribers": { + "get": { + "operationId": "getReportsExportsSubscribers", "tags": [ - "webhooks" + "reports" ], - "summary": "Delete a workspace webhook", + "summary": "Export subscribers (max 5000)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7168,14 +7167,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -7192,7 +7183,18 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExportSubscriber" + } + } + }, + "required": [ + "data" + ] } } } @@ -7238,14 +7240,16 @@ } } } - }, - "patch": { - "operationId": "patchWebhooksId", + } + }, + "/reports/by-event": { + "get": { + "operationId": "getReportsByEvent", "tags": [ - "webhooks" + "reports" ], - "summary": "Edit a webhook without rotating its signing secret", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nChanges `url`, `events` or `active` while keeping the `signingSecret`. It is the alternative to `DELETE` + `POST`, which rotates the secret and forces the integrator on the other end to reconfigure signature verification.", + "summary": "Sales KPIs per workspace event", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7256,13 +7260,39 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "from", + "in": "query", + "required": false, + "description": "ISO 8601, filters Sale.created_at (gte)", + "schema": { + "type": "string" + } + }, + { + "name": "to", + "in": "query", + "required": false, + "description": "ISO 8601, filters Sale.created_at (lte)", "schema": { "type": "string" } }, + { + "name": "status", + "in": "query", + "required": false, + "description": "PENDING|CONFIRMED (default)|ABANDONED|CANCELLED|REFUNDED", + "schema": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -7273,16 +7303,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/WebhookUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -7292,7 +7312,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Webhook" + "type": "array", + "items": { + "$ref": "#/components/schemas/ReportByEventRow" + } } }, "required": [ @@ -7302,6 +7325,16 @@ } } }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "401": { "description": "Missing or invalid credential.", "content": { @@ -7345,15 +7378,14 @@ } } }, - "/membership-plans/{id}/subscribers": { + "/reports/timeseries": { "get": { - "operationId": "getMembershipPlansIdSubscribers", + "operationId": "getReportsTimeseries", "tags": [ - "membership-plans", - "subscriptions" + "reports" ], - "summary": "List subscribers of a membership plan", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Time series of CONFIRMED sales per bucket (day|week|month)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7364,43 +7396,42 @@ ], "parameters": [ { - "name": "id", - "in": "path", + "name": "interval", + "in": "query", "required": true, + "description": "day | week | month", "schema": { - "type": "string" + "type": "string", + "enum": [ + "day", + "week", + "month" + ] } }, { - "name": "status", + "name": "from", "in": "query", "required": false, - "description": "PENDING|ACTIVE|EXPIRED|CANCELLED|PAUSED", + "description": "ISO 8601, filters Sale.created_at (gte)", "schema": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] + "type": "string" } }, { - "name": "limit", + "name": "to", "in": "query", "required": false, - "description": "1-100, default 20", + "description": "ISO 8601, filters Sale.created_at (lte)", "schema": { - "type": "integer", - "default": 20 + "type": "string" } }, { - "name": "cursor", + "name": "event", "in": "query", "required": false, + "description": "Workspace event ID (optional)", "schema": { "type": "string" } @@ -7426,21 +7457,27 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Subscriber" + "$ref": "#/components/schemas/ReportTimeseriesRow" } - }, - "page": { - "$ref": "#/components/schemas/Page" } }, "required": [ - "data", - "page" + "data" ] } } } }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "401": { "description": "Missing or invalid credential.", "content": { @@ -7484,15 +7521,14 @@ } } }, - "/subscriptions/{id}/cancel": { - "post": { - "operationId": "postSubscriptionsIdCancel", + "/reports/financials": { + "get": { + "operationId": "getReportsFinancials", "tags": [ - "subscriptions", - "membership-plans" + "reports" ], - "summary": "Cancel a membership subscription", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Financial statement per event date: gross, costs, and net payable", + "description": "One row per event date (event_date) with the financial breakdown of its confirmed sales — gross collected, platform fee + VAT (IVA), face value, payment gateway fee (actual for MercadoPago, rate-estimated for Wompi or Bold), 4x1000 tax, and net payable — plus the status of the associated settlement. If wompiSalesWithoutRate > 0, the gateway fee for some Wompi or Bold sales could not be estimated and the net amount is overstated.", "security": [ { "apiKey": [] @@ -7503,13 +7539,27 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "event", + "in": "query", + "required": false, + "description": "Filter by event id", "schema": { "type": "string" } }, + { + "name": "past", + "in": "query", + "required": false, + "description": "true = only event dates that already took place (settleable); false = upcoming ones", + "schema": { + "type": "string", + "enum": [ + "true", + "false" + ] + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -7529,7 +7579,16 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SubscriptionCancelResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/ReportFinancialsRow" + } + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } } }, "required": [ @@ -7539,8 +7598,8 @@ } } }, - "401": { - "description": "Missing or invalid credential.", + "400": { + "description": "Bad request: malformed parameters.", "content": { "application/json": { "schema": { @@ -7549,8 +7608,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -7559,8 +7618,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -7569,8 +7628,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -7579,8 +7638,8 @@ } } }, - "502": { - "description": "The external provider failed to complete the operation.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -7592,14 +7651,14 @@ } } }, - "/sales/{id}/tickets": { + "/settlements": { "get": { - "operationId": "getSalesIdTickets", + "operationId": "getSettlements", "tags": [ - "sales" + "settlements" ], - "summary": "List the individual tickets of a sale", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Workspace settlements (payouts to the organizer)", + "description": "Lists the settlements visible to the organization (SENT, AWAITING_PAYMENT, PAID) with their standard id, amount, event/event date, and payment proofs. Download the files with `GET /settlements/{id}/document` (PDF) and `GET /settlements/{id}/proofs/{fileName}` (bank transfer proofs).", "security": [ { "apiKey": [] @@ -7610,9 +7669,43 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "event", + "in": "query", + "required": false, + "description": "Filter by event id", + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "description": "SENT|AWAITING_PAYMENT|PAID", + "schema": { + "type": "string", + "enum": [ + "SENT", + "AWAITING_PAYMENT", + "PAID" + ] + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1..100 (default 20)", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "description": "Id of the last row of the previous page", "schema": { "type": "string" } @@ -7638,17 +7731,31 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/SaleTicket" + "$ref": "#/components/schemas/Settlement" } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } } }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "401": { "description": "Missing or invalid credential.", "content": { @@ -7692,14 +7799,14 @@ } } }, - "/sales/{id}/attempts": { + "/settlements/{id}": { "get": { - "operationId": "getSalesIdAttempts", + "operationId": "getSettlementsId", "tags": [ - "sales" + "settlements" ], - "summary": "List a sale's payment attempt history", - "description": "Minimum role: `STAFF`. One event per payment movement reported by the gateway (approved, declined, or a later refund), ordered from newest to oldest. It exists to answer \"why didn't this sale go through?\" without leaving the API: `Sale.status` only reflects the final outcome, and from `GET /sales/{id}` a `CANCELLED`/`ABANDONED` sale with `confirmedAt: null` is indistinguishable from an order that simply expired — see the derived `failureReason`/`paymentStatus`/`declineCode` fields on `SaleDetail`.", + "summary": "Get a settlement", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nThe same resource the list returns, by id. Only settlements already sent to the organizer (`SENT`, `AWAITING_PAYMENT`, `PAID`): internal master statuses are not exposed. Download the files with `GET /settlements/{id}/document` and `GET /settlements/{id}/proofs/{fileName}`.", "security": [ { "apiKey": [] @@ -7736,10 +7843,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PaymentAttempt" - } + "$ref": "#/components/schemas/Settlement" } }, "required": [ @@ -7792,14 +7896,14 @@ } } }, - "/tickets/{ticketCode}": { - "patch": { - "operationId": "patchTicketsTicketCode", + "/settlements/{id}/document": { + "get": { + "operationId": "getSettlementsIdDocument", "tags": [ - "tickets" + "settlements" ], - "summary": "Reassign a sold ticket to another date or ticket type", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nMoves an ALREADY SOLD ticket to another `ticketTypeId` and/or to the `eventDateId` date (at least one of the two is required). Intended for a postponement: moving buyers from the old date to the new one without refunding and reselling.\n\nWith only `eventDateId`, the target ticket type is resolved by NAME (the same type the ticket had, on the new date); if the target date doesn't have exactly one type with that name, it responds 422 and you must pass an explicit `ticketTypeId`.\n\nIt does NOT charge or refund the price difference if the new type costs something else: the ticket's `unitPrice`/`subtotal` keep the sale's ORIGINAL price. If money needs adjusting, use `POST /sales/{id}/refund` separately.\n\nIt does NOT reissue the QR: `ticketCode` is always preserved (it is what the buyer already has printed, in Wallet and in their email).\n\nIt does NOT notify the buyer. This endpoint only moves data; to resend the updated ticket use `POST /tickets/{ticketCode}/resend`, and for a bulk postponement notice, use the communications module.\n\nA ticket that is already checked in, or that belongs to a sale that is not CONFIRMED, responds 409 and is not reassigned. A ticket refunded by item (or whose seat was blocked after a refund) responds 409 `TICKET_REFUNDED`.\n\nNUMBERED SEATING (seats.io): if the target date has numbered seating, `seatLabel` is REQUIRED (409 `SEAT_REQUIRED` if missing) — the server never picks a seat on its own. The seat is validated and booked in seats.io before moving the ticket; if it is no longer available, it responds 409 `SEAT_UNAVAILABLE` without changing anything. If the ticket held a numbered seat on the source date, that seat is released after the move is confirmed.", + "summary": "Download a settlement PDF", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Files live in a private bucket, so the response is a **302** to a signed URL valid for 5 minutes (the client must follow the redirect; the `storage_path` is never exposed). Only settlements visible to the organization (SENT, AWAITING_PAYMENT, PAID) and within the key's `event_scope`.", "security": [ { "apiKey": [] @@ -7810,7 +7914,7 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", "in": "path", "required": true, "schema": { @@ -7827,37 +7931,12 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TicketReassign" - } - } - } - }, "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/SaleItem" - } - }, - "required": [ - "data" - ] - } - } - } + "302": { + "description": "Redirect to the signed URL (5 min TTL) of the PDF, with Content-Disposition: attachment." }, "401": { - "description": "Missing or invalid credential.", + "description": "Invalid or missing credential.", "content": { "application/json": { "schema": { @@ -7867,7 +7946,7 @@ } }, "403": { - "description": "Insufficient role or resource not accessible.", + "description": "Insufficient role (< ADMIN).", "content": { "application/json": { "schema": { @@ -7877,7 +7956,7 @@ } }, "404": { - "description": "Resource does not exist or is out of scope.", + "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no document yet.", "content": { "application/json": { "schema": { @@ -7886,8 +7965,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "502": { + "description": "Could not sign the storage URL.", "content": { "application/json": { "schema": { @@ -7896,18 +7975,8 @@ } } }, - "422": { - "description": "Operation error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "502": { - "description": "The external provider failed to complete the operation.", + "503": { + "description": "Storage is not configured.", "content": { "application/json": { "schema": { @@ -7919,14 +7988,14 @@ } } }, - "/tickets/{ticketCode}/resend": { - "post": { - "operationId": "postTicketsTicketCodeResend", + "/settlements/{id}/proofs/{fileName}": { + "get": { + "operationId": "getSettlementsIdProofsFileName", "tags": [ - "tickets" + "settlements" ], - "summary": "Resend the confirmation email with the ticket", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Download a settlement payment proof", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. `fileName` is the same value returned in `paymentProofs[].fileName` by `GET /settlements` (URL-encoded). Like `/document`, it responds with a **302** to a signed URL, valid for 5 minutes, in the private bucket.", "security": [ { "apiKey": [] @@ -7937,7 +8006,15 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "fileName", "in": "path", "required": true, "schema": { @@ -7955,26 +8032,11 @@ } ], "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ResendTicket" - } - }, - "required": [ - "data" - ] - } - } - } + "302": { + "description": "Redirect to the signed URL (5 min TTL) of the payment proof, with Content-Disposition: attachment." }, "401": { - "description": "Missing or invalid credential.", + "description": "Invalid or missing credential.", "content": { "application/json": { "schema": { @@ -7984,7 +8046,7 @@ } }, "403": { - "description": "Insufficient role or resource not accessible.", + "description": "Insufficient role (< ADMIN).", "content": { "application/json": { "schema": { @@ -7994,17 +8056,7 @@ } }, "404": { - "description": "Resource does not exist or is out of scope.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no payment proof with that name.", "content": { "application/json": { "schema": { @@ -8013,8 +8065,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "502": { + "description": "Could not sign the storage URL.", "content": { "application/json": { "schema": { @@ -8023,8 +8075,8 @@ } } }, - "502": { - "description": "The external provider failed to complete the operation.", + "503": { + "description": "Storage is not configured.", "content": { "application/json": { "schema": { @@ -8036,14 +8088,14 @@ } } }, - "/tickets/{ticketCode}/checkin": { - "post": { - "operationId": "postTicketsTicketCodeCheckin", + "/discounts": { + "get": { + "operationId": "getDiscounts", "tags": [ - "tickets" + "discounts" ], - "summary": "Check in a ticket at the door", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List workspace discount codes", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8054,9 +8106,37 @@ ], "parameters": [ { - "name": "ticketCode", - "in": "path", - "required": true, + "name": "event", + "in": "query", + "required": false, + "description": "event id to filter by", + "schema": { + "type": "string" + } + }, + { + "name": "active", + "in": "query", + "required": false, + "description": "true|false", + "schema": { + "type": "boolean" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, "schema": { "type": "string" } @@ -8071,16 +8151,6 @@ } } ], - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CheckinRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -8090,11 +8160,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CheckinResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/Discount" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -8130,16 +8207,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -8151,16 +8218,14 @@ } } } - } - }, - "/tickets/{ticketCode}/access": { - "get": { - "operationId": "getTicketsTicketCodeAccess", + }, + "post": { + "operationId": "postDiscounts", "tags": [ - "tickets" + "discounts" ], - "summary": "Check a ticket's validity without consuming it", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Create a discount code", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8170,14 +8235,6 @@ } ], "parameters": [ - { - "name": "ticketCode", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -8188,8 +8245,18 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DiscountCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -8197,7 +8264,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketAccess" + "$ref": "#/components/schemas/Discount" } }, "required": [ @@ -8237,6 +8304,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -8250,14 +8327,14 @@ } } }, - "/api-keys": { - "get": { - "operationId": "getApiKeys", + "/discounts/{id}": { + "patch": { + "operationId": "patchDiscountsId", "tags": [ - "api-keys" + "discounts" ], - "summary": "List my API keys", - "description": "Lists the authenticated user's API keys (never the hash or the plaintext secret).", + "summary": "Update a discount code", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8268,19 +8345,9 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -8295,6 +8362,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DiscountUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -8304,18 +8381,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ApiKey" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/Discount" } }, "required": [ - "data", - "page" + "data" ] } } @@ -8363,13 +8433,13 @@ } } }, - "post": { - "operationId": "postApiKeys", + "delete": { + "operationId": "deleteDiscountsId", "tags": [ - "api-keys" + "discounts" ], - "summary": "Mint an API key (returns the plaintext exactly once)", - "description": "Creates a service API key for the authenticated user. scope=\"read\" (default) only allows GET/HEAD; scope=\"write\" enables mutations according to the user role. The plaintext secret only appears in this response.", + "summary": "Delete a discount code (soft delete)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8380,40 +8450,30 @@ ], "parameters": [ { - "name": "X-Workspace-Id", - "in": "header", - "required": false, + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiKeyCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/ApiKeyCreated" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -8461,14 +8521,14 @@ } } }, - "/api-keys/{id}": { - "delete": { - "operationId": "deleteApiKeysId", + "/webhooks": { + "get": { + "operationId": "getWebhooks", "tags": [ - "api-keys" + "webhooks" ], - "summary": "Revoke one of my API keys", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List workspace webhooks", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8479,9 +8539,19 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, "schema": { "type": "string" } @@ -8502,7 +8572,22 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Webhook" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] } } } @@ -8548,30 +8633,45 @@ } } } - } - }, - "/customer/auth/request": { + }, "post": { - "operationId": "postCustomerAuthRequest", + "operationId": "postWebhooks", "tags": [ - "customer", - "auth" + "webhooks" + ], + "summary": "Create a webhook (returns the signingSecret only once)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } ], - "summary": "Request an access code to sign in (or create an account)", - "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", - "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomerAuthRequest" + "$ref": "#/components/schemas/WebhookCreate" } } } }, "responses": { - "202": { + "201": { "description": "OK", "content": { "application/json": { @@ -8579,7 +8679,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerAuthRequestResult" + "$ref": "#/components/schemas/WebhookCreated" } }, "required": [ @@ -8620,80 +8720,66 @@ } }, "422": { - "description": "Operation error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } } } } } }, - "/customer/auth/verify": { - "post": { - "operationId": "postCustomerAuthVerify", + "/webhooks/{id}": { + "delete": { + "operationId": "deleteWebhooksId", "tags": [ - "customer", - "auth" + "webhooks" ], - "summary": "Exchange the access code for a buyer session", - "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", - "security": [], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerAuthVerify" - } + "summary": "Delete a workspace webhook", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" } } - }, + ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/CustomerAuthVerifyResult" - } - }, - "required": [ - "data" - ] + "type": "object" } } } }, "401": { - "description": "Operation error.", + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -8723,47 +8809,24 @@ } }, "422": { - "description": "Operation error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } } } } - } - }, - "/customer/me": { - "get": { - "operationId": "getCustomerMe", + }, + "patch": { + "operationId": "patchWebhooksId", "tags": [ - "customer" + "webhooks" ], - "summary": "Authenticated buyer identity", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: if sent, it must be an enterprise service key (403 otherwise); without a key, it responds the same for the buyer acting on their own.", + "summary": "Edit a webhook without rotating its signing secret", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nChanges `url`, `events` or `active` while keeping the `signingSecret`. It is the alternative to `DELETE` + `POST`, which rotates the secret and forces the integrator on the other end to reconfigure signature verification.", "security": [ { "apiKey": [] @@ -8773,6 +8836,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -8783,6 +8854,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -8792,7 +8873,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerMe" + "$ref": "#/components/schemas/Webhook" } }, "required": [ @@ -8845,14 +8926,15 @@ } } }, - "/customer/tickets": { + "/membership-plans/{id}/subscribers": { "get": { - "operationId": "getCustomerTickets", + "operationId": "getMembershipPlansIdSubscribers", "tags": [ - "customer" + "membership-plans", + "subscriptions" ], - "summary": "Buyer's tickets", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, results are additionally scoped to the workspace pinned to the key (its own events AND those where it is listed as a linked artist); without a key, returns ALL of the buyer's tickets, not limited to any workspace. Only CONFIRMED sales, matched by the buyer's account or purchase email.", + "summary": "List subscribers of a membership plan", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8862,6 +8944,30 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "description": "PENDING|ACTIVE|EXPIRED|CANCELLED|PAUSED", + "schema": { + "type": "string", + "enum": [ + "PENDING", + "ACTIVE", + "EXPIRED", + "CANCELLED", + "PAUSED" + ] + } + }, { "name": "limit", "in": "query", @@ -8901,7 +9007,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/CustomerSale" + "$ref": "#/components/schemas/Subscriber" } }, "page": { @@ -8959,14 +9065,15 @@ } } }, - "/customer/tickets/{id}": { - "get": { - "operationId": "getCustomerTicketsId", + "/subscriptions/{id}/cancel": { + "post": { + "operationId": "postSubscriptionsIdCancel", "tags": [ - "customer" + "subscriptions", + "membership-plans" ], - "summary": "Detail of a buyer's ticket (deep link)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, results are additionally scoped to the workspace pinned to the key; without a key, any of the buyer's own tickets is visible, not limited to a workspace. `{id}` accepts the sale id or its `reference`. Returns 404 if the ticket does not belong to the session's buyer or falls outside the scope.", + "summary": "Cancel a membership subscription", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -9003,7 +9110,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSale" + "$ref": "#/components/schemas/SubscriptionCancelResult" } }, "required": [ @@ -9052,18 +9159,28 @@ } } } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/customer/tickets/{id}/cancel": { - "post": { - "operationId": "postCustomerTicketsIdCancel", + "/sales/{id}/tickets": { + "get": { + "operationId": "getSalesIdTickets", "tags": [ - "customer" + "sales" ], - "summary": "Cancel the buyer's own purchase (only if not yet paid)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (see /customer/tickets). Only cancels PENDING sales (releases inventory and seats). A CONFIRMED sale responds 409 with code `REFUND_REQUIRED`: refunds are handled by the organizer. `{id}` accepts the sale id or its `reference`.", + "summary": "List the individual tickets of a sale", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -9100,7 +9217,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerTicketCancelResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/SaleTicket" + } } }, "required": [ @@ -9140,16 +9260,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -9163,14 +9273,14 @@ } } }, - "/customer/logout": { - "post": { - "operationId": "postCustomerLogout", + "/sales/{id}/attempts": { + "get": { + "operationId": "getSalesIdAttempts", "tags": [ - "customer" + "sales" ], - "summary": "Sign out the buyer session", - "description": "Revokes the session presented in `X-Customer-Session`: the token stops working immediately. Idempotent. The enterprise service API key is OPTIONAL: if sent, it must be an enterprise service key.", + "summary": "List a sale's payment attempt history", + "description": "Minimum role: `STAFF`. One event per payment movement reported by the gateway (approved, declined, or a later refund), ordered from newest to oldest. It exists to answer \"why didn't this sale go through?\" without leaving the API: `Sale.status` only reflects the final outcome, and from `GET /sales/{id}` a `CANCELLED`/`ABANDONED` sale with `confirmedAt: null` is indistinguishable from an order that simply expired — see the derived `failureReason`/`paymentStatus`/`declineCode` fields on `SaleDetail`.", "security": [ { "apiKey": [] @@ -9180,6 +9290,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9199,7 +9317,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerLogout" + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentAttempt" + } } }, "required": [ @@ -9252,14 +9373,14 @@ } } }, - "/api/customer-auth/enterprise-exchange": { - "post": { - "operationId": "postApiCustomerAuthEnterpriseExchange", + "/tickets/{ticketCode}": { + "patch": { + "operationId": "patchTicketsTicketCode", "tags": [ - "customer" + "tickets" ], - "summary": "Exchange the headless SSO one-time token for a session token", - "description": "Server-to-server: requires an enterprise service API key (Bearer or x-api-key). Exchanges the one-time token issued by /api/customer-auth/enterprise-return (single-use, 60 s TTL) for the buyer's session token. Plain body, no { data } envelope.", + "summary": "Reassign a sold ticket to another date or ticket type", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nMoves an ALREADY SOLD ticket to another `ticketTypeId` and/or to the `eventDateId` date (at least one of the two is required). Intended for a postponement: moving buyers from the old date to the new one without refunding and reselling.\n\nWith only `eventDateId`, the target ticket type is resolved by NAME (the same type the ticket had, on the new date); if the target date doesn't have exactly one type with that name, it responds 422 and you must pass an explicit `ticketTypeId`.\n\nIt does NOT charge or refund the price difference if the new type costs something else: the ticket's `unitPrice`/`subtotal` keep the sale's ORIGINAL price. If money needs adjusting, use `POST /sales/{id}/refund` separately.\n\nIt does NOT reissue the QR: `ticketCode` is always preserved (it is what the buyer already has printed, in Wallet and in their email).\n\nIt does NOT notify the buyer. This endpoint only moves data; to resend the updated ticket use `POST /tickets/{ticketCode}/resend`, and for a bulk postponement notice, use the communications module.\n\nA ticket that is already checked in, or that belongs to a sale that is not CONFIRMED, responds 409 and is not reassigned. A ticket refunded by item (or whose seat was blocked after a refund) responds 409 `TICKET_REFUNDED`.\n\nNUMBERED SEATING (seats.io): if the target date has numbered seating, `seatLabel` is REQUIRED (409 `SEAT_REQUIRED` if missing) — the server never picks a seat on its own. The seat is validated and booked in seats.io before moving the ticket; if it is no longer available, it responds 409 `SEAT_UNAVAILABLE` without changing anything. If the ticket held a numbered seat on the source date, that seat is released after the move is confirmed.", "security": [ { "apiKey": [] @@ -9268,13 +9389,15 @@ "apiKeyHeader": [] } ], - "servers": [ - { - "url": "/", - "description": "Canonical host (outside /api/v1)" - } - ], "parameters": [ + { + "name": "ticketCode", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9290,70 +9413,11 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EnterpriseExchangeRequest" + "$ref": "#/components/schemas/TicketReassign" } } } }, - "responses": { - "200": { - "description": "Buyer session exchanged.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EnterpriseExchangeResponse" - } - } - } - }, - "401": { - "description": "Missing or invalid API key, or invalid/expired token." - }, - "403": { - "description": "The API key doesn't belong to an enterprise service user, or the token was minted for another workspace." - }, - "422": { - "description": "Invalid body." - } - } - } - }, - "/customer/membership": { - "get": { - "operationId": "getCustomerMembership", - "tags": [ - "customer" - ], - "summary": "Buyer membership status in a workspace", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the workspace is the one pinned to it (`workspaceId` is ignored); without a key, `workspaceId` is REQUIRED (422 if missing). `active` is true only with an ACTIVE, unexpired membership. If none is current, `membership` returns the most recent one (expired, cancelled or pending payment) so the landing page can choose the CTA; `null` = never a member of that workspace.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } - ], - "parameters": [ - { - "name": "workspaceId", - "in": "query", - "required": false, - "description": "Required only without an enterprise service API key. Ignored with a key.", - "schema": { - "type": "string" - } - }, - { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", - "schema": { - "type": "string" - } - } - ], "responses": { "200": { "description": "OK", @@ -9363,7 +9427,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerMembershipState" + "$ref": "#/components/schemas/SaleItem" } }, "required": [ @@ -9403,6 +9467,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Operation error.", "content": { @@ -9412,19 +9486,28 @@ } } } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/customer/subscriptions": { + "/tickets/{ticketCode}/resend": { "post": { - "operationId": "postCustomerSubscriptions", + "operationId": "postTicketsTicketCodeResend", "tags": [ - "customer", - "subscriptions" + "tickets" ], - "summary": "Start a membership sign-up (returns the payment URL)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the plan must belong to the workspace pinned to it; without a key, any active plan by its id (the plan itself determines the sign-up workspace). Validates that the buyer can acquire it and returns the membership checkout URL on the canonical host (the platform completes the charge). On return, re-read `GET /customer/membership`.", + "summary": "Resend the confirmation email with the ticket", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -9434,6 +9517,14 @@ } ], "parameters": [ + { + "name": "ticketCode", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9444,16 +9535,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerSubscribeRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -9463,7 +9544,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSubscribeResult" + "$ref": "#/components/schemas/ResendTicket" } }, "required": [ @@ -9522,19 +9603,28 @@ } } } - } - } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } } }, - "/customer/subscriptions/cancel": { + "/tickets/{ticketCode}/checkin": { "post": { - "operationId": "postCustomerSubscriptionsCancel", + "operationId": "postTicketsTicketCodeCheckin", "tags": [ - "customer", - "subscriptions" + "tickets" ], - "summary": "Cancel the buyer's own membership", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the workspace is the one pinned to it (any `workspaceId` in the body is ignored); without a key, `workspaceId` is REQUIRED in the body (422 if missing). The membership is ALWAYS resolved from the buyer session (a CustomerMembership id is never accepted). It first cancels the recurring charge at the provider and then marks the membership as CANCELLED. Idempotent.", + "summary": "Check in a ticket at the door", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -9544,6 +9634,14 @@ } ], "parameters": [ + { + "name": "ticketCode", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9555,11 +9653,11 @@ } ], "requestBody": { - "required": true, + "required": false, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomerSubscriptionCancelRequest" + "$ref": "#/components/schemas/CheckinRequest" } } } @@ -9573,7 +9671,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSubscriptionCancelResult" + "$ref": "#/components/schemas/CheckinResult" } }, "required": [ @@ -9604,7 +9702,7 @@ } }, "404": { - "description": "Operation error.", + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -9613,8 +9711,8 @@ } } }, - "422": { - "description": "Operation error.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -9623,8 +9721,8 @@ } } }, - "502": { - "description": "The external provider failed to complete the operation.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -9634,16 +9732,14 @@ } } } - } - }, - "/customer/profile": { - "get": { - "operationId": "getCustomerProfile", + }, + "delete": { + "operationId": "deleteTicketsTicketCodeCheckin", "tags": [ - "customer" + "tickets" ], - "summary": "Buyer profile (name and phone)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (issue #673): this endpoint is scoped only by the session's `customer.id`, so it behaves identically with or without a key.", + "summary": "Undo a ticket check-in (destructive)", + "description": "DESTRUCTIVE: reverts a door check-in so the ticket is valid again. Use it to fix a wrong scan; it is recorded in the audit log as CHECKIN_UNDO. Requires `ADMIN` (not `STAFF`): a checked-in ticket blocks cancelling its sale, and undoing the check-in reopens that path. The show's validation window does not apply. Idempotent: a ticket that is not checked in answers 200 with `undone: false`. 409 CHECKIN_CHANGED when the check-in changed between the read and the write (another undo or a new scan): re-read the ticket and retry. Minimum role: `ADMIN`.", "security": [ { "apiKey": [] @@ -9652,7 +9748,16 @@ "apiKeyHeader": [] } ], + "x-ft-destructive": true, "parameters": [ + { + "name": "ticketCode", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9672,7 +9777,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerProfile" + "$ref": "#/components/schemas/CheckinUndoResult" } }, "required": [ @@ -9712,6 +9817,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -9723,14 +9838,16 @@ } } } - }, - "patch": { - "operationId": "patchCustomerProfile", + } + }, + "/tickets/{ticketCode}/access": { + "get": { + "operationId": "getTicketsTicketCodeAccess", "tags": [ - "customer" + "tickets" ], - "summary": "Update the buyer profile", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Only updates the session's buyer: name and phone. The email cannot be changed (it is the account identity). Omitted fields are left untouched.", + "summary": "Check a ticket's validity without consuming it", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -9740,6 +9857,14 @@ } ], "parameters": [ + { + "name": "ticketCode", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9750,16 +9875,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerProfileUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -9769,7 +9884,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerProfile" + "$ref": "#/components/schemas/TicketAccess" } }, "required": [ @@ -9822,15 +9937,14 @@ } } }, - "/customer/orders/{id}/payment": { - "post": { - "operationId": "postCustomerOrdersIdPayment", + "/api-keys": { + "get": { + "operationId": "getApiKeys", "tags": [ - "customer", - "orders" + "api-keys" ], - "summary": "Open payment for a reservation (Bold or MercadoPago, depending on the event)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). The payment rail is chosen on the SERVER: Bold-eligible events (legend plan + allowlist) return the SIGNED configuration of the embedded Bold Payment Button (`apiKey` + `renderMode: \"embedded\"` + `integritySignature`, …), which the landing page mounts with `new BoldCheckout({...})`; all others return `publicKey` + `amount` + `currency` + `reference` + `payerEmail` to mount the MercadoPago Payment Brick (`POST .../payment/card` to charge, `POST .../payment/pse` for PSE). The landing page tells the rails apart by the SHAPE of the response (`apiKey`/`renderMode` ⇒ Bold, `publicKey` ⇒ MercadoPago), never by a separate flag. The sale must belong to the session buyer (and, with a key, to the workspace pinned to it): anything else is 404. Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, or (Bold only) the event has no legend plan or a payment attempt is already in flight with another gateway. `{id}` accepts the sale id or its `reference`. Limited to 10 opens per minute per buyer (429 with `Retry-After`).", + "summary": "List my API keys", + "description": "Lists the authenticated user's API keys (never the hash or the plaintext secret).", "security": [ { "apiKey": [] @@ -9841,27 +9955,28 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", "schema": { - "type": "string" + "type": "integer", + "default": 20 } }, { - "name": "X-Workspace-Id", - "in": "header", + "name": "cursor", + "in": "query", "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } }, { - "name": "X-Purchase-Session", + "name": "X-Workspace-Id", "in": "header", "required": false, - "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", "schema": { "type": "string" } @@ -9876,11 +9991,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderStartPayment" + "type": "array", + "items": { + "$ref": "#/components/schemas/ApiKey" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -9916,16 +10038,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -9935,40 +10047,16 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } - } } } - } - }, - "/customer/orders/{id}/payment/card": { + }, "post": { - "operationId": "postCustomerOrdersIdPaymentCard", + "operationId": "postApiKeys", "tags": [ - "customer", - "orders" + "api-keys" ], - "summary": "Charge with the MercadoPago Payment Brick token", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Receives the token the Payment Brick produced on the landing page's domain and charges through the Orders API using the sale amount (never one sent by the client); `payer.email` travels in the body but is ignored — the payer is ALWAYS the sale's. `status` is `approved`, `pending` (normal, may require additional authentication from the bank) or `rejected` (business decline; the reason is in `message`) — all three are returned with 200. With `rejected`, `saleAlive` tells what happened to the purchase: `false` = it was cancelled and a new one must be started; `true` = this payment was declined but the purchase is still pending because another payment is in progress on it (do not start a new purchase: wait and check the order). Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, a payment attempt is in flight with another gateway, the event only charges through Bold, or MercadoPago returned an error that cannot be classified as a decline. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 attempts per minute per buyer (429 with `Retry-After`).", + "summary": "Mint an API key (returns the plaintext exactly once)", + "description": "Creates a service API key for the authenticated user. scope=\"read\" (default) only allows GET/HEAD; scope=\"write\" enables mutations according to the user role. The plaintext secret only appears in this response.", "security": [ { "apiKey": [] @@ -9978,14 +10066,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -9994,15 +10074,6 @@ "schema": { "type": "string" } - }, - { - "name": "X-Purchase-Session", - "in": "header", - "required": false, - "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", - "schema": { - "type": "string" - } } ], "requestBody": { @@ -10010,13 +10081,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeRequest" + "$ref": "#/components/schemas/ApiKeyCreate" } } } }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -10024,7 +10095,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeResult" + "$ref": "#/components/schemas/ApiKeyCreated" } }, "required": [ @@ -10064,59 +10135,27 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { - "description": "Operation error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } } } } } }, - "/customer/orders/{id}/payment/pse": { - "post": { - "operationId": "postCustomerOrdersIdPaymentPse", + "/api-keys/{id}": { + "delete": { + "operationId": "deleteApiKeysId", "tags": [ - "customer", - "orders" + "api-keys" ], - "summary": "Open a PSE payment through MercadoPago (redirect)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Creates a MercadoPago preference restricted to PSE and returns `redirectUrl` (`init_point`): the landing page must REDIRECT the browser there, not mount it in an iframe. The buyer picks their bank and confirms the transfer inside MercadoPago; on return, they land on `GET /api/mp/return` (our domain), which issues a 302 to the `returnUrl` sent in `POST /customer/orders` — the landing page must call `GET /customer/orders/{id}` for the authoritative status, never infer it from the return URL. The sale is confirmed by webhook when the bank settles the payment (asynchronous: it may take a while). Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, a payment attempt is in flight with another gateway, or the event only charges through Bold. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 opens per minute per buyer (429 with `Retry-After`).", + "summary": "Revoke one of my API keys", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -10142,15 +10181,6 @@ "schema": { "type": "string" } - }, - { - "name": "X-Purchase-Session", - "in": "header", - "required": false, - "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", - "schema": { - "type": "string" - } } ], "responses": { @@ -10159,15 +10189,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoPse" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -10202,16 +10224,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -10221,69 +10233,32 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } - } } } } }, - "/customer/orders/{id}/release": { + "/customer/auth/request": { "post": { - "operationId": "postCustomerOrdersIdRelease", + "operationId": "postCustomerAuthRequest", "tags": [ "customer", - "orders" - ], - "summary": "Release a reservation the buyer will not pay for", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Abandons the PENDING sale and returns its inventory (and its seats) to stock, so the buyer can start over without waiting for the reservation to expire. It is the counterpart of `pending_sale_in_progress`: when `POST /customer/orders` rejects with that `reason`, the landing page can offer *continue paying* (`/payment`, idempotent) or *start over* (this route). It ONLY releases with evidence that nobody started the payment: if Bold reports any transaction, if a provider response is already stored, or if the payment goes through a rail we cannot query, it responds 409 with `details.reason` = `payment_in_flight` and the sale is left intact. If the gateway does not respond, 503 (`gateway_unreachable`): retry later. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 calls per minute per buyer.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } + "auth" ], - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", - "schema": { - "type": "string" + "summary": "Request an access code to sign in (or create an account)", + "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", + "security": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerAuthRequest" + } } } - ], + }, "responses": { - "200": { + "202": { "description": "OK", "content": { "application/json": { @@ -10291,7 +10266,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderRelease" + "$ref": "#/components/schemas/CustomerAuthRequestResult" } }, "required": [ @@ -10331,18 +10306,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -10371,56 +10336,30 @@ "$ref": "#/components/headers/RateLimitPolicy" } } - }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } } }, - "/customer/orders/{id}": { - "get": { - "operationId": "getCustomerOrdersId", + "/customer/auth/verify": { + "post": { + "operationId": "postCustomerAuthVerify", "tags": [ "customer", - "orders" - ], - "summary": "Status of a headless purchase (and its tickets, once paid)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). `{id}` accepts the `reference` (FT-…) or the sale id. If the sale is still PENDING and its payment goes through Bold, the authoritative payment status is re-read from Bold; between re-reads it responds with the internal status, which the webhook keeps up to date. `status` is `approved`, `pending` or `rejected`; `pending` is a NORMAL state (asynchronous payment methods take time) and the landing page must retry. `tickets` —with each ticket's `ticketCode`— is only present when `status` is `approved`. The purchase must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. The route MAY rate-limit polling and respond 429: honor `Retry-After` and apply backoff. Polling every ~2 s fits comfortably, but do not treat any threshold as a guarantee.", - "security": [ - { - "apiKey": [] - }, - { - "apiKeyHeader": [] - } + "auth" ], - "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, - { - "name": "X-Workspace-Id", - "in": "header", - "required": false, - "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", - "schema": { - "type": "string" + "summary": "Exchange the access code for a buyer session", + "description": "Public endpoint (no auth): credential bootstrap for the Device Authorization Grant (RFC 8628).", + "security": [], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerAuthVerify" + } } } - ], + }, "responses": { "200": { "description": "OK", @@ -10430,7 +10369,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderStatus" + "$ref": "#/components/schemas/CustomerAuthVerifyResult" } }, "required": [ @@ -10441,7 +10380,7 @@ } }, "401": { - "description": "Missing or invalid credential.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -10471,7 +10410,7 @@ } }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -10504,15 +10443,14 @@ } } }, - "/customer/purchase-sessions": { - "post": { - "operationId": "postCustomerPurchaseSessions", + "/customer/me": { + "get": { + "operationId": "getCustomerMe", "tags": [ - "customer", - "purchase-sessions" + "customer" ], - "summary": "Open the purchase session (only one live per buyer)", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, the event date must belong to the workspace pinned to it; otherwise 404). Opens THE buyer purchase session: there is ONLY one live per buyer across any tab or device, and the latest wins — the previous one becomes `superseded` (it can no longer create an order or start a new payment) and its seats.io hold is released, unless it backs a live sale. On seated event dates the server ISSUES the `holdToken` (mount the chart with `session: \"manual\"`) and sets `seatsDeadline`: each session gets up to 3 minutes and the budget is 3 attempts (9 CUMULATIVE minutes) per buyer and event date, summing all of their sessions within a 30-minute window, and it only runs while no order has been created. Once exhausted, it responds 429 with `error.code` `SEAT_BUDGET_EXHAUSTED`, `error.details.reason` `seat_budget_exhausted` and `error.details.retryAfterSeconds` (10-minute cooldown; also in the `Retry-After` header). If the SAME browser (`deviceKey`) reopens the SAME event date with its session alive, it gets that same session with 200 instead of 201. Only event dates on sale: published event and current event date (otherwise 404). Limits: 10 creations per minute per buyer, 30 per minute per IP when called without an API key, and a global ceiling per event date (429 `RATE_LIMITED`). Once the session is created, `POST /customer/orders` and the payment POSTs carry the `X-Purchase-Session: ` header; when the clock runs out, call `POST /customer/purchase-sessions/{id}/release`.", + "summary": "Authenticated buyer identity", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: if sent, it must be an enterprise service key (403 otherwise); without a key, it responds the same for the buyer acting on their own.", "security": [ { "apiKey": [] @@ -10532,36 +10470,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/PurchaseSessionCreateRequest" - } - } - } - }, "responses": { "200": { - "description": "The SAME browser (`deviceKey`) reopened the SAME event date while its session was still alive: that session is returned (same `holdToken`, same clock) and nothing was created.", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/PurchaseSessionCreated" - } - }, - "required": [ - "data" - ] - } - } - } - }, - "201": { "description": "OK", "content": { "application/json": { @@ -10569,7 +10479,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionCreated" + "$ref": "#/components/schemas/CustomerMe" } }, "required": [ @@ -10618,53 +10528,21 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } - } - }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/customer/purchase-sessions/{id}/release": { - "post": { - "operationId": "postCustomerPurchaseSessionsIdRelease", - "tags": [ - "customer", - "purchase-sessions" - ], - "summary": "Release the seats of a purchase session", - "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Marks the session `expired` and releases in seats.io the seats held with its `holdToken`. Idempotent: repeating it changes nothing. It NEVER releases a token that backs a live sale (pending payment or confirmed) nor that of a `converted` session: those seats belong to the order. Call it when the map clock runs out. Another buyer's session is 404.", - "security": [ - { - "apiKey": [] + } + } + } + }, + "/customer/tickets": { + "get": { + "operationId": "getCustomerTickets", + "tags": [ + "customer" + ], + "summary": "Buyer's tickets", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, results are additionally scoped to the workspace pinned to the key (its own events AND those where it is listed as a linked artist); without a key, returns ALL of the buyer's tickets, not limited to any workspace. Only CONFIRMED sales, matched by the buyer's account or purchase email.", + "security": [ + { + "apiKey": [] }, { "apiKeyHeader": [] @@ -10672,9 +10550,19 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, "schema": { "type": "string" } @@ -10698,11 +10586,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionStatus" + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerSale" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -10747,39 +10642,18 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } - } } } } }, - "/content/videos": { + "/customer/tickets/{id}": { "get": { - "operationId": "getContentVideos", + "operationId": "getCustomerTicketsId", "tags": [ - "content" + "customer" ], - "summary": "List the organization's published videos", - "description": "Only published videos that have finished processing (READY) in the active workspace. Does not include the playback id: to play one, request a token from `POST /content/playback-token`.", + "summary": "Detail of a buyer's ticket (deep link)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, results are additionally scoped to the workspace pinned to the key; without a key, any of the buyer's own tickets is visible, not limited to a workspace. `{id}` accepts the sale id or its `reference`. Returns 404 if the ticket does not belong to the session's buyer or falls outside the scope.", "security": [ { "apiKey": [] @@ -10790,19 +10664,9 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -10826,18 +10690,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentVideo" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/CustomerSale" } }, "required": [ - "data", - "page" + "data" ] } } @@ -10886,14 +10743,14 @@ } } }, - "/content/posts": { - "get": { - "operationId": "getContentPosts", + "/customer/tickets/{id}/cancel": { + "post": { + "operationId": "postCustomerTicketsIdCancel", "tags": [ - "content" + "customer" ], - "summary": "List the organization's community feed", - "description": "Posts from the active workspace, newest first, excluding deleted posts and posts scheduled for the future. A post with `locked: true` arrives redacted (`content`, `imageUrl`, `videoId`, `eventId` and `link` set to null, `commentsCount` set to 0): it is members-only content and the key does not represent a buyer with a current membership. Does not include `likes_count` (only visible to the workspace owner) or the post's internal author.", + "summary": "Cancel the buyer's own purchase (only if not yet paid)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (see /customer/tickets). Only cancels PENDING sales (releases inventory and seats). A CONFIRMED sale responds 409 with code `REFUND_REQUIRED`: refunds are handled by the organizer. `{id}` accepts the sale id or its `reference`.", "security": [ { "apiKey": [] @@ -10904,19 +10761,9 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -10940,18 +10787,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentPost" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/CustomerTicketCancelResult" } }, "required": [ - "data", - "page" + "data" ] } } @@ -10987,6 +10827,16 @@ } } }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -10998,14 +10848,16 @@ } } } - }, + } + }, + "/customer/logout": { "post": { - "operationId": "postContentPosts", + "operationId": "postCustomerLogout", "tags": [ - "content" + "customer" ], - "summary": "Publish community content (including articles)", - "description": "Creates a community post. `type=ARTICLE` requires `title` and `body` (Markdown) and builds a slug unique per organization (manual via `slug`, or derived from `title` if omitted); `type=TEXT`/`IMAGE` require `content` or `imageUrl`, same as the dashboard composer. Unlike the dashboard, this path does NOT resolve the link's Open Graph snapshot (`link` is always null in the response). Minimum role ADMIN, like every other `POST` in `/api/v1`. If the workspace has the `community_v2` flag enabled, publishing enqueues a notification to members in the same transaction; with a future `publishedAt`, the notification goes out when the post is published. The response does not change.", + "summary": "Sign out the buyer session", + "description": "Revokes the session presented in `X-Customer-Session`: the token stops working immediately. Idempotent. The enterprise service API key is OPTIONAL: if sent, it must be an enterprise service key.", "security": [ { "apiKey": [] @@ -11025,18 +10877,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPostCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -11044,7 +10886,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentPost" + "$ref": "#/components/schemas/CustomerLogout" } }, "required": [ @@ -11054,16 +10896,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -11094,16 +10926,6 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "422": { "description": "Request body/parameter validation failed.", "content": { @@ -11117,14 +10939,14 @@ } } }, - "/content/lives": { - "get": { - "operationId": "getContentLives", + "/api/customer-auth/enterprise-exchange": { + "post": { + "operationId": "postApiCustomerAuthEnterpriseExchange", "tags": [ - "content" + "customer" ], - "summary": "List the organization's live streams", - "description": "Live streams from the active workspace, newest first. `status: ACTIVE` is the one on air. Does not include the RTMP key or the playback ids.", + "summary": "Exchange the headless SSO one-time token for a session token", + "description": "Server-to-server: requires an enterprise service API key (Bearer or x-api-key). Exchanges the one-time token issued by /api/customer-auth/enterprise-return (single-use, 60 s TTL) for the buyer's session token. Plain body, no { data } envelope.", "security": [ { "apiKey": [] @@ -11133,25 +10955,13 @@ "apiKeyHeader": [] } ], - "parameters": [ - { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, + "servers": [ { - "name": "cursor", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - }, + "url": "/", + "description": "Canonical host (outside /api/v1)" + } + ], + "parameters": [ { "name": "X-Workspace-Id", "in": "header", @@ -11162,83 +10972,47 @@ } } ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentLive" - } - }, - "page": { - "$ref": "#/components/schemas/Page" - } - }, - "required": [ - "data", - "page" - ] - } + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnterpriseExchangeRequest" } } - }, - "401": { - "description": "Missing or invalid credential.", + } + }, + "responses": { + "200": { + "description": "Buyer session exchanged.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Error" + "$ref": "#/components/schemas/EnterpriseExchangeResponse" } } } }, - "403": { - "description": "Insufficient role or resource not accessible.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "401": { + "description": "Missing or invalid API key, or invalid/expired token." }, - "404": { - "description": "Resource does not exist or is out of scope.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "403": { + "description": "The API key doesn't belong to an enterprise service user, or the token was minted for another workspace." }, "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "description": "Invalid body." } } } }, - "/content/lives/{id}": { + "/customer/membership": { "get": { - "operationId": "getContentLivesId", + "operationId": "getCustomerMembership", "tags": [ - "content" + "customer" ], - "summary": "Live stream status", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Buyer membership status in a workspace", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the workspace is the one pinned to it (`workspaceId` is ignored); without a key, `workspaceId` is REQUIRED (422 if missing). `active` is true only with an ACTIVE, unexpired membership. If none is current, `membership` returns the most recent one (expired, cancelled or pending payment) so the landing page can choose the CTA; `null` = never a member of that workspace.", "security": [ { "apiKey": [] @@ -11249,9 +11023,10 @@ ], "parameters": [ { - "name": "id", - "in": "path", - "required": true, + "name": "workspaceId", + "in": "query", + "required": false, + "description": "Required only without an enterprise service API key. Ignored with a key.", "schema": { "type": "string" } @@ -11275,7 +11050,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentLive" + "$ref": "#/components/schemas/CustomerMembershipState" } }, "required": [ @@ -11316,7 +11091,7 @@ } }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -11328,14 +11103,15 @@ } } }, - "/content/playback-token": { + "/customer/subscriptions": { "post": { - "operationId": "postContentPlaybackToken", + "operationId": "postCustomerSubscriptions", "tags": [ - "content" + "customer", + "subscriptions" ], - "summary": "Signed token to play a video or a live stream", - "description": "Requires an enterprise service API key. `memberOnly` content additionally requires the `X-Customer-Session` header of a buyer with a current membership in the key's organization or, for a live stream tied to a show date, a CONFIRMED ticket for that date (otherwise 403 `MEMBERSHIP_REQUIRED`). Rate limited: 600 requests/min per key and 30/min per buyer (429 `RATE_LIMITED` with `Retry-After`). Content from another organization responds 404. Short-lived tokens: 30 minutes for live streams, 1 hour for videos.", + "summary": "Start a membership sign-up (returns the payment URL)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the plan must belong to the workspace pinned to it; without a key, any active plan by its id (the plan itself determines the sign-up workspace). Validates that the buyer can acquire it and returns the membership checkout URL on the canonical host (the platform completes the charge). On return, re-read `GET /customer/membership`.", "security": [ { "apiKey": [] @@ -11360,7 +11136,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContentPlaybackTokenRequest" + "$ref": "#/components/schemas/CustomerSubscribeRequest" } } } @@ -11374,7 +11150,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentPlaybackToken" + "$ref": "#/components/schemas/CustomerSubscribeResult" } }, "required": [ @@ -11414,39 +11190,18 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } } }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -11458,14 +11213,15 @@ } } }, - "/waitlist": { + "/customer/subscriptions/cancel": { "post": { - "operationId": "postWaitlist", + "operationId": "postCustomerSubscriptionsCancel", "tags": [ - "waitlist" + "customer", + "subscriptions" ], - "summary": "Join the per-city waitlist of an enterprise landing", - "description": "Requires an enterprise service API key; the entry belongs to the key's organization. `X-Customer-Session` is optional: when present the entry is linked to that buyer. `contact` must be an email or a phone number (7-15 digits; only a leading `+`, spaces and dashes besides digits — parentheses, dots, letters or extensions respond 422). Phones are stored without spaces or dashes. Idempotent per (organization, city folded without accents/case, contact normalized — lowercased email, or the last 10 phone digits so `+57 300…` and `300…` are the same contact): 201 with `created: true` on the first call, 200 with `created: false` afterwards. Rate limited: 120 requests/min per key and 10/min per contact (429 `RATE_LIMITED` with `Retry-After`). Invalid JSON responds 400; an invalid body 422.", + "summary": "Cancel the buyer's own membership", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the workspace is the one pinned to it (any `workspaceId` in the body is ignored); without a key, `workspaceId` is REQUIRED in the body (422 if missing). The membership is ALWAYS resolved from the buyer session (a CustomerMembership id is never accepted). It first cancels the recurring charge at the provider and then marks the membership as CANCELLED. Idempotent.", "security": [ { "apiKey": [] @@ -11483,15 +11239,6 @@ "schema": { "type": "string" } - }, - { - "name": "X-Customer-Session", - "in": "header", - "required": false, - "description": "Optional buyer session token; links the entry to that buyer.", - "schema": { - "type": "string" - } } ], "requestBody": { @@ -11499,31 +11246,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WaitlistEntryCreate" + "$ref": "#/components/schemas/CustomerSubscriptionCancelRequest" } } } }, "responses": { "200": { - "description": "Already on this city's waitlist (`created: false`).", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/WaitlistEntryResult" - } - }, - "required": [ - "data" - ] - } - } - } - }, - "201": { "description": "OK", "content": { "application/json": { @@ -11531,7 +11260,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/WaitlistEntryResult" + "$ref": "#/components/schemas/CustomerSubscriptionCancelResult" } }, "required": [ @@ -11541,16 +11270,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -11572,7 +11291,7 @@ } }, "404": { - "description": "Resource does not exist or is out of scope.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -11582,7 +11301,7 @@ } }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -11591,36 +11310,27 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "502": { + "description": "The external provider failed to complete the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } - }, - "headers": { - "Retry-After": { - "$ref": "#/components/headers/RetryAfter" - }, - "RateLimit": { - "$ref": "#/components/headers/RateLimit" - }, - "RateLimit-Policy": { - "$ref": "#/components/headers/RateLimitPolicy" - } } } } - }, + } + }, + "/customer/profile": { "get": { - "operationId": "getWaitlist", + "operationId": "getCustomerProfile", "tags": [ - "waitlist" + "customer" ], - "summary": "List the waitlist entries of the workspace", - "description": "Export for staff (CLI/MCP). Contains personal data, so it requires ADMIN. Newest first, cursor pagination; `city` filters by the folded city (accents and case ignored).", + "summary": "Buyer profile (name and phone)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (issue #673): this endpoint is scoped only by the session's `customer.id`, so it behaves identically with or without a key.", "security": [ { "apiKey": [] @@ -11630,33 +11340,6 @@ } ], "parameters": [ - { - "name": "city", - "in": "query", - "required": false, - "description": "City name; accents and case are ignored", - "schema": { - "type": "string" - } - }, - { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", - "schema": { - "type": "integer", - "default": 20 - } - }, - { - "name": "cursor", - "in": "query", - "required": false, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -11676,18 +11359,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/WaitlistEntry" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/CustomerProfile" } }, "required": [ - "data", - "page" + "data" ] } } @@ -11734,767 +11410,16003 @@ } } } - } - } - }, - "components": { - "schemas": { - "Error": { - "type": "object", - "properties": { + }, + "patch": { + "operationId": "patchCustomerProfile", + "tags": [ + "customer" + ], + "summary": "Update the buyer profile", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Only updates the session's buyer: name and phone. The email cannot be changed (it is the account identity). Omitted fields are left untouched.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerProfileUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerProfile" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/customer/orders": { + "get": { + "operationId": "getCustomerOrders", + "tags": [ + "customer", + "orders" + ], + "summary": "The purchase the buyer left unfinished for this event date", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, results are additionally scoped to the workspace pinned to it; without a key, any of the buyer's own unfinished purchases is visible. Returns the PENDING sale whose inventory hold is STILL ALIVE that the buyer has for that event date —with its seats, its total and when it expires—, or `order: null` if there is none. This is what lets reloading the checkout, or coming back from signing in, RESUME the purchase instead of starting from scratch: the seats remain held in that person's name. If `paymentOpened` is true the payment is already open and `POST /customer/orders/{id}/payment` returns the SAME signed configuration; to discard it and pick other seats, use `POST /customer/orders/{id}/release`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "eventDateId", + "in": "query", + "required": false, + "description": "Required. The event date being queried.", + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderCurrent" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postCustomerOrders", + "tags": [ + "customer", + "orders" + ], + "summary": "Create the ticket reservation (step 1 of the headless purchase)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL: with a key, the date and the ticket type must belong to the workspace pinned to it (anything else is 404); without a key, it is enough for the ticket type to exist and be on sale (same eligibility as the first-party checkout). Reserves inventory and creates the PENDING sale with the SAME rules as the first-party checkout (stock under lock, seats validated against seats.io, per-buyer limit, presale, memberships and virtual queue turn). The buyer email comes from the session, never from the body. Rejections carry a stable `reason` in `error.details.reason` (`sold_out`, `queue_turn_required`, `seats_not_held`, `members_only`, `members_only_withdrawn` — a members-only ticket whose artist withdrew the permission or left the lineup: it is no longer sold even to members —, …). With `pending_sale_in_progress` the inventory is taken by a half-paid purchase FROM THE SAME buyer: `error.details.pendingSaleId` and `pendingReference` identify it, and the right step is to reopen its payment with `POST /customer/orders/{pendingSaleId}/payment` (idempotent) instead of reserving again. If `free` is true the sale is already confirmed and `/payment` must NOT be called. Next step: `POST /customer/orders/{id}/payment`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "X-Purchase-Session", + "in": "header", + "required": false, + "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerOrderCreateRequest" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderCreateResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/customer/orders/{id}/payment": { + "post": { + "operationId": "postCustomerOrdersIdPayment", + "tags": [ + "customer", + "orders" + ], + "summary": "Open payment for a reservation (Bold or MercadoPago, depending on the event)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). The payment rail is chosen on the SERVER: Bold-eligible events (legend plan + allowlist) return the SIGNED configuration of the embedded Bold Payment Button (`apiKey` + `renderMode: \"embedded\"` + `integritySignature`, …), which the landing page mounts with `new BoldCheckout({...})`; all others return `publicKey` + `amount` + `currency` + `reference` + `payerEmail` to mount the MercadoPago Payment Brick (`POST .../payment/card` to charge, `POST .../payment/pse` for PSE). The landing page tells the rails apart by the SHAPE of the response (`apiKey`/`renderMode` ⇒ Bold, `publicKey` ⇒ MercadoPago), never by a separate flag. The sale must belong to the session buyer (and, with a key, to the workspace pinned to it): anything else is 404. Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, or (Bold only) the event has no legend plan or a payment attempt is already in flight with another gateway. `{id}` accepts the sale id or its `reference`. Limited to 10 opens per minute per buyer (429 with `Retry-After`).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "X-Purchase-Session", + "in": "header", + "required": false, + "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderStartPayment" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + } + } + } + }, + "/customer/orders/{id}/payment/card": { + "post": { + "operationId": "postCustomerOrdersIdPaymentCard", + "tags": [ + "customer", + "orders" + ], + "summary": "Charge with the MercadoPago Payment Brick token", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Receives the token the Payment Brick produced on the landing page's domain and charges through the Orders API using the sale amount (never one sent by the client); `payer.email` travels in the body but is ignored — the payer is ALWAYS the sale's. `status` is `approved`, `pending` (normal, may require additional authentication from the bank) or `rejected` (business decline; the reason is in `message`) — all three are returned with 200. With `rejected`, `saleAlive` tells what happened to the purchase: `false` = it was cancelled and a new one must be started; `true` = this payment was declined but the purchase is still pending because another payment is in progress on it (do not start a new purchase: wait and check the order). Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, a payment attempt is in flight with another gateway, the event only charges through Bold, or MercadoPago returned an error that cannot be classified as a decline. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 attempts per minute per buyer (429 with `Retry-After`).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "X-Purchase-Session", + "in": "header", + "required": false, + "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + } + } + } + }, + "/customer/orders/{id}/payment/pse": { + "post": { + "operationId": "postCustomerOrdersIdPaymentPse", + "tags": [ + "customer", + "orders" + ], + "summary": "Open a PSE payment through MercadoPago (redirect)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Creates a MercadoPago preference restricted to PSE and returns `redirectUrl` (`init_point`): the landing page must REDIRECT the browser there, not mount it in an iframe. The buyer picks their bank and confirms the transfer inside MercadoPago; on return, they land on `GET /api/mp/return` (our domain), which issues a 302 to the `returnUrl` sent in `POST /customer/orders` — the landing page must call `GET /customer/orders/{id}` for the authoritative status, never infer it from the return URL. The sale is confirmed by webhook when the bank settles the payment (asynchronous: it may take a while). Responds 409 with code `PAYMENT_UNAVAILABLE` if the reservation expired, the sale is no longer pending, a payment attempt is in flight with another gateway, or the event only charges through Bold. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 opens per minute per buyer (429 with `Retry-After`).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "X-Purchase-Session", + "in": "header", + "required": false, + "description": "Purchase session id (`POST /customer/purchase-sessions`). Required when the event's workspace enforces a single purchase session; if present, it is always validated. The requirement is decided by the EVENT, not the API key: it applies if the owning workspace, a linked artist or a catalog seller of the show has the flag, with or without a key. Rejections (409; uppercase `error.code` and the slug in `error.details.reason`): `PURCHASE_SESSION_REQUIRED` (missing, or belongs to another buyer or another event date), `PURCHASE_SESSION_SUPERSEDED` (another tab or device replaced it), `PURCHASE_SESSION_EXPIRED` (the map clock ran out before the order was created), `PURCHASE_SESSION_BUSY` (an order is already in flight with this session) and, on `POST /customer/orders` with seats, `HOLD_TOKEN_MISMATCH` (the `holdToken` is not the session's, or belongs to a replaced session or another buyer even if the header is absent). Payment POSTs accept the buyer's live session or the session that created THAT order, as long as no other session has been opened since. Rejecting a new payment NEVER affects a payment already in flight.", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderMercadoPagoPse" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + } + } + } + }, + "/customer/orders/{id}/release": { + "post": { + "operationId": "postCustomerOrdersIdRelease", + "tags": [ + "customer", + "orders" + ], + "summary": "Release a reservation the buyer will not pay for", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). Abandons the PENDING sale and returns its inventory (and its seats) to stock, so the buyer can start over without waiting for the reservation to expire. It is the counterpart of `pending_sale_in_progress`: when `POST /customer/orders` rejects with that `reason`, the landing page can offer *continue paying* (`/payment`, idempotent) or *start over* (this route). It ONLY releases with evidence that nobody started the payment: if Bold reports any transaction, if a provider response is already stored, or if the payment goes through a rail we cannot query, it responds 409 with `details.reason` = `payment_in_flight` and the sale is left intact. If the gateway does not respond, 503 (`gateway_unreachable`): retry later. The sale must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. `{id}` accepts the sale id or its `reference`. Limited to 10 calls per minute per buyer.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderRelease" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/customer/orders/{id}": { + "get": { + "operationId": "getCustomerOrdersId", + "tags": [ + "customer", + "orders" + ], + "summary": "Status of a headless purchase (and its tickets, once paid)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, results are additionally scoped to the workspace pinned to it). `{id}` accepts the `reference` (FT-…) or the sale id. If the sale is still PENDING and its payment goes through Bold, the authoritative payment status is re-read from Bold; between re-reads it responds with the internal status, which the webhook keeps up to date. `status` is `approved`, `pending` or `rejected`; `pending` is a NORMAL state (asynchronous payment methods take time) and the landing page must retry. `tickets` —with each ticket's `ticketCode`— is only present when `status` is `approved`. The purchase must belong to the session's buyer (and, with a key, to the workspace pinned to it): anything else is 404. The route MAY rate-limit polling and respond 429: honor `Retry-After` and apply backoff. Polling every ~2 s fits comfortably, but do not treat any threshold as a guarantee.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderStatus" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + } + } + } + }, + "/customer/purchase-sessions": { + "post": { + "operationId": "postCustomerPurchaseSessions", + "tags": [ + "customer", + "purchase-sessions" + ], + "summary": "Open the purchase session (only one live per buyer)", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL (with a key, the event date must belong to the workspace pinned to it; otherwise 404). Opens THE buyer purchase session: there is ONLY one live per buyer across any tab or device, and the latest wins — the previous one becomes `superseded` (it can no longer create an order or start a new payment) and its seats.io hold is released, unless it backs a live sale. On seated event dates the server ISSUES the `holdToken` (mount the chart with `session: \"manual\"`) and sets `seatsDeadline`: each session gets up to 3 minutes and the budget is 3 attempts (9 CUMULATIVE minutes) per buyer and event date, summing all of their sessions within a 30-minute window, and it only runs while no order has been created. Once exhausted, it responds 429 with `error.code` `SEAT_BUDGET_EXHAUSTED`, `error.details.reason` `seat_budget_exhausted` and `error.details.retryAfterSeconds` (10-minute cooldown; also in the `Retry-After` header). If the SAME browser (`deviceKey`) reopens the SAME event date with its session alive, it gets that same session with 200 instead of 201. Only event dates on sale: published event and current event date (otherwise 404). Limits: 10 creations per minute per buyer, 30 per minute per IP when called without an API key, and a global ceiling per event date (429 `RATE_LIMITED`). Once the session is created, `POST /customer/orders` and the payment POSTs carry the `X-Purchase-Session: ` header; when the clock runs out, call `POST /customer/purchase-sessions/{id}/release`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PurchaseSessionCreateRequest" + } + } + } + }, + "responses": { + "200": { + "description": "The SAME browser (`deviceKey`) reopened the SAME event date while its session was still alive: that session is returned (same `holdToken`, same clock) and nothing was created.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PurchaseSessionCreated" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PurchaseSessionCreated" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/customer/purchase-sessions/{id}": { + "get": { + "operationId": "getCustomerPurchaseSessionsId", + "tags": [ + "customer", + "purchase-sessions" + ], + "summary": "Purchase session status", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Returns the status of one of THE buyer's purchase sessions: `live` (this tab can create the order), `superseded` (another tab or device replaced it: stop offering the map and the payment), `expired` (the map clock ran out or it was released) or `converted` (it already created its order: `orderId`). A session whose `seatsDeadline` has passed is reported as `expired` immediately. Designed to be polled every ~10 s. Another buyer's session is 404.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PurchaseSessionStatus" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/customer/purchase-sessions/{id}/release": { + "post": { + "operationId": "postCustomerPurchaseSessionsIdRelease", + "tags": [ + "customer", + "purchase-sessions" + ], + "summary": "Release the seats of a purchase session", + "description": "Requires the `X-Customer-Session` header. The enterprise service API key is OPTIONAL. Marks the session `expired` and releases in seats.io the seats held with its `holdToken`. Idempotent: repeating it changes nothing. It NEVER releases a token that backs a live sale (pending payment or confirmed) nor that of a `converted` session: those seats belong to the order. Call it when the map clock runs out. Another buyer's session is 404.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PurchaseSessionStatus" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + } + } + } + }, + "/content/videos": { + "get": { + "operationId": "getContentVideos", + "tags": [ + "content" + ], + "summary": "List the organization's published videos", + "description": "Only published videos that have finished processing (READY) in the active workspace. Does not include the playback id: to play one, request a token from `POST /content/playback-token`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentVideo" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/posts": { + "get": { + "operationId": "getContentPosts", + "tags": [ + "content" + ], + "summary": "List the organization's community feed", + "description": "Posts from the active workspace, newest first, excluding deleted posts and posts scheduled for the future. A post with `locked: true` arrives redacted (`content`, `imageUrl`, `videoId`, `eventId` and `link` set to null, `commentsCount` set to 0): it is members-only content and the key does not represent a buyer with a current membership. Does not include `likes_count` (only visible to the workspace owner) or the post's internal author.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentPost" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postContentPosts", + "tags": [ + "content" + ], + "summary": "Publish community content (including articles)", + "description": "Creates a community post. `type=ARTICLE` requires `title` and `body` (Markdown) and builds a slug unique per organization (manual via `slug`, or derived from `title` if omitted); `type=TEXT`/`IMAGE` require `content` or `imageUrl`, same as the dashboard composer. Unlike the dashboard, this path does NOT resolve the link's Open Graph snapshot (`link` is always null in the response). Minimum role ADMIN, like every other `POST` in `/api/v1`. If the workspace has the `community_v2` flag enabled, publishing enqueues a notification to members in the same transaction; with a future `publishedAt`, the notification goes out when the post is published. The response does not change.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentPostCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentPost" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/lives": { + "get": { + "operationId": "getContentLives", + "tags": [ + "content" + ], + "summary": "List the organization's live streams", + "description": "Live streams from the active workspace, newest first. `status: ACTIVE` is the one on air. Does not include the RTMP key or the playback ids.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentLive" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postContentLives", + "tags": [ + "content" + ], + "summary": "Create a live stream", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"New live stream\" in the dashboard: creates the stream in Mux and returns the RTMPS server and stream key to configure OBS or any encoder.\n\nSECURITY: `streamKey` is a secret that grants broadcasting rights on this stream in the organization's name. It is returned ONLY here and by `POST /content/lives/{id}/reset-key`, never by `GET /content/lives`, `GET /content/lives/{id}` or `PATCH`. Store it like a password; if it leaks, rotate it with reset-key.\n\n`memberOnly` is forced to false when the workspace has no active membership plan (nobody to restrict it to). With `eventDateId` and no `scheduledAt`, the stream inherits the show date's start time.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: `title` empty or longer than 120 characters, or `scheduledAt` not in \"YYYY-MM-DDTHH:mm\" format.\n- 400 `INVALID_SCHEDULE`: `scheduledAt` is in the past or more than 2 years ahead.\n- 403 `FEATURE_LOCKED`: the workspace plan does not include streaming.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: `eventDateId` does not exist or is not an event of this workspace (as owner or linked artist).\n- 409 `EVENT_DATE_HAS_LIVE`: that show date already has a live stream.\n- 502 `MUX_ERROR`: Mux rejected the request or is not configured; nothing was created.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentLiveCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentLiveCreated" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/lives/{id}": { + "get": { + "operationId": "getContentLivesId", + "tags": [ + "content" + ], + "summary": "Live stream status", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentLive" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "patch": { + "operationId": "patchContentLivesId", + "tags": [ + "content" + ], + "summary": "Update a live stream's schedule or audience", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same actions as the dashboard's scheduled-time picker and members-only switch. Send `scheduledAt` and/or `memberOnly`; absent fields keep their value. Never returns the stream key.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: `scheduledAt` not in \"YYYY-MM-DDTHH:mm\" format.\n- 400 `INVALID_SCHEDULE`: `scheduledAt` is in the past or more than 2 years ahead.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the stream does not exist, was deleted or belongs to another workspace.\n- 409 `LIVE_NOT_IDLE`: `scheduledAt` sent for a stream that is on air or already ended.\n- 409 `MEMBERSHIP_PREREQ`: the workspace has no active membership plan yet; create one first (members-only content needs something to pay for). Only checked for `memberOnly: true`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentLiveUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentLiveSettings" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteContentLivesId", + "tags": [ + "content" + ], + "summary": "Delete a live stream", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as deleting a live stream in the dashboard.\n\nDESTRUCTIVE and irreversible: deletes the stream in Mux (its stream key stops working, an encoder on air is cut off) and soft-deletes it locally, so it disappears from the dashboard and the API listings. Cannot be restored through the API.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the stream does not exist, was already deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentMediaDeleted" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/playback-token": { + "post": { + "operationId": "postContentPlaybackToken", + "tags": [ + "content" + ], + "summary": "Signed token to play a video or a live stream", + "description": "Requires an enterprise service API key. `memberOnly` content additionally requires the `X-Customer-Session` header of a buyer with a current membership in the key's organization or, for a live stream tied to a show date, a CONFIRMED ticket for that date (otherwise 403 `MEMBERSHIP_REQUIRED`). Rate limited: 600 requests/min per key and 30/min per buyer (429 `RATE_LIMITED` with `Retry-After`). Content from another organization responds 404. Short-lived tokens: 30 minutes for live streams, 1 hour for videos.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentPlaybackTokenRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentPlaybackToken" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/waitlist": { + "post": { + "operationId": "postWaitlist", + "tags": [ + "waitlist" + ], + "summary": "Join the per-city waitlist of an enterprise landing", + "description": "Requires an enterprise service API key; the entry belongs to the key's organization. `X-Customer-Session` is optional: when present the entry is linked to that buyer. `contact` must be an email or a phone number (7-15 digits; only a leading `+`, spaces and dashes besides digits — parentheses, dots, letters or extensions respond 422). Phones are stored without spaces or dashes. Idempotent per (organization, city folded without accents/case, contact normalized — lowercased email, or the last 10 phone digits so `+57 300…` and `300…` are the same contact): 201 with `created: true` on the first call, 200 with `created: false` afterwards. Rate limited: 120 requests/min per key and 10/min per contact (429 `RATE_LIMITED` with `Retry-After`). Invalid JSON responds 400; an invalid body 422.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "X-Customer-Session", + "in": "header", + "required": false, + "description": "Optional buyer session token; links the entry to that buyer.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WaitlistEntryCreate" + } + } + } + }, + "responses": { + "200": { + "description": "Already on this city's waitlist (`created: false`).", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WaitlistEntryResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WaitlistEntryResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + } + } + }, + "get": { + "operationId": "getWaitlist", + "tags": [ + "waitlist" + ], + "summary": "List the waitlist entries of the workspace", + "description": "Export for staff (CLI/MCP). Contains personal data, so it requires ADMIN. Newest first, cursor pagination; `city` filters by the folded city (accents and case ignored).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "city", + "in": "query", + "required": false, + "description": "City name; accents and case are ignored", + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WaitlistEntry" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/events/{id}/schedule": { + "post": { + "operationId": "postEventsIdSchedule", + "tags": [ + "events" + ], + "summary": "Schedule a draft event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nSend exactly one of:\n- `publishAt`: the DRAFT publishes itself at that instant (checked every ~5 minutes). Must be in the future and before at least one of the event's dates. The response's `publishAt` echoes it.\n- `saleStartsAt`: publishes the DRAFT now and opens sales at that instant, setting `saleStartsAt` on every ticket type of the upcoming dates in the same transaction. Must be in the future and before the first upcoming date.\n\nErrors (`error.code`):\n- 409 `EVENT_NOT_DRAFT`: only drafts can be scheduled (also when it got published concurrently).\n- 422 `SCHEDULE_IN_PAST`, 422 `SCHEDULE_AFTER_EVENT_DATE`.\n- 409 `NO_FUTURE_DATE`, 409 `NO_TICKET_TYPES`, 422 `TICKET_TYPE_SALE_CLOSES_BEFORE` (`saleStartsAt` only).\n- Seated (seats.io) events: 409 `SEATSIO_INVALID`, 409 `SEAT_MAP_CATEGORIES_UNCOVERED` (`error.details.zones[]`), 503 `SEAT_MAP_UNVERIFIABLE` (retryable) — same as `POST /events/{id}/publish`.\n- 409 `IDENTITY_VERIFICATION_REQUIRED` (`saleStartsAt` on a paid event of an unverified workspace). Unlike `POST /events/{id}/publish`, the event is NOT queued: retry after the verification is approved.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventSchedule" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Event" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteEventsIdSchedule", + "tags": [ + "events" + ], + "summary": "Cancel a scheduled publication", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nClears the pending scheduled publication (`publishAt` becomes null). The event keeps its status. Does not undo a `saleStartsAt` schedule: edit the ticket types' `saleStartsAt` instead.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Event" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/ticket-types/{id}/presale-windows": { + "get": { + "operationId": "getTicketTypesIdPresaleWindows", + "tags": [ + "ticket-types" + ], + "summary": "List a ticket type's presale windows", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PresaleWindow" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postTicketTypesIdPresaleWindows", + "tags": [ + "ticket-types" + ], + "summary": "Create a presale window", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nActive members of `planId` can buy this ticket type between `presaleStartsAt` and `presaleEndsAt` (instants in UTC), optionally capped by `presaleCapacity`. One window per plan and ticket type.\n\nErrors (`error.code`): 422 `PLAN_NOT_ELIGIBLE` (the plan is not an active plan of the workspace that owns the event), 422 `PRESALE_WINDOW_INVERTED` (end not after start), 409 `DUPLICATE_PLAN` (that plan already has a window on this ticket type), 403 `EVENT_SCOPE_FORBIDDEN` (key restricted to other events).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PresaleWindowCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PresaleWindow" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/presale-windows/{id}": { + "patch": { + "operationId": "patchPresaleWindowsId", + "tags": [ + "ticket-types" + ], + "summary": "Update a presale window", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nAbsent fields are left untouched; the start/end order is checked against the stored values.\n\nErrors (`error.code`): 422 `PLAN_NOT_ELIGIBLE` (the plan is not an active plan of the workspace that owns the event), 422 `PRESALE_WINDOW_INVERTED` (end not after start), 409 `DUPLICATE_PLAN` (that plan already has a window on this ticket type), 403 `EVENT_SCOPE_FORBIDDEN` (key restricted to other events).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PresaleWindowUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PresaleWindow" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deletePresaleWindowsId", + "tags": [ + "ticket-types" + ], + "summary": "Delete a presale window", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.\n\nDESTRUCTIVE: permanently deletes the window; members lose that presale access immediately. Re-creating it yields a new id.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/reports/live-attendance": { + "get": { + "operationId": "getReportsLiveAttendance", + "tags": [ + "reports" + ], + "summary": "Events happening right now, with check-in progress", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same data as the \"Live\" cards of the dashboard summary (section `inicio`).\n\nReturns the event dates whose live window contains the current instant (doors open, or start, until `ends_at`; 6 hours after the start when there is no end), for PUBLISHED/SOLD_OUT events visible to the workspace (own and collaborative) plus shows of other organizers hosted in one of the workspace's venues (occupancy only). Sorted by `sold` descending. `sold`/`validated` count tickets (QR) of CONFIRMED sales; `validatedPct` is 0-100. Meant for polling (the dashboard polls every 20 s).\n\n`scope` narrows like the dashboard selector: `all` (default), `own` (only the workspace's own shows; hosted shows are excluded), `partner:` (shows shared with that partner). An event-scoped API key only sees its events.\n\nErrors (`error.code`): 400 `BAD_REQUEST` (invalid `scope`).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "scope", + "in": "query", + "required": false, + "description": "all (default) | own | partner:", + "schema": { + "type": "string", + "default": "all" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/LiveAttendance" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/event-dates/{id}/access-close": { + "get": { + "operationId": "getEventDatesIdAccessClose", + "tags": [ + "events", + "tickets" + ], + "summary": "Live entry count and access-close status of an event date", + "description": "Minimum role: `STAFF` (any role that validates tickets), with the `validar` section when the access is scoped. Active workspace via the `X-Workspace-Id` header. Same gate and same count as the access-close screen of the dashboard: a door validator limited to some events only sees those.\n\nOnly event dates of the workspace's OWN events that admit an access-close record (not cancelled, PUBLISHED/SOLD_OUT/COMPLETED event, no external ticketing). `live.issued` counts tickets of CONFIRMED sales (courtesies included); `live.checkins` is what a signature would freeze right now. Once closed, `closedCheckins` is the frozen number. Date fields are labels already formatted in the event date's time zone.\n\nErrors (`error.code`): 403 `ACCESS_CLOSE_FORBIDDEN` (role/section/validator scope), 404 (not found, another workspace, collaborative/hosted event or outside the key's `event_scope`).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/AccessCloseStatus" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postEventDatesIdAccessClose", + "tags": [ + "events", + "tickets" + ], + "summary": "Sign the access-close record of an event date (irreversible)", + "description": "Minimum role: `ADMIN` (stricter than the dashboard, where door staff can also sign). Active workspace via the `X-Workspace-Id` header.\n\nDESTRUCTIVE and IRREVERSIBLE: freezes the number of check-ins of the event date as its access-close record, signed by the API key owner, and emails the record to the workspace. It does not stop the scanner. There is no endpoint to undo it. Requires the body `{\"confirm\": true}` (422 without it). Only one signature per date: concurrent calls are resolved atomically and the loser gets 409.\n\nSigning opens 2 hours after the date starts.\n\nErrors (`error.code`):\n- 403 `ACCESS_CLOSE_FORBIDDEN` (section/validator scope), 403 `EVENT_SCOPE_FORBIDDEN` (outside the key's `event_scope`).\n- 404: not found, another workspace, or a date that does not admit a record (cancelled, draft event, external ticketing, collaborative/hosted event).\n- 409 `ACCESS_CLOSE_NOT_SIGNABLE_YET`: `error.details.signableFrom` (ISO 8601).\n- 409 `ACCESS_ALREADY_CLOSED`: someone signed first or the automatic close ran; `error.details` has `closedAt`, `closedByName` (null if automatic) and `automatic`. Not retryable.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessCloseSignRequest" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/AccessCloseSigned" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/payment-intents": { + "get": { + "operationId": "getPaymentIntents", + "tags": [ + "sales" + ], + "summary": "Purchase intents of an event (checkout funnel and abandoned journeys)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same data as the dashboard's Sales → Intents screen.\n\nFolds the checkout funnel log of ONE event (own or collaborative) into one journey per visitor (the buyer account when known, otherwise the device), with how far it got (`stage`) and how it ended (`outcome`: `NO_SALE`, `REJECTED` with `reason`, or the sale status). `funnel` counts ALL journeys of the filter, not only the page. Journeys are sorted by last activity, newest first.\n\nPagination: pass `nextCursor` back as `cursor` (opaque); `null` means no more pages. `eventDate` must belong to the event, otherwise all dates are used (`selectedDateId` echoes the one applied). `onlyAbandoned=true` keeps journeys that picked seats and did not pay (excludes sales still PENDING).\n\nPersonal data: `personName`/`personEmail` come from the buyer account or what was typed at checkout — the same data `GET /sales` returns. Device identifiers never leave the server (`threadId` is a hash).\n\nErrors (`error.code`): 400 `BAD_REQUEST` (missing `event`, invalid `limit`/`onlyAbandoned`), 404 (event not found, not visible, or outside the key's `event_scope`).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "event", + "in": "query", + "required": true, + "description": "event id", + "schema": { + "type": "string" + } + }, + { + "name": "eventDate", + "in": "query", + "required": false, + "description": "event date id (must belong to the event)", + "schema": { + "type": "string" + } + }, + { + "name": "onlyAbandoned", + "in": "query", + "required": false, + "description": "true = only journeys that picked seats and did not pay", + "schema": { + "type": "boolean" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 100", + "schema": { + "type": "integer", + "default": 100 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "description": "`nextCursor` of the previous page", + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/PaymentIntentsPage" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/sales/{id}/abandon": { + "post": { + "operationId": "postSalesIdAbandon", + "tags": [ + "sales" + ], + "summary": "Mark a pending sale as abandoned (releases its stock)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Mark as abandoned\" in the dashboard.\n\nDESTRUCTIVE: a PENDING sale whose payment never started moves to ABANDONED (terminal) and its stock reservations are deleted, so the inventory goes back on sale immediately. It does not touch seats.io holds (same as the dashboard). Use `POST /sales/{id}/cancel` for confirmed sales.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: an item of the sale is outside the key's `event_scope`.\n- 409 `SALE_NOT_PENDING`: only PENDING sales (also when it is already ABANDONED).\n- 409 `PAYMENT_IN_PROGRESS`: a payment was started (`payment_ref` set) and may still be confirmed by the gateway; wait for reconciliation.\n- 409 `SALE_STATE_CHANGED`: the sale changed between the read and the write (e.g. a payment started); re-read it.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Sale" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/posts/{id}": { + "patch": { + "operationId": "patchContentPostsId", + "tags": [ + "content" + ], + "summary": "Update a community post or article", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as editing a post or an article in the dashboard.\n\nPartial update: absent fields keep their stored value; `null` clears a nullable field. The stored post decides the shape: an ARTICLE accepts `title`, `subtitle`, `body`, `slug`, `imageUrl` (cover), `locked`, `eventId` and `publishedAt`; a TEXT/IMAGE/VIDEO post accepts `type` (TEXT/IMAGE), `content`, `imageUrl`, `locked`, `eventId`, `channelId` and `publishedAt`. Unlike `POST /content/posts`, changing the text of a short post re-resolves its link preview, like the dashboard. Member posts cannot be edited (404); moderate them under `/content/moderation/member-posts`. The response is redacted like `GET /content/posts` when the post is `locked`.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: a field that does not apply to the post's type, or the result would be empty (a short post needs `content` or `imageUrl`).\n- 404 `NOT_FOUND`: the post, the linked `eventId` or the `channelId` does not exist in this workspace.\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: `channelId` was sent but channels are not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 409 `SLUG_CONFLICT`: another article of the organization already uses that slug.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentPostUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentPost" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteContentPostsId", + "tags": [ + "content" + ], + "summary": "Delete a community post", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as deleting a post in the dashboard.\n\nDESTRUCTIVE: soft-deletes the post (organization post, article or member post), unpins it and redacts the member notifications that pointed to it. It disappears from the feed immediately and cannot be restored through the API. To take down a member post with a notice to its author, prefer `POST /content/moderation/member-posts/{id}/remove`.\n\nErrors: 404 `NOT_FOUND` (does not exist, already deleted or belongs to another workspace); 403 `EVENT_SCOPE_FORBIDDEN`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/posts/{id}/pin": { + "put": { + "operationId": "putContentPostsIdPin", + "tags": [ + "content" + ], + "summary": "Pin or unpin a community post", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Pin\" in the dashboard.\n\nAt most one pinned post per workspace: `pinned: true` unpins the previous one in the same transaction. Only a published post can be pinned; unpinning works on any post. Idempotent.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 404 `NOT_FOUND`: the post does not exist, is deleted, is not published (when pinning) or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentPostPin" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentPostPinned" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/comments/{id}": { + "delete": { + "operationId": "deleteContentCommentsId", + "tags": [ + "content" + ], + "summary": "Delete a community comment (moderation)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as deleting a comment from the dashboard.\n\nDESTRUCTIVE: soft-deletes the comment and, if it is a top-level comment, all its live replies; the post's comment count is recomputed. Cannot be undone through the API. To hide it reversibly use `POST /content/moderation/comments/{id}/hide`.\n\nErrors: 404 `NOT_FOUND` (does not exist, already deleted or belongs to another workspace); 403 `EVENT_SCOPE_FORBIDDEN`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentCommentDeleted" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/channels": { + "get": { + "operationId": "getContentChannels", + "tags": [ + "content" + ], + "summary": "List the community channels", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same list as the dashboard's Channels screen: active channels in display order (archived ones are omitted). Like the dashboard, the default Announcements and General channels are created on first read if the workspace has none.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommunityChannel" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postContentChannels", + "tags": [ + "content" + ], + "summary": "Create a community channel", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"New channel\" in the dashboard: a CITY or CUSTOM channel, appended at the end. The slug is derived from the name, unique in the workspace, and never changes afterwards.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 400 `BAD_REQUEST`: `city` missing on a CITY channel.\n- 409 `CHANNEL_LIMIT_REACHED`: the workspace already has the maximum of active channels; archive one first.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommunityChannelCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityChannel" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/channels/{id}": { + "patch": { + "operationId": "patchContentChannelsId", + "tags": [ + "content" + ], + "summary": "Update a community channel", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as editing a channel in the dashboard. Partial: absent fields keep their value; `null` clears `description`/`city`. The slug does not change on rename. Archived channels cannot be edited.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 400 `ANNOUNCEMENTS_STAFF_ONLY`: Announcements cannot be opened to members (`whoCanPost` must stay STAFF).\n- 400 `CITY_REQUIRED`: a CITY channel needs a city.\n- 404 `NOT_FOUND`: the channel does not exist, is archived or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommunityChannelUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityChannel" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/channels/order": { + "put": { + "operationId": "putContentChannelsOrder", + "tags": [ + "content" + ], + "summary": "Reorder the community channels", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as dragging channels in the dashboard. Send EVERY active channel id (from `GET /content/channels`) in the new order, Announcements first; a partial list is rejected, not applied halfway.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 400 `BAD_REQUEST`: repeated ids.\n- 400 `ANNOUNCEMENTS_FIRST`: Announcements must stay first.\n- 409 `CHANNEL_LIST_CHANGED`: the ids are not exactly the active channels (one was created/archived, or an id from another workspace); re-read and retry.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommunityChannelOrder" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityChannelOrder" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/channels/{id}/archive": { + "post": { + "operationId": "postContentChannelsIdArchive", + "tags": [ + "content" + ], + "summary": "Archive a community channel", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Archive\" in the dashboard.\n\nDESTRUCTIVE: the channel tab disappears for members and staff can no longer post to it; its posts remain visible under \"All\". There is no unarchive endpoint, and its slug stays taken.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 404 `NOT_FOUND`: the channel does not exist, is already archived or belongs to another workspace.\n- 409 `ANNOUNCEMENTS_NOT_ARCHIVABLE`: Announcements cannot be archived.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/queue": { + "get": { + "operationId": "getContentModerationQueue", + "tags": [ + "content" + ], + "summary": "List reported community comments (moderation queue)", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header. Same queue as the dashboard's Moderation screen: comments with open reports, most reported first, including auto-hidden ones and comments deleted with reports still open (deleting does not dodge a ban). 50 per page; `page` is 0-based (an empty array means no more pages).\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "page", + "in": "query", + "required": false, + "description": "0-based page", + "schema": { + "type": "integer", + "default": 0 + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModerationQueueItem" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/bans": { + "get": { + "operationId": "getContentModerationBans", + "tags": [ + "content" + ], + "summary": "List members banned from the community", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header. Same list as the dashboard's Moderation screen: the latest 200 bans, newest first. Lift one with `DELETE /content/members/{customerId}/ban`.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommunityBan" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/member-posts": { + "get": { + "operationId": "getContentModerationMemberPosts", + "tags": [ + "content" + ], + "summary": "List member posts awaiting review (or recently published)", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header. Same lists as the dashboard's Moderation → Posts view. `status=PENDING_REVIEW` (default): posts waiting for approval, oldest first, 30 per 0-based `page`; their `imageUrl` is a short-lived signed URL. `status=PUBLISHED`: the latest 30 published member posts (no paging), to remove one. Approving needs the `updatedAt` read here.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 403 `MEMBER_POSTS_UNAVAILABLE`: member posts are not enabled for this workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "status", + "in": "query", + "required": false, + "description": "PENDING_REVIEW (default) or PUBLISHED", + "schema": { + "type": "string", + "enum": [ + "PENDING_REVIEW", + "PUBLISHED" + ], + "default": "PENDING_REVIEW" + } + }, + { + "name": "page", + "in": "query", + "required": false, + "description": "0-based page (PENDING_REVIEW only)", + "schema": { + "type": "integer", + "default": 0 + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MemberPostQueueItem" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/comments/{id}/hide": { + "post": { + "operationId": "postContentModerationCommentsIdHide", + "tags": [ + "content" + ], + "summary": "Hide a community comment", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header. Same action as \"Hide\" in the dashboard's moderation queue.\n\nHides the comment (and its replies from the count) and resolves its open reports as HIDDEN. Reversible with `/unhide`. Idempotent: hiding a hidden comment returns `changed: false`.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the comment does not exist, is deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommentModerated" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/comments/{id}/unhide": { + "post": { + "operationId": "postContentModerationCommentsIdUnhide", + "tags": [ + "content" + ], + "summary": "Show a hidden community comment again", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header. Same action as \"Show\" in the dashboard's moderation queue.\n\nShows the comment again, marks it as cleared (it will not be auto-hidden again) and resolves its open reports as IGNORED. Idempotent.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the comment does not exist, is deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommentModerated" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/comments/{id}/ignore-reports": { + "post": { + "operationId": "postContentModerationCommentsIdIgnoreReports", + "tags": [ + "content" + ], + "summary": "Dismiss the open reports of a community comment", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header. Same action as \"Ignore\" in the dashboard's moderation queue.\n\nLeaves the comment as it is, resolves its open reports as IGNORED and takes it out of the queue; it will no longer be auto-hidden. New reports put it back in the queue. Works on deleted comments too.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the comment does not exist or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommentModerated" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/member-posts/{id}/approve": { + "post": { + "operationId": "postContentModerationMemberPostsIdApprove", + "tags": [ + "content" + ], + "summary": "Approve a pending member post", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header. Same action as \"Approve\" in the dashboard's Moderation → Posts view: the post is published at the top of the feed, its author is notified and mentioned members are notified.\n\nOnly the version you read is approved: send the post's `updatedAt` from `GET /content/moderation/member-posts` as `expectedUpdatedAt`. If the author edited it since, nothing is published (409 `EDITED_SINCE_READ`): re-read and review again.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 403 `MEMBER_POSTS_UNAVAILABLE`: member posts are not enabled for this workspace.\n- 404 `NOT_FOUND`: not a member post of this workspace, or deleted.\n- 409 `ALREADY_REVIEWED`: it is no longer pending.\n- 409 `EDITED_SINCE_READ`: the author edited it after `expectedUpdatedAt`.\n- 502 `IMAGE_PROMOTION_FAILED`: the image could not be published; retry.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPostApprove" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MemberPostReviewed" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/member-posts/{id}/reject": { + "post": { + "operationId": "postContentModerationMemberPostsIdReject", + "tags": [ + "content" + ], + "summary": "Reject a pending member post", + "description": "Minimum role: `STAFF` (`ADMIN` with `banAuthor: true`). Active workspace via the `X-Workspace-Id` header. Same action as \"Reject\" in the dashboard's Moderation → Posts view.\n\nDESTRUCTIVE: the pending post is rejected (it never gets published), the author is notified in their inbox and the image is purged from storage. The optional `reason` is shown to the author. With `banAuthor` the author is also banned from the community in the same transaction.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 403 `BAN_REQUIRES_ADMIN`: `banAuthor` with a role below ADMIN.\n- 400 `BAD_REQUEST`: invalid `reason`.\n- 404 `NOT_FOUND`: not a member post of this workspace, or deleted.\n- 409 `ALREADY_REVIEWED`: another moderator already reviewed it.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPostDecision" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MemberPostReviewed" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/moderation/member-posts/{id}/remove": { + "post": { + "operationId": "postContentModerationMemberPostsIdRemove", + "tags": [ + "content" + ], + "summary": "Remove a published member post", + "description": "Minimum role: `STAFF` (`ADMIN` with `banAuthor: true`). Active workspace via the `X-Workspace-Id` header. Same action as \"Remove\" in the dashboard's Moderation → Posts view.\n\nDESTRUCTIVE: the published post is soft-deleted, the author is notified in their inbox and the image is purged from storage. The optional `reason` is shown to the author. With `banAuthor` the author is also banned from the community in the same transaction.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 403 `BAN_REQUIRES_ADMIN`: `banAuthor` with a role below ADMIN.\n- 400 `BAD_REQUEST`: invalid `reason`.\n- 404 `NOT_FOUND`: not a published member post of this workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": false, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberPostDecision" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MemberPostReviewed" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/members/{id}/ban": { + "post": { + "operationId": "postContentMembersIdBan", + "tags": [ + "content" + ], + "summary": "Ban a member from the community", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. `{id}` is the member's customer id (`author.customerId` in the moderation queue). Same action as \"Ban\" in the dashboard's moderation queue.\n\nDESTRUCTIVE: the member can no longer post, comment or RSVP in this workspace's community; their RSVPs to upcoming meetups are cancelled (the seat is released); `commentId` (or, with `hideAllComments`, all their comments in this workspace) is hidden and the open reports are resolved as BANNED. Idempotent on the ban itself. Lift it with `DELETE`.\n\nThe ban always comes from a comment of this workspace: the banned member is that comment's author, and `{id}` must match it.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the comment does not exist in this workspace or was not written by `{id}`.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MemberBanCreate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MemberBanResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteContentMembersIdBan", + "tags": [ + "content" + ], + "summary": "Lift a member's community ban", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Lift ban\" in the dashboard. Deletes the ban (leaving an audit log entry); hidden comments stay hidden and cancelled RSVPs stay cancelled.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the member is not banned in this workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MemberBanResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/meetups": { + "get": { + "operationId": "getContentMeetups", + "tags": [ + "content" + ], + "summary": "List community meetups", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same list as the dashboard's Meetups screen: the latest 100 meetups by start date (newest first), in any status, with confirmed and pending-request counts.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (meetups are community content, not ticketed events).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommunityMeetup" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postContentMeetups", + "tags": [ + "content" + ], + "summary": "Create a community meetup (draft)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same form as \"New meetup\" in the dashboard; it is created as DRAFT (publish it with `POST /content/meetups/{id}/publish`). `startsAt`/`endsAt` are local wall times in the workspace's timezone (`YYYY-MM-DDTHH:mm`). An ONLINE meetup keeps `onlineUrl` and drops the address; IN_PERSON the opposite.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (meetups are community content, not ticketed events).\n- 400 `BAD_REQUEST`: malformed wall time, `endsAt` not after `startsAt`, or `onlineUrl` not https.\n- 400 `STARTS_IN_PAST`: the start must be in the future.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommunityMeetupCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityMeetupDetail" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/meetups/{id}": { + "get": { + "operationId": "getContentMeetupsId", + "tags": [ + "content" + ], + "summary": "Get a community meetup with its attendees and requests", + "description": "Minimum role: `STAFF` (includes the name and email of members who requested a seat). Active workspace via the `X-Workspace-Id` header. Same detail as the dashboard: confirmed attendees (with check-in) and RSVP requests (pending first). `local` carries the editable values in the workspace's wall time.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (meetups are community content, not ticketed events).\n- 404 `NOT_FOUND`: the meetup does not exist in this workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityMeetupDetail" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "patch": { + "operationId": "patchContentMeetupsId", + "tags": [ + "content" + ], + "summary": "Update a community meetup", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same form as editing a meetup in the dashboard. Partial: absent fields keep the stored value (see `local` in the detail); an empty string clears an optional text field. Times are local wall times in the workspace's timezone.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (meetups are community content, not ticketed events).\n- 400 `BAD_REQUEST`: malformed values (see `POST /content/meetups`).\n- 400 `STARTS_IN_PAST`: a past start is only accepted if it is the one already stored.\n- 404 `NOT_FOUND`: the meetup does not exist in this workspace.\n- 409 `EVENT_CANCELLED`: a cancelled meetup cannot be edited.\n- 409 `CAPACITY_BELOW_GOING`: `capacity` lower than the members already confirmed.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommunityMeetupUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityMeetupDetail" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/meetups/{id}/publish": { + "post": { + "operationId": "postContentMeetupsIdPublish", + "tags": [ + "content" + ], + "summary": "Publish a draft community meetup", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Publish\" in the dashboard: the draft becomes visible to members and a notification to the whole community is queued in the same transaction (sent by the background job, not by this request).\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (meetups are community content, not ticketed events).\n- 404 `NOT_FOUND`: the meetup does not exist in this workspace.\n- 409 `NOT_DRAFT`: only a draft can be published.\n- 409 `STARTS_IN_PAST`: its start already passed; update it first.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityMeetupDetail" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/meetups/{id}/cancel": { + "post": { + "operationId": "postContentMeetupsIdCancel", + "tags": [ + "content" + ], + "summary": "Cancel a community meetup", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Cancel meetup\" in the dashboard.\n\nDESTRUCTIVE: the meetup (draft or published) moves to CANCELLED, which is terminal: it cannot be edited or published again. Members who confirmed are notified by email/inbox (queued in the same transaction, sent by the background job). RSVPs are kept as they are.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (meetups are community content, not ticketed events).\n- 404 `NOT_FOUND`: the meetup does not exist in this workspace.\n- 409 `ALREADY_CANCELLED`: it was already cancelled.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityMeetupDetail" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/meetups/{id}/rsvps/{rsvpId}": { + "patch": { + "operationId": "patchContentMeetupsIdRsvpsRsvpId", + "tags": [ + "content" + ], + "summary": "Approve or reject a meetup RSVP request", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as approving/rejecting a request in the dashboard (meetups with `requiresApproval`). The member gets an email with the decision after the change is committed. APPROVE also works on a previously rejected request (the staff can change its mind); REJECT only on a pending one.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (meetups are community content, not ticketed events).\n- 404 `NOT_FOUND`: the meetup or the request does not exist in this workspace.\n- 409 `NOT_PENDING`: already reviewed.\n- 409 `EVENT_FULL`: no seats left; raise the capacity first.\n- 409 `EVENT_CLOSED`: the meetup is not published or already started.\n- 409 `MEMBER_BANNED`: the member is banned from the community.\n- 409 `NO_MEMBERSHIP`: the member no longer has an active membership.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "rsvpId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommunityMeetupRsvpReview" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityMeetupRsvpReviewed" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/meetups/{id}/attendance": { + "put": { + "operationId": "putContentMeetupsIdAttendance", + "tags": [ + "content" + ], + "summary": "Mark or unmark a meetup attendee as checked in", + "description": "Minimum role: `STAFF` (door work, like `POST /tickets/{ticketCode}/checkin`). Active workspace via the `X-Workspace-Id` header. Same action as the \"Attended\" checkbox in the dashboard. Only on a confirmed (GOING) RSVP of a meetup that is not cancelled; repeating the same mark changes nothing (`changed: false`, also when the RSVP is not GOING or does not belong to the meetup).\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `COMMUNITY_UNAVAILABLE`: the community (`community_v2`) is not enabled for this workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (meetups are community content, not ticketed events).\n- 404 `NOT_FOUND`: the meetup does not exist in this workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommunityMeetupAttendance" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommunityMeetupAttendanceResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/products": { + "get": { + "operationId": "getProducts", + "tags": [ + "products" + ], + "summary": "List digital products and courses", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same list as the dashboard's Products screen (downloadable products and courses, not the merch store): non-deleted products, newest first, with CONFIRMED sales count and revenue.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Product" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postProducts", + "tags": [ + "products" + ], + "summary": "Create a digital product or course", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as the dashboard's product wizard. A DOWNLOADABLE needs `fileName`/`filePath` of a file already in the workspace's product files folder; a COURSE needs at least one module with one lesson. Files and lesson videos cannot be uploaded through the API: reference ones uploaded from the dashboard. Created as DRAFT unless `publish: true`. Returns the full product.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: a dashboard validation rule failed (e.g. a DOWNLOADABLE without a file, a COURSE without modules or a module without lessons, decimals in a COP price, more than one free preview lesson per module, a QUIZ lesson without questions). `error.message` says which.\n- 400 `INVALID_FILE`: a `filePath`/`samplePath`/lesson file/resource path is not under this workspace's product files folder.\n- 400 `INVALID_LESSON_THUMBNAIL`: a lesson `thumbnailUrl` is not an image of this workspace's media library.\n- 400 `INVALID_LESSON_VIDEO`: a lesson `videoId` is not a course video of this workspace, or is linked to another product.\n- 400 `DUPLICATE_LESSON_VIDEO`: the same `videoId` is used in two lessons.\n- 403 `LIVE_LESSONS_PLAN_REQUIRED`: a lesson has `isLive: true` and the workspace plan does not include streaming (Icon).\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProductCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ProductDetail" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/products/{id}": { + "get": { + "operationId": "getProductsId", + "tags": [ + "products" + ], + "summary": "Get a digital product or course", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same detail the dashboard's product wizard opens: product data, CONFIRMED sales totals and, for courses, modules and lessons in order. Lesson quizzes (with the correct answers) are only included for `ADMIN` keys.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the product does not exist, was deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ProductDetail" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "patch": { + "operationId": "patchProductsId", + "tags": [ + "products" + ], + "summary": "Update a digital product or course", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as saving the dashboard's product wizard. Partial: absent fields keep their saved value. Omit `modules` to leave the course tree untouched (only product fields are written). Sending `modules` replaces the WHOLE tree: modules, lessons and resources are matched by `id` and the ones missing from the list are deleted, along with buyers' progress on those lessons — fetch a fresh `GET /products/{id}` right before and send its tree back with your changes. Changing `type` or `unlockMode` requires sending `modules`. New lessons on a published course with buyers notify them, like the dashboard. Returns the full product.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: a dashboard validation rule failed (e.g. a DOWNLOADABLE without a file, a COURSE without modules or a module without lessons, decimals in a COP price, more than one free preview lesson per module, a QUIZ lesson without questions). `error.message` says which.\n- 400 `INVALID_FILE`: a `filePath`/`samplePath`/lesson file/resource path is not under this workspace's product files folder.\n- 400 `INVALID_LESSON_THUMBNAIL`: a lesson `thumbnailUrl` is not an image of this workspace's media library.\n- 400 `INVALID_LESSON_VIDEO`: a lesson `videoId` is not a course video of this workspace, or is linked to another product.\n- 400 `DUPLICATE_LESSON_VIDEO`: the same `videoId` is used in two lessons.\n- 403 `LIVE_LESSONS_PLAN_REQUIRED`: a lesson has `isLive: true` and the workspace plan does not include streaming (Icon).\n- 400 `MODULES_REQUIRED`: `type` or `unlockMode` changes without `modules`.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the product does not exist, was deleted or belongs to another workspace.\n- 409 `COURSE_CHANGED`: the course changed concurrently (e.g. a lesson id no longer exists); read it again and retry.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProductUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ProductDetail" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteProductsId", + "tags": [ + "products" + ], + "summary": "Delete a digital product or course", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Delete\" in the dashboard.\n\nDESTRUCTIVE: the product disappears from the dashboard, the API and the public pages (soft delete). There is no restore endpoint.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the product does not exist, was already deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/products/{id}/status": { + "post": { + "operationId": "postProductsIdStatus", + "tags": [ + "products" + ], + "summary": "Publish or unpublish a digital product or course", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as the publish toggle in the dashboard's product list, with the target status explicit: sending the current status is a no-op. Publishing re-checks the plan for live lessons; unpublishing never does.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 403 `LIVE_LESSONS_PLAN_REQUIRED`: the course has live lessons and the workspace plan does not include streaming (Icon).\n- 404 `NOT_FOUND`: the product does not exist, was deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ProductStatusUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/videos/{id}": { + "patch": { + "operationId": "patchContentVideosId", + "tags": [ + "content" + ], + "summary": "Update an on-demand video", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as editing a video in the dashboard's Content screen. Partial: only the fields sent are validated and written (at least one); absent fields keep their stored value; `null` or `\"\"` clears `description`. Works on drafts and published videos. Uploading a video is not available through the API (the Mux direct upload needs a browser); course lesson videos are managed from their course and answer 404 here.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: `title` empty or longer than 120 characters, or `description` longer than 2000.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the video does not exist, was deleted, is a course video or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentVideoUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentVideoSummary" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteContentVideosId", + "tags": [ + "content" + ], + "summary": "Delete an on-demand video", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as deleting a video in the dashboard.\n\nDESTRUCTIVE and irreversible: soft-deletes the video and deletes its asset in Mux (the encoded file is gone; it cannot be restored through the API or the dashboard). Members lose access immediately.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the video does not exist, was already deleted, is a course video or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentMediaDeleted" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/videos/{id}/published": { + "put": { + "operationId": "putContentVideosIdPublished", + "tags": [ + "content" + ], + "summary": "Publish or unpublish an on-demand video", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as the publish switch in the dashboard. Publishing puts the video in the community feed as a VIDEO post (republishing revives the same post and members are notified once); unpublishing removes it from the feed.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the video does not exist, was deleted, is a course video or belongs to another workspace.\n- 409 `VIDEO_NOT_READY`: publishing a video Mux has not finished processing.\n- 409 `MEMBERSHIP_PREREQ`: the workspace has no active membership plan yet; create one first (members-only content needs something to pay for). Only checked when publishing.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentVideoPublish" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentVideoPublished" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/videos/{id}/series": { + "put": { + "operationId": "putContentVideosIdSeries", + "tags": [ + "content" + ], + "summary": "Move a video into a series or out of it", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as choosing a series for a video in the dashboard. `seriesId: null` leaves the video loose. Does not change whether the video is published.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the video, or the `seriesId` (see `error.message`), does not exist, was deleted or belongs to another workspace; course videos also answer 404.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentVideoSeriesAssign" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentVideoSeriesResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/series": { + "get": { + "operationId": "getContentSeries", + "tags": [ + "content" + ], + "summary": "List the video series", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Series of the dashboard's Content screen, published and drafts, newest first, with their video count.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "limit", + "in": "query", + "required": false, + "description": "1-100, default 20", + "schema": { + "type": "integer", + "default": 20 + } + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentSeries" + } + }, + "page": { + "$ref": "#/components/schemas/Page" + } + }, + "required": [ + "data", + "page" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postContentSeries", + "tags": [ + "content" + ], + "summary": "Create a video series", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"New series\" in the dashboard. The series is born unpublished and empty; add videos with `PUT /content/videos/{id}/series` and publish it with `PUT /content/series/{id}/published`.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: `title` empty or longer than 120 characters, `description` longer than 2000, or `coverImageUrl` not an absolute URL.\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 409 `MEMBERSHIP_PREREQ`: the workspace has no active membership plan yet; create one first (members-only content needs something to pay for).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentSeriesCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentSeries" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/series/{id}": { + "patch": { + "operationId": "patchContentSeriesId", + "tags": [ + "content" + ], + "summary": "Update a video series", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as editing a series in the dashboard. Partial: only the fields sent are validated and written (at least one); absent fields keep their stored value; `null` clears `description` / `coverImageUrl`.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: `title` empty or longer than 120 characters, `description` longer than 2000, or `coverImageUrl` not an absolute URL.\n- 403 `FEATURE_LOCKED`: the workspace plan does not include Content.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the series does not exist, was deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentSeriesUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentSeries" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteContentSeriesId", + "tags": [ + "content" + ], + "summary": "Delete a video series", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as deleting a series in the dashboard.\n\nDESTRUCTIVE: soft-deletes the series; it cannot be restored through the API. Its videos are NOT deleted or unpublished: they are left loose (no series, position reset), so the original grouping and order are lost.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the series does not exist, was already deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentMediaDeleted" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/series/{id}/published": { + "put": { + "operationId": "putContentSeriesIdPublished", + "tags": [ + "content" + ], + "summary": "Publish or unpublish a video series", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as the publish switch of a series in the dashboard. Only the series changes: its videos keep their own published state. Publishing again refreshes `publishedAt`.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the series does not exist, was deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentSeriesPublish" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentSeries" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/lives/{id}/reset-key": { + "post": { + "operationId": "postContentLivesIdResetKey", + "tags": [ + "content" + ], + "summary": "Rotate a live stream's stream key", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Reset key\" in the dashboard: Mux issues a new stream key and returns it with the RTMPS server.\n\nDESTRUCTIVE: the current key stops working immediately; any encoder (OBS) configured with it can no longer connect and must be updated with the new one. Use it when the key may have leaked.\n\nSECURITY: `streamKey` is a secret that grants broadcasting rights on this stream in the organization's name. It is returned only here and by `POST /content/lives`; store it like a password.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the stream does not exist, was deleted or belongs to another workspace.\n- 502 `MUX_ERROR`: Mux rejected the request or is not configured; the old key keeps working.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentLiveStreamKey" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/content/lives/{id}/chat": { + "get": { + "operationId": "getContentLivesIdChat", + "tags": [ + "content" + ], + "summary": "Chat history of a live stream", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header. Same history as \"View chat\" in the dashboard, for a stream on air or already ended: oldest to newest, capped (`truncated: true` when the oldest messages were cut). Contains buyers' display names and messages: treat it as personal data.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `NOT_FOUND`: the stream does not exist, was deleted or belongs to another workspace.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ContentLiveChat" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/website": { + "get": { + "operationId": "getWebsite", + "tags": [ + "website" + ], + "summary": "Get the workspace website configuration", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same data as the dashboard's Website screen: landing texts, social links, accent color, template, section visibility/order, and the public listing state (`published`, `canPublish`, `profileListable`). `customLandingEnabled` says whether the plan allows `PUT /website`.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (workspace configuration is out of its scope).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Website" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "put": { + "operationId": "putWebsite", + "tags": [ + "website" + ], + "summary": "Save the workspace website configuration", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Save\" in the dashboard's Website editor. FULL replacement: every field is required; `null` clears an optional text. Read `GET /website` first and send everything back. Shared columns: `name`, `bio`, `instagramUrl`, `tiktokUrl` and `youtubeUrl` are the same workspace columns that `PATCH /organization/profile` edits (`artist.name`, `artist.bio`, `social.*`) — a PUT with `null` here wipes them there too. An empty `name` is not accepted, and unlike the profile it is NOT mirrored to the brand. The profile photo and cover are NOT edited here (see `PATCH /organization`). Returns the saved configuration.\n\nErrors (`error.code`):\n- 403 `FEATURE_LOCKED`: the workspace plan does not include the custom landing.\n- 400 `INVALID_SECTIONS`: `webSections` is malformed.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebsiteUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Website" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/website/published": { + "put": { + "operationId": "putWebsitePublished", + "tags": [ + "website" + ], + "summary": "Publish or unpublish the public profile", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same switch as \"Appear in Artists\" in the dashboard: sets whether the organization's public page is listed. Available on every plan. Idempotent: send the desired state.\n\nErrors (`error.code`):\n- 409 `NO_ORGANIZATION`: the workspace has no umbrella organization.\n- 409 `NOT_PRIMARY_WORKSPACE`: only the organization's primary workspace can publish.\n- 409 `PROFILE_INCOMPLETE`: publishing needs the brand name and profile photo (unpublishing is always allowed).\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebsitePublished" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WebsitePublished" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/organization": { + "patch": { + "operationId": "patchOrganization", + "tags": [ + "organization" + ], + "summary": "Update the organization's public identity", + "description": "Minimum role: `ADMIN`, and the user must be OWNER/ADMIN of the umbrella organization of the active workspace (`X-Workspace-Id`). Same action as the identity card in the dashboard's organization settings: public name, profile photo and cover. Partial: absent fields keep their value; `null` clears an image. The name is mirrored to the primary workspace. The slug (public URL) cannot be changed here. Returns the organization.\n\nErrors (`error.code`):\n- 403 `ORG_ADMIN_REQUIRED`: the user is not OWNER/ADMIN of the organization.\n- 409 `NO_ORGANIZATION`: the workspace has no umbrella organization.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Organization" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/organization/analytics": { + "patch": { + "operationId": "patchOrganizationAnalytics", + "tags": [ + "organization" + ], + "summary": "Set the organization's GA4 property", + "description": "Minimum role: `ADMIN`, and the user must be OWNER/ADMIN of the umbrella organization of the active workspace (`X-Workspace-Id`). Same action as the analytics card in the dashboard's organization settings: the brand's own GA4 Measurement ID, added to the checkout of its events next to FreeTicket's. `null` (or an empty string) disconnects it.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: not a GA4 Measurement ID (G-XXXXXXXXXX).\n- 403 `ORG_ADMIN_REQUIRED`: the user is not OWNER/ADMIN of the organization.\n- 409 `NO_ORGANIZATION`: the workspace has no umbrella organization.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationAnalyticsUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/OrganizationAnalytics" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/organization/profile": { + "get": { + "operationId": "getOrganizationProfile", + "tags": [ + "organization" + ], + "summary": "Get the workspace profile", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same data as the dashboard's Profile screen: artist/venue/organizer data, brand photo and cover (from the umbrella organization), contact and social links. Billing/plan data is not included.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/OrganizationProfile" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "patch": { + "operationId": "patchOrganizationProfile", + "tags": [ + "organization" + ], + "summary": "Update the workspace profile", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same actions as the four cards of the dashboard's Profile screen, as optional sections: `artist` (name, slug, bio, type, country, timezone), `visual` (brand photo/cover, stored on the umbrella organization), `contact` and `social`. Partial: only the fields sent are written; absent fields keep their value and `null` clears an optional one. Sections are applied in order artist → visual → contact → social; if one fails, the earlier ones stay saved. Changing `artist.slug` changes the workspace's URLs. `visual` and `artist.name` write organization-level columns (the brand photo/cover and the brand name mirror), so they additionally require the user to be OWNER/ADMIN of the umbrella organization — checked before ANY section is written (stricter than the dashboard, same rule as `PATCH /organization`). Returns the updated profile.\n\nErrors (`error.code`):\n- 403 `ORG_ADMIN_REQUIRED`: `visual` or `artist.name` sent by a user who is not OWNER/ADMIN of the organization (nothing is written).\n- 409 `SLUG_TAKEN`: `artist.slug` is used by another workspace, including deleted ones (nothing is written).\n- 409 `ORG_NOT_INITIALIZED`: `visual` sent but the workspace has no umbrella organization (nothing is written).\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationProfileUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/OrganizationProfile" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/ticket-templates": { + "get": { + "operationId": "getTicketTemplates", + "tags": [ + "ticket-templates" + ], + "summary": "List the ticket templates", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header. Same list as the dashboard's Ticket templates screen: reusable ticket-type definitions (price, capacity, member discount/gate, buyer form fields), ordered for display. Deleted templates are omitted.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (templates are workspace configuration).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TicketTemplate" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postTicketTemplates", + "tags": [ + "ticket-templates" + ], + "summary": "Create a ticket template", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"New template\" in the dashboard. A SELECT field needs at least 2 options (422 otherwise).\n\nErrors (`error.code`):\n- 400 `INVALID_CURRENCY`: the currency is not one the checkout charges.\n- 400 `DISCOUNT_PLAN_INVALID`: `discount.planId` is not an active membership plan of this workspace.\n- 400 `MEMBERS_ONLY_PLAN_INVALID`: `membersOnlyPlanId` cannot gate this workspace's tickets.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketTemplateCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TicketTemplate" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/ticket-templates/{id}": { + "patch": { + "operationId": "patchTicketTemplatesId", + "tags": [ + "ticket-templates" + ], + "summary": "Update a ticket template", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as editing a template in the dashboard. Partial: only the fields sent are written; `null` clears an optional one (`discount: null` removes the member discount, `membersOnlyPlanId: null` opens it to everyone). `fields` replaces the whole buyer-form list when sent and is left intact when absent. Ticket types already created from the template are copies and do not change. A legacy currency outside the checkout list is accepted only if unchanged.\n\nErrors (`error.code`):\n- 400 `INVALID_CURRENCY`: the currency is not one the checkout charges.\n- 400 `DISCOUNT_PLAN_INVALID`: `discount.planId` is not an active membership plan of this workspace.\n- 400 `MEMBERS_ONLY_PLAN_INVALID`: `membersOnlyPlanId` cannot gate this workspace's tickets.\n- 404 `NOT_FOUND`: the template does not exist, is deleted or belongs to another workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketTemplateUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TicketTemplate" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteTicketTemplatesId", + "tags": [ + "ticket-templates" + ], + "summary": "Delete a ticket template", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as deleting a template in the dashboard.\n\nDESTRUCTIVE: the template is removed from the workspace (soft delete, there is no restore via API). Ticket types already created from it keep working.\n\nErrors (`error.code`):\n- 404 `NOT_FOUND`: the template does not exist, is already deleted or belongs to another workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WorkspaceConfigDeleted" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/ticket-templates/{id}/instantiate": { + "post": { + "operationId": "postTicketTemplatesIdInstantiate", + "tags": [ + "ticket-templates" + ], + "summary": "Create a ticket type from a template", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"Use template\" in the dashboard: creates a ticket type on `eventDateId` copying the template (price, capacity, discount, members-only gate, buyer form). `name`, `price` and `capacity` override the template's. A discount or gate whose plan is no longer valid is dropped instead of failing. Keys restricted to events may use it only on dates of their events.\n\nErrors (`error.code`):\n- 404 `NOT_FOUND`: the template does not exist, is deleted or belongs to another workspace.\n- 404 `EVENT_DATE_NOT_FOUND`: the event date does not exist or belongs to another workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to events and the date's event is not one of them.\n- 400 `CAPACITY_REQUIRED`: the template has no capacity and `capacity` was not sent.\n- 400 `INVALID_CURRENCY`: the template's legacy currency is not one the checkout charges.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketTemplateInstantiate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TicketTemplateInstance" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/master-qrs": { + "get": { + "operationId": "getMasterQrs", + "tags": [ + "master-qrs" + ], + "summary": "List the master box-office QR codes", + "description": "Minimum role: `ADMIN` (also for reading, like the dashboard). Active workspace via the `X-Workspace-Id` header. Same list as the dashboard's Box-office QR screen: live (not deleted) QR codes, newest first, with scan counters. `code` and `url` are SECRET: they are what the printed QR encodes and open the public sale flow; they cannot be rotated. Do not log or share them.\n\nErrors (`error.code`):\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events (org-wide QR codes span every show).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MasterQr" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "operationId": "postMasterQrs", + "tags": [ + "master-qrs" + ], + "summary": "Create a master box-office QR code", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as \"New QR\" in the dashboard. `eventId` absent/null = org-wide QR (all shows); `ticketTypeId` pins a ticket type of that event (not allowed on an org-wide QR → 422). Returns the QR with its code. `code` and `url` are SECRET: they are what the printed QR encodes and open the public sale flow; they cannot be rotated. Do not log or share them.\n\nErrors (`error.code`):\n- 400 `INVALID_TARGET`: the event is not of this workspace, or the ticket type is not a visible ticket type of a sellable date of that event.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MasterQrCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MasterQr" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/master-qrs/{id}": { + "patch": { + "operationId": "patchMasterQrsId", + "tags": [ + "master-qrs" + ], + "summary": "Update a master box-office QR code", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as editing a QR in the dashboard. Partial: `label` and `mode` can be sent alone; the target (`eventId` + `ticketTypeId`, `null` for none / org-wide) must be sent as a pair (422 otherwise). The code does not change, so the printed QR keeps working and now points to the new target.\n\nErrors (`error.code`):\n- 400 `INVALID_TARGET`: the event is not of this workspace, or the ticket type does not belong to it.\n- 404 `NOT_FOUND`: the QR does not exist, is deleted or belongs to another workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MasterQrUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MasterQr" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "operationId": "deleteMasterQrsId", + "tags": [ + "master-qrs" + ], + "summary": "Delete a master box-office QR code", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same action as deleting a QR in the dashboard.\n\nDESTRUCTIVE: the QR is deactivated and deleted (soft delete, the scan history is kept); the printed code stops working and cannot be restored via API. To pause it instead, use `PUT /master-qrs/{id}/active`.\n\nErrors (`error.code`):\n- 404 `NOT_FOUND`: the QR does not exist, is already deleted or belongs to another workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "x-ft-destructive": true, + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/WorkspaceConfigDeleted" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/master-qrs/{id}/active": { + "put": { + "operationId": "putMasterQrsIdActive", + "tags": [ + "master-qrs" + ], + "summary": "Activate or deactivate a master box-office QR code", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header. Same switch as in the dashboard's QR table. While inactive, scanning the QR answers 404. Idempotent: send the desired state.\n\nErrors (`error.code`):\n- 404 `NOT_FOUND`: the QR does not exist, is deleted or belongs to another workspace.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MasterQrActive" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MasterQrActive" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Resource does not exist or is out of scope.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/merch/catalog": { + "get": { + "operationId": "getMerchCatalog", + "tags": [ + "merch" + ], + "summary": "Merch store catalog of the key's brand", + "description": "Requires an enterprise service API key (Legend headless landing, called server-side); the store is ALWAYS the one of the key's organization. Returns the store settings (brand, support, shipping fees by zone — Bogotá is DANE 11001 —, free-shipping threshold, delivery modes), the PUBLISHED products with their active variants and `stock` (units available right now, already net of open 15-minute reservations), the active pickup points (only when pickup is enabled) and the MercadoPago public key for the Payment Brick. Prices are COP integers, VAT included; the buyer pays no service fee. 403 `MERCH_STORE_LOCKED` when the brand's Legend plan is not active; 404 `STORE_NOT_READY` when the brand has no store or its onboarding is incomplete.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MerchCatalog" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "Missing or invalid credential.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/merch/orders": { + "post": { + "operationId": "postMerchOrders", + "tags": [ + "merch" + ], + "summary": "Create a merch order and reserve its stock", + "description": "Requires an enterprise service API key AND a valid `X-Customer-Session` (401 without it); the buyer email is the session's (it is NOT sent in the body) and the order is always linked to that customer. The order belongs to the key's organization store (variant ids from another store respond 409 `VARIANT_UNAVAILABLE`). Creates a PENDING order and reserves the stock for 15 minutes, all-or-nothing: if any variant lacks units nothing is reserved (409 `OUT_OF_STOCK` with `details: [{ variantId, requested, available }]`). Prices, shipping and totals are computed server-side from the catalog (`total = subtotal + shippingFee`; shipping is 0 for pickup or above the free-shipping threshold). `max_per_order` is per product, adding all its variants (422 `MAX_PER_ORDER`); a delivery mode that is disabled, or an inactive pickup point, responds 422 `DELIVERY_UNAVAILABLE`. DANE codes are validated by shape (department 2 digits, city 5 digits starting with the department). Accepts `Idempotency-Key` (unique per store): retrying with the same key returns the order created on the first attempt (201 with `Idempotent-Replay: true`) without reserving stock again; the replay is only returned to the same customer as the original order (otherwise 422 `IDEMPOTENCY_KEY_REUSED`). A customer with a live PENDING order in the store who places another one REPLACES it (the previous order is cancelled and its stock returned in the same transaction), unless that order already has a payment attempt in flight (409 `ACTIVE_ORDER_EXISTS`). A live PENDING order of ANOTHER customer with the same phone (normalized to E.164, any country code) also responds 409 `ACTIVE_ORDER_EXISTS` (the existing order is never revealed). Optional `X-Buyer-Ip` (the buyer's IPv4/IPv6, sent by the landing server-to-server; invalid values are ignored): at most 10 orders per 10 minutes per store and IP (429 `RATE_LIMITED`). Rate limited: 5 orders/min per customer (429 `RATE_LIMITED` with `Retry-After`). 403 `MERCH_STORE_LOCKED` without an active Legend plan; 404 `STORE_NOT_READY` without a ready store. The buyer document is never returned.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "Idempotency-Key", + "in": "header", + "required": false, + "description": "Client-chosen idempotency key (max. 255 characters). Retrying with the SAME key returns the order created by the first attempt instead of reserving stock again. Unique per store.", + "schema": { + "type": "string" + } + }, + { + "name": "X-Buyer-Ip", + "in": "header", + "required": false, + "description": "Optional IPv4/IPv6 of the end buyer, forwarded by the landing server-to-server. Invalid values are ignored. Limits 10 orders per 10 minutes per store and IP.", + "schema": { + "type": "string" + } + }, + { + "name": "X-Customer-Session", + "in": "header", + "required": false, + "description": "REQUIRED buyer session token (401 without it). Its customer is the buyer identity: email, rate limits, idempotency replay and ownership.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MerchOrderCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MerchOrder" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + } + } + } + }, + "/merch/orders/lookup": { + "post": { + "operationId": "postMerchOrdersLookup", + "tags": [ + "merch" + ], + "summary": "Look up one of the session buyer's merch orders by code", + "description": "Requires an enterprise service API key AND a valid `X-Customer-Session` (401 without it). Only orders of the key's organization store that belong to the session's customer are visible, found by the public `code` (e.g. `M-7K3Q9ZTA`, case-insensitive). An unknown code, a code from another brand and a code of another customer all respond the same 404 `ORDER_NOT_FOUND`. The buyer document is never returned. Rate limited: 10 lookups/min per key and code (429 `RATE_LIMITED` with `Retry-After`). Lookups keep working after the brand's Legend plan lapses (the order was already placed); 404 `STORE_NOT_READY` when the brand has no store.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "X-Customer-Session", + "in": "header", + "required": false, + "description": "REQUIRED buyer session token (401 without it). Orders are scoped to its customer.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MerchOrderLookup" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MerchOrder" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Insufficient role or resource not accessible.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + } + } + } + }, + "/merch/orders/{code}/payment/card": { + "post": { + "operationId": "postMerchOrdersCodePaymentCard", + "tags": [ + "merch" + ], + "summary": "Charge a merch order with the Payment Brick token", + "description": "Requires an enterprise service API key AND a valid `X-Customer-Session` (401 without it). Only orders of the key's organization store that belong to the session's customer are reachable (an unknown code, a code from another brand and a code of another customer all respond the same 404 `ORDER_NOT_FOUND`). Receives the token the Payment Brick produced on the landing's domain and charges through the MercadoPago Orders API using the order total from the database (never one sent by the client); the reservation is extended (capped at 45 minutes after creation) before the charge. Card only. `status` is `approved`, `pending` (normal: bank authentication or processing, also for an unrecognized MercadoPago status; confirmed later by webhook — poll `/merch/orders/lookup`) or `rejected` (business decline, reason in `message`; the order stays pending until its reservation expires, so the buyer can retry with another card) — all three return 200. Responds 409 `RESERVATION_EXPIRED` when the reservation lapsed (start a new order), 409 `ORDER_NOT_PAYABLE` when the order is no longer pending, 409 `PAYMENT_IN_PROGRESS` when another charge of the order is still in flight (pending bank authentication or processing, or a concurrent request with a different token): poll `/merch/orders/lookup` instead of charging another card — a definitively rejected charge never blocks a new attempt, and retrying with the SAME token is allowed (idempotent at MercadoPago), 409 `PAYMENT_REFUNDED` when the card was approved after the reservation expired and the stock ran out (the amount is refunded automatically), 502 `PAYMENT_GATEWAY_ERROR` when MercadoPago did not answer or failed (timeout, network, 5xx): the payment may still confirm via webhook, so until it is resolved another card gets 409 `PAYMENT_IN_PROGRESS` — the block lifts when MercadoPago reports the charge rejected, or about 90 seconds later if MercadoPago has no record of it. 403 `MERCH_STORE_LOCKED` when the brand's Legend plan is not active; 404 `STORE_NOT_READY` when the brand has no store. Limited to 10 attempts per minute per API key, customer and order code (429 with `Retry-After`).", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "code", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "X-Workspace-Id", + "in": "header", + "required": false, + "description": "Active workspace to operate on. Optional: when omitted, the default workspace of the user who owns the key is used (pickActiveOrg).", + "schema": { + "type": "string" + } + }, + { + "name": "X-Customer-Session", + "in": "header", + "required": false, + "description": "REQUIRED buyer session token (401 without it). Orders are scoped to its customer.", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MerchCardPayment" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MerchCardPaymentResult" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "401": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "403": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Operation error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many requests: rate limit exceeded.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } + } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Error": { + "type": "object", + "properties": { + "error": { + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "retryable": { + "type": "boolean" + }, + "details": {} + }, + "required": [ + "code", + "message", + "retryable" + ], + "additionalProperties": false + } + }, + "required": [ + "error" + ], + "additionalProperties": false + }, + "Warning": { + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "message": { + "type": "string" + }, + "field": { + "type": "string" + }, + "activeWorkspaceId": { + "type": "string" + }, + "activeWorkspaceName": { + "type": "string" + }, + "accessibleWorkspaces": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "suggestedWorkspaceId": { + "type": "string" + }, + "suggestedWorkspaceName": { + "type": "string" + }, + "ids": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "code", + "message" + ], + "additionalProperties": false + }, + "Page": { + "type": "object", + "properties": { + "nextCursor": { + "type": [ + "string", + "null" + ] + }, + "hasMore": { + "type": "boolean" + }, + "total": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "nextCursor", + "hasMore" + ], + "additionalProperties": false + }, + "Workspace": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "type": "string" + } + }, + "required": [ + "id", + "name", + "slug" + ], + "additionalProperties": false + }, + "WorkspaceAccess": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "role": { + "type": "string", + "enum": [ + "SUPER_ADMIN", + "ADMIN", + "STAFF", + "VIEWER", + "MINCULTURA", + "MERCH_MANAGER" + ], + "description": "The user's effective role IN THIS workspace." + }, + "sections": { + "anyOf": [ + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "null" + } + ], + "description": "Enabled sections (slugs). null = unrestricted; [] = access expired or revoked." + } + }, + "required": [ + "id", + "name", + "slug", + "role", + "sections" + ], + "additionalProperties": false + }, + "Me": { + "type": "object", + "properties": { + "userId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "role": { + "type": "string", + "enum": [ + "SUPER_ADMIN", + "ADMIN", + "STAFF", + "VIEWER", + "MINCULTURA", + "MERCH_MANAGER" + ], + "description": "DEPRECATED: effective role in the ACTIVE workspace. Use the `role` of each `workspaces` row instead. Kept for compatibility with already-published clients." + }, + "activeWorkspaceId": { + "type": [ + "string", + "null" + ] + }, + "workspaces": { + "type": "array", + "items": { + "$ref": "#/components/schemas/WorkspaceAccess" + } + } + }, + "required": [ + "userId", + "name", + "email", + "role", + "activeWorkspaceId", + "workspaces" + ], + "additionalProperties": false + }, + "SignupRequest": { + "type": "object", + "properties": { + "email": { + "type": "string", + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + }, + "name": { + "type": "string", + "minLength": 2, + "maxLength": 120 + }, + "workspaceName": { + "type": "string", + "minLength": 2, + "maxLength": 80 + } + }, + "required": [ + "email", + "name" + ], + "additionalProperties": false + }, + "SignupResponse": { + "type": "object", + "properties": { + "user_id": { + "type": "string" + }, + "status": { + "type": "string", + "const": "pending_verification" + }, + "verification_sent_to": { + "type": "string" + } + }, + "required": [ + "user_id", + "status", + "verification_sent_to" + ], + "additionalProperties": false + }, + "WorkspaceCreate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 80 + }, + "slug": { + "type": "string", + "minLength": 2, + "maxLength": 50, + "pattern": "^[a-z0-9-]+$" + } + }, + "required": [ + "name", + "slug" + ], + "additionalProperties": false + }, + "DeviceCodeResponse": { + "type": "object", + "properties": { + "device_code": { + "type": "string" + }, + "user_code": { + "type": "string" + }, + "verification_uri": { + "type": "string" + }, + "verification_uri_complete": { + "type": "string" + }, + "expires_in": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "interval": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "device_code", + "user_code", + "verification_uri", + "verification_uri_complete", + "expires_in", + "interval" + ], + "additionalProperties": false + }, + "DeviceTokenRequest": { + "type": "object", + "properties": { + "device_code": { + "type": "string", + "minLength": 1 + }, + "grant_type": { + "type": "string", + "const": "urn:ietf:params:oauth:grant-type:device_code" + } + }, + "required": [ + "device_code" + ], + "additionalProperties": false + }, + "DeviceTokenResponse": { + "type": "object", + "properties": { + "access_token": { + "type": "string" + }, + "token_type": { + "type": "string", + "const": "Bearer" + }, + "user": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "email": { + "type": "string" + }, + "role": { + "type": "string", + "enum": [ + "SUPER_ADMIN", + "ADMIN", + "STAFF", + "VIEWER", + "MINCULTURA", + "MERCH_MANAGER" + ] + } + }, + "required": [ + "id", + "email", + "role" + ], + "additionalProperties": false + }, + "workspaces": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Workspace" + } + } + }, + "required": [ + "access_token", + "token_type", + "user", + "workspaces" + ], + "additionalProperties": false + }, + "DeviceTokenError": { + "type": "object", + "properties": { "error": { + "type": "string", + "enum": [ + "authorization_pending", + "slow_down", + "expired_token", + "access_denied", + "invalid_request" + ] + } + }, + "required": [ + "error" + ], + "additionalProperties": false + }, + "Venue": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "address": { + "type": "string" + }, + "city": { + "type": "string" + }, + "country": { + "type": "string" + }, + "latitude": { + "type": [ + "number", + "null" + ] + }, + "longitude": { + "type": [ + "number", + "null" + ] + }, + "capacity": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "googlePlaceId": { + "type": [ + "string", + "null" + ] + }, + "portalVisible": { + "type": "boolean" + }, + "organizationId": { + "type": [ + "string", + "null" + ] + }, + "seatsioChartKey": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "name", + "slug", + "address", + "city", + "country", + "latitude", + "longitude", + "capacity", + "googlePlaceId", + "portalVisible", + "organizationId", + "seatsioChartKey", + "createdAt" + ], + "additionalProperties": false + }, + "EventNextDate": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "label": { + "type": [ + "string", + "null" + ] + }, + "startsAt": { + "type": "string" + }, + "endsAt": { + "type": [ + "string", + "null" + ] + }, + "timezone": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "SOLD_OUT", + "CANCELLED", + "COMPLETED" + ] + } + }, + "required": [ + "id", + "label", + "startsAt", + "endsAt", + "timezone", + "status" + ], + "additionalProperties": false + }, + "EventArtist": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "type": [ + "string", + "null" + ] + }, + "type": { + "type": "string", + "enum": [ + "ARTIST", + "VENUE", + "ORGANIZER" + ] + } + }, + "required": [ + "id", + "name", + "slug", + "type" + ], + "additionalProperties": false + }, + "Event": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "SOLD_OUT", + "CANCELLED", + "COMPLETED" + ] + }, + "coverImageUrl": { + "type": [ + "string", + "null" + ] + }, + "bannerImageUrl": { + "type": [ + "string", + "null" + ] + }, + "squareImageUrl": { + "type": [ + "string", + "null" + ] + }, + "storyImageUrl": { + "type": [ + "string", + "null" + ] + }, + "organizationId": { + "type": "string" + }, + "venueId": { + "type": [ + "string", + "null" + ] + }, + "venue": { + "anyOf": [ + { + "$ref": "#/components/schemas/Venue" + }, + { + "type": "null" + } + ] + }, + "externalTicketUrl": { + "type": [ + "string", + "null" + ] + }, + "access": { + "type": "string", + "enum": [ + "owner", + "artist" + ], + "description": "owner = the key's workspace owns the event (editable). artist = read-only: linked artist or catalog access." + }, + "nextDate": { + "anyOf": [ + { + "$ref": "#/components/schemas/EventNextDate" + }, + { + "type": "null" + } + ] + }, + "artists": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EventArtist" + } + }, + "publishAt": { + "description": "Scheduled publication instant (ISO 8601, UTC) of a DRAFT event; null = not scheduled. See `POST /events/{id}/schedule`.", + "type": [ + "string", + "null" + ] + }, + "pulepCode": { + "description": "PULEP registration code (Colombian Ministry of Culture). Required for performing-arts events with capacity above 400.", + "type": [ + "string", + "null" + ] + }, + "listedOnPortal": { + "description": "false = hidden from portal discovery (listings, search, home); still reachable by direct link.", + "type": "boolean" + }, + "genreOther": { + "description": "Free-text event type, only when the genre is \"otro\".", + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": [ + "id", + "name", + "slug", + "description", + "status", + "coverImageUrl", + "bannerImageUrl", + "squareImageUrl", + "storyImageUrl", + "organizationId", + "venueId", + "venue", + "externalTicketUrl", + "access", + "createdAt", + "updatedAt" + ], + "additionalProperties": false + }, + "TicketPriceStage": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "price": { + "type": "number" + }, + "sortOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "endsAt": { + "description": "Closes once this date passes (ISO 8601). null = no date cutoff.", + "type": [ + "string", + "null" + ] + }, + "quantity": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ], + "description": "Tickets at this price. The cutoff is CUMULATIVE across the ticket type: the stage closes when sold + reserved reaches the sum of `quantity` for this stage and all previous ones. null = no quantity cutoff." + }, + "isCurrent": { + "type": "boolean", + "description": "true for the stage currently in effect (the first one still open). If none is, the ticket type's `price` applies." + } + }, + "required": [ + "id", + "name", + "price", + "sortOrder", + "endsAt", + "quantity", + "isCurrent" + ], + "additionalProperties": false + }, + "TicketType": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "eventDateId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "price": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "capacity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "sold": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "available": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "soldOut": { + "type": "boolean" + }, + "maxPerOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "saleStartsAt": { + "type": [ + "string", + "null" + ] + }, + "saleEndsAt": { + "type": [ + "string", + "null" + ] + }, + "isVisible": { + "type": "boolean" + }, + "organizerAbsorbsFee": { + "type": "boolean" + }, + "buyerServiceFee": { + "type": "number" + }, + "seatingSurcharge": { + "type": "number" + }, + "iva": { + "type": "number" + }, + "buyerTotal": { + "type": "number" + }, + "seatsioCategoryKey": { + "type": [ + "string", + "null" + ] + }, + "priceStages": { + "description": "Price stages preceding the final price, ordered by `sortOrder`. `[]` = fixed price. Absent if the response does not include them.", + "type": "array", + "items": { + "$ref": "#/components/schemas/TicketPriceStage" + } + }, + "currentPrice": { + "description": "CURRENT base price per unit (the open stage, or `price` if none). Present alongside `priceStages`.", + "type": "number" + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "eventDateId", + "name", + "description", + "price", + "currency", + "capacity", + "sold", + "available", + "soldOut", + "maxPerOrder", + "saleStartsAt", + "saleEndsAt", + "isVisible", + "organizerAbsorbsFee", + "buyerServiceFee", + "seatingSurcharge", + "iva", + "buyerTotal", + "seatsioCategoryKey", + "createdAt" + ], + "additionalProperties": false + }, + "EventDate": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "eventId": { + "type": "string" + }, + "label": { + "type": [ + "string", + "null" + ] + }, + "startsAt": { + "type": "string" + }, + "endsAt": { + "type": [ + "string", + "null" + ] + }, + "doorsOpenAt": { + "type": [ + "string", + "null" + ] + }, + "timezone": { + "type": "string" + }, + "venueId": { + "type": [ + "string", + "null" + ] + }, + "venue": { + "anyOf": [ + { + "$ref": "#/components/schemas/Venue" + }, + { + "type": "null" + } + ] + }, + "ticketTypes": { + "default": [], + "type": "array", + "items": { + "$ref": "#/components/schemas/TicketType" + } + }, + "seatsioEventKey": { + "readOnly": true, + "description": "seats.io event key. Read-only: issued by automatic provisioning; writing it by hand orphans seats already sold.", + "type": [ + "string", + "null" + ] + }, + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "SOLD_OUT", + "CANCELLED", + "COMPLETED" + ] + }, + "streamType": { + "type": "string" + }, + "maxPerCustomer": { + "description": "Cumulative per-buyer cap across ALL ticket types of this date. null = no date-level cap (each ticket type's own cap applies).", + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "eventId", + "label", + "startsAt", + "endsAt", + "doorsOpenAt", + "timezone", + "venueId", + "venue", + "ticketTypes", + "seatsioEventKey", + "status", + "streamType", + "createdAt" + ], + "additionalProperties": false + }, + "EventCreate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "slug": { + "type": "string", + "minLength": 1, + "pattern": "^[a-z0-9-]+$" + }, + "description": { + "type": "string" + }, + "venueId": { + "type": [ + "string", + "null" + ] + }, + "dates": { + "minItems": 1, + "type": "array", + "items": { + "type": "object", + "properties": { + "startsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "endsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "timezone": { + "default": "America/Bogota", + "type": "string", + "minLength": 1 + } + }, + "required": [ + "startsAt", + "timezone" + ], + "additionalProperties": false + } + } + }, + "required": [ + "name", + "slug", + "dates" + ], + "additionalProperties": false + }, + "EventUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "venueId": { + "type": [ + "string", + "null" + ] + }, + "coverImageUrl": { + "anyOf": [ + { + "type": "string", + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "slug": { + "description": "Public URL slug. Must be unique across live events (409 `SLUG_TAKEN`).", + "type": "string", + "minLength": 1, + "maxLength": 100, + "pattern": "^[a-z0-9-]+$" + }, + "squareImageUrl": { + "anyOf": [ + { + "type": "string", + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "storyImageUrl": { + "anyOf": [ + { + "type": "string", + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "pulepCode": { + "description": "PULEP code. Required (422 `PULEP_REQUIRED`) when the event is performing arts (or has no genre) and its capacity per date exceeds 400.", + "anyOf": [ + { + "type": "string", + "maxLength": 50 + }, + { + "type": "null" + } + ] + }, + "listedOnPortal": { + "type": "boolean" + }, + "genre": { + "description": "Event type from the taxonomy.", + "type": "string", + "enum": [ + "comedia", + "musica", + "teatro", + "danza", + "cultura", + "familiar", + "fiesta", + "deporte", + "conferencia", + "otro" + ] + }, + "subgenre": { + "description": "Subtype; must belong to `genre`, which must be sent in the same request. null = no subtype.", + "anyOf": [ + { + "type": "string", + "enum": [ + "stand_up", + "impro", + "sketch", + "satira", + "rock", + "indie", + "pop", + "urbano", + "salsa", + "vallenato", + "electronica", + "tributo", + "opera", + "musical" + ] + }, + { + "type": "null" + } + ] + }, + "genreOther": { + "description": "Free-text type. Required when `genre` is \"otro\".", + "type": "string", + "minLength": 1, + "maxLength": 60 + }, + "audience": { + "description": "Minimum age classification. null = unspecified.", + "anyOf": [ + { + "type": "string", + "enum": [ + "todo_publico", + "mayores_14", + "mayores_18", + "infantil" + ] + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "EventDateCreate": { + "type": "object", + "properties": { + "label": { + "anyOf": [ + { + "type": "string", + "maxLength": 200 + }, + { + "type": "null" + } + ] + }, + "startsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "endsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "doorsOpenAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "timezone": { + "default": "America/Bogota", + "type": "string", + "minLength": 1 + }, + "venueId": { + "type": [ + "string", + "null" + ] + }, + "streamType": { + "default": "PRESENCIAL", + "type": "string", + "enum": [ + "PRESENCIAL", + "ONLINE", + "HIBRIDO" + ] + }, + "maxPerCustomer": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 10000 + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "startsAt", + "timezone" + ], + "additionalProperties": false + }, + "EventDateUpdate": { + "type": "object", + "properties": { + "label": { + "anyOf": [ + { + "type": "string", + "maxLength": 200 + }, + { + "type": "null" + } + ] + }, + "startsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "endsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "doorsOpenAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "timezone": { + "type": "string", + "minLength": 1 + }, + "venueId": { + "type": [ + "string", + "null" + ] + }, + "streamType": { + "type": "string", + "enum": [ + "PRESENCIAL", + "ONLINE", + "HIBRIDO" + ] + }, + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "SOLD_OUT", + "CANCELLED", + "COMPLETED" + ] + }, + "maxPerCustomer": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 10000 + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "TicketTypeCreate": { + "type": "object", + "properties": { + "eventDateId": { + "type": "string", + "minLength": 1 + }, + "name": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": "string" + }, + "price": { + "type": "number", + "minimum": 0 + }, + "currency": { + "default": "COP", + "type": "string", + "enum": [ + "COP" + ] + }, + "capacity": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "maxPerOrder": { + "default": 10, + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "isVisible": { + "default": true, + "type": "boolean" + }, + "organizerAbsorbsFee": { + "default": false, + "type": "boolean" + }, + "saleStartsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "saleEndsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "seatsioCategoryKey": { + "anyOf": [ + { + "type": "string", + "minLength": 1 + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "eventDateId", + "name", + "price", + "currency", + "capacity", + "maxPerOrder", + "isVisible", + "organizerAbsorbsFee" + ], + "additionalProperties": false + }, + "TicketTypeUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "price": { + "type": "number", + "minimum": 0 + }, + "currency": { + "description": "Solo COP; se tolera la moneda ya guardada si no cambia.", + "type": "string", + "minLength": 3, + "maxLength": 3 + }, + "capacity": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "maxPerOrder": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "isVisible": { + "type": "boolean" + }, + "organizerAbsorbsFee": { + "type": "boolean" + }, + "saleStartsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "saleEndsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] + }, + "seatsioCategoryKey": { + "anyOf": [ + { + "type": "string", + "minLength": 1 + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "EventSchedule": { + "type": "object", + "properties": { + "publishAt": { + "description": "Publish the DRAFT automatically at this instant (UTC). Must be in the future and before at least one of its dates.", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "saleStartsAt": { + "description": "Publish the DRAFT NOW and open ticket sales at this instant (UTC): sets `saleStartsAt` on every ticket type of the upcoming dates. Must be in the future and before the first upcoming date.", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + } + }, + "additionalProperties": false + }, + "PresaleWindow": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "ticketTypeId": { + "type": "string" + }, + "planId": { + "type": "string", + "description": "Membership plan whose active members get early access." + }, + "presaleStartsAt": { + "type": "string" + }, + "presaleEndsAt": { + "type": "string" + }, + "presaleCapacity": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ], + "description": "Sub-cap of tickets sellable during the presale. null = shares the ticket type's whole capacity." + }, + "isActive": { + "type": "boolean" + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + } + }, + "required": [ + "id", + "ticketTypeId", + "planId", + "presaleStartsAt", + "presaleEndsAt", + "presaleCapacity", + "isActive", + "createdAt", + "updatedAt" + ], + "additionalProperties": false + }, + "PresaleWindowCreate": { + "type": "object", + "properties": { + "planId": { + "type": "string", + "minLength": 1 + }, + "presaleStartsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "presaleEndsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "presaleCapacity": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "isActive": { + "default": true, + "type": "boolean" + } + }, + "required": [ + "planId", + "presaleStartsAt", + "presaleEndsAt" + ], + "additionalProperties": false + }, + "PresaleWindowUpdate": { + "type": "object", + "properties": { + "planId": { + "type": "string", + "minLength": 1 + }, + "presaleStartsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "presaleEndsAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "presaleCapacity": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "isActive": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "SaleItem": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "ticketTypeId": { + "type": "string" + }, + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "unitPrice": { + "type": "number" + }, + "subtotal": { + "type": "number" + }, + "ticketCode": { + "type": "string" + }, + "checkedInAt": { + "type": [ + "string", + "null" + ] + }, + "seatLabel": { + "type": [ + "string", + "null" + ] + }, + "refundedAt": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "ticketTypeId", + "quantity", + "unitPrice", + "subtotal", + "ticketCode", + "checkedInAt", + "seatLabel", + "refundedAt" + ], + "additionalProperties": false + }, + "Sale": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "reference": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + }, + "channel": { + "type": "string" + }, + "subtotal": { + "type": "number" + }, + "discountAmount": { + "type": "number" + }, + "serviceFee": { + "type": "number" + }, + "iva": { + "type": "number" + }, + "total": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "buyerName": { + "type": "string" + }, + "buyerEmail": { + "type": "string" + }, + "buyerPhone": { + "type": [ + "string", + "null" + ] + }, + "buyerDocumentType": { + "type": [ + "string", + "null" + ] + }, + "buyerDocumentNumber": { + "type": [ + "string", + "null" + ] + }, + "organizationId": { + "type": [ + "string", + "null" + ] + }, + "paymentProvider": { + "type": [ + "string", + "null" + ] + }, + "paymentRef": { + "type": [ + "string", + "null" + ] + }, + "confirmedAt": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" + }, + "failureReason": { + "type": [ + "string", + "null" + ] + }, + "paymentStatus": { + "description": "Status of the latest payment event. Usually the payment gateway's RAW status in its own vocabulary. Values prefixed with `FT_` come from FreeTicket, not the gateway: currently `FT_SALE_APPROVED_POST_CONFIRM`, which marks that the gateway re-notified an already-confirmed charge — this is how Bold reports its refunds. A CONFIRMED sale with this status may have money refunded that is not yet recorded.", + "type": [ + "string", + "null" + ] + }, + "declineCode": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "reference", + "status", + "channel", + "subtotal", + "discountAmount", + "serviceFee", + "iva", + "total", + "currency", + "buyerName", + "buyerEmail", + "buyerPhone", + "buyerDocumentType", + "buyerDocumentNumber", + "organizationId", + "paymentProvider", + "paymentRef", + "confirmedAt", + "createdAt", + "failureReason", + "paymentStatus", + "declineCode" + ], + "additionalProperties": false + }, + "SaleDetail": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "reference": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + }, + "channel": { + "type": "string" + }, + "subtotal": { + "type": "number" + }, + "discountAmount": { + "type": "number" + }, + "serviceFee": { + "type": "number" + }, + "iva": { + "type": "number" + }, + "total": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "buyerName": { + "type": "string" + }, + "buyerEmail": { + "type": "string" + }, + "buyerPhone": { + "type": [ + "string", + "null" + ] + }, + "buyerDocumentType": { + "type": [ + "string", + "null" + ] + }, + "buyerDocumentNumber": { + "type": [ + "string", + "null" + ] + }, + "organizationId": { + "type": [ + "string", + "null" + ] + }, + "paymentProvider": { + "type": [ + "string", + "null" + ] + }, + "paymentRef": { + "type": [ + "string", + "null" + ] + }, + "confirmedAt": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" + }, + "failureReason": { + "type": [ + "string", + "null" + ] + }, + "paymentStatus": { + "description": "Status of the latest payment event. Usually the payment gateway's RAW status in its own vocabulary. Values prefixed with `FT_` come from FreeTicket, not the gateway: currently `FT_SALE_APPROVED_POST_CONFIRM`, which marks that the gateway re-notified an already-confirmed charge — this is how Bold reports its refunds. A CONFIRMED sale with this status may have money refunded that is not yet recorded.", + "type": [ + "string", + "null" + ] + }, + "declineCode": { + "type": [ + "string", + "null" + ] + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SaleItem" + } + } + }, + "required": [ + "id", + "reference", + "status", + "channel", + "subtotal", + "discountAmount", + "serviceFee", + "iva", + "total", + "currency", + "buyerName", + "buyerEmail", + "buyerPhone", + "buyerDocumentType", + "buyerDocumentNumber", + "organizationId", + "paymentProvider", + "paymentRef", + "confirmedAt", + "createdAt", + "failureReason", + "paymentStatus", + "declineCode", + "items" + ], + "additionalProperties": false + }, + "MembershipPlan": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "organizationId": { + "type": [ + "string", + "null" + ] + }, + "name": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "price": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "billingCycle": { + "type": "string", + "enum": [ + "MONTHLY", + "QUARTERLY", + "SEMIANNUAL", + "ANNUAL", + "LIFETIME" + ] + }, + "benefits": { + "type": "object", + "properties": { + "presale": { + "type": "boolean" + }, + "freeTicket": { + "type": "boolean" + }, + "discount": { + "type": "boolean" + }, + "exclusiveContent": { + "type": "boolean" + }, + "merch": { + "type": "boolean" + } + }, + "required": [ + "presale", + "freeTicket", + "discount", + "exclusiveContent", + "merch" + ], + "additionalProperties": false + }, + "isActive": { + "type": "boolean" + }, + "sortOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "organizationId", + "name", + "description", + "price", + "currency", + "billingCycle", + "benefits", + "isActive", + "sortOrder", + "createdAt" + ], + "additionalProperties": false + }, + "MembershipPlanCreate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": "string" + }, + "price": { + "type": "number", + "minimum": 0 + }, + "currency": { + "default": "COP", + "type": "string" + }, + "billingCycle": { + "type": "string", + "enum": [ + "MONTHLY", + "QUARTERLY", + "SEMIANNUAL", + "ANNUAL", + "LIFETIME" + ] + }, + "benefitPresale": { + "default": false, + "type": "boolean" + }, + "benefitFreeTicket": { + "default": false, + "type": "boolean" + }, + "benefitDiscount": { + "default": false, + "type": "boolean" + }, + "benefitExclusiveContent": { + "default": false, + "type": "boolean" + }, + "benefitMerch": { + "default": false, + "type": "boolean" + }, + "isActive": { + "default": true, + "type": "boolean" + }, + "sortOrder": { + "default": 0, + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "required": [ + "name", + "price", + "currency", + "billingCycle", + "benefitPresale", + "benefitFreeTicket", + "benefitDiscount", + "benefitExclusiveContent", + "benefitMerch", + "isActive", + "sortOrder" + ], + "additionalProperties": false + }, + "MembershipPlanUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "price": { + "type": "number", + "minimum": 0 + }, + "currency": { + "type": "string" + }, + "billingCycle": { + "type": "string", + "enum": [ + "MONTHLY", + "QUARTERLY", + "SEMIANNUAL", + "ANNUAL", + "LIFETIME" + ] + }, + "benefitPresale": { + "type": "boolean" + }, + "benefitFreeTicket": { + "type": "boolean" + }, + "benefitDiscount": { + "type": "boolean" + }, + "benefitExclusiveContent": { + "type": "boolean" + }, + "benefitMerch": { + "type": "boolean" + }, + "isActive": { + "type": "boolean" + }, + "sortOrder": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + } + }, + "additionalProperties": false + }, + "VenueCreate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "address": { + "type": "string", + "minLength": 1 + }, + "city": { + "type": "string", + "minLength": 1 + }, + "country": { + "default": "CO", + "type": "string" + }, + "capacity": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "latitude": { + "type": "number", + "minimum": -90, + "maximum": 90 + }, + "longitude": { + "type": "number", + "minimum": -180, + "maximum": 180 + } + }, + "required": [ + "name", + "address", + "city", + "country" + ], + "additionalProperties": false + }, + "VenueUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "address": { + "type": "string", + "minLength": 1 + }, + "city": { + "type": "string", + "minLength": 1 + }, + "country": { + "type": "string", + "minLength": 2, + "maxLength": 2 + }, + "capacity": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "latitude": { + "anyOf": [ + { + "type": "number", + "minimum": -90, + "maximum": 90 + }, + { + "type": "null" + } + ] + }, + "longitude": { + "anyOf": [ + { + "type": "number", + "minimum": -180, + "maximum": 180 + }, + { + "type": "null" + } + ] + }, + "portalVisible": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "StaffUser": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "role": { + "type": "string", + "enum": [ + "SUPER_ADMIN", + "ADMIN", + "STAFF", + "VIEWER", + "MINCULTURA", + "MERCH_MANAGER" + ] + }, + "organizationId": { + "type": [ + "string", + "null" + ] + }, + "workspaceId": { + "type": "string" + }, + "workspaceName": { + "type": "string" + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "name", + "email", + "role", + "organizationId", + "createdAt" + ], + "additionalProperties": false + }, + "StaffCreate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "email": { + "type": "string", + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + }, + "required": [ + "name", + "email" + ], + "additionalProperties": false + }, + "RoleUpdate": { + "type": "object", + "properties": { + "role": { + "type": "string", + "enum": [ + "SUPER_ADMIN", + "ADMIN", + "STAFF", + "VIEWER", + "MINCULTURA", + "MERCH_MANAGER" + ] + } + }, + "required": [ + "role" + ], + "additionalProperties": false + }, + "ReportSummary": { + "type": "object", + "properties": { + "period": { + "type": "string" + }, + "currency": { + "type": "string" + }, + "revenue": { + "type": "number" + }, + "ticketsSold": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "salesCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "activeMemberships": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "period", + "currency", + "revenue", + "ticketsSold", + "salesCount", + "activeMemberships" + ], + "additionalProperties": false + }, + "MatchStatus": { + "type": "string", + "enum": [ + "OK", + "MISSING_INVOICE", + "MISSING_CUFE", + "AMOUNT_MISMATCH", + "MISSING_PAYMENT" + ] + }, + "InventoryRow": { + "type": "object", + "properties": { + "eventId": { + "type": "string" + }, + "eventName": { + "type": "string" + }, + "eventStatus": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "SOLD_OUT", + "CANCELLED", + "COMPLETED" + ] + }, + "eventDateId": { + "type": [ + "string", + "null" + ] + }, + "startsAt": { + "type": [ + "string", + "null" + ] + }, + "ticketTypeId": { + "type": [ + "string", + "null" + ] + }, + "ticketTypeName": { + "type": [ + "string", + "null" + ] + }, + "capacity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "sold": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "reserved": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "available": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "eventId", + "eventName", + "eventStatus", + "eventDateId", + "startsAt", + "ticketTypeId", + "ticketTypeName", + "capacity", + "sold", + "reserved", + "available" + ], + "additionalProperties": false + }, + "ReconciliationRow": { + "type": "object", + "properties": { + "sale_reference": { + "type": "string" + }, + "sale_status": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + }, + "sale_amount": { + "type": "number" + }, + "mp_payment_ref": { + "type": [ + "string", + "null" + ] + }, + "mp_provider": { + "type": [ + "string", + "null" + ] + }, + "mp_amount": { + "type": [ + "number", + "null" + ] + }, + "siigo_invoice_name": { + "type": [ + "string", + "null" + ] + }, + "siigo_invoice_status": { + "type": [ + "string", + "null" + ] + }, + "siigo_cufe": { + "type": [ + "string", + "null" + ] + }, + "match_status": { + "$ref": "#/components/schemas/MatchStatus" + }, + "event_id": { + "type": [ + "string", + "null" + ] + }, + "event_name": { + "type": [ + "string", + "null" + ] + }, + "event_date_id": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "sale_reference", + "sale_status", + "sale_amount", + "mp_payment_ref", + "mp_provider", + "mp_amount", + "siigo_invoice_name", + "siigo_invoice_status", + "siigo_cufe", + "match_status", + "event_id", + "event_name", + "event_date_id" + ], + "additionalProperties": false + }, + "ExportSaleItem": { + "type": "object", + "properties": { + "eventId": { + "type": "string" + }, + "eventName": { + "type": "string" + }, + "eventDateId": { + "type": "string" + }, + "eventDateStartsAt": { + "type": "string" + }, + "ticketTypeId": { + "type": "string" + }, + "ticketTypeName": { + "type": "string" + }, + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "eventId", + "eventName", + "eventDateId", + "eventDateStartsAt", + "ticketTypeId", + "ticketTypeName", + "quantity" + ], + "additionalProperties": false + }, + "ExportBuyer": { + "type": "object", + "properties": { + "reference": { + "type": "string" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "phone": { + "type": [ + "string", + "null" + ] + }, + "documentType": { + "type": [ + "string", + "null" + ] + }, + "documentNumber": { + "type": [ + "string", + "null" + ] + }, + "total": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "saleStatus": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + }, + "createdAt": { + "type": "string" + }, + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ExportSaleItem" + } + } + }, + "required": [ + "reference", + "name", + "email", + "phone", + "documentType", + "documentNumber", + "total", + "currency", + "saleStatus", + "createdAt", + "items" + ], + "additionalProperties": false + }, + "ExportAttendee": { + "type": "object", + "properties": { + "reference": { + "type": "string" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "phone": { + "type": [ + "string", + "null" + ] + }, + "documentType": { + "type": [ + "string", + "null" + ] + }, + "documentNumber": { + "type": [ + "string", + "null" + ] + }, + "ticketCode": { + "type": "string" + }, + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "checkedInAt": { + "type": [ + "string", + "null" + ] + }, + "checkedInSource": { + "type": [ + "string", + "null" + ] + }, + "eventId": { + "type": "string" + }, + "eventName": { + "type": "string" + }, + "eventDateId": { + "type": "string" + }, + "eventDateStartsAt": { + "type": "string" + }, + "ticketTypeId": { + "type": "string" + }, + "ticketTypeName": { + "type": "string" + }, + "saleStatus": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "reference", + "name", + "email", + "phone", + "documentType", + "documentNumber", + "ticketCode", + "quantity", + "checkedInAt", + "checkedInSource", + "eventId", + "eventName", + "eventDateId", + "eventDateStartsAt", + "ticketTypeId", + "ticketTypeName", + "saleStatus", + "createdAt" + ], + "additionalProperties": false + }, + "ExportSubscriber": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "plan": { + "type": "string" + }, + "status": { + "type": "string" + }, + "since": { + "type": "string" + }, + "expiresAt": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "name", + "email", + "plan", + "status", + "since", + "expiresAt" + ], + "additionalProperties": false + }, + "EventArtistsReplace": { + "type": "object", + "properties": { + "artistIds": { + "maxItems": 50, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "inviteEmails": { + "maxItems": 20, + "type": "array", + "items": { + "type": "string", + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + } + }, + "required": [ + "artistIds" + ], + "additionalProperties": false + }, + "ArtistSummary": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slug": { + "type": [ + "string", + "null" + ] + }, + "logoUrl": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "name", + "slug", + "logoUrl" + ], + "additionalProperties": false + }, + "ArtistInvitation": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "email": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "EXPIRED" + ] + }, + "expiresAt": { + "type": "string" + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "email", + "status", + "expiresAt", + "createdAt" + ], + "additionalProperties": false + }, + "EventArtistUnlink": { + "type": "object", + "properties": { + "eventId": { + "type": "string" + }, + "organizationId": { + "type": "string" + }, + "unlinked": { + "type": "boolean" + } + }, + "required": [ + "eventId", + "organizationId", + "unlinked" + ], + "additionalProperties": false + }, + "ArtistInvitationDeleted": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "deleted": { + "type": "boolean", + "const": true + } + }, + "required": [ + "id", + "deleted" + ], + "additionalProperties": false + }, + "EventViewer": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "email": { + "type": "string" + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "email", + "createdAt" + ], + "additionalProperties": false + }, + "EventViewerInvite": { + "type": "object", + "properties": { + "email": { + "type": "string", + "maxLength": 255, + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + }, + "required": [ + "email" + ], + "additionalProperties": false + }, + "EventViewerInviteResult": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "email": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "newAccount": { + "deprecated": true, + "description": "Deprecated, never sent: it revealed whether the email already had a FreeTicket account.", + "type": "boolean" + } + }, + "required": [ + "id", + "email", + "createdAt" + ], + "additionalProperties": false + }, + "EventViewerRevoke": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "eventId": { + "type": "string" + }, + "revoked": { + "type": "boolean" + } + }, + "required": [ + "id", + "eventId", + "revoked" + ], + "additionalProperties": false + }, + "EventValidator": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "userId": { + "description": "Only present when the person is a member of the active workspace.", + "type": "string" + }, + "name": { + "description": "Only present when the person is a member of the active workspace.", + "type": "string" + }, + "email": { + "type": "string" + }, + "isActive": { + "type": "boolean" + }, + "allEvents": { + "type": "boolean" + } + }, + "required": [ + "id", + "email", + "isActive", + "allEvents" + ], + "additionalProperties": false + }, + "EventValidatorCreate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 100 + }, + "email": { + "type": "string", + "maxLength": 255, + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + }, + "required": [ + "name", + "email" + ], + "additionalProperties": false + }, + "EventValidatorCreateResult": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "userId": { + "description": "Only present when the person is a member of the active workspace.", + "type": "string" + }, + "name": { + "description": "Only present when the person is a member of the active workspace.", + "type": "string" + }, + "email": { + "type": "string" + }, + "isActive": { + "type": "boolean" + }, + "allEvents": { + "type": "boolean" + }, + "invited": { + "type": "boolean" + } + }, + "required": [ + "id", + "email", + "isActive", + "allEvents", + "invited" + ], + "additionalProperties": false + }, + "StaffInviteResend": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "email": { + "type": "string" + }, + "sent": { + "type": "boolean" + } + }, + "required": [ + "id", + "email", + "sent" + ], + "additionalProperties": false + }, + "StaffAccessUpdate": { + "type": "object", + "properties": { + "accessType": { + "type": "string", + "enum": [ + "admin", + "validador", + "personalizado", + "lectura" + ] + }, + "sections": { + "maxItems": 50, + "type": "array", + "items": { + "type": "string", + "enum": [ + "inicio", + "eventos", + "validar", + "membresias", + "contenido", + "productos", + "pagina_web", + "comunicacion", + "informes", + "liquidaciones", + "tienda", + "perfil" + ] + } + }, + "validatorEventIds": { + "maxItems": 200, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "viewerEventIds": { + "maxItems": 200, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "expiresAt": { + "anyOf": [ + { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "accessType" + ], + "additionalProperties": false + }, + "StaffAccess": { + "type": "object", + "properties": { + "userId": { + "type": "string" + }, + "accessType": { + "type": "string", + "enum": [ + "admin", + "validador", + "personalizado", + "lectura" + ] + }, + "role": { + "type": "string", + "enum": [ + "ADMIN", + "STAFF", + "VIEWER" + ] + }, + "sections": { + "type": "array", + "items": { + "type": "string" + } + }, + "validatorEventIds": { + "type": "array", + "items": { + "type": "string" + } + }, + "viewerEventIds": { + "type": "array", + "items": { + "type": "string" + } + }, + "expiresAt": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "userId", + "accessType", + "role", + "sections", + "validatorEventIds", + "viewerEventIds", + "expiresAt" + ], + "additionalProperties": false + }, + "SaleCreate": { + "type": "object", + "properties": { + "buyer": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "email": { + "type": "string", + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + }, + "phone": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "name", + "email" + ], + "additionalProperties": false + }, + "items": { + "minItems": 1, + "type": "array", + "items": { + "type": "object", + "properties": { + "ticketTypeId": { + "type": "string", + "minLength": 1 + }, + "quantity": { + "type": "integer", + "minimum": 1, + "maximum": 9007199254740991 + }, + "seats": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } + } + }, + "required": [ + "ticketTypeId", + "quantity" + ], + "additionalProperties": false + } + }, + "channel": { + "default": "ADMIN", + "type": "string", + "enum": [ + "WEB", + "MOBILE", + "POS", + "ADMIN" + ] + }, + "comp": { + "default": false, + "type": "boolean" + }, + "notes": { + "type": "string" + } + }, + "required": [ + "buyer", + "items", + "channel", + "comp" + ], + "additionalProperties": false + }, + "SaleCancelRequest": { + "type": "object", + "properties": { + "acknowledge_open_payment": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "SaleRefundRequest": { + "type": "object", + "properties": { + "acknowledge_manual": { + "type": "boolean" + }, + "items": { + "minItems": 1, + "maxItems": 200, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "block_seats": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "SaleRefundResult": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "reference": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + }, + "channel": { + "type": "string" + }, + "subtotal": { + "type": "number" + }, + "discountAmount": { + "type": "number" + }, + "serviceFee": { + "type": "number" + }, + "iva": { + "type": "number" + }, + "total": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "buyerName": { + "type": "string" + }, + "buyerEmail": { + "type": "string" + }, + "buyerPhone": { + "type": [ + "string", + "null" + ] + }, + "buyerDocumentType": { + "type": [ + "string", + "null" + ] + }, + "buyerDocumentNumber": { + "type": [ + "string", + "null" + ] + }, + "organizationId": { + "type": [ + "string", + "null" + ] + }, + "paymentProvider": { + "type": [ + "string", + "null" + ] + }, + "paymentRef": { + "type": [ + "string", + "null" + ] + }, + "confirmedAt": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" + }, + "failureReason": { + "type": [ + "string", + "null" + ] + }, + "paymentStatus": { + "description": "Status of the latest payment event. Usually the payment gateway's RAW status in its own vocabulary. Values prefixed with `FT_` come from FreeTicket, not the gateway: currently `FT_SALE_APPROVED_POST_CONFIRM`, which marks that the gateway re-notified an already-confirmed charge — this is how Bold reports its refunds. A CONFIRMED sale with this status may have money refunded that is not yet recorded.", + "type": [ + "string", + "null" + ] + }, + "declineCode": { + "type": [ + "string", + "null" + ] + }, + "refund": { "type": "object", "properties": { - "code": { - "type": "string" + "amount": { + "type": [ + "number", + "null" + ] + }, + "refundedItemIds": { + "type": "array", + "items": { + "type": "string" + } + }, + "saleRefunded": { + "type": "boolean" + }, + "gatewayRefunded": { + "type": "boolean" + }, + "seats": { + "type": "string", + "enum": [ + "blocked", + "block_failed", + "released", + "release_failed", + "none" + ] + } + }, + "required": [ + "amount", + "refundedItemIds", + "saleRefunded", + "gatewayRefunded", + "seats" + ], + "additionalProperties": false + } + }, + "required": [ + "id", + "reference", + "status", + "channel", + "subtotal", + "discountAmount", + "serviceFee", + "iva", + "total", + "currency", + "buyerName", + "buyerEmail", + "buyerPhone", + "buyerDocumentType", + "buyerDocumentNumber", + "organizationId", + "paymentProvider", + "paymentRef", + "confirmedAt", + "createdAt", + "failureReason", + "paymentStatus", + "declineCode" + ], + "additionalProperties": false + }, + "SaleItemTransferRequest": { + "type": "object", + "properties": { + "email": { + "type": "string", + "maxLength": 254, + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + }, + "required": [ + "email" + ], + "additionalProperties": false + }, + "SaleItemTransfer": { + "type": "object", + "properties": { + "saleId": { + "type": "string" + }, + "itemId": { + "type": "string" + }, + "ticketCode": { + "type": "string", + "description": "New ticket code (the previous QR is void)." + }, + "holderName": { + "type": "string" + }, + "holderEmail": { + "type": "string" + }, + "transferredAt": { + "type": "string" + } + }, + "required": [ + "saleId", + "itemId", + "ticketCode", + "holderName", + "holderEmail", + "transferredAt" + ], + "additionalProperties": false + }, + "CourtesyRecipientUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 120 + }, + "email": { + "type": "string", + "maxLength": 254, + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + }, + "required": [ + "name", + "email" + ], + "additionalProperties": false + }, + "CourtesyRecipient": { + "type": "object", + "properties": { + "saleId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "resent": { + "type": "boolean" + }, + "ticketCodesRotated": { + "type": "boolean", + "description": "true when the email changed: the previous QR codes are void (transferred tickets keep theirs)." + } + }, + "required": [ + "saleId", + "name", + "email", + "resent", + "ticketCodesRotated" + ], + "additionalProperties": false + }, + "CourtesySeats": { + "type": "object", + "properties": { + "eventDateId": { + "type": "string" + }, + "eventId": { + "type": "string" + }, + "ticketTypes": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ticketTypeId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "labels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Blocked seat labels of this ticket type's category that no live sale claims, in natural order." + } + }, + "required": [ + "ticketTypeId", + "name", + "labels" + ], + "additionalProperties": false + } + } + }, + "required": [ + "eventDateId", + "eventId", + "ticketTypes" + ], + "additionalProperties": false + }, + "ReportByEventRow": { + "type": "object", + "properties": { + "eventId": { + "type": "string" + }, + "eventName": { + "type": "string" + }, + "revenue": { + "type": "number" + }, + "ticketsSold": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "salesCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "available": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "eventId", + "eventName", + "revenue", + "ticketsSold", + "salesCount", + "available" + ], + "additionalProperties": false + }, + "ReportTimeseriesRow": { + "type": "object", + "properties": { + "bucket": { + "type": "string" + }, + "revenue": { + "type": "number" + }, + "ticketsSold": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "salesCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "bucket", + "revenue", + "ticketsSold", + "salesCount" + ], + "additionalProperties": false + }, + "ReportFinancialsRow": { + "type": "object", + "properties": { + "eventId": { + "type": "string" + }, + "eventName": { + "type": "string" + }, + "eventDateId": { + "type": "string" + }, + "startsAt": { + "type": "string" + }, + "past": { + "type": "boolean" + }, + "unitsSold": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "gross": { + "type": "number" + }, + "platformFee": { + "type": "number" + }, + "facial": { + "type": "number" + }, + "paymentFee": { + "type": "number" + }, + "wompiSalesWithoutRate": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "gmf": { + "type": "number" + }, + "net": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "settlementStatus": { + "anyOf": [ + { + "type": "string", + "enum": [ + "SENT", + "AWAITING_PAYMENT", + "PAID" + ] + }, + { + "type": "null" + } + ] + }, + "settlementId": { + "type": [ + "string", + "null" + ] + }, + "settlementAmount": { + "type": [ + "number", + "null" + ] + } + }, + "required": [ + "eventId", + "eventName", + "eventDateId", + "startsAt", + "past", + "unitsSold", + "gross", + "platformFee", + "facial", + "paymentFee", + "wompiSalesWithoutRate", + "gmf", + "net", + "currency", + "settlementStatus", + "settlementId", + "settlementAmount" + ], + "additionalProperties": false + }, + "Settlement": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "reference": { + "type": "string" + }, + "label": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "SENT", + "AWAITING_PAYMENT", + "PAID" + ] + }, + "amount": { + "type": "number" + }, + "grossAmount": { + "type": [ + "number", + "null" + ] + }, + "unitsSold": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "currency": { + "type": "string" + }, + "notes": { + "type": [ + "string", + "null" + ] + }, + "rejectionReason": { + "type": [ + "string", + "null" + ] + }, + "event": { + "anyOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "id", + "name" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ] + }, + "eventDate": { + "anyOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "startsAt": { + "type": "string" + } + }, + "required": [ + "id", + "startsAt" + ], + "additionalProperties": false }, - "message": { - "type": "string" + { + "type": "null" + } + ] + }, + "hasDocument": { + "type": "boolean" + }, + "paymentProofs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "fileName": { + "type": "string" + } }, - "retryable": { - "type": "boolean" + "required": [ + "fileName" + ], + "additionalProperties": false + } + }, + "allocations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "bankAccountId": { + "type": "string" + }, + "percentage": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "amount": { + "type": "number" + }, + "mode": { + "type": "string", + "enum": [ + "PERCENT", + "AMOUNT" + ] + } }, - "details": {} - }, - "required": [ - "code", - "message", - "retryable" - ], - "additionalProperties": false + "required": [ + "bankAccountId", + "percentage" + ], + "additionalProperties": false + } + }, + "requestedAt": { + "type": [ + "string", + "null" + ] + }, + "paidAt": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" } }, "required": [ - "error" + "id", + "reference", + "label", + "status", + "amount", + "grossAmount", + "unitsSold", + "currency", + "notes", + "rejectionReason", + "event", + "eventDate", + "hasDocument", + "paymentProofs", + "allocations", + "requestedAt", + "paidAt", + "createdAt" ], "additionalProperties": false }, - "Warning": { + "DiscountType": { + "type": "string", + "enum": [ + "PERCENT", + "FIXED" + ] + }, + "Discount": { "type": "object", "properties": { - "code": { + "id": { "type": "string" }, - "message": { + "code": { "type": "string" }, - "field": { - "type": "string" + "type": { + "$ref": "#/components/schemas/DiscountType" }, - "activeWorkspaceId": { - "type": "string" + "value": { + "type": "number" }, - "activeWorkspaceName": { - "type": "string" + "eventId": { + "type": [ + "string", + "null" + ] }, - "accessibleWorkspaces": { + "active": { + "type": "boolean" + }, + "maxUses": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "uses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, - "suggestedWorkspaceId": { - "type": "string" + "startsAt": { + "type": [ + "string", + "null" + ] }, - "suggestedWorkspaceName": { + "endsAt": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { "type": "string" } }, "required": [ + "id", "code", - "message" + "type", + "value", + "eventId", + "active", + "maxUses", + "uses", + "startsAt", + "endsAt", + "createdAt" ], "additionalProperties": false }, - "Page": { + "DiscountCreate": { "type": "object", "properties": { - "nextCursor": { + "code": { + "type": "string", + "minLength": 1 + }, + "type": { + "$ref": "#/components/schemas/DiscountType" + }, + "value": { + "type": "number", + "exclusiveMinimum": 0 + }, + "eventId": { "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1 }, { "type": "null" } ] }, - "hasMore": { - "type": "boolean" - }, - "total": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - } - }, - "required": [ - "nextCursor", - "hasMore" - ], - "additionalProperties": false - }, - "Workspace": { - "type": "object", - "properties": { - "id": { - "type": "string" + "maxUses": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] }, - "name": { - "type": "string" + "startsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] }, - "slug": { - "type": "string" + "endsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] } }, "required": [ - "id", - "name", - "slug" + "code", + "type", + "value" ], "additionalProperties": false }, - "WorkspaceAccess": { + "DiscountUpdate": { "type": "object", "properties": { - "id": { - "type": "string" + "active": { + "type": "boolean" }, - "name": { - "type": "string" + "value": { + "type": "number", + "exclusiveMinimum": 0 }, - "slug": { - "type": "string" + "maxUses": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] }, - "role": { - "type": "string", - "enum": [ - "SUPER_ADMIN", - "ADMIN", - "STAFF", - "VIEWER", - "MINCULTURA" - ], - "description": "The user's effective role IN THIS workspace." + "startsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] }, - "sections": { + "endsAt": { "anyOf": [ { - "type": "array", - "items": { - "type": "string" - } + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } - ], - "description": "Enabled sections (slugs). null = unrestricted; [] = access expired or revoked." + ] } }, - "required": [ - "id", - "name", - "slug", - "role", - "sections" - ], "additionalProperties": false }, - "Me": { + "Webhook": { "type": "object", "properties": { - "userId": { + "id": { "type": "string" }, - "name": { + "url": { "type": "string" }, - "email": { - "type": "string" + "events": { + "type": "array", + "items": { + "type": "string" + } }, - "role": { - "type": "string", - "enum": [ - "SUPER_ADMIN", - "ADMIN", - "STAFF", - "VIEWER", - "MINCULTURA" - ], - "description": "DEPRECATED: effective role in the ACTIVE workspace. Use the `role` of each `workspaces` row instead. Kept for compatibility with already-published clients." + "active": { + "type": "boolean" }, - "activeWorkspaceId": { + "lastDeliveryAt": { + "type": [ + "string", + "null" + ] + }, + "lastDeliveryStatus": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "workspaces": { - "type": "array", - "items": { - "$ref": "#/components/schemas/WorkspaceAccess" - } - } - }, - "required": [ - "userId", - "name", - "email", - "role", - "activeWorkspaceId", - "workspaces" - ], - "additionalProperties": false - }, - "SignupRequest": { - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" - }, - "name": { - "type": "string", - "minLength": 2, - "maxLength": 120 + "failureCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "workspaceName": { - "type": "string", - "minLength": 2, - "maxLength": 80 - } - }, - "required": [ - "email", - "name" - ], - "additionalProperties": false - }, - "SignupResponse": { - "type": "object", - "properties": { - "user_id": { + "createdAt": { "type": "string" }, - "status": { - "type": "string", - "const": "pending_verification" - }, - "verification_sent_to": { + "updatedAt": { "type": "string" } }, "required": [ - "user_id", - "status", - "verification_sent_to" + "id", + "url", + "events", + "active", + "lastDeliveryAt", + "lastDeliveryStatus", + "failureCount", + "createdAt", + "updatedAt" ], "additionalProperties": false }, - "WorkspaceCreate": { + "WebhookUpdate": { "type": "object", "properties": { - "name": { + "url": { "type": "string", - "minLength": 2, - "maxLength": 80 + "format": "uri" }, - "slug": { - "type": "string", - "minLength": 2, - "maxLength": 50, - "pattern": "^[a-z0-9-]+$" + "events": { + "minItems": 1, + "type": "array", + "items": { + "type": "string", + "enum": [ + "sale.confirmed", + "sale.refunded" + ] + } + }, + "active": { + "type": "boolean" } }, - "required": [ - "name", - "slug" - ], "additionalProperties": false }, - "DeviceCodeResponse": { + "WebhookCreated": { "type": "object", "properties": { - "device_code": { + "id": { "type": "string" }, - "user_code": { + "url": { "type": "string" }, - "verification_uri": { - "type": "string" + "events": { + "type": "array", + "items": { + "type": "string" + } }, - "verification_uri_complete": { - "type": "string" + "active": { + "type": "boolean" }, - "expires_in": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "lastDeliveryAt": { + "type": [ + "string", + "null" + ] }, - "interval": { + "lastDeliveryStatus": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 + }, + "createdAt": { + "type": "string" + }, + "updatedAt": { + "type": "string" + }, + "signingSecret": { + "type": "string" } }, "required": [ - "device_code", - "user_code", - "verification_uri", - "verification_uri_complete", - "expires_in", - "interval" + "id", + "url", + "events", + "active", + "lastDeliveryAt", + "lastDeliveryStatus", + "failureCount", + "createdAt", + "updatedAt", + "signingSecret" ], "additionalProperties": false }, - "DeviceTokenRequest": { + "WebhookCreate": { "type": "object", "properties": { - "device_code": { + "url": { "type": "string", - "minLength": 1 + "format": "uri" }, - "grant_type": { + "events": { + "minItems": 1, + "type": "array", + "items": { + "type": "string", + "enum": [ + "sale.confirmed", + "sale.refunded" + ] + }, + "description": "Subset of: sale.confirmed, sale.refunded" + }, + "secret": { "type": "string", - "const": "urn:ietf:params:oauth:grant-type:device_code" + "minLength": 1 } }, "required": [ - "device_code" + "url", + "events" ], "additionalProperties": false }, - "DeviceTokenResponse": { + "Subscriber": { "type": "object", "properties": { - "access_token": { + "id": { "type": "string" }, - "token_type": { + "customerName": { + "type": [ + "string", + "null" + ] + }, + "customerEmail": { + "type": "string" + }, + "status": { "type": "string", - "const": "Bearer" + "enum": [ + "PENDING", + "ACTIVE", + "EXPIRED", + "CANCELLED", + "PAUSED" + ] }, - "user": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "email": { - "type": "string" - }, - "role": { - "type": "string", - "enum": [ - "SUPER_ADMIN", - "ADMIN", - "STAFF", - "VIEWER", - "MINCULTURA" - ] - } - }, - "required": [ - "id", - "email", - "role" - ], - "additionalProperties": false + "startedAt": { + "type": [ + "string", + "null" + ] }, - "workspaces": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Workspace" - } + "currentPeriodEnd": { + "type": [ + "string", + "null" + ] } }, "required": [ - "access_token", - "token_type", - "user", - "workspaces" + "id", + "customerName", + "customerEmail", + "status", + "startedAt", + "currentPeriodEnd" ], "additionalProperties": false }, - "DeviceTokenError": { + "SubscriptionCancelResult": { "type": "object", "properties": { - "error": { + "id": { + "type": "string" + }, + "status": { "type": "string", "enum": [ - "authorization_pending", - "slow_down", - "expired_token", - "access_denied", - "invalid_request" + "PENDING", + "ACTIVE", + "EXPIRED", + "CANCELLED", + "PAUSED" + ] + }, + "cancelledAt": { + "type": [ + "string", + "null" ] } }, "required": [ - "error" + "id", + "status", + "cancelledAt" ], "additionalProperties": false }, - "Venue": { + "SaleTicket": { "type": "object", "properties": { "id": { "type": "string" }, - "name": { - "type": "string" - }, - "slug": { + "ticketCode": { "type": "string" }, - "address": { + "ticketTypeId": { "type": "string" }, - "city": { + "ticketTypeName": { "type": "string" }, - "country": { - "type": "string" + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "latitude": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } + "seatLabel": { + "type": [ + "string", + "null" ] }, - "longitude": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } + "checkedInAt": { + "type": [ + "string", + "null" ] }, - "capacity": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - { - "type": "null" - } + "refundedAt": { + "type": [ + "string", + "null" ] }, - "googlePlaceId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "refundAmount": { + "type": [ + "number", + "null" ] }, - "portalVisible": { + "seatBlocked": { "type": "boolean" - }, - "organizationId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "seatsioChartKey": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "createdAt": { - "type": "string" } }, "required": [ "id", - "name", - "slug", - "address", - "city", - "country", - "latitude", - "longitude", - "capacity", - "googlePlaceId", - "portalVisible", - "organizationId", - "seatsioChartKey", - "createdAt" + "ticketCode", + "ticketTypeId", + "ticketTypeName", + "quantity", + "seatLabel", + "checkedInAt", + "refundedAt", + "refundAmount", + "seatBlocked" ], "additionalProperties": false }, - "EventNextDate": { + "PaymentAttempt": { "type": "object", "properties": { "id": { "type": "string" }, - "label": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "provider": { + "type": "string" + }, + "status": { + "type": "string", + "description": "Status of the payment event. Usually this is the gateway's RAW status in its own vocabulary (PAID, APPROVED, REJECTED, VOID_APPROVED…). Values prefixed with `FT_` come from FreeTicket, not the gateway: currently `FT_SALE_APPROVED_POST_CONFIRM`, which flags that the gateway re-notified a payment that was already confirmed — this is how Bold reports its refunds, and the sale may remain CONFIRMED while someone verifies the refunded amount." + }, + "declineCode": { + "type": [ + "string", + "null" ] }, - "startsAt": { - "type": "string" + "declineReason": { + "type": [ + "string", + "null" + ] }, - "endsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "amount": { + "type": [ + "number", + "null" ] }, - "timezone": { + "externalRef": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { "type": "string" + } + }, + "required": [ + "id", + "provider", + "status", + "declineCode", + "declineReason", + "amount", + "externalRef", + "createdAt" + ], + "additionalProperties": false + }, + "TicketReassign": { + "type": "object", + "properties": { + "eventDateId": { + "type": "string", + "minLength": 1 }, - "status": { + "ticketTypeId": { "type": "string", - "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" - ] + "minLength": 1 + }, + "seatLabel": { + "type": "string", + "minLength": 1 } }, - "required": [ - "id", - "label", - "startsAt", - "endsAt", - "timezone", - "status" - ], "additionalProperties": false }, - "EventArtist": { + "ResendTicket": { "type": "object", "properties": { - "id": { + "ticketCode": { "type": "string" }, - "name": { + "sentTo": { "type": "string" }, - "slug": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "type": { - "type": "string", - "enum": [ - "ARTIST", - "VENUE", - "ORGANIZER" - ] + "sentAt": { + "type": "string" } }, "required": [ - "id", - "name", - "slug", - "type" + "ticketCode", + "sentTo", + "sentAt" ], "additionalProperties": false }, - "Event": { + "CheckinResult": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "slug": { + "ticketCode": { "type": "string" }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "checkedInAt": { + "type": [ + "string", + "null" ] }, - "status": { - "type": "string", - "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" + "checkedInBy": { + "type": [ + "string", + "null" ] }, - "coverImageUrl": { + "alreadyCheckedIn": { + "type": "boolean" + } + }, + "required": [ + "ticketCode", + "checkedInAt", + "checkedInBy", + "alreadyCheckedIn" + ], + "additionalProperties": false + }, + "CheckinRequest": { + "type": "object", + "properties": { + "source": { "anyOf": [ { - "type": "string" + "type": "string", + "enum": [ + "pdf", + "web", + "apple", + "google" + ] }, { "type": "null" } ] + } + }, + "additionalProperties": false + }, + "CheckinUndoResult": { + "type": "object", + "properties": { + "ticketCode": { + "type": "string" }, - "bannerImageUrl": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "undone": { + "type": "boolean", + "description": "true when this call reverted the check-in; false when the ticket was not checked in (idempotent no-op)." }, - "squareImageUrl": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "previousCheckedInAt": { + "type": [ + "string", + "null" ] }, - "storyImageUrl": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "previousCheckedInBy": { + "type": [ + "string", + "null" ] - }, - "organizationId": { + } + }, + "required": [ + "ticketCode", + "undone", + "previousCheckedInAt", + "previousCheckedInBy" + ], + "additionalProperties": false + }, + "TicketAccess": { + "type": "object", + "properties": { + "ticketCode": { "type": "string" }, - "venueId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "venue": { - "anyOf": [ - { - "$ref": "#/components/schemas/Venue" - }, - { - "type": "null" - } - ] + "valid": { + "type": "boolean" }, - "externalTicketUrl": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "status": { + "type": "string", + "enum": [ + "VALID", + "USED", + "INVALID" ] }, - "access": { + "saleStatus": { "type": "string", "enum": [ - "owner", - "artist" - ], - "description": "owner = the key's workspace owns the event (editable). artist = read-only: linked artist or catalog access." - }, - "nextDate": { - "anyOf": [ - { - "$ref": "#/components/schemas/EventNextDate" - }, - { - "type": "null" - } + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" ] }, - "artists": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EventArtist" - } + "eventId": { + "type": "string" }, - "createdAt": { + "eventName": { "type": "string" }, - "updatedAt": { + "eventDateId": { + "type": "string" + }, + "startsAt": { + "type": "string" + }, + "ticketTypeName": { "type": "string" + }, + "checkedInAt": { + "type": [ + "string", + "null" + ] } }, "required": [ - "id", - "name", - "slug", - "description", + "ticketCode", + "valid", "status", - "coverImageUrl", - "bannerImageUrl", - "squareImageUrl", - "storyImageUrl", - "organizationId", - "venueId", - "venue", - "externalTicketUrl", - "access", - "createdAt", - "updatedAt" + "saleStatus", + "eventId", + "eventName", + "eventDateId", + "startsAt", + "ticketTypeName", + "checkedInAt" ], "additionalProperties": false }, - "TicketPriceStage": { + "ApiKeyScope": { + "type": "string", + "enum": [ + "read", + "write" + ] + }, + "ApiKey": { "type": "object", "properties": { "id": { @@ -12503,413 +27415,644 @@ "name": { "type": "string" }, - "price": { - "type": "number" + "scope": { + "$ref": "#/components/schemas/ApiKeyScope" + }, + "keyPrefix": { + "type": "string" }, - "sortOrder": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "lastUsedAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + { + "type": "null" + } + ] }, - "endsAt": { + "expiresAt": { "anyOf": [ { - "type": "string" + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } - ], - "description": "Closes once this date passes (ISO 8601). null = no date cutoff." + ] }, - "quantity": { + "revokedAt": { "anyOf": [ { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } - ], - "description": "Tickets at this price. The cutoff is CUMULATIVE across the ticket type: the stage closes when sold + reserved reaches the sum of `quantity` for this stage and all previous ones. null = no quantity cutoff." + ] }, - "isCurrent": { - "type": "boolean", - "description": "true for the stage currently in effect (the first one still open). If none is, the ticket type's `price` applies." + "createdAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ "id", "name", - "price", - "sortOrder", - "endsAt", - "quantity", - "isCurrent" + "scope", + "keyPrefix", + "lastUsedAt", + "expiresAt", + "revokedAt", + "createdAt" ], "additionalProperties": false }, - "TicketType": { + "ApiKeyCreated": { "type": "object", "properties": { "id": { "type": "string" }, - "eventDateId": { + "name": { "type": "string" }, - "name": { + "scope": { + "$ref": "#/components/schemas/ApiKeyScope" + }, + "keyPrefix": { "type": "string" }, - "description": { + "lastUsedAt": { "anyOf": [ { - "type": "string" + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, - "price": { - "type": "number" - }, - "currency": { - "type": "string" - }, - "capacity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "sold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "available": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "soldOut": { - "type": "boolean" - }, - "maxPerOrder": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "saleStartsAt": { + "expiresAt": { "anyOf": [ { - "type": "string" + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, - "saleEndsAt": { + "revokedAt": { "anyOf": [ { - "type": "string" + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, { "type": "null" } ] }, - "isVisible": { + "createdAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + }, + "key": { + "type": "string" + } + }, + "required": [ + "id", + "name", + "scope", + "keyPrefix", + "lastUsedAt", + "expiresAt", + "revokedAt", + "createdAt", + "key" + ], + "additionalProperties": false + }, + "ApiKeyCreate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "scope": { + "default": "read", + "$ref": "#/components/schemas/ApiKeyScope" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" + } + }, + "required": [ + "name", + "scope" + ], + "additionalProperties": false + }, + "CustomerAuthRequest": { + "type": "object", + "properties": { + "email": { + "type": "string", + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + } + }, + "required": [ + "email" + ], + "additionalProperties": false + }, + "CustomerAuthRequestResult": { + "type": "object", + "properties": { + "status": { + "type": "string", + "const": "sent" + }, + "sent_to": { + "type": "string", + "description": "Masked email (`c***@mail.com`). Never the full address." + }, + "expires_in": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Code lifetime, in seconds." + } + }, + "required": [ + "status", + "sent_to", + "expires_in" + ], + "additionalProperties": false + }, + "CustomerAuthVerify": { + "type": "object", + "properties": { + "email": { + "type": "string", + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + }, + "code": { + "type": "string", + "minLength": 6, + "maxLength": 6 + } + }, + "required": [ + "email", + "code" + ], + "additionalProperties": false + }, + "CustomerAuthVerifyResult": { + "type": "object", + "properties": { + "session_token": { + "type": "string", + "description": "Usable as-is as the `X-Customer-Session` header on /api/v1/customer/*." + }, + "expires_in": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Session lifetime, in seconds." + } + }, + "required": [ + "session_token", + "expires_in" + ], + "additionalProperties": false + }, + "CustomerMe": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "email": { + "type": "string" + }, + "name": { + "type": "string" + }, + "emailVerified": { "type": "boolean" }, - "organizerAbsorbsFee": { - "type": "boolean" + "expiresAt": { + "type": "string", + "description": "Buyer session expiry (ISO 8601)." + } + }, + "required": [ + "id", + "email", + "name", + "emailVerified", + "expiresAt" + ], + "additionalProperties": false + }, + "CustomerTicketItem": { + "type": "object", + "properties": { + "ticketTypeName": { + "type": "string" + }, + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "buyerServiceFee": { - "type": "number" + "ticketCode": { + "type": "string", + "description": "Opaque ticket code. The QR code must encode the validator URL (`https://admin.appfreeticket.com/dashboard/tickets/validar?code=`)." }, - "seatingSurcharge": { - "type": "number" + "seatLabel": { + "description": "Exact seat for seated events (seats.io), or null.", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ticketTypeName", + "quantity", + "ticketCode", + "seatLabel" + ], + "additionalProperties": false + }, + "CustomerSale": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "iva": { - "type": "number" + "reference": { + "type": "string" }, - "buyerTotal": { - "type": "number" + "status": { + "type": "string" }, - "seatsioCategoryKey": { - "anyOf": [ - { + "event": { + "type": "object", + "properties": { + "name": { "type": "string" }, - { - "type": "null" + "slug": { + "type": "string" } - ] + }, + "required": [ + "name", + "slug" + ], + "additionalProperties": false }, - "priceStages": { - "description": "Price stages preceding the final price, ordered by `sortOrder`. `[]` = fixed price. Absent if the response does not include them.", + "eventDate": { + "type": "object", + "properties": { + "startsAt": { + "type": "string", + "description": "Event start instant in ISO 8601 UTC." + }, + "timezone": { + "type": "string", + "description": "IANA time zone of the event." + } + }, + "required": [ + "startsAt", + "timezone" + ], + "additionalProperties": false + }, + "items": { "type": "array", "items": { - "$ref": "#/components/schemas/TicketPriceStage" + "$ref": "#/components/schemas/CustomerTicketItem" } }, - "currentPrice": { - "description": "CURRENT base price per unit (the open stage, or `price` if none). Present alongside `priceStages`.", + "total": { "type": "number" }, - "createdAt": { + "currency": { "type": "string" } }, "required": [ "id", - "eventDateId", - "name", - "description", - "price", - "currency", - "capacity", - "sold", - "available", - "soldOut", - "maxPerOrder", - "saleStartsAt", - "saleEndsAt", - "isVisible", - "organizerAbsorbsFee", - "buyerServiceFee", - "seatingSurcharge", - "iva", - "buyerTotal", - "seatsioCategoryKey", - "createdAt" + "reference", + "status", + "event", + "eventDate", + "items", + "total", + "currency" ], "additionalProperties": false }, - "EventDate": { + "CustomerTicketCancelResult": { "type": "object", "properties": { "id": { "type": "string" }, - "eventId": { + "reference": { "type": "string" }, - "label": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "startsAt": { + "status": { "type": "string" + } + }, + "required": [ + "id", + "reference", + "status" + ], + "additionalProperties": false + }, + "CustomerLogout": { + "type": "object", + "properties": { + "revoked": { + "type": "boolean", + "description": "true if the session existed and was deleted; false if the token was no longer valid (it ends up closed either way)." + } + }, + "required": [ + "revoked" + ], + "additionalProperties": false + }, + "EnterpriseExchangeRequest": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 1, + "maxLength": 256, + "description": "One-time token received on the landing page callback (format `{slug}.{token}`, forwarded as is)." + } + }, + "required": [ + "token" + ], + "additionalProperties": false + }, + "EnterpriseExchangeResponse": { + "type": "object", + "properties": { + "session_token": { + "type": "string", + "description": "Buyer session token. Send it as the `X-Customer-Session` header on /api/v1/customer/*." }, - "endsAt": { - "anyOf": [ - { + "expires_at": { + "type": "string", + "description": "Session expiry (ISO 8601, 7-day sliding window)." + }, + "customer": { + "type": "object", + "properties": { + "id": { "type": "string" }, - { - "type": "null" - } - ] - }, - "doorsOpenAt": { - "anyOf": [ - { + "email": { "type": "string" }, - { - "type": "null" - } - ] - }, - "timezone": { - "type": "string" - }, - "venueId": { - "anyOf": [ - { + "name": { "type": "string" }, - { - "type": "null" + "email_verified": { + "type": "boolean" } - ] + }, + "required": [ + "id", + "email", + "name", + "email_verified" + ], + "additionalProperties": false + } + }, + "required": [ + "session_token", + "expires_at", + "customer" + ], + "additionalProperties": false + }, + "CustomerMembershipState": { + "type": "object", + "properties": { + "active": { + "type": "boolean", + "description": "true only with an ACTIVE, unexpired membership in this workspace." }, - "venue": { + "membership": { "anyOf": [ { - "$ref": "#/components/schemas/Venue" + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "ACTIVE", + "EXPIRED", + "CANCELLED", + "PAUSED" + ] + }, + "plan": { + "$ref": "#/components/schemas/MembershipPlan" + }, + "startedAt": { + "type": [ + "string", + "null" + ] + }, + "expiresAt": { + "description": "null = LIFETIME or a membership with no expiry.", + "type": [ + "string", + "null" + ] + }, + "autoRenew": { + "type": "boolean" + } + }, + "required": [ + "id", + "status", + "plan", + "startedAt", + "expiresAt", + "autoRenew" + ], + "additionalProperties": false }, { "type": "null" } ] + } + }, + "required": [ + "active", + "membership" + ], + "additionalProperties": false + }, + "CustomerSubscribeRequest": { + "type": "object", + "properties": { + "planId": { + "type": "string", + "minLength": 1, + "description": "Id of an active MembershipPlan in the key's workspace." + } + }, + "required": [ + "planId" + ], + "additionalProperties": false + }, + "CustomerSubscribeResult": { + "type": "object", + "properties": { + "checkoutUrl": { + "type": "string", + "description": "Membership checkout URL on the canonical host. The landing page must redirect the buyer there." }, - "ticketTypes": { - "default": [], - "type": "array", - "items": { - "$ref": "#/components/schemas/TicketType" - } - }, - "seatsioEventKey": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "readOnly": true, - "description": "seats.io event key. Read-only: issued by automatic provisioning; writing it by hand orphans seats already sold." + "planId": { + "type": "string" + } + }, + "required": [ + "checkoutUrl", + "planId" + ], + "additionalProperties": false + }, + "CustomerSubscriptionCancelResult": { + "type": "object", + "properties": { + "id": { + "type": "string" }, "status": { "type": "string", "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", + "PENDING", + "ACTIVE", + "EXPIRED", "CANCELLED", - "COMPLETED" + "PAUSED" ] }, - "streamType": { - "type": "string" - }, - "createdAt": { - "type": "string" + "cancelledAt": { + "type": [ + "string", + "null" + ] } }, "required": [ "id", - "eventId", - "label", - "startsAt", - "endsAt", - "doorsOpenAt", - "timezone", - "venueId", - "venue", - "ticketTypes", - "seatsioEventKey", "status", - "streamType", - "createdAt" + "cancelledAt" ], "additionalProperties": false }, - "EventCreate": { + "CustomerSubscriptionCancelRequest": { "type": "object", "properties": { - "name": { + "workspaceId": { + "description": "Required only without an enterprise service API key: which membership (by workspace) to cancel. Ignored with a key — the workspace is the one pinned to it.", "type": "string", "minLength": 1 + } + }, + "additionalProperties": false + }, + "CustomerProfile": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "slug": { - "type": "string", - "minLength": 1, - "pattern": "^[a-z0-9-]+$" + "email": { + "type": "string" }, - "description": { + "name": { "type": "string" }, - "venueId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "phone": { + "type": [ + "string", + "null" ] - }, - "dates": { - "minItems": 1, - "type": "array", - "items": { - "type": "object", - "properties": { - "startsAt": { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - "endsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } - ] - }, - "timezone": { - "default": "America/Bogota", - "type": "string", - "minLength": 1 - } - }, - "required": [ - "startsAt", - "timezone" - ], - "additionalProperties": false - } } }, "required": [ + "id", + "email", "name", - "slug", - "dates" + "phone" ], "additionalProperties": false }, - "EventUpdate": { + "CustomerProfileUpdate": { "type": "object", "properties": { "name": { "type": "string", - "minLength": 1 - }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "venueId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "minLength": 1, + "maxLength": 120 }, - "coverImageUrl": { + "phone": { + "description": "null or an empty string clears the phone.", "anyOf": [ { "type": "string", - "format": "uri" + "maxLength": 30 }, { "type": "null" @@ -12919,431 +28062,489 @@ }, "additionalProperties": false }, - "EventDateCreate": { + "PurchaseSessionCreateRequest": { "type": "object", - "properties": { - "label": { - "anyOf": [ - { - "type": "string", - "maxLength": 200 - }, - { - "type": "null" - } - ] - }, - "startsAt": { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - "endsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } - ] - }, - "doorsOpenAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } - ] - }, - "timezone": { - "default": "America/Bogota", - "type": "string", - "minLength": 1 - }, - "venueId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "properties": { + "eventDateId": { + "type": "string", + "minLength": 1, + "maxLength": 64 }, - "streamType": { - "default": "PRESENCIAL", + "deviceKey": { "type": "string", - "enum": [ - "PRESENCIAL", - "ONLINE", - "HIBRIDO" - ] + "minLength": 8, + "maxLength": 200, + "description": "Stable browser identifier (e.g. stored in localStorage). If the SAME browser reopens the SAME event date while its session is still alive, it gets that same session (same `holdToken`, same clock) instead of a new one." } }, "required": [ - "startsAt", - "timezone" + "eventDateId", + "deviceKey" ], "additionalProperties": false }, - "EventDateUpdate": { + "PurchaseSessionCreated": { "type": "object", "properties": { - "label": { - "anyOf": [ - { - "type": "string", - "maxLength": 200 - }, - { - "type": "null" - } - ] + "id": { + "type": "string" }, - "startsAt": { + "eventDateId": { + "type": "string" + }, + "state": { "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "const": "live" }, - "endsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } - ] + "seated": { + "type": "boolean", + "description": "true = the event date has a seats.io map." }, - "doorsOpenAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } + "holdToken": { + "description": "seats.io hold token ISSUED BY THE SERVER. Mount the chart with `session: \"manual\"` and this `holdToken` (https://docs.seats.io/docs/renderer/config-session/), never with `session: \"continue\"`. It is the ONLY token `POST /customer/orders` accepts for this session. null for event dates without a map.", + "type": [ + "string", + "null" ] }, - "timezone": { - "type": "string", - "minLength": 1 + "seatsDeadline": { + "description": "Instant (ISO 8601 UTC) until which the order with seats can be created. This is the clock to display over the map. The seats.io hold expires AFTER this instant, never before. null for event dates without a map.", + "type": [ + "string", + "null" + ] }, - "venueId": { + "budgetSeconds": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } + ], + "description": "Budget seconds granted to this session (= seatsDeadline − now). The budget is CUMULATIVE per buyer and event date: opening another tab does not reset it." + }, + "replacedSessionId": { + "description": "Live session that this one replaced (now `superseded`), or null. That tab can no longer create an order or start a new payment.", + "type": [ + "string", + "null" ] + } + }, + "required": [ + "id", + "eventDateId", + "state", + "seated", + "holdToken", + "seatsDeadline", + "budgetSeconds", + "replacedSessionId" + ], + "additionalProperties": false + }, + "PurchaseSessionStatus": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "streamType": { + "state": { "type": "string", "enum": [ - "PRESENCIAL", - "ONLINE", - "HIBRIDO" + "live", + "superseded", + "expired", + "converted" + ], + "description": "`live`: can create the order. `superseded`: another tab/device replaced it. `expired`: the map clock ran out or it was released. `converted`: it already created its order (`orderId`)." + }, + "seatsDeadline": { + "type": [ + "string", + "null" ] }, - "status": { - "type": "string", - "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" + "orderId": { + "description": "Sale created with this session, if any.", + "type": [ + "string", + "null" ] } }, + "required": [ + "id", + "state", + "seatsDeadline", + "orderId" + ], "additionalProperties": false }, - "TicketTypeCreate": { + "CustomerOrderCreateResult": { "type": "object", "properties": { - "eventDateId": { - "type": "string", - "minLength": 1 + "free": { + "type": "boolean", + "description": "true = the purchase was CONFIRMED without a payment gateway (100% discount). In that case do NOT call /payment: there is nothing to charge and the other fields are null." }, - "name": { + "reference": { "type": "string", - "minLength": 1 - }, - "description": { - "type": "string" - }, - "price": { - "type": "number", - "minimum": 0 + "description": "Sale reference (FT-…). Always identifies the purchase." }, - "currency": { - "default": "COP", - "type": "string", - "enum": [ - "COP" + "saleId": { + "description": "Sale id. null when `free` is true.", + "type": [ + "string", + "null" ] }, - "capacity": { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 - }, - "maxPerOrder": { - "default": 10, - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 - }, - "isVisible": { - "default": true, - "type": "boolean" - }, - "organizerAbsorbsFee": { - "default": false, - "type": "boolean" - }, - "saleStartsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } + "total": { + "description": "Amount to charge. null when `free` is true.", + "type": [ + "number", + "null" ] }, - "saleEndsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } + "currency": { + "type": [ + "string", + "null" ] }, - "seatsioCategoryKey": { + "expiresAt": { + "description": "Instant (ISO 8601 UTC) at which the inventory reservation expires. After that, the purchase must be started over.", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "free", + "reference", + "saleId", + "total", + "currency", + "expiresAt" + ], + "additionalProperties": false + }, + "CustomerOrderCurrent": { + "type": "object", + "properties": { + "order": { "anyOf": [ { - "type": "string", - "minLength": 1 + "type": "object", + "properties": { + "saleId": { + "type": "string" + }, + "reference": { + "type": "string" + }, + "total": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "expiresAt": { + "type": "string", + "description": "Instant (ISO 8601 UTC) at which the inventory hold expires. This is the countdown to display." + }, + "paymentOpened": { + "type": "boolean", + "description": "true = payment has already been opened for this sale. Reopening it with /payment returns the SAME signed configuration while the reservation is still alive." + }, + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "ticketTypeId": { + "type": "string" + }, + "ticketTypeName": { + "type": "string" + }, + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "seatLabel": { + "description": "seats.io numbered seat, or null if not seated.", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "ticketTypeId", + "ticketTypeName", + "quantity", + "seatLabel" + ], + "additionalProperties": false + } + } + }, + "required": [ + "saleId", + "reference", + "total", + "currency", + "expiresAt", + "paymentOpened", + "items" + ], + "additionalProperties": false }, { "type": "null" } - ] + ], + "description": "The purchase the buyer left unfinished for this event date, or null if there is none." } }, "required": [ - "eventDateId", - "name", - "price", - "currency", - "capacity", - "maxPerOrder", - "isVisible", - "organizerAbsorbsFee" + "order" ], "additionalProperties": false }, - "TicketTypeUpdate": { + "CustomerOrderRelease": { "type": "object", "properties": { - "name": { + "released": { + "type": "boolean", + "const": true, + "description": "The sale is now ABANDONED and its inventory went back to stock. A rejection never lands here: it is returned as an error with `details.reason`." + } + }, + "required": [ + "released" + ], + "additionalProperties": false + }, + "CustomerOrderPayment": { + "type": "object", + "properties": { + "orderId": { "type": "string", - "minLength": 1 - }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "description": "Merchant reference = `reference`." }, - "price": { - "type": "number", - "minimum": 0 + "amount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Whole pesos, no decimals." }, "currency": { - "description": "Solo COP; se tolera la moneda ya guardada si no cambia.", + "type": "string" + }, + "apiKey": { "type": "string", - "minLength": 3, - "maxLength": 3 + "description": "Bold IDENTITY key (public, sent to the browser)." }, - "capacity": { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "integritySignature": { + "type": "string", + "description": "SHA256 that binds the charge to the amount. Computed on the server." }, - "maxPerOrder": { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "renderMode": { + "type": "string", + "const": "embedded" }, - "isVisible": { - "type": "boolean" + "redirectionUrl": { + "type": "string" }, - "organizerAbsorbsFee": { - "type": "boolean" + "description": { + "type": "string" }, - "saleStartsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } - ] + "expirationDate": { + "type": "number", + "description": "Epoch in NANOSECONDS (what the Bold library expects)." + } + }, + "required": [ + "orderId", + "amount", + "currency", + "apiKey", + "integritySignature", + "renderMode", + "redirectionUrl", + "description", + "expirationDate" + ], + "additionalProperties": false + }, + "CustomerOrderMercadoPagoConfig": { + "type": "object", + "properties": { + "publicKey": { + "type": "string", + "description": "MercadoPago (Tickets) public key. Sent to the browser: it is what `initMercadoPago()`/`` from the `@mercadopago/sdk-react` SDK (or equivalent) receives to mount the Payment Brick. Present ONLY on the MercadoPago rail — it is the marker the landing page uses to tell it apart from the Bold rail (which carries `apiKey`+`renderMode` and NEVER `publicKey`)." }, - "saleEndsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } - ] + "amount": { + "type": "number", + "description": "Amount to charge, in the currency's major unit (pesos, not cents) — the same `total` already returned by `POST /customer/orders`. It is re-read from the sale on every call: do not treat it as final if a long time passes between mounting the Brick and charging." }, - "seatsioCategoryKey": { - "anyOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "null" - } - ] + "currency": { + "type": "string" + }, + "reference": { + "type": "string", + "description": "Sale reference (FT-…)." + }, + "payerEmail": { + "type": "string", + "description": "Buyer email (from the sale, not editable). Informational: the charge ALWAYS uses the sale's email, never one sent by the client." } }, + "required": [ + "publicKey", + "amount", + "currency", + "reference", + "payerEmail" + ], "additionalProperties": false }, - "SaleItem": { + "CustomerOrderStartPayment": { + "anyOf": [ + { + "$ref": "#/components/schemas/CustomerOrderPayment" + }, + { + "$ref": "#/components/schemas/CustomerOrderMercadoPagoConfig" + } + ] + }, + "CustomerOrderMercadoPagoChargeRequest": { "type": "object", "properties": { - "id": { - "type": "string" + "token": { + "type": "string", + "minLength": 1, + "description": "Card token returned by the Payment Brick when tokenizing." }, - "ticketTypeId": { - "type": "string" + "paymentMethodId": { + "type": "string", + "minLength": 1, + "description": "`payment_method_id` returned by the Brick (e.g. `visa`, `debmaster`)." }, - "quantity": { + "installments": { + "default": 1, "type": "integer", - "minimum": -9007199254740991, + "minimum": 1, "maximum": 9007199254740991 }, - "unitPrice": { - "type": "number" - }, - "subtotal": { - "type": "number" - }, - "ticketCode": { + "issuerId": { + "description": "`issuer_id` returned by the Brick. Some BINs require it.", "type": "string" }, - "checkedInAt": { - "anyOf": [ - { + "payer": { + "type": "object", + "properties": { + "email": { + "description": "Ignored: the charge ALWAYS uses the sale's email, never one sent by the client.", "type": "string" }, - { - "type": "null" + "identification": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "number": { + "type": "string" + } + }, + "required": [ + "type", + "number" + ], + "additionalProperties": false } - ] + }, + "additionalProperties": false + } + }, + "required": [ + "token", + "paymentMethodId", + "installments" + ], + "additionalProperties": false + }, + "CustomerOrderMercadoPagoChargeResult": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "approved", + "pending", + "rejected" + ], + "description": "`pending` is normal: it may require additional authentication from the bank. `rejected` is a business decline (funds, card details, …) — the buyer can retry with another card." + }, + "reference": { + "type": "string" }, - "seatLabel": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "message": { + "description": "Human-readable message for the buyer. Only present with `rejected`.", + "type": "string" }, - "refundedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "saleAlive": { + "description": "Only present with `rejected`. `false`: the purchase was cancelled and its tickets (and seats) went back to inventory — a new purchase must be started. `true`: THIS payment was declined but the purchase is still pending because another payment is in progress on it (e.g. a PSE payment waiting on the bank); do NOT start a new purchase: show the message, wait, and check the order status.", + "type": "boolean" } }, "required": [ - "id", - "ticketTypeId", - "quantity", - "unitPrice", - "subtotal", - "ticketCode", - "checkedInAt", - "seatLabel", - "refundedAt" + "status", + "reference" ], "additionalProperties": false }, - "Sale": { + "CustomerOrderMercadoPagoPse": { + "type": "object", + "properties": { + "redirectUrl": { + "type": "string", + "description": "`init_point` of the MercadoPago preference. Redirect the buyer there (it is not an iframe): they pick their bank and confirm the transfer on MercadoPago." + } + }, + "required": [ + "redirectUrl" + ], + "additionalProperties": false + }, + "CustomerOrderStatus": { "type": "object", "properties": { - "id": { - "type": "string" - }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - }, - "channel": { - "type": "string" - }, - "subtotal": { - "type": "number" - }, - "discountAmount": { - "type": "number" - }, - "serviceFee": { - "type": "number" + "approved", + "pending", + "rejected" + ], + "description": "`pending` is a NORMAL state: Bold may take a while to reflect the payment (PSE, Nequi and the Bancolombia button approve asynchronously) and the webhook settles it. The landing page must retry, not treat the purchase as lost." }, - "iva": { - "type": "number" + "saleStatus": { + "type": "string", + "description": "Internal sale status (PENDING, CONFIRMED, …)." }, "total": { "type": "number" @@ -13351,1376 +28552,1170 @@ "currency": { "type": "string" }, - "buyerName": { - "type": "string" - }, - "buyerEmail": { - "type": "string" - }, - "buyerPhone": { + "tickets": { "anyOf": [ { - "type": "string" + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerTicketItem" + } }, { "type": "null" } - ] + ], + "description": "Tickets with their `ticketCode`. ONLY present when `status` is `approved`; null in any other case. A code handed out before the payment settles would be a valid ticket with no money behind it." + } + }, + "required": [ + "reference", + "status", + "saleStatus", + "total", + "currency", + "tickets" + ], + "additionalProperties": false + }, + "CustomerOrderItem": { + "type": "object", + "properties": { + "ticketTypeId": { + "type": "string", + "minLength": 1 }, - "buyerDocumentType": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "quantity": { + "type": "integer", + "minimum": 1, + "maximum": 30 }, - "buyerDocumentNumber": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "seats": { + "description": "seats.io labels. Only for seated events.", + "maxItems": 30, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 120 + } + } + }, + "required": [ + "ticketTypeId", + "quantity" + ], + "additionalProperties": false + }, + "CustomerOrderCreateRequest": { + "type": "object", + "properties": { + "eventDateId": { + "type": "string", + "minLength": 1 }, - "organizationId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "items": { + "minItems": 1, + "maxItems": 1, + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerOrderItem" + } }, - "paymentProvider": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "holdToken": { + "description": "Hold token of the seats.io map session. Required if seats are sent.", + "type": "string", + "maxLength": 120 }, - "paymentRef": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "discountCode": { + "type": "string", + "maxLength": 40 }, - "confirmedAt": { - "anyOf": [ - { - "type": "string" + "buyer": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 120 }, - { - "type": "null" - } - ] - }, - "createdAt": { - "type": "string" - }, - "failureReason": { - "anyOf": [ - { - "type": "string" + "phone": { + "type": "string", + "maxLength": 40 }, - { - "type": "null" - } - ] - }, - "paymentStatus": { - "anyOf": [ - { - "type": "string" + "idType": { + "type": "string", + "enum": [ + "CC", + "CE", + "NIT", + "PP", + "TI", + "PEP" + ] }, - { - "type": "null" + "idNumber": { + "type": "string", + "minLength": 5, + "maxLength": 20 + }, + "nitDigit": { + "description": "Check digit. Required if idType is NIT.", + "type": "string", + "maxLength": 1 } + }, + "required": [ + "name", + "phone", + "idType", + "idNumber" ], - "description": "Status of the latest payment event. Usually the payment gateway's RAW status in its own vocabulary. Values prefixed with `FT_` come from FreeTicket, not the gateway: currently `FT_SALE_APPROVED_POST_CONFIRM`, which marks that the gateway re-notified an already-confirmed charge — this is how Bold reports its refunds. A CONFIRMED sale with this status may have money refunded that is not yet recorded." + "additionalProperties": false }, - "declineCode": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "returnUrl": { + "type": "string", + "maxLength": 2048, + "description": "Absolute URL of the landing page the buyer returns to. Validated against the enterprise domain allowlist and the workspace that owns the event; if it fails validation it is ignored and the purchase proceeds as usual." } }, "required": [ - "id", - "reference", - "status", - "channel", - "subtotal", - "discountAmount", - "serviceFee", - "iva", - "total", - "currency", - "buyerName", - "buyerEmail", - "buyerPhone", - "buyerDocumentType", - "buyerDocumentNumber", - "organizationId", - "paymentProvider", - "paymentRef", - "confirmedAt", - "createdAt", - "failureReason", - "paymentStatus", - "declineCode" + "eventDateId", + "items", + "buyer", + "returnUrl" ], "additionalProperties": false }, - "SaleDetail": { + "ContentVideo": { "type": "object", "properties": { "id": { "type": "string" }, - "reference": { - "type": "string" - }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - }, - "channel": { - "type": "string" - }, - "subtotal": { - "type": "number" - }, - "discountAmount": { - "type": "number" - }, - "serviceFee": { - "type": "number" - }, - "iva": { - "type": "number" - }, - "total": { - "type": "number" - }, - "currency": { - "type": "string" - }, - "buyerName": { - "type": "string" - }, - "buyerEmail": { + "title": { "type": "string" }, - "buyerPhone": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "buyerDocumentType": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "description": { + "type": [ + "string", + "null" ] }, - "buyerDocumentNumber": { + "durationSeconds": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "organizationId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "posterUrl": { + "type": [ + "string", + "null" ] }, - "paymentProvider": { + "series": { "anyOf": [ { - "type": "string" + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "title": { + "type": "string" + } + }, + "required": [ + "id", + "title" + ], + "additionalProperties": false }, { "type": "null" } ] }, - "paymentRef": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "memberOnly": { + "type": "boolean", + "description": "true = only current members of the organization can play it." }, - "confirmedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "publishedAt": { + "type": [ + "string", + "null" ] - }, - "createdAt": { - "type": "string" - }, - "failureReason": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + } + }, + "required": [ + "id", + "title", + "description", + "durationSeconds", + "posterUrl", + "series", + "memberOnly", + "publishedAt" + ], + "additionalProperties": false + }, + "ContentPostUpdate": { + "type": "object", + "properties": { + "type": { + "description": "TEXT/IMAGE posts only. An ARTICLE stays an ARTICLE (and vice versa).", + "type": "string", + "enum": [ + "TEXT", + "IMAGE" ] }, - "paymentStatus": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Status of the latest payment event. Usually the payment gateway's RAW status in its own vocabulary. Values prefixed with `FT_` come from FreeTicket, not the gateway: currently `FT_SALE_APPROVED_POST_CONFIRM`, which marks that the gateway re-notified an already-confirmed charge — this is how Bold reports its refunds. A CONFIRMED sale with this status may have money refunded that is not yet recorded." + "content": { + "type": "string", + "maxLength": 5000 }, - "declineCode": { + "imageUrl": { + "description": "ARTICLE posts: the cover image. null removes it.", "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 2048, + "format": "uri" }, { "type": "null" } ] }, - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SaleItem" - } - } - }, - "required": [ - "id", - "reference", - "status", - "channel", - "subtotal", - "discountAmount", - "serviceFee", - "iva", - "total", - "currency", - "buyerName", - "buyerEmail", - "buyerPhone", - "buyerDocumentType", - "buyerDocumentNumber", - "organizationId", - "paymentProvider", - "paymentRef", - "confirmedAt", - "createdAt", - "failureReason", - "paymentStatus", - "declineCode", - "items" - ], - "additionalProperties": false - }, - "MembershipPlan": { - "type": "object", - "properties": { - "id": { - "type": "string" + "locked": { + "type": "boolean" }, - "organizationId": { + "eventId": { + "description": "null unlinks the event.", "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1 }, { "type": "null" } ] }, - "name": { - "type": "string" - }, - "description": { + "channelId": { + "description": "TEXT/IMAGE posts only. Active channel of the workspace; null moves it back to Announcements.", "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 64 }, { "type": "null" } ] }, - "price": { - "type": "number" - }, - "currency": { - "type": "string" + "publishedAt": { + "description": "Reschedules the post (and its member notification, if any).", + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" }, - "billingCycle": { + "title": { "type": "string", - "enum": [ - "MONTHLY", - "QUARTERLY", - "SEMIANNUAL", - "ANNUAL", - "LIFETIME" - ] + "minLength": 1, + "maxLength": 140 }, - "benefits": { - "type": "object", - "properties": { - "presale": { - "type": "boolean" - }, - "freeTicket": { - "type": "boolean" - }, - "discount": { - "type": "boolean" - }, - "exclusiveContent": { - "type": "boolean" + "subtitle": { + "anyOf": [ + { + "type": "string", + "maxLength": 280 }, - "merch": { - "type": "boolean" + { + "type": "null" } - }, - "required": [ - "presale", - "freeTicket", - "discount", - "exclusiveContent", - "merch" - ], - "additionalProperties": false - }, - "isActive": { - "type": "boolean" + ] }, - "sortOrder": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "body": { + "type": "string", + "minLength": 1, + "maxLength": 100000 }, - "createdAt": { - "type": "string" + "slug": { + "description": "ARTICLE only. null re-derives it from the title.", + "anyOf": [ + { + "type": "string", + "maxLength": 200 + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "ContentPostPin": { + "type": "object", + "properties": { + "pinned": { + "type": "boolean" } }, "required": [ - "id", - "organizationId", - "name", - "description", - "price", - "currency", - "billingCycle", - "benefits", - "isActive", - "sortOrder", - "createdAt" + "pinned" ], "additionalProperties": false }, - "MembershipPlanCreate": { + "ContentPostPinned": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "description": { - "type": "string" - }, - "price": { - "type": "number", - "minimum": 0 - }, - "currency": { - "default": "COP", + "id": { "type": "string" }, - "billingCycle": { - "type": "string", - "enum": [ - "MONTHLY", - "QUARTERLY", - "SEMIANNUAL", - "ANNUAL", - "LIFETIME" + "pinnedAt": { + "description": "null when unpinned. At most one pinned post per workspace.", + "type": [ + "string", + "null" ] - }, - "benefitPresale": { - "default": false, - "type": "boolean" - }, - "benefitFreeTicket": { - "default": false, - "type": "boolean" - }, - "benefitDiscount": { - "default": false, - "type": "boolean" - }, - "benefitExclusiveContent": { - "default": false, - "type": "boolean" - }, - "benefitMerch": { - "default": false, - "type": "boolean" - }, - "isActive": { - "default": true, - "type": "boolean" - }, - "sortOrder": { - "default": 0, - "type": "integer", - "minimum": 0, - "maximum": 9007199254740991 } }, "required": [ - "name", - "price", - "currency", - "billingCycle", - "benefitPresale", - "benefitFreeTicket", - "benefitDiscount", - "benefitExclusiveContent", - "benefitMerch", - "isActive", - "sortOrder" + "id", + "pinnedAt" ], "additionalProperties": false }, - "MembershipPlanUpdate": { + "ContentCommentDeleted": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "price": { - "type": "number", - "minimum": 0 - }, - "currency": { + "id": { "type": "string" }, - "billingCycle": { - "type": "string", - "enum": [ - "MONTHLY", - "QUARTERLY", - "SEMIANNUAL", - "ANNUAL", - "LIFETIME" - ] - }, - "benefitPresale": { - "type": "boolean" - }, - "benefitFreeTicket": { - "type": "boolean" - }, - "benefitDiscount": { - "type": "boolean" - }, - "benefitExclusiveContent": { - "type": "boolean" - }, - "benefitMerch": { - "type": "boolean" - }, - "isActive": { - "type": "boolean" + "deleted": { + "type": "boolean", + "const": true }, - "sortOrder": { - "type": "integer", - "minimum": 0, - "maximum": 9007199254740991 + "deletedIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The comment plus its live replies (top-level comments)." } }, + "required": [ + "id", + "deleted", + "deletedIds" + ], "additionalProperties": false }, - "VenueCreate": { + "CommunityChannel": { "type": "object", "properties": { - "name": { + "id": { + "type": "string" + }, + "kind": { "type": "string", - "minLength": 1 + "enum": [ + "ANNOUNCEMENTS", + "GENERAL", + "CITY", + "CUSTOM" + ] }, - "address": { + "name": { + "type": "string" + }, + "slug": { "type": "string", - "minLength": 1 + "description": "Tab URL slug. Does not change on rename." + }, + "description": { + "type": [ + "string", + "null" + ] }, "city": { + "type": [ + "string", + "null" + ] + }, + "whoCanPost": { "type": "string", - "minLength": 1 + "enum": [ + "STAFF", + "MEMBERS" + ] }, - "country": { - "default": "CO", - "type": "string" + "requiresApproval": { + "type": "boolean" }, - "capacity": { + "position": { "type": "integer", - "exclusiveMinimum": 0, + "minimum": -9007199254740991, "maximum": 9007199254740991 - }, - "latitude": { - "type": "number", - "minimum": -90, - "maximum": 90 - }, - "longitude": { - "type": "number", - "minimum": -180, - "maximum": 180 } }, "required": [ + "id", + "kind", "name", - "address", + "slug", + "description", "city", - "country" + "whoCanPost", + "requiresApproval", + "position" ], "additionalProperties": false }, - "VenueUpdate": { + "CommunityChannelCreate": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "address": { - "type": "string", - "minLength": 1 - }, - "city": { + "kind": { "type": "string", - "minLength": 1 + "enum": [ + "CITY", + "CUSTOM" + ] }, - "country": { + "name": { "type": "string", - "minLength": 2, - "maxLength": 2 + "minLength": 1, + "maxLength": 40 }, - "capacity": { + "description": { "anyOf": [ { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "type": "string", + "maxLength": 200 }, { "type": "null" } ] }, - "latitude": { + "city": { + "description": "Required when kind=CITY; ignored otherwise.", "anyOf": [ { - "type": "number", - "minimum": -90, - "maximum": 90 + "type": "string", + "maxLength": 60 }, { "type": "null" } ] }, - "longitude": { - "anyOf": [ - { - "type": "number", - "minimum": -180, - "maximum": 180 - }, - { - "type": "null" - } + "whoCanPost": { + "default": "STAFF", + "type": "string", + "enum": [ + "STAFF", + "MEMBERS" ] }, - "portalVisible": { + "requiresApproval": { + "default": true, "type": "boolean" } }, + "required": [ + "kind", + "name", + "whoCanPost", + "requiresApproval" + ], "additionalProperties": false }, - "StaffUser": { + "CommunityChannelUpdate": { "type": "object", "properties": { - "id": { - "type": "string" - }, "name": { - "type": "string" - }, - "email": { - "type": "string" - }, - "role": { "type": "string", - "enum": [ - "SUPER_ADMIN", - "ADMIN", - "STAFF", - "VIEWER", - "MINCULTURA" - ] + "minLength": 1, + "maxLength": 40 }, - "organizationId": { + "description": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 200 }, { "type": "null" } ] }, - "workspaceId": { - "type": "string" - }, - "workspaceName": { - "type": "string" + "city": { + "anyOf": [ + { + "type": "string", + "maxLength": 60 + }, + { + "type": "null" + } + ] }, - "createdAt": { - "type": "string" - } - }, - "required": [ - "id", - "name", - "email", - "role", - "organizationId", - "createdAt" - ], - "additionalProperties": false - }, - "StaffCreate": { - "type": "object", - "properties": { - "name": { + "whoCanPost": { "type": "string", - "minLength": 1 + "enum": [ + "STAFF", + "MEMBERS" + ] }, - "email": { - "type": "string", - "format": "email", - "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + "requiresApproval": { + "type": "boolean" } }, - "required": [ - "name", - "email" - ], "additionalProperties": false }, - "RoleUpdate": { + "CommunityChannelOrder": { "type": "object", "properties": { - "role": { - "type": "string", - "enum": [ - "SUPER_ADMIN", - "ADMIN", - "STAFF", - "VIEWER", - "MINCULTURA" - ] + "orderedIds": { + "minItems": 1, + "maxItems": 20, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "description": "EVERY active channel id, in the new order, Announcements first." } }, "required": [ - "role" + "orderedIds" ], "additionalProperties": false }, - "ReportSummary": { + "ModerationQueueItem": { "type": "object", "properties": { - "period": { + "commentId": { "type": "string" }, - "currency": { + "body": { "type": "string" }, - "revenue": { - "type": "number" + "createdAt": { + "type": "string" }, - "ticketsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "isReply": { + "type": "boolean" }, - "salesCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "hidden": { + "type": "boolean" }, - "activeMemberships": { + "deleted": { + "type": "boolean", + "description": "Deleted (by its author or the team) with reports still open." + }, + "hiddenSource": { + "description": "MODERATOR | AUTO_REPORTS", + "type": [ + "string", + "null" + ] + }, + "openReportCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 - } - }, - "required": [ - "period", - "currency", - "revenue", - "ticketsSold", - "salesCount", - "activeMemberships" - ], - "additionalProperties": false - }, - "MatchStatus": { - "type": "string", - "enum": [ - "OK", - "MISSING_INVOICE", - "MISSING_CUFE", - "AMOUNT_MISMATCH", - "MISSING_PAYMENT" - ] - }, - "InventoryRow": { - "type": "object", - "properties": { - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" }, - "eventStatus": { - "type": "string", - "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" - ] - }, - "eventDateId": { - "anyOf": [ - { + "author": { + "type": "object", + "properties": { + "customerId": { "type": "string" }, - { - "type": "null" - } - ] - }, - "startsAt": { - "anyOf": [ - { + "name": { "type": "string" }, - { - "type": "null" - } - ] - }, - "ticketTypeId": { - "anyOf": [ - { - "type": "string" + "image": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" + "banned": { + "type": "boolean" } - ] + }, + "required": [ + "customerId", + "name", + "image", + "banned" + ], + "additionalProperties": false }, - "ticketTypeName": { - "anyOf": [ - { + "post": { + "type": "object", + "properties": { + "id": { "type": "string" }, - { - "type": "null" + "label": { + "type": "string" } + }, + "required": [ + "id", + "label" + ], + "additionalProperties": false + }, + "reasons": { + "type": "array", + "items": { + "type": "object", + "properties": { + "reason": { + "type": "string" + }, + "count": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "reason", + "count" + ], + "additionalProperties": false + } + }, + "details": { + "type": "array", + "items": { + "type": "string" + } + }, + "lastReportAt": { + "type": [ + "string", + "null" ] + } + }, + "required": [ + "commentId", + "body", + "createdAt", + "isReply", + "hidden", + "deleted", + "hiddenSource", + "openReportCount", + "author", + "post", + "reasons", + "details", + "lastReportAt" + ], + "additionalProperties": false + }, + "CommunityBan": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "capacity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "customerName": { + "type": "string" }, - "sold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "customerImage": { + "type": [ + "string", + "null" + ] }, - "reserved": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "reason": { + "type": [ + "string", + "null" + ] }, - "available": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "createdAt": { + "type": "string" } }, "required": [ - "eventId", - "eventName", - "eventStatus", - "eventDateId", - "startsAt", - "ticketTypeId", - "ticketTypeName", - "capacity", - "sold", - "reserved", - "available" + "id", + "customerName", + "customerImage", + "reason", + "createdAt" ], "additionalProperties": false }, - "ReconciliationRow": { + "MemberPostQueueItem": { "type": "object", "properties": { - "sale_reference": { + "postId": { "type": "string" }, - "sale_status": { + "status": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" + "PENDING_REVIEW", + "PUBLISHED" ] }, - "sale_amount": { - "type": "number" - }, - "mp_payment_ref": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "content": { + "type": [ + "string", + "null" ] }, - "mp_provider": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "imageUrl": { + "description": "PENDING_REVIEW: short-lived signed URL (the image lives in a private bucket until approved).", + "type": [ + "string", + "null" ] }, - "mp_amount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] + "createdAt": { + "type": "string" }, - "siigo_invoice_name": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "publishedAt": { + "type": "string" }, - "siigo_invoice_status": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "updatedAt": { + "type": "string", + "description": "Version read by the moderator: pass it as `expectedUpdatedAt` to approve." }, - "siigo_cufe": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "channelName": { + "type": [ + "string", + "null" ] }, - "match_status": { - "$ref": "#/components/schemas/MatchStatus" - }, - "event_id": { - "anyOf": [ - { + "author": { + "type": "object", + "properties": { + "customerId": { "type": "string" }, - { - "type": "null" - } - ] - }, - "event_name": { - "anyOf": [ - { + "displayName": { "type": "string" }, - { - "type": "null" - } - ] - }, - "event_date_id": { - "anyOf": [ - { - "type": "string" + "handle": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" + "avatarUrl": { + "type": [ + "string", + "null" + ] + }, + "banned": { + "type": "boolean" } - ] + }, + "required": [ + "customerId", + "displayName", + "handle", + "avatarUrl", + "banned" + ], + "additionalProperties": false + }, + "openReportCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 } }, "required": [ - "sale_reference", - "sale_status", - "sale_amount", - "mp_payment_ref", - "mp_provider", - "mp_amount", - "siigo_invoice_name", - "siigo_invoice_status", - "siigo_cufe", - "match_status", - "event_id", - "event_name", - "event_date_id" + "postId", + "status", + "content", + "imageUrl", + "createdAt", + "publishedAt", + "updatedAt", + "channelName", + "author", + "openReportCount" ], "additionalProperties": false }, - "ExportSaleItem": { + "CommentModerated": { "type": "object", "properties": { - "eventId": { + "commentId": { "type": "string" }, - "eventName": { - "type": "string" + "changed": { + "type": "boolean", + "description": "false = it was already in that state (idempotent)." + } + }, + "required": [ + "commentId", + "changed" + ], + "additionalProperties": false + }, + "MemberBanCreate": { + "type": "object", + "properties": { + "commentId": { + "type": "string", + "minLength": 1, + "description": "Comment of this member in the workspace that motivates the ban (required: a ban always comes from a reported comment)." }, - "eventDateId": { - "type": "string" + "reason": { + "type": "string", + "maxLength": 500 }, - "eventDateStartsAt": { + "hideAllComments": { + "default": false, + "description": "true = hide every comment of the member in this workspace, not only `commentId`.", + "type": "boolean" + } + }, + "required": [ + "commentId", + "hideAllComments" + ], + "additionalProperties": false + }, + "MemberBanResult": { + "type": "object", + "properties": { + "customerId": { "type": "string" }, - "ticketTypeId": { - "type": "string" + "banned": { + "type": "boolean" + } + }, + "required": [ + "customerId", + "banned" + ], + "additionalProperties": false + }, + "MemberPostApprove": { + "type": "object", + "properties": { + "expectedUpdatedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", + "description": "`updatedAt` of the post as read from `GET /content/moderation/member-posts`." + } + }, + "required": [ + "expectedUpdatedAt" + ], + "additionalProperties": false + }, + "MemberPostDecision": { + "type": "object", + "properties": { + "reason": { + "description": "Shown to the author in their inbox.", + "type": "string", + "maxLength": 1000 }, - "ticketTypeName": { + "banAuthor": { + "default": false, + "description": "Also bans the author from the community. Requires ADMIN.", + "type": "boolean" + } + }, + "required": [ + "banAuthor" + ], + "additionalProperties": false + }, + "MemberPostReviewed": { + "type": "object", + "properties": { + "postId": { "type": "string" }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "status": { + "type": "string", + "enum": [ + "PUBLISHED", + "REJECTED", + "REMOVED" + ] } }, "required": [ - "eventId", - "eventName", - "eventDateId", - "eventDateStartsAt", - "ticketTypeId", - "ticketTypeName", - "quantity" + "postId", + "status" ], "additionalProperties": false }, - "ExportBuyer": { + "CommunityMeetupCreate": { "type": "object", "properties": { - "reference": { - "type": "string" + "title": { + "type": "string", + "minLength": 3, + "maxLength": 120 }, - "name": { - "type": "string" + "description": { + "type": "string", + "maxLength": 5000 }, - "email": { + "format": { + "type": "string", + "enum": [ + "IN_PERSON", + "ONLINE" + ] + }, + "startsAt": { + "type": "string", + "description": "Local wall time in the workspace's timezone, `YYYY-MM-DDTHH:mm` (same as the dashboard form)." + }, + "endsAt": { + "description": "Local wall time in the workspace's timezone, `YYYY-MM-DDTHH:mm` (same as the dashboard form). Empty = none.", "type": "string" }, - "phone": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "city": { + "type": "string", + "maxLength": 80 }, - "documentType": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "locationName": { + "type": "string", + "maxLength": 120 }, - "documentNumber": { + "locationDetail": { + "type": "string", + "maxLength": 500 + }, + "onlineUrl": { + "description": "ONLINE only; must start with https://", + "type": "string", + "maxLength": 500 + }, + "capacity": { + "description": "null = unlimited.", "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": 1, + "maximum": 100000 }, { "type": "null" } ] }, - "total": { - "type": "number" - }, - "currency": { - "type": "string" - }, - "saleStatus": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - }, - "createdAt": { - "type": "string" - }, - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExportSaleItem" - } + "requiresApproval": { + "description": "true = the staff approves each RSVP request.", + "type": "boolean" } }, "required": [ - "reference", - "name", - "email", - "phone", - "documentType", - "documentNumber", - "total", - "currency", - "saleStatus", - "createdAt", - "items" + "title", + "format", + "startsAt" ], "additionalProperties": false }, - "ExportAttendee": { + "CommunityMeetupUpdate": { "type": "object", "properties": { - "reference": { - "type": "string" - }, - "name": { - "type": "string" - }, - "email": { - "type": "string" + "title": { + "type": "string", + "minLength": 3, + "maxLength": 120 }, - "phone": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "description": { + "type": "string", + "maxLength": 5000 }, - "documentType": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "format": { + "type": "string", + "enum": [ + "IN_PERSON", + "ONLINE" ] }, - "documentNumber": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "startsAt": { + "type": "string", + "description": "Local wall time in the workspace's timezone, `YYYY-MM-DDTHH:mm` (same as the dashboard form)." }, - "ticketCode": { + "endsAt": { + "description": "Local wall time in the workspace's timezone, `YYYY-MM-DDTHH:mm` (same as the dashboard form). Empty = none.", "type": "string" }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "city": { + "type": "string", + "maxLength": 80 }, - "checkedInAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "locationName": { + "type": "string", + "maxLength": 120 }, - "checkedInSource": { + "locationDetail": { + "type": "string", + "maxLength": 500 + }, + "onlineUrl": { + "description": "ONLINE only; must start with https://", + "type": "string", + "maxLength": 500 + }, + "capacity": { + "description": "null = unlimited.", "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": 1, + "maximum": 100000 }, { "type": "null" } ] }, - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" - }, - "eventDateId": { - "type": "string" - }, - "eventDateStartsAt": { - "type": "string" - }, - "ticketTypeId": { - "type": "string" - }, - "ticketTypeName": { - "type": "string" - }, - "saleStatus": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - }, - "createdAt": { - "type": "string" + "requiresApproval": { + "description": "true = the staff approves each RSVP request.", + "type": "boolean" } }, - "required": [ - "reference", - "name", - "email", - "phone", - "documentType", - "documentNumber", - "ticketCode", - "quantity", - "checkedInAt", - "checkedInSource", - "eventId", - "eventName", - "eventDateId", - "eventDateStartsAt", - "ticketTypeId", - "ticketTypeName", - "saleStatus", - "createdAt" - ], "additionalProperties": false }, - "ExportSubscriber": { + "CommunityMeetup": { "type": "object", "properties": { - "name": { + "id": { "type": "string" }, - "email": { + "title": { "type": "string" }, - "plan": { - "type": "string" + "format": { + "type": "string", + "enum": [ + "IN_PERSON", + "ONLINE" + ] }, "status": { - "type": "string" + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "CANCELLED" + ] }, - "since": { + "startsAt": { "type": "string" }, - "expiresAt": { + "city": { + "type": [ + "string", + "null" + ] + }, + "capacity": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] - } - }, - "required": [ - "name", - "email", - "plan", - "status", - "since", - "expiresAt" - ], - "additionalProperties": false - }, - "PurchaseSessionCreateRequest": { - "type": "object", - "properties": { - "eventDateId": { - "type": "string", - "minLength": 1, - "maxLength": 64 }, - "deviceKey": { - "type": "string", - "minLength": 8, - "maxLength": 200, - "description": "Stable browser identifier (e.g. stored in localStorage). If the SAME browser reopens the SAME event date while its session is still alive, it gets that same session (same `holdToken`, same clock) instead of a new one." + "goingCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "requiresApproval": { + "type": "boolean" + }, + "pendingCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "PENDING RSVP requests." } }, "required": [ - "eventDateId", - "deviceKey" + "id", + "title", + "format", + "status", + "startsAt", + "city", + "capacity", + "goingCount", + "requiresApproval", + "pendingCount" ], "additionalProperties": false }, - "PurchaseSessionCreated": { + "CommunityMeetupDetail": { "type": "object", "properties": { "id": { "type": "string" }, - "eventDateId": { + "title": { "type": "string" }, - "state": { + "format": { "type": "string", - "const": "live" + "enum": [ + "IN_PERSON", + "ONLINE" + ] }, - "seated": { - "type": "boolean", - "description": "true = the event date has a seats.io map." + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "CANCELLED" + ] }, - "holdToken": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "seats.io hold token ISSUED BY THE SERVER. Mount the chart with `session: \"manual\"` and this `holdToken` (https://docs.seats.io/docs/renderer/config-session/), never with `session: \"continue\"`. It is the ONLY token `POST /customer/orders` accepts for this session. null for event dates without a map." + "startsAt": { + "type": "string" }, - "seatsDeadline": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Instant (ISO 8601 UTC) until which the order with seats can be created. This is the clock to display over the map. The seats.io hold expires AFTER this instant, never before. null for event dates without a map." + "city": { + "type": [ + "string", + "null" + ] }, - "budgetSeconds": { + "capacity": { "anyOf": [ { "type": "integer", @@ -14730,1661 +29725,1697 @@ { "type": "null" } - ], - "description": "Budget seconds granted to this session (= seatsDeadline − now). The budget is CUMULATIVE per buyer and event date: opening another tab does not reset it." + ] }, - "replacedSessionId": { - "anyOf": [ - { + "goingCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "requiresApproval": { + "type": "boolean" + }, + "pendingCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "PENDING RSVP requests." + }, + "endsAt": { + "type": [ + "string", + "null" + ] + }, + "publishedAt": { + "type": [ + "string", + "null" + ] + }, + "cancelledAt": { + "type": [ + "string", + "null" + ] + }, + "local": { + "type": "object", + "properties": { + "title": { "type": "string" }, - { - "type": "null" + "description": { + "type": "string" + }, + "format": { + "type": "string", + "enum": [ + "IN_PERSON", + "ONLINE" + ] + }, + "startsAt": { + "type": "string" + }, + "endsAt": { + "type": "string" + }, + "city": { + "type": "string" + }, + "locationName": { + "type": "string" + }, + "locationDetail": { + "type": "string" + }, + "onlineUrl": { + "type": "string" + }, + "capacity": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "requiresApproval": { + "type": "boolean" } + }, + "required": [ + "title", + "description", + "format", + "startsAt", + "endsAt", + "city", + "locationName", + "locationDetail", + "onlineUrl", + "capacity", + "requiresApproval" ], - "description": "Live session that this one replaced (now `superseded`), or null. That tab can no longer create an order or start a new payment." + "additionalProperties": false, + "description": "Editable values in the workspace's local wall time (the shape `PATCH /content/meetups/{id}` accepts)." + }, + "attendees": { + "type": "array", + "items": { + "type": "object", + "properties": { + "rsvpId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "confirmedAt": { + "type": "string" + }, + "checkedInAt": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "rsvpId", + "name", + "confirmedAt", + "checkedInAt" + ], + "additionalProperties": false + } + }, + "requests": { + "type": "array", + "items": { + "type": "object", + "properties": { + "rsvpId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "requestedAt": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "GOING", + "DECLINED" + ] + } + }, + "required": [ + "rsvpId", + "name", + "email", + "requestedAt", + "status" + ], + "additionalProperties": false + } } }, "required": [ "id", - "eventDateId", - "state", - "seated", - "holdToken", - "seatsDeadline", - "budgetSeconds", - "replacedSessionId" + "title", + "format", + "status", + "startsAt", + "city", + "capacity", + "goingCount", + "requiresApproval", + "pendingCount", + "endsAt", + "publishedAt", + "cancelledAt", + "local", + "attendees", + "requests" ], "additionalProperties": false }, - "PurchaseSessionStatus": { + "CommunityMeetupRsvpReview": { "type": "object", "properties": { - "id": { + "decision": { + "type": "string", + "enum": [ + "APPROVE", + "REJECT" + ] + } + }, + "required": [ + "decision" + ], + "additionalProperties": false + }, + "CommunityMeetupRsvpReviewed": { + "type": "object", + "properties": { + "rsvpId": { "type": "string" }, - "state": { + "status": { "type": "string", "enum": [ - "live", - "superseded", - "expired", - "converted" - ], - "description": "`live`: can create the order. `superseded`: another tab/device replaced it. `expired`: the map clock ran out or it was released. `converted`: it already created its order (`orderId`)." - }, - "seatsDeadline": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "GOING", + "DECLINED" ] - }, - "orderId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Sale created with this session, if any." } }, "required": [ - "id", - "state", - "seatsDeadline", - "orderId" + "rsvpId", + "status" + ], + "additionalProperties": false + }, + "CommunityMeetupAttendance": { + "type": "object", + "properties": { + "rsvpId": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "attended": { + "type": "boolean" + } + }, + "required": [ + "rsvpId", + "attended" ], "additionalProperties": false }, - "CustomerTicketItem": { + "CommunityMeetupAttendanceResult": { "type": "object", "properties": { - "ticketTypeName": { + "rsvpId": { "type": "string" }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "ticketCode": { - "type": "string", - "description": "Opaque ticket code. The QR code must encode the validator URL (`https://admin.appfreeticket.com/dashboard/tickets/validar?code=`)." + "attended": { + "type": "boolean" }, - "seatLabel": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Exact seat for seated events (seats.io), or null." + "changed": { + "type": "boolean", + "description": "false = already in that state, or the RSVP is not GOING / the meetup is cancelled." } }, "required": [ - "ticketTypeName", - "quantity", - "ticketCode", - "seatLabel" + "rsvpId", + "attended", + "changed" ], "additionalProperties": false }, - "CustomerSale": { + "ContentPost": { "type": "object", "properties": { "id": { "type": "string" }, - "reference": { - "type": "string" + "type": { + "type": "string", + "enum": [ + "TEXT", + "IMAGE", + "VIDEO", + "ARTICLE" + ] }, - "status": { - "type": "string" + "content": { + "type": [ + "string", + "null" + ] }, - "event": { - "type": "object", - "properties": { - "name": { - "type": "string" + "imageUrl": { + "description": "ARTICLE post: also serves as the article's cover image.", + "type": [ + "string", + "null" + ] + }, + "videoId": { + "description": "VIDEO post: id of the ContentVideo, to cross-reference with `GET /content/videos`.", + "type": [ + "string", + "null" + ] + }, + "eventId": { + "type": [ + "string", + "null" + ] + }, + "locked": { + "type": "boolean", + "description": "true = post restricted to current members; its content arrives redacted." + }, + "title": { + "description": "ARTICLE posts only; null for every other type.", + "type": [ + "string", + "null" + ] + }, + "subtitle": { + "description": "ARTICLE posts only.", + "type": [ + "string", + "null" + ] + }, + "slug": { + "description": "ARTICLE posts only. Permalink at /comunidades/articulos/{slug}, unique per organization.", + "type": [ + "string", + "null" + ] + }, + "body": { + "description": "ARTICLE posts only. Body in Markdown.", + "type": [ + "string", + "null" + ] + }, + "readingMinutes": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "slug": { - "type": "string" + { + "type": "null" } - }, - "required": [ - "name", - "slug" ], - "additionalProperties": false + "description": "ARTICLE posts only. Not redacted when `locked`: it does not leak content, only its length." }, - "eventDate": { - "type": "object", - "properties": { - "startsAt": { - "type": "string", - "description": "Event start instant in ISO 8601 UTC." + "link": { + "anyOf": [ + { + "type": "object", + "properties": { + "url": { + "type": "string" + }, + "title": { + "type": [ + "string", + "null" + ] + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "imageUrl": { + "type": [ + "string", + "null" + ] + }, + "domain": { + "type": "string" + } + }, + "required": [ + "url", + "title", + "description", + "imageUrl", + "domain" + ], + "additionalProperties": false }, - "timezone": { - "type": "string", - "description": "IANA time zone of the event." + { + "type": "null" } - }, - "required": [ - "startsAt", - "timezone" ], - "additionalProperties": false - }, - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerTicketItem" - } + "description": "Open Graph snapshot of the first link in the text. Always null for ARTICLE posts." }, - "total": { - "type": "number" + "commentsCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Visible comments: excludes deleted ones and those hidden by moderation (and replies to a hidden comment). 0 if the post arrives redacted." }, - "currency": { + "publishedAt": { "type": "string" } }, "required": [ "id", - "reference", - "status", - "event", - "eventDate", - "items", - "total", - "currency" + "type", + "content", + "imageUrl", + "videoId", + "eventId", + "locked", + "title", + "subtitle", + "slug", + "body", + "readingMinutes", + "link", + "commentsCount", + "publishedAt" ], "additionalProperties": false }, - "CustomerOrderCreateResult": { + "ContentPostCreate": { "type": "object", "properties": { - "free": { - "type": "boolean", - "description": "true = the purchase was CONFIRMED without a payment gateway (100% discount). In that case do NOT call /payment: there is nothing to charge and the other fields are null." + "type": { + "default": "TEXT", + "type": "string", + "enum": [ + "TEXT", + "IMAGE", + "ARTICLE" + ] }, - "reference": { + "content": { "type": "string", - "description": "Sale reference (FT-…). Always identifies the purchase." + "maxLength": 5000 }, - "saleId": { + "imageUrl": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 2048, + "format": "uri" }, { "type": "null" } - ], - "description": "Sale id. null when `free` is true." + ] }, - "total": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ], - "description": "Amount to charge. null when `free` is true." + "title": { + "description": "Required when type=ARTICLE.", + "type": "string", + "minLength": 1, + "maxLength": 140 }, - "currency": { + "subtitle": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 280 }, { "type": "null" } ] }, - "expiresAt": { + "slug": { + "description": "Manual; if omitted it is derived from the title.", "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 200 }, { "type": "null" } - ], - "description": "Instant (ISO 8601 UTC) at which the inventory reservation expires. After that, the purchase must be started over." - } - }, - "required": [ - "free", - "reference", - "saleId", - "total", - "currency", - "expiresAt" - ], - "additionalProperties": false - }, - "CustomerOrderCurrent": { - "type": "object", - "properties": { - "order": { + ] + }, + "body": { + "description": "Markdown. Required when type=ARTICLE.", + "type": "string", + "minLength": 1, + "maxLength": 100000 + }, + "locked": { + "default": false, + "description": "true = restricted to current members.", + "type": "boolean" + }, + "eventId": { "anyOf": [ { - "type": "object", - "properties": { - "saleId": { - "type": "string" - }, - "reference": { - "type": "string" - }, - "total": { - "type": "number" - }, - "currency": { - "type": "string" - }, - "expiresAt": { - "type": "string", - "description": "Instant (ISO 8601 UTC) at which the inventory hold expires. This is the countdown to display." - }, - "paymentOpened": { - "type": "boolean", - "description": "true = payment has already been opened for this sale. Reopening it with /payment returns the SAME signed configuration while the reservation is still alive." - }, - "items": { - "type": "array", - "items": { - "type": "object", - "properties": { - "ticketTypeId": { - "type": "string" - }, - "ticketTypeName": { - "type": "string" - }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "seatLabel": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "seats.io numbered seat, or null if not seated." - } - }, - "required": [ - "ticketTypeId", - "ticketTypeName", - "quantity", - "seatLabel" - ], - "additionalProperties": false - } - } - }, - "required": [ - "saleId", - "reference", - "total", - "currency", - "expiresAt", - "paymentOpened", - "items" - ], - "additionalProperties": false + "type": "string", + "minLength": 1 }, { "type": "null" } - ], - "description": "The purchase the buyer left unfinished for this event date, or null if there is none." + ] + }, + "publishedAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$" } }, "required": [ - "order" + "type", + "locked" ], "additionalProperties": false }, - "CustomerOrderRelease": { + "ContentMediaDeleted": { "type": "object", "properties": { - "released": { + "id": { + "type": "string" + }, + "deleted": { "type": "boolean", - "const": true, - "description": "The sale is now ABANDONED and its inventory went back to stock. A rejection never lands here: it is returned as an error with `details.reason`." + "const": true } }, "required": [ - "released" + "id", + "deleted" ], "additionalProperties": false }, - "CustomerOrderPayment": { + "ContentVideoUpdate": { "type": "object", "properties": { - "orderId": { - "type": "string", - "description": "Merchant reference = `reference`." - }, - "amount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Whole pesos, no decimals." - }, - "currency": { + "title": { "type": "string" }, - "apiKey": { - "type": "string", - "description": "Bold IDENTITY key (public, sent to the browser)." - }, - "integritySignature": { - "type": "string", - "description": "SHA256 that binds the charge to the amount. Computed on the server." + "description": { + "description": "`null` or empty clears the description.", + "type": [ + "string", + "null" + ] }, - "renderMode": { - "type": "string", - "const": "embedded" + "memberOnly": { + "description": "true = only current members can play it.", + "type": "boolean" + } + }, + "additionalProperties": false + }, + "ContentVideoSummary": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "redirectionUrl": { + "title": { "type": "string" }, "description": { - "type": "string" + "type": [ + "string", + "null" + ] }, - "expirationDate": { - "type": "number", - "description": "Epoch in NANOSECONDS (what the Bold library expects)." + "memberOnly": { + "type": "boolean" } }, "required": [ - "orderId", - "amount", - "currency", - "apiKey", - "integritySignature", - "renderMode", - "redirectionUrl", + "id", + "title", "description", - "expirationDate" + "memberOnly" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoConfig": { + "ContentVideoPublish": { "type": "object", "properties": { - "publicKey": { - "type": "string", - "description": "MercadoPago (Tickets) public key. Sent to the browser: it is what `initMercadoPago()`/`` from the `@mercadopago/sdk-react` SDK (or equivalent) receives to mount the Payment Brick. Present ONLY on the MercadoPago rail — it is the marker the landing page uses to tell it apart from the Bold rail (which carries `apiKey`+`renderMode` and NEVER `publicKey`)." - }, - "amount": { - "type": "number", - "description": "Amount to charge, in the currency's major unit (pesos, not cents) — the same `total` already returned by `POST /customer/orders`. It is re-read from the sale on every call: do not treat it as final if a long time passes between mounting the Brick and charging." - }, - "currency": { - "type": "string" - }, - "reference": { - "type": "string", - "description": "Sale reference (FT-…)." - }, - "payerEmail": { - "type": "string", - "description": "Buyer email (from the sale, not editable). Informational: the charge ALWAYS uses the sale's email, never one sent by the client." + "published": { + "type": "boolean" } }, "required": [ - "publicKey", - "amount", - "currency", - "reference", - "payerEmail" + "published" ], "additionalProperties": false }, - "CustomerOrderStartPayment": { - "anyOf": [ - { - "$ref": "#/components/schemas/CustomerOrderPayment" - }, - { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoConfig" - } - ] - }, - "CustomerOrderMercadoPagoChargeRequest": { + "ContentVideoPublished": { "type": "object", "properties": { - "token": { - "type": "string", - "minLength": 1, - "description": "Card token returned by the Payment Brick when tokenizing." - }, - "paymentMethodId": { - "type": "string", - "minLength": 1, - "description": "`payment_method_id` returned by the Brick (e.g. `visa`, `debmaster`)." - }, - "installments": { - "default": 1, - "type": "integer", - "minimum": 1, - "maximum": 9007199254740991 - }, - "issuerId": { - "description": "`issuer_id` returned by the Brick. Some BINs require it.", + "id": { "type": "string" }, - "payer": { - "type": "object", - "properties": { - "email": { - "description": "Ignored: the charge ALWAYS uses the sale's email, never one sent by the client.", - "type": "string" - }, - "identification": { - "type": "object", - "properties": { - "type": { - "type": "string" - }, - "number": { - "type": "string" - } - }, - "required": [ - "type", - "number" - ], - "additionalProperties": false - } - }, - "additionalProperties": false + "published": { + "type": "boolean" } }, "required": [ - "token", - "paymentMethodId", - "installments" + "id", + "published" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoChargeResult": { + "ContentVideoSeriesAssign": { "type": "object", "properties": { - "status": { - "type": "string", - "enum": [ - "approved", - "pending", - "rejected" + "seriesId": { + "anyOf": [ + { + "type": "string", + "minLength": 1 + }, + { + "type": "null" + } ], - "description": "`pending` is normal: it may require additional authentication from the bank. `rejected` is a business decline (funds, card details, …) — the buyer can retry with another card." - }, - "reference": { - "type": "string" - }, - "message": { - "description": "Human-readable message for the buyer. Only present with `rejected`.", - "type": "string" - }, - "saleAlive": { - "description": "Only present with `rejected`. `false`: the purchase was cancelled and its tickets (and seats) went back to inventory — a new purchase must be started. `true`: THIS payment was declined but the purchase is still pending because another payment is in progress on it (e.g. a PSE payment waiting on the bank); do NOT start a new purchase: show the message, wait, and check the order status.", - "type": "boolean" + "description": "Series to put the video in; `null` removes it from its series." } }, "required": [ - "status", - "reference" + "seriesId" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoPse": { + "ContentVideoSeriesResult": { "type": "object", "properties": { - "redirectUrl": { - "type": "string", - "description": "`init_point` of the MercadoPago preference. Redirect the buyer there (it is not an iframe): they pick their bank and confirm the transfer on MercadoPago." + "id": { + "type": "string" + }, + "seriesId": { + "type": [ + "string", + "null" + ] } }, "required": [ - "redirectUrl" + "id", + "seriesId" ], "additionalProperties": false }, - "CustomerOrderStatus": { + "ContentSeries": { "type": "object", "properties": { - "reference": { + "id": { "type": "string" }, - "status": { - "type": "string", - "enum": [ - "approved", - "pending", - "rejected" - ], - "description": "`pending` is a NORMAL state: Bold may take a while to reflect the payment (PSE, Nequi and the Bancolombia button approve asynchronously) and the webhook settles it. The landing page must retry, not treat the purchase as lost." + "title": { + "type": "string" }, - "saleStatus": { - "type": "string", - "description": "Internal sale status (PENDING, CONFIRMED, …)." + "description": { + "type": [ + "string", + "null" + ] }, - "total": { - "type": "number" + "coverImageUrl": { + "type": [ + "string", + "null" + ] }, - "currency": { - "type": "string" + "memberOnly": { + "type": "boolean" }, - "tickets": { - "anyOf": [ - { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerTicketItem" - } - }, - { - "type": "null" - } - ], - "description": "Tickets with their `ticketCode`. ONLY present when `status` is `approved`; null in any other case. A code handed out before the payment settles would be a valid ticket with no money behind it." + "published": { + "type": "boolean" + }, + "publishedAt": { + "type": [ + "string", + "null" + ] + }, + "videoCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Videos in the series (published or not, course videos excluded)." + }, + "createdAt": { + "type": "string" } }, "required": [ - "reference", - "status", - "saleStatus", - "total", - "currency", - "tickets" + "id", + "title", + "description", + "coverImageUrl", + "memberOnly", + "published", + "publishedAt", + "videoCount", + "createdAt" ], "additionalProperties": false }, - "CustomerOrderItem": { + "ContentSeriesCreate": { "type": "object", "properties": { - "ticketTypeId": { + "title": { "type": "string", - "minLength": 1 + "description": "1–120 characters." }, - "quantity": { - "type": "integer", - "minimum": 1, - "maximum": 30 + "description": { + "description": "Up to 2000 characters.", + "type": [ + "string", + "null" + ] }, - "seats": { - "description": "seats.io labels. Only for seated events.", - "maxItems": 30, - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "maxLength": 120 - } + "coverImageUrl": { + "description": "Absolute URL of the cover.", + "type": [ + "string", + "null" + ] + }, + "memberOnly": { + "description": "Default true.", + "type": "boolean" } }, "required": [ - "ticketTypeId", - "quantity" + "title" ], "additionalProperties": false }, - "CustomerOrderCreateRequest": { + "ContentSeriesUpdate": { "type": "object", "properties": { - "eventDateId": { - "type": "string", - "minLength": 1 + "title": { + "type": "string" }, - "items": { - "minItems": 1, - "maxItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerOrderItem" - } + "description": { + "description": "`null` clears it.", + "type": [ + "string", + "null" + ] }, - "holdToken": { - "description": "Hold token of the seats.io map session. Required if seats are sent.", - "type": "string", - "maxLength": 120 + "coverImageUrl": { + "description": "`null` clears it.", + "type": [ + "string", + "null" + ] }, - "discountCode": { + "memberOnly": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "ContentSeriesPublish": { + "type": "object", + "properties": { + "published": { + "type": "boolean" + } + }, + "required": [ + "published" + ], + "additionalProperties": false + }, + "ContentLiveCreate": { + "type": "object", + "properties": { + "title": { "type": "string", - "maxLength": 40 + "description": "1–120 characters." }, - "buyer": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 2, - "maxLength": 120 - }, - "phone": { - "type": "string", - "maxLength": 40 - }, - "idType": { - "type": "string", - "enum": [ - "CC", - "CE", - "NIT", - "PP", - "TI", - "PEP" - ] - }, - "idNumber": { - "type": "string", - "minLength": 5, - "maxLength": 20 - }, - "nitDigit": { - "description": "Check digit. Required if idType is NIT.", - "type": "string", - "maxLength": 1 - } - }, - "required": [ - "name", - "phone", - "idType", - "idNumber" - ], - "additionalProperties": false + "eventDateId": { + "description": "Show date to tie the stream to (owned by the workspace or with the workspace as a linked artist). One stream per date.", + "type": [ + "string", + "null" + ] }, - "returnUrl": { - "type": "string", - "maxLength": 2048, - "description": "Absolute URL of the landing page the buyer returns to. Validated against the enterprise domain allowlist and the workspace that owns the event; if it fails validation it is ignored and the purchase proceeds as usual." + "memberOnly": { + "description": "Default true. Ignored (stream is public) when the workspace has no active membership plan.", + "type": "boolean" + }, + "scheduledAt": { + "description": "Wall-clock time \"YYYY-MM-DDTHH:mm\" in the WORKSPACE time zone (not UTC, no offset). Must be in the future and at most 2 years ahead. Absent: inherits the show date's start time when `eventDateId` is set.", + "type": [ + "string", + "null" + ] } }, "required": [ - "eventDateId", - "items", - "buyer", - "returnUrl" + "title" ], "additionalProperties": false }, - "SaleCreate": { + "ContentLiveCreated": { "type": "object", "properties": { - "buyer": { - "type": "object", - "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "email": { - "type": "string", - "format": "email", - "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" - }, - "phone": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "name", - "email" - ], - "additionalProperties": false + "id": { + "type": "string" }, - "items": { - "minItems": 1, - "type": "array", - "items": { - "type": "object", - "properties": { - "ticketTypeId": { - "type": "string", - "minLength": 1 - }, - "quantity": { - "type": "integer", - "minimum": 1, - "maximum": 9007199254740991 - }, - "seats": { - "type": "array", - "items": { - "type": "string", - "minLength": 1 - } - } - }, - "required": [ - "ticketTypeId", - "quantity" - ], - "additionalProperties": false - } + "title": { + "type": "string" + }, + "memberOnly": { + "type": "boolean" + }, + "scheduledAt": { + "description": "UTC ISO 8601.", + "type": [ + "string", + "null" + ] + }, + "eventDateId": { + "type": [ + "string", + "null" + ] }, - "channel": { - "default": "ADMIN", + "rtmpUrl": { "type": "string", - "enum": [ - "WEB", - "MOBILE", - "POS", - "ADMIN" - ] + "description": "RTMPS ingest server for OBS / the encoder." }, - "comp": { - "default": false, - "type": "boolean" + "streamKey": { + "type": "string", + "description": "SECRET. RTMP stream key: whoever has it can broadcast on this stream in the organization's name. Store it like a password; it is never returned by any read endpoint. Rotate it with `POST /content/lives/{id}/reset-key`." + } + }, + "required": [ + "id", + "title", + "memberOnly", + "scheduledAt", + "eventDateId", + "rtmpUrl", + "streamKey" + ], + "additionalProperties": false + }, + "ContentLiveStreamKey": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "notes": { + "rtmpUrl": { "type": "string" + }, + "streamKey": { + "type": "string", + "description": "SECRET. RTMP stream key: whoever has it can broadcast on this stream in the organization's name. Store it like a password; it is never returned by any read endpoint. Rotate it with `POST /content/lives/{id}/reset-key`." } }, "required": [ - "buyer", - "items", - "channel", - "comp" + "id", + "rtmpUrl", + "streamKey" ], "additionalProperties": false }, - "SaleCancelRequest": { + "ContentLiveUpdate": { "type": "object", "properties": { - "acknowledge_open_payment": { + "scheduledAt": { + "description": "Wall-clock time \"YYYY-MM-DDTHH:mm\" in the WORKSPACE time zone (not UTC, no offset). Must be in the future and at most 2 years ahead. `null` removes the scheduled time. Only while the stream is IDLE.", + "type": [ + "string", + "null" + ] + }, + "memberOnly": { "type": "boolean" } }, "additionalProperties": false }, - "SaleRefundRequest": { + "ContentLiveSettings": { "type": "object", "properties": { - "acknowledge_manual": { + "id": { + "type": "string" + }, + "memberOnly": { "type": "boolean" }, - "items": { - "minItems": 1, - "maxItems": 200, + "scheduledAt": { + "description": "UTC ISO 8601.", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "memberOnly", + "scheduledAt" + ], + "additionalProperties": false + }, + "ContentLiveChat": { + "type": "object", + "properties": { + "messages": { "type": "array", "items": { - "type": "string", - "minLength": 1, - "maxLength": 64 + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "authorId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "text": { + "type": "string" + }, + "sentAt": { + "type": "string" + }, + "host": { + "description": "Present (true) on messages sent by the organization.", + "type": "boolean" + } + }, + "required": [ + "id", + "authorId", + "name", + "text", + "sentAt" + ], + "additionalProperties": false } }, - "block_seats": { - "type": "boolean" + "truncated": { + "type": "boolean", + "description": "true if the history cap was reached and the oldest messages are missing." } }, + "required": [ + "messages", + "truncated" + ], "additionalProperties": false }, - "SaleRefundResult": { + "ContentLive": { "type": "object", "properties": { "id": { "type": "string" }, - "reference": { + "title": { "type": "string" }, "status": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - }, - "channel": { - "type": "string" - }, - "subtotal": { - "type": "number" - }, - "discountAmount": { - "type": "number" - }, - "serviceFee": { - "type": "number" - }, - "iva": { - "type": "number" - }, - "total": { - "type": "number" - }, - "currency": { - "type": "string" - }, - "buyerName": { - "type": "string" - }, - "buyerEmail": { - "type": "string" - }, - "buyerPhone": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "buyerDocumentType": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "buyerDocumentNumber": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "organizationId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "IDLE", + "ACTIVE", + "COMPLETED", + "DISABLED" + ], + "description": "ACTIVE = streaming right now (live banner)." }, - "paymentProvider": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "memberOnly": { + "type": "boolean" }, - "paymentRef": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "startedAt": { + "type": [ + "string", + "null" ] }, - "confirmedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "endedAt": { + "type": [ + "string", + "null" ] }, - "createdAt": { - "type": "string" - }, - "failureReason": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "hasRecording": { + "type": "boolean", + "description": "true if a playable recording remains after the stream." + } + }, + "required": [ + "id", + "title", + "status", + "memberOnly", + "startedAt", + "endedAt", + "hasRecording" + ], + "additionalProperties": false + }, + "ContentPlaybackTokenRequest": { + "type": "object", + "properties": { + "kind": { + "type": "string", + "enum": [ + "video", + "live" ] }, - "paymentStatus": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Status of the latest payment event. Usually the payment gateway's RAW status in its own vocabulary. Values prefixed with `FT_` come from FreeTicket, not the gateway: currently `FT_SALE_APPROVED_POST_CONFIRM`, which marks that the gateway re-notified an already-confirmed charge — this is how Bold reports its refunds. A CONFIRMED sale with this status may have money refunded that is not yet recorded." - }, - "declineCode": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "id": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "kind", + "id" + ], + "additionalProperties": false + }, + "ContentPlaybackToken": { + "type": "object", + "properties": { + "playbackId": { + "type": "string" }, - "refund": { + "tokens": { "type": "object", "properties": { - "amount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] - }, - "refundedItemIds": { - "type": "array", - "items": { - "type": "string" - } + "playback": { + "type": "string" }, - "saleRefunded": { - "type": "boolean" + "drm": { + "type": "string" }, - "gatewayRefunded": { - "type": "boolean" + "thumbnail": { + "type": "string" }, - "seats": { - "type": "string", - "enum": [ - "blocked", - "block_failed", - "released", - "release_failed", - "none" - ] + "storyboard": { + "type": "string" } }, "required": [ - "amount", - "refundedItemIds", - "saleRefunded", - "gatewayRefunded", - "seats" + "playback", + "drm" ], "additionalProperties": false } }, "required": [ - "id", - "reference", - "status", - "channel", - "subtotal", - "discountAmount", - "serviceFee", - "iva", - "total", - "currency", - "buyerName", - "buyerEmail", - "buyerPhone", - "buyerDocumentType", - "buyerDocumentNumber", - "organizationId", - "paymentProvider", - "paymentRef", - "confirmedAt", - "createdAt", - "failureReason", - "paymentStatus", - "declineCode" + "playbackId", + "tokens" ], "additionalProperties": false }, - "ReportByEventRow": { + "WaitlistEntryCreate": { "type": "object", "properties": { - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" - }, - "revenue": { - "type": "number" + "city": { + "type": "string", + "minLength": 1, + "maxLength": 60 }, - "ticketsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "name": { + "type": "string", + "minLength": 1, + "maxLength": 80 }, - "salesCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "contact": { + "type": "string", + "minLength": 1, + "maxLength": 120 }, - "available": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "source": { + "type": "string", + "maxLength": 40 } }, "required": [ - "eventId", - "eventName", - "revenue", - "ticketsSold", - "salesCount", - "available" + "city", + "name", + "contact" ], "additionalProperties": false }, - "ReportTimeseriesRow": { + "WaitlistEntryResult": { "type": "object", "properties": { - "bucket": { + "id": { "type": "string" }, - "revenue": { - "type": "number" - }, - "ticketsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "city": { + "type": "string" }, - "salesCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "created": { + "type": "boolean" } }, "required": [ - "bucket", - "revenue", - "ticketsSold", - "salesCount" + "id", + "city", + "created" ], "additionalProperties": false }, - "ReportFinancialsRow": { + "WaitlistEntry": { "type": "object", "properties": { - "eventId": { + "id": { "type": "string" }, - "eventName": { + "city": { "type": "string" }, - "eventDateId": { + "name": { "type": "string" }, - "startsAt": { + "contact": { "type": "string" }, - "past": { - "type": "boolean" + "customerId": { + "type": [ + "string", + "null" + ] }, - "unitsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "source": { + "type": [ + "string", + "null" + ] }, - "gross": { - "type": "number" + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "city", + "name", + "contact", + "customerId", + "source", + "createdAt" + ], + "additionalProperties": false + }, + "LiveAttendance": { + "type": "object", + "properties": { + "eventDateId": { + "type": "string" }, - "platformFee": { - "type": "number" + "eventId": { + "type": "string" }, - "facial": { - "type": "number" + "eventName": { + "type": "string" }, - "paymentFee": { - "type": "number" + "city": { + "type": [ + "string", + "null" + ] }, - "wompiSalesWithoutRate": { + "imageUrl": { + "type": [ + "string", + "null" + ] + }, + "sold": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, - "gmf": { - "type": "number" - }, - "net": { - "type": "number" - }, - "currency": { - "type": "string" - }, - "settlementStatus": { - "anyOf": [ - { - "type": "string", - "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" - ] - }, - { - "type": "null" - } - ] - }, - "settlementId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "validated": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "settlementAmount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] + "validatedPct": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 } }, "required": [ + "eventDateId", "eventId", "eventName", - "eventDateId", - "startsAt", - "past", - "unitsSold", - "gross", - "platformFee", - "facial", - "paymentFee", - "wompiSalesWithoutRate", - "gmf", - "net", - "currency", - "settlementStatus", - "settlementId", - "settlementAmount" + "city", + "imageUrl", + "sold", + "validated", + "validatedPct" ], "additionalProperties": false }, - "Settlement": { + "AccessCloseStatus": { "type": "object", "properties": { - "id": { + "eventDateId": { "type": "string" }, - "reference": { + "eventId": { + "type": "string" + }, + "eventName": { "type": "string" }, + "venueName": { + "type": [ + "string", + "null" + ] + }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" + "pending", + "manual", + "auto" ] }, - "amount": { - "type": "number" - }, - "grossAmount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ] + "closed": { + "type": "boolean" }, - "unitsSold": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - { - "type": "null" - } - ] + "signable": { + "type": "boolean" }, - "currency": { + "signableFromLabel": { "type": "string" }, - "notes": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "rejectionReason": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "event": { - "anyOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "required": [ - "id", - "name" - ], - "additionalProperties": false - }, - { - "type": "null" - } + "closedByName": { + "type": [ + "string", + "null" ] }, - "eventDate": { - "anyOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "startsAt": { - "type": "string" - } - }, - "required": [ - "id", - "startsAt" - ], - "additionalProperties": false - }, - { - "type": "null" - } + "closedAtLabel": { + "type": [ + "string", + "null" ] }, - "hasDocument": { - "type": "boolean" - }, - "paymentProofs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "fileName": { - "type": "string" - } - }, - "required": [ - "fileName" - ], - "additionalProperties": false - } - }, - "allocations": { - "type": "array", - "items": { - "type": "object", - "properties": { - "bankAccountId": { - "type": "string" - }, - "percentage": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "amount": { - "type": "number" - }, - "mode": { - "type": "string", - "enum": [ - "PERCENT", - "AMOUNT" - ] - } - }, - "required": [ - "bankAccountId", - "percentage" - ], - "additionalProperties": false - } - }, - "requestedAt": { + "closedCheckins": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "paidAt": { - "anyOf": [ - { - "type": "string" + "live": { + "type": "object", + "properties": { + "issued": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - { - "type": "null" + "checkins": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 } - ] - }, - "createdAt": { - "type": "string" + }, + "required": [ + "issued", + "checkins" + ], + "additionalProperties": false } }, "required": [ - "id", - "reference", + "eventDateId", + "eventId", + "eventName", + "venueName", "label", "status", - "amount", - "grossAmount", - "unitsSold", - "currency", - "notes", - "rejectionReason", - "event", - "eventDate", - "hasDocument", - "paymentProofs", - "allocations", - "requestedAt", - "paidAt", - "createdAt" + "closed", + "signable", + "signableFromLabel", + "closedByName", + "closedAtLabel", + "closedCheckins", + "live" ], "additionalProperties": false }, - "DiscountType": { - "type": "string", - "enum": [ - "PERCENT", - "FIXED" - ] + "AccessCloseSignRequest": { + "type": "object", + "properties": { + "confirm": { + "type": "boolean", + "const": true + } + }, + "required": [ + "confirm" + ], + "additionalProperties": false }, - "Discount": { + "AccessCloseSigned": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "code": { + "eventDateId": { "type": "string" }, - "type": { - "$ref": "#/components/schemas/DiscountType" - }, - "value": { - "type": "number" - }, "eventId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "type": "string" }, - "active": { - "type": "boolean" + "status": { + "type": "string", + "const": "manual" }, - "maxUses": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - { - "type": "null" - } - ] + "closedAt": { + "type": "string" }, - "uses": { + "checkins": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, - "startsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "endsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "createdAt": { + "closedByName": { "type": "string" } }, "required": [ - "id", - "code", - "type", - "value", + "eventDateId", "eventId", - "active", - "maxUses", - "uses", - "startsAt", - "endsAt", - "createdAt" + "status", + "closedAt", + "checkins", + "closedByName" ], "additionalProperties": false }, - "DiscountCreate": { + "PaymentIntentRow": { "type": "object", "properties": { - "code": { - "type": "string", - "minLength": 1 + "threadId": { + "type": "string" }, - "type": { - "$ref": "#/components/schemas/DiscountType" + "deviceTag": { + "type": "string" }, - "value": { - "type": "number", - "exclusiveMinimum": 0 + "hasAccount": { + "type": "boolean" }, - "eventId": { - "anyOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "null" - } + "customerId": { + "type": [ + "string", + "null" ] }, - "maxUses": { - "anyOf": [ - { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 - }, - { - "type": "null" - } + "personName": { + "type": [ + "string", + "null" ] }, - "startsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } + "personEmail": { + "type": [ + "string", + "null" ] }, - "endsAt": { + "personSource": { "anyOf": [ { "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "enum": [ + "account", + "checkout" + ] }, { "type": "null" } ] + }, + "seats": { + "type": "array", + "items": { + "type": "string" + } + }, + "category": { + "type": [ + "string", + "null" + ] + }, + "eventDateId": { + "type": [ + "string", + "null" + ] + }, + "firstAt": { + "type": "string" + }, + "lastAt": { + "type": "string" + }, + "stage": { + "type": "string", + "enum": [ + "seatmap", + "seats", + "continue", + "checkout", + "payment", + "purchased" + ] + }, + "outcome": { + "type": "string", + "enum": [ + "NO_SALE", + "REJECTED", + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + }, + "reason": { + "type": [ + "string", + "null" + ] + }, + "paymentStatus": { + "type": [ + "string", + "null" + ] + }, + "mapFailed": { + "type": "boolean" + }, + "saleId": { + "type": [ + "string", + "null" + ] + }, + "saleReference": { + "type": [ + "string", + "null" + ] + }, + "saleTotal": { + "type": [ + "number", + "null" + ] } }, "required": [ - "code", - "type", - "value" + "threadId", + "deviceTag", + "hasAccount", + "customerId", + "personName", + "personEmail", + "personSource", + "seats", + "category", + "eventDateId", + "firstAt", + "lastAt", + "stage", + "outcome", + "reason", + "paymentStatus", + "mapFailed", + "saleId", + "saleReference", + "saleTotal" ], "additionalProperties": false }, - "DiscountUpdate": { + "PaymentIntentsPage": { "type": "object", "properties": { - "active": { - "type": "boolean" - }, - "value": { - "type": "number", - "exclusiveMinimum": 0 - }, - "maxUses": { - "anyOf": [ - { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "event": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - { - "type": "null" + "name": { + "type": "string" + }, + "city": { + "type": [ + "string", + "null" + ] } - ] + }, + "required": [ + "id", + "name", + "city" + ], + "additionalProperties": false }, - "startsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "dates": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "startsAt": { + "type": "string" + }, + "timezone": { + "type": "string" + }, + "label": { + "type": [ + "string", + "null" + ] + } }, - { - "type": "null" - } + "required": [ + "id", + "startsAt", + "timezone", + "label" + ], + "additionalProperties": false + } + }, + "selectedDateId": { + "type": [ + "string", + "null" ] }, - "endsAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "funnel": { + "type": "object", + "properties": { + "threads": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - { - "type": "null" + "opened": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "selected": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "continued": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "checkout": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "payment": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "purchased": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "abandoned": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "inferred": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 } + }, + "required": [ + "threads", + "opened", + "selected", + "continued", + "checkout", + "payment", + "purchased", + "abandoned", + "inferred" + ], + "additionalProperties": false + }, + "rows": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentIntentRow" + } + }, + "nextCursor": { + "type": [ + "string", + "null" ] } }, + "required": [ + "event", + "dates", + "selectedDateId", + "funnel", + "rows", + "nextCursor" + ], "additionalProperties": false }, - "Webhook": { + "ProductLessonResourceInput": { "type": "object", "properties": { "id": { - "type": "string" + "description": "Id of a saved resource; absent/null creates a new one.", + "type": [ + "string", + "null" + ] }, - "url": { + "kind": { + "type": "string", + "enum": [ + "FILE", + "LINK" + ] + }, + "label": { "type": "string" }, - "events": { - "type": "array", - "items": { - "type": "string" - } + "url": { + "description": "LINK only: http(s) URL.", + "type": [ + "string", + "null" + ] }, - "active": { - "type": "boolean" + "filePath": { + "description": "FILE only: path in the private product files bucket, under this workspace.", + "type": [ + "string", + "null" + ] }, - "lastDeliveryAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "fileName": { + "type": [ + "string", + "null" ] }, - "lastDeliveryStatus": { + "fileSize": { "anyOf": [ { "type": "integer", @@ -16395,235 +31426,253 @@ "type": "null" } ] - }, - "failureCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "createdAt": { - "type": "string" - }, - "updatedAt": { - "type": "string" } }, "required": [ - "id", - "url", - "events", - "active", - "lastDeliveryAt", - "lastDeliveryStatus", - "failureCount", - "createdAt", - "updatedAt" + "kind", + "label" ], "additionalProperties": false }, - "WebhookUpdate": { + "ProductLessonQuiz": { "type": "object", "properties": { - "url": { - "type": "string", - "format": "uri" - }, - "events": { - "minItems": 1, + "questions": { "type": "array", "items": { - "type": "string", - "enum": [ - "sale.confirmed", - "sale.refunded" - ] + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "prompt": { + "type": "string" + }, + "options": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "text": { + "type": "string" + } + }, + "required": [ + "id", + "text" + ], + "additionalProperties": false + } + }, + "correctOptionId": { + "type": "string" + } + }, + "required": [ + "id", + "prompt", + "options", + "correctOptionId" + ], + "additionalProperties": false } }, - "active": { + "passScore": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Minimum score to pass, 0–100." + }, + "showAnswers": { "type": "boolean" } }, + "required": [ + "questions", + "passScore", + "showAnswers" + ], "additionalProperties": false }, - "WebhookCreated": { + "ProductLessonInput": { "type": "object", "properties": { "id": { - "type": "string" + "description": "Id of a saved lesson; absent/null creates a new one. Keep ids on edit so buyers keep their progress.", + "type": [ + "string", + "null" + ] }, - "url": { + "title": { "type": "string" }, - "events": { - "type": "array", - "items": { - "type": "string" - } + "description": { + "type": [ + "string", + "null" + ] }, - "active": { + "isLive": { "type": "boolean" }, - "lastDeliveryAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "content": { + "type": "string", + "enum": [ + "VIDEO", + "FILE", + "TEXT", + "QUIZ" ] }, - "lastDeliveryStatus": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - { - "type": "null" - } + "body": { + "description": "Markdown; TEXT lessons only.", + "type": [ + "string", + "null" ] }, - "failureCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "thumbnailUrl": { + "type": [ + "string", + "null" + ] }, - "createdAt": { - "type": "string" + "videoId": { + "description": "Course video id; VIDEO lessons only. Uploading a video is not available through the API.", + "type": [ + "string", + "null" + ] }, - "updatedAt": { - "type": "string" + "fileName": { + "type": [ + "string", + "null" + ] }, - "signingSecret": { - "type": "string" - } - }, - "required": [ - "id", - "url", - "events", - "active", - "lastDeliveryAt", - "lastDeliveryStatus", - "failureCount", - "createdAt", - "updatedAt", - "signingSecret" - ], - "additionalProperties": false - }, - "WebhookCreate": { - "type": "object", - "properties": { - "url": { - "type": "string", - "format": "uri" + "filePath": { + "type": [ + "string", + "null" + ] }, - "events": { - "minItems": 1, + "resources": { + "description": "Absent keeps the saved resources; [] removes them all.", "type": "array", "items": { - "type": "string", - "enum": [ - "sale.confirmed", - "sale.refunded" - ] - }, - "description": "Subset of: sale.confirmed, sale.refunded" + "$ref": "#/components/schemas/ProductLessonResourceInput" + } }, - "secret": { - "type": "string", - "minLength": 1 + "isPreview": { + "description": "Free preview on the public page (VIDEO/TEXT only, max one per module). Absent keeps the saved value.", + "type": "boolean" + }, + "quiz": { + "description": "QUIZ lessons only.", + "anyOf": [ + { + "$ref": "#/components/schemas/ProductLessonQuiz" + }, + { + "type": "null" + } + ] } }, "required": [ - "url", - "events" + "title", + "isLive", + "content" ], "additionalProperties": false }, - "Subscriber": { + "ProductModuleInput": { "type": "object", "properties": { "id": { - "type": "string" - }, - "customerName": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "description": "Id of a saved module; absent/null creates a new one.", + "type": [ + "string", + "null" ] }, - "customerEmail": { + "title": { "type": "string" }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" + "description": { + "type": [ + "string", + "null" ] }, - "startedAt": { + "unlockAfterDays": { + "description": "Drip by days after purchase (unlockMode DAYS).", "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "currentPeriodEnd": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "unlockAt": { + "description": "Drip by date, ISO 8601 with offset (unlockMode DATE).", + "type": [ + "string", + "null" ] + }, + "lessons": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductLessonInput" + } } }, "required": [ - "id", - "customerName", - "customerEmail", - "status", - "startedAt", - "currentPeriodEnd" + "title", + "lessons" ], "additionalProperties": false }, - "SubscriptionCancelResult": { + "ProductCourseMeta": { "type": "object", "properties": { - "id": { - "type": "string" + "learn": { + "description": "\"What you will learn\": empty, or 3 to 8 items.", + "type": "array", + "items": { + "type": "string" + } }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" + "audience": { + "type": [ + "string", + "null" ] }, - "cancelledAt": { + "requirements": { + "type": [ + "string", + "null" + ] + }, + "level": { "anyOf": [ { - "type": "string" + "type": "string", + "enum": [ + "BEGINNER", + "INTERMEDIATE", + "ADVANCED" + ] }, { "type": "null" @@ -16631,922 +31680,1687 @@ ] } }, - "required": [ - "id", - "status", - "cancelledAt" - ], "additionalProperties": false }, - "SaleTicket": { + "ProductCreate": { "type": "object", "properties": { - "id": { - "type": "string" + "type": { + "type": "string", + "enum": [ + "DOWNLOADABLE", + "COURSE" + ] }, - "ticketCode": { + "name": { "type": "string" }, - "ticketTypeId": { + "description": { + "default": "", "type": "string" }, - "ticketTypeName": { - "type": "string" + "coverImageUrl": { + "default": null, + "type": [ + "string", + "null" + ] }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "price": { + "type": "number", + "description": "COP: integer. USD: up to 2 decimals." }, - "seatLabel": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "currency": { + "default": "COP", + "type": "string", + "enum": [ + "COP", + "USD" ] }, - "checkedInAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "access": { + "default": "PUBLIC", + "type": "string", + "enum": [ + "PUBLIC", + "SUBSCRIBERS" ] }, - "refundedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "includedInMembership": { + "default": false, + "type": "boolean", + "description": "Members of the workspace get it at no cost." + }, + "fileName": { + "default": null, + "type": [ + "string", + "null" ] }, - "refundAmount": { + "filePath": { + "default": null, + "description": "DOWNLOADABLE only (required there): path in the private product files bucket, under this workspace. Uploading files is not available through the API.", + "type": [ + "string", + "null" + ] + }, + "sampleName": { + "default": null, + "type": [ + "string", + "null" + ] + }, + "samplePath": { + "default": null, + "type": [ + "string", + "null" + ] + }, + "modules": { + "default": [], + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductModuleInput" + }, + "description": "COURSE only (at least one module with one lesson)." + }, + "courseMeta": { + "description": "COURSE only. Absent keeps the saved one; null clears it.", "anyOf": [ { - "type": "number" + "$ref": "#/components/schemas/ProductCourseMeta" }, { "type": "null" } ] }, - "seatBlocked": { + "unlockMode": { + "description": "COURSE drip rule. Absent keeps the saved one (OPEN on create).", + "type": "string", + "enum": [ + "OPEN", + "SEQUENTIAL", + "DAYS", + "DATE" + ] + }, + "publish": { + "default": false, + "description": "true creates it PUBLISHED; default DRAFT.", "type": "boolean" } }, "required": [ - "id", - "ticketCode", - "ticketTypeId", - "ticketTypeName", - "quantity", - "seatLabel", - "checkedInAt", - "refundedAt", - "refundAmount", - "seatBlocked" + "type", + "name", + "description", + "coverImageUrl", + "price", + "currency", + "access", + "includedInMembership", + "fileName", + "filePath", + "sampleName", + "samplePath", + "modules", + "publish" ], "additionalProperties": false }, - "PaymentAttempt": { + "ProductUpdate": { "type": "object", "properties": { - "id": { + "type": { + "type": "string", + "enum": [ + "DOWNLOADABLE", + "COURSE" + ] + }, + "name": { "type": "string" }, - "provider": { + "description": { "type": "string" }, - "status": { + "coverImageUrl": { + "type": [ + "string", + "null" + ] + }, + "price": { + "type": "number", + "description": "COP: integer. USD: up to 2 decimals." + }, + "currency": { "type": "string", - "description": "Status of the payment event. Usually this is the gateway's RAW status in its own vocabulary (PAID, APPROVED, REJECTED, VOID_APPROVED…). Values prefixed with `FT_` come from FreeTicket, not the gateway: currently `FT_SALE_APPROVED_POST_CONFIRM`, which flags that the gateway re-notified a payment that was already confirmed — this is how Bold reports its refunds, and the sale may remain CONFIRMED while someone verifies the refunded amount." + "enum": [ + "COP", + "USD" + ] }, - "declineCode": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "access": { + "type": "string", + "enum": [ + "PUBLIC", + "SUBSCRIBERS" ] }, - "declineReason": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "includedInMembership": { + "type": "boolean", + "description": "Members of the workspace get it at no cost." + }, + "fileName": { + "type": [ + "string", + "null" ] }, - "amount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } + "filePath": { + "description": "DOWNLOADABLE only (required there): path in the private product files bucket, under this workspace. Uploading files is not available through the API.", + "type": [ + "string", + "null" ] }, - "externalRef": { + "sampleName": { + "type": [ + "string", + "null" + ] + }, + "samplePath": { + "type": [ + "string", + "null" + ] + }, + "modules": { + "description": "Omit to leave the course tree untouched. When sent, it replaces the WHOLE tree: modules, lessons and resources missing from the list are deleted, along with buyers' progress on those lessons. Fetch a fresh GET right before and send its tree back with your changes. Required when changing `type` or `unlockMode`.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductModuleInput" + } + }, + "courseMeta": { + "description": "COURSE only. Absent keeps the saved one; null clears it.", "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/ProductCourseMeta" }, { "type": "null" } ] }, - "createdAt": { - "type": "string" + "unlockMode": { + "description": "COURSE drip rule. Absent keeps the saved one (OPEN on create).", + "type": "string", + "enum": [ + "OPEN", + "SEQUENTIAL", + "DAYS", + "DATE" + ] + } + }, + "additionalProperties": false + }, + "ProductStatusUpdate": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED" + ] } }, "required": [ - "id", - "provider", - "status", - "declineCode", - "declineReason", - "amount", - "externalRef", - "createdAt" + "status" ], "additionalProperties": false }, - "TicketReassign": { + "Product": { "type": "object", "properties": { - "eventDateId": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "type": { "type": "string", - "minLength": 1 + "enum": [ + "DOWNLOADABLE", + "COURSE" + ] }, - "ticketTypeId": { + "status": { "type": "string", - "minLength": 1 + "enum": [ + "DRAFT", + "PUBLISHED" + ] }, - "seatLabel": { + "price": { + "type": "number" + }, + "currency": { "type": "string", - "minLength": 1 + "enum": [ + "COP", + "USD" + ] + }, + "coverImageUrl": { + "type": [ + "string", + "null" + ] + }, + "salesCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "CONFIRMED purchases." + }, + "revenue": { + "type": "number", + "description": "Sum of CONFIRMED purchase amounts." + }, + "includedInMembership": { + "type": "boolean" } }, + "required": [ + "id", + "name", + "type", + "status", + "price", + "currency", + "coverImageUrl", + "salesCount", + "revenue", + "includedInMembership" + ], "additionalProperties": false }, - "ResendTicket": { + "ProductLesson": { "type": "object", "properties": { - "ticketCode": { + "id": { "type": "string" }, - "sentTo": { - "type": "string" + "title": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "isLive": { + "type": "boolean" + }, + "content": { + "type": "string", + "enum": [ + "VIDEO", + "FILE", + "TEXT", + "QUIZ" + ] + }, + "body": { + "description": "Markdown; TEXT lessons only.", + "type": [ + "string", + "null" + ] + }, + "thumbnailUrl": { + "type": [ + "string", + "null" + ] + }, + "videoId": { + "description": "Course video id; VIDEO lessons only. Uploading a video is not available through the API.", + "type": [ + "string", + "null" + ] }, - "sentAt": { - "type": "string" - } - }, - "required": [ - "ticketCode", - "sentTo", - "sentAt" - ], - "additionalProperties": false - }, - "CheckinResult": { - "type": "object", - "properties": { - "ticketCode": { - "type": "string" + "fileName": { + "type": [ + "string", + "null" + ] }, - "checkedInAt": { + "filePath": { + "type": [ + "string", + "null" + ] + }, + "resources": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductLessonResourceInput" + } + }, + "isPreview": { + "type": "boolean" + }, + "quiz": { + "description": "Only for ADMIN keys (it includes the correct answers).", "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/ProductLessonQuiz" }, { "type": "null" } ] }, - "checkedInBy": { + "videoStatus": { "anyOf": [ { - "type": "string" + "type": "string", + "enum": [ + "DRAFT", + "PROCESSING", + "READY", + "ERROR" + ] }, { "type": "null" } ] }, - "alreadyCheckedIn": { - "type": "boolean" + "durationSeconds": { + "type": [ + "number", + "null" + ] } }, "required": [ - "ticketCode", - "checkedInAt", - "checkedInBy", - "alreadyCheckedIn" + "id", + "title", + "isLive", + "content", + "resources", + "isPreview", + "videoStatus", + "durationSeconds" ], "additionalProperties": false }, - "CheckinRequest": { + "ProductModule": { "type": "object", "properties": { - "source": { + "id": { + "type": "string" + }, + "title": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "unlockAfterDays": { + "description": "Drip by days after purchase (unlockMode DAYS).", "anyOf": [ { - "type": "string", - "enum": [ - "pdf", - "web", - "apple", - "google" - ] + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] + }, + "unlockAt": { + "description": "Drip by date, ISO 8601 with offset (unlockMode DATE).", + "type": [ + "string", + "null" + ] + }, + "lessons": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductLesson" + } } }, + "required": [ + "id", + "title", + "lessons" + ], "additionalProperties": false }, - "TicketAccess": { + "ProductDetail": { "type": "object", "properties": { - "ticketCode": { + "id": { "type": "string" }, - "valid": { - "type": "boolean" + "name": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "DOWNLOADABLE", + "COURSE" + ] }, "status": { "type": "string", "enum": [ - "VALID", - "USED", - "INVALID" + "DRAFT", + "PUBLISHED" ] }, - "saleStatus": { + "price": { + "type": "number" + }, + "currency": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" + "COP", + "USD" ] }, - "eventId": { - "type": "string" + "coverImageUrl": { + "type": [ + "string", + "null" + ] }, - "eventName": { - "type": "string" + "salesCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "CONFIRMED purchases." }, - "eventDateId": { - "type": "string" + "revenue": { + "type": "number", + "description": "Sum of CONFIRMED purchase amounts." }, - "startsAt": { - "type": "string" + "includedInMembership": { + "type": "boolean" }, - "ticketTypeName": { + "description": { "type": "string" }, - "checkedInAt": { + "access": { + "type": "string", + "enum": [ + "PUBLIC", + "SUBSCRIBERS" + ] + }, + "fileName": { + "type": [ + "string", + "null" + ] + }, + "filePath": { + "type": [ + "string", + "null" + ] + }, + "sampleName": { + "type": [ + "string", + "null" + ] + }, + "samplePath": { + "type": [ + "string", + "null" + ] + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductModule" + } + }, + "courseMeta": { "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/ProductCourseMeta" }, { "type": "null" } ] + }, + "unlockMode": { + "type": "string", + "enum": [ + "OPEN", + "SEQUENTIAL", + "DAYS", + "DATE" + ] } }, "required": [ - "ticketCode", - "valid", + "id", + "name", + "type", "status", - "saleStatus", - "eventId", - "eventName", - "eventDateId", - "startsAt", - "ticketTypeName", - "checkedInAt" + "price", + "currency", + "coverImageUrl", + "salesCount", + "revenue", + "includedInMembership", + "description", + "access", + "fileName", + "filePath", + "sampleName", + "samplePath", + "modules", + "courseMeta", + "unlockMode" ], "additionalProperties": false }, - "ApiKeyScope": { - "type": "string", - "enum": [ - "read", - "write" - ] - }, - "ApiKey": { + "Website": { "type": "object", "properties": { - "id": { - "type": "string" + "slug": { + "type": "string", + "description": "Public slug (organization subdomain)." }, "name": { "type": "string" }, - "scope": { - "$ref": "#/components/schemas/ApiKeyScope" + "tagline": { + "type": [ + "string", + "null" + ] }, - "keyPrefix": { - "type": "string" + "bio": { + "type": [ + "string", + "null" + ] }, - "lastUsedAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } + "accentColor": { + "type": [ + "string", + "null" ] }, - "expiresAt": { - "anyOf": [ - { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - }, - { - "type": "null" - } + "webTemplate": { + "type": [ + "string", + "null" ] }, - "revokedAt": { + "webSections": { "anyOf": [ { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + } }, { "type": "null" } + ], + "description": "Per-section visibility booleans plus the reserved `order` key (array of section ids)." + }, + "instagramUrl": { + "type": [ + "string", + "null" ] }, - "createdAt": { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "tiktokUrl": { + "type": [ + "string", + "null" + ] + }, + "youtubeUrl": { + "type": [ + "string", + "null" + ] + }, + "customLandingEnabled": { + "type": "boolean", + "description": "The plan includes the custom landing (`PUT /website` answers 403 FEATURE_LOCKED otherwise)." + }, + "published": { + "type": "boolean", + "description": "Listed publicly (/artistas)." + }, + "canPublish": { + "type": "boolean", + "description": "Only the organization's primary workspace can publish/unpublish." + }, + "profileListable": { + "type": "boolean", + "description": "The brand has the name and photo required to publish." } }, "required": [ - "id", + "slug", "name", - "scope", - "keyPrefix", - "lastUsedAt", - "expiresAt", - "revokedAt", - "createdAt" + "tagline", + "bio", + "accentColor", + "webTemplate", + "webSections", + "instagramUrl", + "tiktokUrl", + "youtubeUrl", + "customLandingEnabled", + "published", + "canPublish", + "profileListable" ], "additionalProperties": false }, - "ApiKeyCreated": { + "WebsiteUpdate": { "type": "object", "properties": { - "id": { - "type": "string" - }, "name": { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 100 }, - "scope": { - "$ref": "#/components/schemas/ApiKeyScope" + "tagline": { + "anyOf": [ + { + "type": "string", + "maxLength": 200 + }, + { + "type": "null" + } + ] }, - "keyPrefix": { - "type": "string" + "bio": { + "anyOf": [ + { + "type": "string", + "maxLength": 5000 + }, + { + "type": "null" + } + ] }, - "lastUsedAt": { + "instagramUrl": { "anyOf": [ { "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "maxLength": 500 }, { "type": "null" } ] }, - "expiresAt": { + "tiktokUrl": { "anyOf": [ { "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "maxLength": 500 }, { "type": "null" } ] }, - "revokedAt": { + "youtubeUrl": { "anyOf": [ { "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "maxLength": 500 }, { "type": "null" } ] }, - "createdAt": { + "accentColor": { "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "pattern": "^#[0-9a-fA-F]{6}$", + "description": "#RRGGBB." }, - "key": { - "type": "string" - } - }, - "required": [ - "id", - "name", - "scope", - "keyPrefix", - "lastUsedAt", - "expiresAt", - "revokedAt", - "createdAt", - "key" - ], - "additionalProperties": false - }, - "ApiKeyCreate": { - "type": "object", - "properties": { - "name": { + "webTemplate": { "type": "string", "minLength": 1, - "maxLength": 120 - }, - "scope": { - "default": "read", - "$ref": "#/components/schemas/ApiKeyScope" + "maxLength": 32 }, - "expiresAt": { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" + "webSections": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "description": "Visibility booleans for the known sections (shows, productos, posts, membresias, contenido, bio, redes) and `order` (array of section ids). Unknown keys are dropped." } }, "required": [ "name", - "scope" + "tagline", + "bio", + "instagramUrl", + "tiktokUrl", + "youtubeUrl", + "accentColor", + "webTemplate", + "webSections" ], "additionalProperties": false }, - "CustomerAuthRequest": { + "WebsitePublished": { "type": "object", "properties": { - "email": { - "type": "string", - "format": "email", - "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + "published": { + "type": "boolean" } }, "required": [ - "email" + "published" ], "additionalProperties": false }, - "CustomerAuthRequestResult": { + "OrganizationProfile": { "type": "object", "properties": { - "status": { + "id": { "type": "string", - "const": "sent" + "description": "Workspace id." }, - "sent_to": { + "name": { "type": "string", - "description": "Masked email (`c***@mail.com`). Never the full address." + "description": "Workspace name." }, - "expires_in": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Code lifetime, in seconds." - } - }, - "required": [ - "status", - "sent_to", - "expires_in" - ], - "additionalProperties": false - }, - "CustomerAuthVerify": { - "type": "object", - "properties": { - "email": { + "brandName": { "type": "string", - "format": "email", - "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + "description": "Public brand name (from the umbrella organization)." }, - "code": { - "type": "string", - "minLength": 6, - "maxLength": 6 - } - }, - "required": [ - "email", - "code" - ], - "additionalProperties": false - }, - "CustomerAuthVerifyResult": { - "type": "object", - "properties": { - "session_token": { + "slug": { + "type": "string" + }, + "bio": { + "type": [ + "string", + "null" + ] + }, + "type": { "type": "string", - "description": "Usable as-is as the `X-Customer-Session` header on /api/v1/customer/*." + "enum": [ + "ARTIST", + "VENUE", + "ORGANIZER" + ] }, - "expires_in": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Session lifetime, in seconds." - } - }, - "required": [ - "session_token", - "expires_in" - ], - "additionalProperties": false - }, - "CustomerMe": { - "type": "object", - "properties": { - "id": { + "country": { "type": "string" }, - "email": { + "timezone": { "type": "string" }, - "name": { - "type": "string" + "logoUrl": { + "type": [ + "string", + "null" + ] }, - "emailVerified": { - "type": "boolean" + "coverUrl": { + "type": [ + "string", + "null" + ] }, - "expiresAt": { - "type": "string", - "description": "Buyer session expiry (ISO 8601)." - } - }, - "required": [ - "id", - "email", - "name", - "emailVerified", - "expiresAt" - ], - "additionalProperties": false - }, - "CustomerTicketCancelResult": { - "type": "object", - "properties": { - "id": { - "type": "string" + "email": { + "type": [ + "string", + "null" + ] }, - "reference": { - "type": "string" + "phone": { + "type": [ + "string", + "null" + ] }, - "status": { - "type": "string" + "website": { + "type": [ + "string", + "null" + ] + }, + "instagramUrl": { + "type": [ + "string", + "null" + ] + }, + "facebookUrl": { + "type": [ + "string", + "null" + ] + }, + "twitterUrl": { + "type": [ + "string", + "null" + ] + }, + "spotifyUrl": { + "type": [ + "string", + "null" + ] + }, + "youtubeUrl": { + "type": [ + "string", + "null" + ] + }, + "tiktokUrl": { + "type": [ + "string", + "null" + ] } }, "required": [ "id", - "reference", - "status" - ], - "additionalProperties": false - }, - "CustomerLogout": { - "type": "object", - "properties": { - "revoked": { - "type": "boolean", - "description": "true if the session existed and was deleted; false if the token was no longer valid (it ends up closed either way)." - } - }, - "required": [ - "revoked" - ], - "additionalProperties": false - }, - "EnterpriseExchangeRequest": { - "type": "object", - "properties": { - "token": { - "type": "string", - "minLength": 1, - "maxLength": 256, - "description": "One-time token received on the landing page callback (format `{slug}.{token}`, forwarded as is)." - } - }, - "required": [ - "token" + "name", + "brandName", + "slug", + "bio", + "type", + "country", + "timezone", + "logoUrl", + "coverUrl", + "email", + "phone", + "website", + "instagramUrl", + "facebookUrl", + "twitterUrl", + "spotifyUrl", + "youtubeUrl", + "tiktokUrl" ], "additionalProperties": false }, - "EnterpriseExchangeResponse": { + "OrganizationProfileUpdate": { "type": "object", "properties": { - "session_token": { - "type": "string", - "description": "Buyer session token. Send it as the `X-Customer-Session` header on /api/v1/customer/*." - }, - "expires_at": { - "type": "string", - "description": "Session expiry (ISO 8601, 7-day sliding window)." + "artist": { + "description": "Same fields as the dashboard's Artist card.", + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "slug": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "pattern": "^[a-z0-9-]+$" + }, + "bio": { + "anyOf": [ + { + "type": "string", + "maxLength": 5000 + }, + { + "type": "null" + } + ] + }, + "type": { + "type": "string", + "enum": [ + "ARTIST", + "VENUE", + "ORGANIZER" + ] + }, + "country": { + "description": "ISO 3166-1 alpha-2.", + "type": "string", + "minLength": 2, + "maxLength": 2 + }, + "timezone": { + "description": "IANA time zone.", + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false }, - "customer": { + "visual": { + "description": "Brand profile photo and cover (stored on the umbrella organization).", "type": "object", "properties": { - "id": { - "type": "string" + "logoUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] }, + "coverUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "contact": { + "type": "object", + "properties": { "email": { - "type": "string" + "anyOf": [ + { + "type": "string", + "maxLength": 200, + "format": "email", + "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" + }, + { + "type": "null" + } + ] }, - "name": { - "type": "string" + "phone": { + "anyOf": [ + { + "type": "string", + "maxLength": 40 + }, + { + "type": "null" + } + ] }, - "email_verified": { - "type": "boolean" + "website": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] } }, - "required": [ - "id", - "email", - "name", - "email_verified" - ], "additionalProperties": false - } - }, - "required": [ - "session_token", - "expires_at", - "customer" - ], - "additionalProperties": false - }, - "CustomerMembershipState": { - "type": "object", - "properties": { - "active": { - "type": "boolean", - "description": "true only with an ACTIVE, unexpired membership in this workspace." }, - "membership": { - "anyOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string" + "social": { + "type": "object", + "properties": { + "instagramUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" }, - "status": { + { + "type": "null" + } + ] + }, + "facebookUrl": { + "anyOf": [ + { "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] + "maxLength": 500, + "format": "uri" }, - "plan": { - "$ref": "#/components/schemas/MembershipPlan" + { + "type": "null" + } + ] + }, + "twitterUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" }, - "startedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + { + "type": "null" + } + ] + }, + "spotifyUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" }, - "expiresAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "null = LIFETIME or a membership with no expiry." + { + "type": "null" + } + ] + }, + "youtubeUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" }, - "autoRenew": { - "type": "boolean" + { + "type": "null" } - }, - "required": [ - "id", - "status", - "plan", - "startedAt", - "expiresAt", - "autoRenew" - ], - "additionalProperties": false + ] }, - { - "type": "null" + "tiktokUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] } - ] - } - }, - "required": [ - "active", - "membership" - ], - "additionalProperties": false - }, - "CustomerSubscribeRequest": { - "type": "object", - "properties": { - "planId": { - "type": "string", - "minLength": 1, - "description": "Id of an active MembershipPlan in the key's workspace." + }, + "additionalProperties": false } }, - "required": [ - "planId" - ], "additionalProperties": false }, - "CustomerSubscribeResult": { + "Organization": { "type": "object", "properties": { - "checkoutUrl": { + "id": { "type": "string", - "description": "Membership checkout URL on the canonical host. The landing page must redirect the buyer there." + "description": "Umbrella organization id." }, - "planId": { + "name": { "type": "string" + }, + "slug": { + "type": "string" + }, + "logoUrl": { + "type": [ + "string", + "null" + ] + }, + "coverUrl": { + "type": [ + "string", + "null" + ] + }, + "ga4MeasurementId": { + "type": [ + "string", + "null" + ] } }, "required": [ - "checkoutUrl", - "planId" + "id", + "name", + "slug", + "logoUrl", + "coverUrl", + "ga4MeasurementId" ], "additionalProperties": false }, - "CustomerSubscriptionCancelResult": { + "OrganizationUpdate": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "status": { + "name": { "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" + "minLength": 2, + "maxLength": 80 + }, + "logoUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } ] }, - "cancelledAt": { + "coverUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, + "OrganizationAnalyticsUpdate": { + "type": "object", + "properties": { + "ga4MeasurementId": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 32 }, { "type": "null" } - ] + ], + "description": "GA4 Measurement ID (G-XXXXXXXXXX); null disconnects it." } }, "required": [ - "id", - "status", - "cancelledAt" + "ga4MeasurementId" ], "additionalProperties": false }, - "CustomerSubscriptionCancelRequest": { + "OrganizationAnalytics": { "type": "object", "properties": { - "workspaceId": { - "description": "Required only without an enterprise service API key: which membership (by workspace) to cancel. Ignored with a key — the workspace is the one pinned to it.", - "type": "string", - "minLength": 1 + "id": { + "type": "string" + }, + "ga4MeasurementId": { + "type": [ + "string", + "null" + ] } }, + "required": [ + "id", + "ga4MeasurementId" + ], "additionalProperties": false }, - "CustomerProfile": { + "TicketTemplateCreate": { "type": "object", "properties": { - "id": { - "type": "string" + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 }, - "email": { - "type": "string" + "description": { + "anyOf": [ + { + "type": "string", + "maxLength": 500 + }, + { + "type": "null" + } + ] }, - "name": { - "type": "string" + "price": { + "type": "number", + "minimum": 0 }, - "phone": { + "currency": { + "default": "COP", + "type": "string", + "minLength": 3, + "maxLength": 3 + }, + "capacity": { "anyOf": [ { - "type": "string" + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "maxPerOrder": { + "default": 10, + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "accentColor": { + "type": [ + "string", + "null" + ] + }, + "includes": { + "anyOf": [ + { + "type": "string", + "maxLength": 500 + }, + { + "type": "null" + } + ] + }, + "instructions": { + "anyOf": [ + { + "type": "string", + "maxLength": 2000 }, { "type": "null" } ] + }, + "organizerAbsorbsFee": { + "default": false, + "type": "boolean" + }, + "discount": { + "anyOf": [ + { + "type": "object", + "properties": { + "planId": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "Active membership plan of this workspace." + }, + "percent": { + "type": "integer", + "minimum": 1, + "maximum": 100 + } + }, + "required": [ + "planId", + "percent" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ], + "description": "Member discount; null = none." + }, + "membersOnlyPlanId": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 50 + }, + { + "type": "null" + } + ], + "description": "Members-only gate plan; null = open to everyone." + }, + "isActive": { + "default": true, + "type": "boolean" + }, + "sortOrder": { + "default": 0, + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "fields": { + "default": [], + "maxItems": 15, + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "fieldType": { + "type": "string", + "enum": [ + "TEXT", + "NUMBER", + "SELECT", + "EMAIL", + "PHONE" + ] + }, + "options": { + "maxItems": 20, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "isRequired": { + "default": false, + "type": "boolean" + } + }, + "required": [ + "label", + "fieldType", + "isRequired" + ], + "additionalProperties": false + }, + "description": "Buyer form fields; the list is replaced as a whole." } }, "required": [ - "id", - "email", "name", - "phone" + "price", + "currency", + "maxPerOrder", + "organizerAbsorbsFee", + "isActive", + "sortOrder", + "fields" ], "additionalProperties": false }, - "CustomerProfileUpdate": { + "TicketTemplateUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, - "maxLength": 120 + "maxLength": 100 }, - "phone": { - "description": "null or an empty string clears the phone.", + "description": { "anyOf": [ { "type": "string", - "maxLength": 30 + "maxLength": 500 + }, + { + "type": "null" + } + ] + }, + "price": { + "type": "number", + "minimum": 0 + }, + "currency": { + "type": "string", + "minLength": 3, + "maxLength": 3 + }, + "capacity": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "maxPerOrder": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "accentColor": { + "type": [ + "string", + "null" + ] + }, + "includes": { + "anyOf": [ + { + "type": "string", + "maxLength": 500 + }, + { + "type": "null" + } + ] + }, + "instructions": { + "anyOf": [ + { + "type": "string", + "maxLength": 2000 + }, + { + "type": "null" + } + ] + }, + "organizerAbsorbsFee": { + "type": "boolean" + }, + "discount": { + "anyOf": [ + { + "type": "object", + "properties": { + "planId": { + "type": "string", + "minLength": 1, + "maxLength": 50, + "description": "Active membership plan of this workspace." + }, + "percent": { + "type": "integer", + "minimum": 1, + "maximum": 100 + } + }, + "required": [ + "planId", + "percent" + ], + "additionalProperties": false + }, + { + "type": "null" + } + ], + "description": "Member discount; null = none." + }, + "membersOnlyPlanId": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 50 + }, + { + "type": "null" + } + ], + "description": "Members-only gate plan; null = open to everyone." + }, + "isActive": { + "type": "boolean" + }, + "sortOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "fields": { + "maxItems": 15, + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "fieldType": { + "type": "string", + "enum": [ + "TEXT", + "NUMBER", + "SELECT", + "EMAIL", + "PHONE" + ] + }, + "options": { + "maxItems": 20, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 100 + } + }, + "isRequired": { + "default": false, + "type": "boolean" + } }, - { - "type": "null" - } - ] + "required": [ + "label", + "fieldType", + "isRequired" + ], + "additionalProperties": false + }, + "description": "Buyer form fields; the list is replaced as a whole." } }, "additionalProperties": false }, - "ContentVideo": { + "TicketTemplate": { "type": "object", "properties": { "id": { "type": "string" }, - "title": { + "name": { "type": "string" }, "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "type": [ + "string", + "null" ] }, - "durationSeconds": { + "price": { + "type": "number" + }, + "currency": { + "type": "string" + }, + "capacity": { "anyOf": [ { "type": "integer", @@ -17558,31 +33372,56 @@ } ] }, - "posterUrl": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "maxPerOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "accentColor": { + "type": [ + "string", + "null" ] }, - "series": { + "includes": { + "type": [ + "string", + "null" + ] + }, + "instructions": { + "type": [ + "string", + "null" + ] + }, + "organizerAbsorbsFee": { + "type": "boolean" + }, + "discount": { "anyOf": [ { "type": "object", "properties": { - "id": { + "planId": { "type": "string" }, - "title": { - "type": "string" + "percent": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] } }, "required": [ - "id", - "title" + "planId", + "percent" ], "additionalProperties": false }, @@ -17591,539 +33430,1131 @@ } ] }, - "memberOnly": { - "type": "boolean", - "description": "true = only current members of the organization can play it." + "membersOnlyPlanId": { + "type": [ + "string", + "null" + ] }, - "publishedAt": { - "anyOf": [ - { - "type": "string" + "isActive": { + "type": "boolean" + }, + "fields": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "label": { + "type": "string" + }, + "fieldType": { + "type": "string", + "enum": [ + "TEXT", + "NUMBER", + "SELECT", + "EMAIL", + "PHONE" + ] + }, + "options": { + "anyOf": [ + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "null" + } + ] + }, + "isRequired": { + "type": "boolean" + }, + "sortOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } }, - { - "type": "null" - } - ] + "required": [ + "id", + "label", + "fieldType", + "options", + "isRequired", + "sortOrder" + ], + "additionalProperties": false + } } }, "required": [ "id", - "title", + "name", "description", - "durationSeconds", - "posterUrl", - "series", - "memberOnly", - "publishedAt" + "price", + "currency", + "capacity", + "maxPerOrder", + "accentColor", + "includes", + "instructions", + "organizerAbsorbsFee", + "discount", + "membersOnlyPlanId", + "isActive", + "fields" ], "additionalProperties": false }, - "ContentPost": { + "TicketTemplateInstantiate": { + "type": "object", + "properties": { + "eventDateId": { + "type": "string", + "minLength": 1, + "description": "Event date of this workspace." + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "price": { + "type": "number", + "minimum": 0 + }, + "capacity": { + "description": "Required when the template has no capacity.", + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + } + }, + "required": [ + "eventDateId" + ], + "additionalProperties": false + }, + "TicketTemplateInstance": { + "type": "object", + "properties": { + "ticketTypeId": { + "type": "string" + }, + "eventId": { + "type": "string" + }, + "eventDateId": { + "type": "string" + } + }, + "required": [ + "ticketTypeId", + "eventId", + "eventDateId" + ], + "additionalProperties": false + }, + "MasterQr": { "type": "object", "properties": { "id": { "type": "string" }, - "type": { + "label": { + "type": "string" + }, + "mode": { "type": "string", "enum": [ - "TEXT", - "IMAGE", - "VIDEO", - "ARTICLE" + "EVENT", + "TODAY" + ], + "description": "EVENT: opens the event page (or the tenant listings when org-wide). TODAY: jumps to today's show." + }, + "eventId": { + "description": "null = org-wide QR (all shows of the workspace).", + "type": [ + "string", + "null" ] }, - "content": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "ticketTypeId": { + "type": [ + "string", + "null" ] }, - "imageUrl": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "ARTICLE post: also serves as the article's cover image." + "active": { + "type": "boolean" }, - "videoId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "VIDEO post: id of the ContentVideo, to cross-reference with `GET /content/videos`." + "scans": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "eventId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "lastScanAt": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" + }, + "code": { + "type": "string", + "description": "SECRET: public code printed in the QR; whoever has it reaches the sale flow. It cannot be rotated." + }, + "url": { + "description": "SECRET: the URL encoded in the QR (null if the workspace has no public organization yet).", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "label", + "mode", + "eventId", + "ticketTypeId", + "active", + "scans", + "lastScanAt", + "createdAt", + "code", + "url" + ], + "additionalProperties": false + }, + "MasterQrCreate": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 1, + "maxLength": 80 + }, + "mode": { + "type": "string", + "enum": [ + "EVENT", + "TODAY" ] }, - "locked": { - "type": "boolean", - "description": "true = post restricted to current members; its content arrives redacted." - }, - "title": { + "eventId": { "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 60 }, { "type": "null" } - ], - "description": "ARTICLE posts only; null for every other type." + ] }, - "subtitle": { + "ticketTypeId": { "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 60 }, { "type": "null" } - ], - "description": "ARTICLE posts only." + ] + } + }, + "required": [ + "label", + "mode" + ], + "additionalProperties": false + }, + "MasterQrUpdate": { + "type": "object", + "properties": { + "label": { + "type": "string", + "minLength": 1, + "maxLength": 80 }, - "slug": { + "mode": { + "type": "string", + "enum": [ + "EVENT", + "TODAY" + ] + }, + "eventId": { "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 60 }, { "type": "null" } - ], - "description": "ARTICLE posts only. Permalink at /comunidades/articulos/{slug}, unique per organization." + ] }, - "body": { + "ticketTypeId": { "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 60 }, { "type": "null" } - ], - "description": "ARTICLE posts only. Body in Markdown." + ] + } + }, + "additionalProperties": false + }, + "MasterQrActive": { + "type": "object", + "properties": { + "active": { + "type": "boolean" + } + }, + "required": [ + "active" + ], + "additionalProperties": false + }, + "WorkspaceConfigDeleted": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "readingMinutes": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "deleted": { + "type": "boolean", + "const": true + } + }, + "required": [ + "id", + "deleted" + ], + "additionalProperties": false + }, + "MerchOrderCreate": { + "type": "object", + "properties": { + "buyer": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 120 }, - { - "type": "null" + "phone": { + "type": "string", + "pattern": "^\\+?[0-9 -]{7,20}$" + }, + "documentType": { + "type": "string", + "enum": [ + "CC", + "CE", + "PP", + "NIT", + "TI", + "PEP" + ] + }, + "document": { + "type": "string", + "minLength": 3, + "maxLength": 20 } + }, + "required": [ + "name", + "phone", + "documentType", + "document" ], - "description": "ARTICLE posts only. Not redacted when `locked`: it does not leak content, only its length." + "additionalProperties": false }, - "link": { - "anyOf": [ + "delivery": { + "oneOf": [ { "type": "object", "properties": { - "url": { - "type": "string" + "kind": { + "type": "string", + "const": "SHIPPING" }, - "title": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "departmentCode": { + "type": "string", + "pattern": "^\\d{2}$" }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "department": { + "type": "string", + "minLength": 1, + "maxLength": 80 }, - "imageUrl": { + "cityCode": { + "type": "string", + "pattern": "^\\d{5}$" + }, + "city": { + "type": "string", + "minLength": 1, + "maxLength": 80 + }, + "address": { + "type": "string", + "minLength": 5, + "maxLength": 200 + }, + "addressExtra": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 200 }, { "type": "null" } ] - }, - "domain": { - "type": "string" } }, "required": [ - "url", - "title", - "description", - "imageUrl", - "domain" + "kind", + "departmentCode", + "department", + "cityCode", + "city", + "address" ], "additionalProperties": false }, { - "type": "null" + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "PICKUP" + }, + "pickupPointId": { + "type": "string", + "minLength": 1, + "maxLength": 64 + } + }, + "required": [ + "kind", + "pickupPointId" + ], + "additionalProperties": false + } + ] + }, + "items": { + "minItems": 1, + "maxItems": 20, + "type": "array", + "items": { + "type": "object", + "properties": { + "variantId": { + "type": "string", + "minLength": 1, + "maxLength": 64 + }, + "quantity": { + "type": "integer", + "minimum": 1, + "maximum": 50 + } + }, + "required": [ + "variantId", + "quantity" + ], + "additionalProperties": false + } + } + }, + "required": [ + "buyer", + "delivery", + "items" + ], + "additionalProperties": false + }, + "MerchOrderLookup": { + "type": "object", + "properties": { + "code": { + "type": "string", + "minLength": 3, + "maxLength": 20 + } + }, + "required": [ + "code" + ], + "additionalProperties": false + }, + "MerchCardPayment": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 1, + "description": "Card token returned by the Payment Brick when tokenizing." + }, + "paymentMethodId": { + "type": "string", + "minLength": 1, + "description": "`payment_method_id` returned by the Brick (e.g. `visa`, `debmaster`)." + }, + "installments": { + "default": 1, + "type": "integer", + "minimum": 1, + "maximum": 36 + }, + "payer": { + "type": "object", + "properties": { + "identification": { + "type": "object", + "properties": { + "type": { + "type": "string", + "minLength": 1 + }, + "number": { + "type": "string", + "minLength": 1 + } + }, + "required": [ + "type", + "number" + ], + "additionalProperties": false } + }, + "additionalProperties": false + } + }, + "required": [ + "token", + "paymentMethodId", + "installments" + ], + "additionalProperties": false + }, + "MerchCardPaymentResult": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "approved", + "pending", + "rejected" ], - "description": "Open Graph snapshot of the first link in the text. Always null for ARTICLE posts." + "description": "`pending` is normal (bank authentication): the order is confirmed by webhook, poll the lookup. `rejected` is a business decline: the order stays pending until its reservation expires and the buyer can retry with another card." }, - "commentsCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Visible comments: excludes deleted ones and those hidden by moderation (and replies to a hidden comment). 0 if the post arrives redacted." + "code": { + "type": "string" }, - "publishedAt": { + "message": { + "description": "Human-readable message. Only present with `rejected`.", "type": "string" } }, "required": [ - "id", - "type", - "content", - "imageUrl", - "videoId", - "eventId", - "locked", - "title", - "subtitle", - "slug", - "body", - "readingMinutes", - "link", - "commentsCount", - "publishedAt" + "status", + "code" ], "additionalProperties": false }, - "ContentPostCreate": { + "MerchOrder": { "type": "object", "properties": { - "type": { - "default": "TEXT", + "code": { + "type": "string" + }, + "status": { "type": "string", "enum": [ - "TEXT", - "IMAGE", - "ARTICLE" + "PENDING", + "PAID", + "PREPARING", + "SHIPPED", + "DELIVERED", + "READY_FOR_PICKUP", + "PICKED_UP", + "CANCELLED", + "REFUNDED" ] }, - "content": { + "currency": { "type": "string", - "maxLength": 5000 + "const": "COP" }, - "imageUrl": { - "anyOf": [ - { - "type": "string", - "maxLength": 2048, - "format": "uri" - }, - { - "type": "null" - } + "reservedUntil": { + "type": [ + "string", + "null" ] }, - "title": { - "description": "Required when type=ARTICLE.", - "type": "string", - "minLength": 1, - "maxLength": 140 + "createdAt": { + "type": "string" }, - "subtitle": { - "anyOf": [ - { - "type": "string", - "maxLength": 280 - }, - { - "type": "null" - } + "paidAt": { + "type": [ + "string", + "null" ] }, - "slug": { - "description": "Manual; if omitted it is derived from the title.", - "anyOf": [ - { - "type": "string", - "maxLength": 200 + "buyer": { + "type": "object", + "properties": { + "email": { + "type": "string" }, - { - "type": "null" - } - ] - }, - "body": { - "description": "Markdown. Required when type=ARTICLE.", - "type": "string", - "minLength": 1, - "maxLength": 100000 - }, - "locked": { - "default": false, - "description": "true = restricted to current members.", - "type": "boolean" - }, - "eventId": { - "anyOf": [ - { - "type": "string", - "minLength": 1 + "name": { + "type": "string" }, - { - "type": "null" + "phone": { + "type": "string" } - ] - }, - "publishedAt": { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - } - }, - "required": [ - "type", - "locked" - ], - "additionalProperties": false - }, - "ContentLive": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "title": { - "type": "string" + }, + "required": [ + "email", + "name", + "phone" + ], + "additionalProperties": false }, - "status": { + "fulfillment": { "type": "string", "enum": [ - "IDLE", - "ACTIVE", - "COMPLETED", - "DISABLED" - ], - "description": "ACTIVE = streaming right now (live banner)." - }, - "memberOnly": { - "type": "boolean" + "SHIPPING", + "PICKUP" + ] }, - "startedAt": { + "shipping": { "anyOf": [ { - "type": "string" + "type": "object", + "properties": { + "departmentCode": { + "type": [ + "string", + "null" + ] + }, + "department": { + "type": [ + "string", + "null" + ] + }, + "cityCode": { + "type": [ + "string", + "null" + ] + }, + "city": { + "type": [ + "string", + "null" + ] + }, + "address": { + "type": [ + "string", + "null" + ] + }, + "addressExtra": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "departmentCode", + "department", + "cityCode", + "city", + "address", + "addressExtra" + ], + "additionalProperties": false }, { "type": "null" } ] }, - "endedAt": { + "pickupPoint": { "anyOf": [ { - "type": "string" + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "address": { + "type": "string" + }, + "city": { + "type": [ + "string", + "null" + ] + }, + "schedule": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "name", + "address", + "city", + "schedule" + ], + "additionalProperties": false }, { "type": "null" } ] }, - "hasRecording": { - "type": "boolean", - "description": "true if a playable recording remains after the stream." - } - }, - "required": [ - "id", - "title", - "status", - "memberOnly", - "startedAt", - "endedAt", - "hasRecording" - ], - "additionalProperties": false - }, - "ContentPlaybackTokenRequest": { - "type": "object", - "properties": { - "kind": { - "type": "string", - "enum": [ - "video", - "live" + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "variantId": { + "type": "string" + }, + "productName": { + "type": "string" + }, + "variantLabel": { + "type": "string" + }, + "sku": { + "type": "string" + }, + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "unitPrice": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "variantId", + "productName", + "variantLabel", + "sku", + "quantity", + "unitPrice" + ], + "additionalProperties": false + } + }, + "subtotal": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "shippingFee": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "total": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "tracking": { + "anyOf": [ + { + "type": "object", + "properties": { + "carrier": { + "type": [ + "string", + "null" + ] + }, + "carrierName": { + "type": [ + "string", + "null" + ] + }, + "trackingNumber": { + "type": [ + "string", + "null" + ] + }, + "trackingUrl": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "carrier", + "carrierName", + "trackingNumber", + "trackingUrl" + ], + "additionalProperties": false + }, + { + "type": "null" + } ] }, - "id": { - "type": "string", - "minLength": 1 + "mpPublicKey": { + "type": [ + "string", + "null" + ] } }, "required": [ - "kind", - "id" + "code", + "status", + "currency", + "reservedUntil", + "createdAt", + "paidAt", + "buyer", + "fulfillment", + "shipping", + "pickupPoint", + "items", + "subtotal", + "shippingFee", + "total", + "tracking", + "mpPublicKey" ], "additionalProperties": false }, - "ContentPlaybackToken": { + "MerchCatalog": { "type": "object", "properties": { - "playbackId": { - "type": "string" - }, - "tokens": { + "store": { "type": "object", "properties": { - "playback": { + "brandName": { "type": "string" }, - "drm": { - "type": "string" + "brandLogoUrl": { + "type": [ + "string", + "null" + ] }, - "thumbnail": { - "type": "string" + "landingUrl": { + "type": [ + "string", + "null" + ] }, - "storyboard": { - "type": "string" + "support": { + "type": "object", + "properties": { + "phone": { + "type": [ + "string", + "null" + ] + }, + "isWhatsapp": { + "type": "boolean" + }, + "email": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "phone", + "isWhatsapp", + "email" + ], + "additionalProperties": false + }, + "shipping": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + }, + "feeBogota": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "feeNational": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "freeShippingThreshold": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "enabled", + "feeBogota", + "feeNational", + "freeShippingThreshold" + ], + "additionalProperties": false + }, + "pickupEnabled": { + "type": "boolean" } }, "required": [ - "playback", - "drm" + "brandName", + "brandLogoUrl", + "landingUrl", + "support", + "shipping", + "pickupEnabled" ], "additionalProperties": false - } - }, - "required": [ - "playbackId", - "tokens" - ], - "additionalProperties": false - }, - "WaitlistEntryCreate": { - "type": "object", - "properties": { - "city": { - "type": "string", - "minLength": 1, - "maxLength": 60 }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 80 + "products": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "slug": { + "type": "string" + }, + "name": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "imageUrls": { + "type": "array", + "items": { + "type": "string" + } + }, + "options": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "name", + "values" + ], + "additionalProperties": false + } + }, + "maxPerOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "variants": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "sku": { + "type": "string" + }, + "label": { + "type": "string" + }, + "attributes": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": {} + }, + "price": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "compareAtPrice": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "stock": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "id", + "sku", + "label", + "attributes", + "price", + "compareAtPrice", + "stock" + ], + "additionalProperties": false + } + } + }, + "required": [ + "id", + "slug", + "name", + "description", + "imageUrls", + "options", + "maxPerOrder", + "variants" + ], + "additionalProperties": false + } }, - "contact": { - "type": "string", - "minLength": 1, - "maxLength": 120 + "pickupPoints": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "address": { + "type": "string" + }, + "city": { + "type": [ + "string", + "null" + ] + }, + "schedule": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "name", + "address", + "city", + "schedule" + ], + "additionalProperties": false + } }, - "source": { + "currency": { "type": "string", - "maxLength": 40 - } - }, - "required": [ - "city", - "name", - "contact" - ], - "additionalProperties": false - }, - "WaitlistEntryResult": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "city": { - "type": "string" - }, - "created": { - "type": "boolean" - } - }, - "required": [ - "id", - "city", - "created" - ], - "additionalProperties": false - }, - "WaitlistEntry": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "city": { - "type": "string" - }, - "name": { - "type": "string" + "const": "COP" }, - "contact": { - "type": "string" - }, - "customerId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "source": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "mpPublicKey": { + "type": [ + "string", + "null" ] - }, - "createdAt": { - "type": "string" } }, "required": [ - "id", - "city", - "name", - "contact", - "customerId", - "source", - "createdAt" + "store", + "products", + "pickupPoints", + "currency", + "mpPublicKey" ], "additionalProperties": false } diff --git a/src/commands/box-office.ts b/src/commands/box-office.ts new file mode 100644 index 0000000..07b6769 --- /dev/null +++ b/src/commands/box-office.ts @@ -0,0 +1,356 @@ +import type { Command } from "commander"; +import { + deleteEventsIdViewersViewerId, + getEventDatesIdAccessClose, + getEventsIdValidators, + getEventsIdViewers, + getMasterQrs, + getPaymentIntents, + getReportsLiveAttendance, + getTicketTemplates, + patchMasterQrsId, + postEventDatesIdAccessClose, + postEventsIdValidators, + postEventsIdViewers, + postMasterQrs, + postStaffIdResendInvite, + postTicketTemplatesIdInstantiate, + putMasterQrsIdActive, + putStaffIdAccess, +} from "../client/sdk.gen"; +import { fail } from "../lib/api"; +import { parseLimit, wholeNumber } from "../lib/input"; +import { list, op, orNull } from "./op"; + +/** + * Box-office and door operations from contracts 1.26-1.36: who may see or + * validate an event, staff access, the access-close record, live attendance, + * the checkout funnel, master QRs and ticket templates. Each one hooks into + * the family it belongs to. + */ + +/** `ft events viewers …` and `ft events validators …` */ +export function registerEventAccess(events: Command): void { + const viewers = events + .command("viewers") + .description("Read-only viewers of an event's statistics"); + + op(viewers, { + name: "list ", + describe: "People with read-only access to the event's statistics", + call: ([eventId]) => getEventsIdViewers({ path: { id: eventId } }), + columns: ["id", "email", "createdAt"], + }); + + op(viewers, { + name: "add ", + describe: + "Grant read-only access to the event's statistics and email the link (creates a VIEWER account if needed)", + required: [["--email ", "viewer's email"]], + confirm: ([eventId], o) => + `Grant ${o.email} read-only access to event ${eventId} and email them?`, + call: ([eventId], o) => + postEventsIdViewers({ path: { id: eventId }, body: { email: o.email } }), + }); + + op(viewers, { + name: "remove ", + describe: + "Revoke a viewer's access (viewerId is the access id from `viewers list`; the account stays)", + confirm: ([eventId, viewerId]) => + `Revoke viewer ${viewerId} of event ${eventId}?`, + call: ([eventId, viewerId]) => + deleteEventsIdViewersViewerId({ path: { id: eventId, viewerId } }), + }); + + const validators = events + .command("validators") + .description("Door staff who can validate an event's tickets"); + + op(validators, { + name: "list ", + describe: + "Validators of the event (assigned to it, plus those with allEvents)", + call: ([eventId]) => getEventsIdValidators({ path: { id: eventId } }), + columns: ["id", "name", "email", "isActive", "allEvents"], + }); + + op(validators, { + name: "add ", + describe: + "Assign door staff to the event (additive; creates a STAFF account and emails an invitation if needed)", + required: [ + ["--name ", "validator's name"], + ["--email ", "validator's email"], + ], + confirm: ([eventId], o) => + `Make ${o.name} <${o.email}> a validator of event ${eventId}? A new account gets an invitation email.`, + call: ([eventId], o) => + postEventsIdValidators({ + path: { id: eventId }, + body: { name: o.name, email: o.email }, + }), + }); +} + +const ACCESS_TYPES = ["admin", "validador", "personalizado", "lectura"]; + +/** Body flags of `staff access` (option key, flag), exclusive with --data. */ +const ACCESS_FLAGS = [ + ["type", "--type"], + ["sections", "--sections"], + ["validatorEvents", "--validator-events"], + ["viewerEvents", "--viewer-events"], + ["expiresAt", "--expires-at"], +] as const; + +/** `ft staff access ` and `ft staff resend-invite ` */ +export function registerStaffAccess(staff: Command): void { + op(staff, { + name: "access ", + describe: + "Replace a staff member's access in this workspace (FULL replace: what you do not pass is removed)", + options: [ + ["--type ", "admin | validador | personalizado | lectura"], + [ + "--sections ", + "personalizado: comma-separated sections (e.g. eventos,validar,informes)", + ], + [ + "--validator-events ", + "events they may validate (comma-separated; empty = all)", + ], + ["--viewer-events ", "lectura: events whose stats they see"], + ["--expires-at ", 'YYYY-MM-DD, or "none" for permanent'], + ], + data: "optional", + check: (_args, o) => { + if (o.data !== undefined) { + // --data is the whole body: flags next to it would be dropped silently, + // and in a full replace a dropped --sections is access removed. + const mixed = ACCESS_FLAGS.filter(([key]) => o[key] !== undefined); + if (mixed.length > 0) + fail( + `Pass either --data or the flags, not both (got --data and ${mixed.map(([, flag]) => flag).join(", ")}).`, + ); + return; + } + if (!o.type) fail("Pass --type (or the whole body with --data)."); + if (!ACCESS_TYPES.includes(o.type)) + fail(`--type must be one of: ${ACCESS_TYPES.join(", ")}.`); + }, + confirm: ([id], o) => + `Replace the access of staff ${id}${o.type ? ` with "${o.type}"` : ""}? Anything not in this request is removed.`, + call: ([id], o, data) => + putStaffIdAccess({ + path: { id }, + body: (data ?? { + accessType: o.type, + sections: list(o.sections), + validatorEventIds: list(o.validatorEvents), + viewerEventIds: list(o.viewerEvents), + expiresAt: + o.expiresAt === undefined ? undefined : orNull(o.expiresAt), + }) as never, + }), + }); + + op(staff, { + name: "resend-invite ", + describe: + "Email the staff member their invitation link again (same persistent link)", + confirm: ([id]) => `Resend the invitation email to staff ${id}?`, + call: ([id]) => postStaffIdResendInvite({ path: { id } }), + }); +} + +/** `ft event-dates access-close status|sign ` */ +export function registerAccessClose(eventDates: Command): void { + const close = eventDates + .command("access-close") + .description("Access-close record of an event date (door count)"); + + op(close, { + name: "status ", + describe: "Live entry count and whether the date is closed or signable", + call: ([dateId]) => getEventDatesIdAccessClose({ path: { id: dateId } }), + }); + + op(close, { + name: "sign ", + describe: + "Sign the access-close record: freezes the check-in count and emails it (IRREVERSIBLE; does not stop the scanner)", + confirm: ([dateId]) => + `Sign the access-close record of date ${dateId}? This is irreversible.`, + call: ([dateId]) => + postEventDatesIdAccessClose({ + path: { id: dateId }, + body: { confirm: true }, + }), + }); +} + +/** `ft sales intents --event ` */ +export function registerPaymentIntents(sales: Command): void { + op(sales, { + name: "intents", + describe: + "Purchase intents of an event: checkout funnel and abandoned journeys (personal data)", + required: [["--event ", "event id"]], + options: [ + ["--event-date ", "only this date"], + ["--only-abandoned", "only journeys that did not buy"], + ["--limit ", "rows per page (1-100)", parseLimit], + ["--cursor ", "pagination cursor"], + ], + call: (_args, o) => + getPaymentIntents({ + query: { + event: o.event, + eventDate: o.eventDate, + onlyAbandoned: o.onlyAbandoned ? true : undefined, + limit: o.limit, + cursor: o.cursor, + }, + }), + // The table shows the journeys; --json keeps funnel and cursor too. + pick: (body, o) => { + if (o.json) return body.data; + if (body.data?.nextCursor) + console.error(`More results: --cursor ${body.data.nextCursor}`); + console.error(`Funnel: ${JSON.stringify(body.data?.funnel ?? {})}`); + return body.data?.rows ?? []; + }, + columns: [ + "personName", + "personEmail", + "stage", + "outcome", + "reason", + "saleReference", + "lastAt", + ], + }); +} + +/** `ft reports live-attendance` */ +export function registerLiveAttendance(reports: Command): void { + op(reports, { + name: "live-attendance", + describe: "Event dates happening right now, with check-in progress", + options: [["--scope ", "all | own | partner:"]], + call: (_args, o) => getReportsLiveAttendance({ query: { scope: o.scope } }), + columns: [ + "eventName", + "city", + "sold", + "validated", + "validatedPct", + "eventDateId", + ], + }); +} + +/** Master QR `code` and `url` are secrets: whoever has them reaches the sale flow. */ +const SECRET_QR_FIELDS = ["code", "url"]; + +/** + * Drops `code`/`url` from a master QR (or a list of them) unless `--full`. + * Applies to `--json` too: a JSON dump piped into a log or an agent's context + * leaks the secret just as well as a table, and it cannot be rotated. + */ +export function redactMasterQr(data: unknown, full: boolean): unknown { + if (full) return data; + const strip = (row: unknown) => + row && typeof row === "object" + ? Object.fromEntries( + Object.entries(row).filter(([k]) => !SECRET_QR_FIELDS.includes(k)), + ) + : row; + return Array.isArray(data) ? data.map(strip) : strip(data); +} + +const FULL: [string, string] = [ + "--full", + "include the secret code and url (table and --json)", +]; + +/** `ft master-qrs list|create|update|activate|deactivate` (delete is CRUD). */ +export function extendMasterQrs(root: Command): void { + op(root, { + name: "list", + describe: + "Master box-office QR codes (`code`/`url` are secret: left out, also from --json, unless --full)", + options: [FULL], + call: () => getMasterQrs({}), + pick: (body, o) => redactMasterQr(body.data, Boolean(o.full)), + columns: (o) => + o.full + ? undefined + : ["id", "label", "mode", "eventId", "active", "scans", "lastScanAt"], + }); + op(root, { + name: "create", + describe: + "Create a master QR. Prints its SECRET code and url: you need them to print the QR, they never rotate, and whoever has them reaches the sale flow. Keep the output private.", + data: "required", + call: (_a, _o, data) => postMasterQrs({ body: data as never }), + }); + op(root, { + name: "update ", + describe: + "Update a master QR (label, mode, eventId, ticketTypeId). The secret code/url are left out of the output unless --full", + data: "required", + options: [FULL], + call: ([id], _o, data) => + patchMasterQrsId({ path: { id }, body: data as never }), + pick: (body, o) => redactMasterQr(body.data, Boolean(o.full)), + }); + for (const [name, active] of [ + ["activate", true], + ["deactivate", false], + ] as const) + op(root, { + name: `${name} `, + describe: `${active ? "Activate" : "Deactivate"} a master QR (a deactivated QR stops opening the sale flow)`, + call: ([id]) => putMasterQrsIdActive({ path: { id }, body: { active } }), + }); +} + +/** Extras of `ft ticket-templates`: list and instantiate. */ +export function extendTicketTemplates(root: Command): void { + op(root, { + name: "list", + describe: "Ticket templates of the workspace", + call: () => getTicketTemplates({}), + columns: ["id", "name", "price", "currency", "capacity", "isActive"], + }); + op(root, { + name: "instantiate ", + describe: "Create a ticket type on an event date from a template", + required: [["--event-date ", "event date that gets the ticket type"]], + options: [ + ["--name ", "override the template's name"], + [ + "--price ", + "override the price (whole COP, no separators: 50000)", + wholeNumber("--price"), + ], + [ + "--capacity ", + "override the capacity (whole number)", + wholeNumber("--capacity"), + ], + ], + call: ([templateId], o) => + postTicketTemplatesIdInstantiate({ + path: { id: templateId }, + body: { + eventDateId: o.eventDate, + name: o.name, + price: o.price, + capacity: o.capacity, + }, + }), + }); +} diff --git a/src/commands/community.ts b/src/commands/community.ts new file mode 100644 index 0000000..9fdce06 --- /dev/null +++ b/src/commands/community.ts @@ -0,0 +1,325 @@ +import type { Command } from "commander"; +import { + deleteContentCommentsId, + deleteContentMembersIdBan, + getContentChannels, + getContentLivesIdChat, + getContentMeetups, + getContentModerationBans, + getContentModerationMemberPosts, + getContentModerationQueue, + patchContentMeetupsIdRsvpsRsvpId, + postContentLivesIdResetKey, + postContentMeetupsIdPublish, + postContentMembersIdBan, + postContentModerationCommentsIdHide, + postContentModerationCommentsIdIgnoreReports, + postContentModerationCommentsIdUnhide, + postContentModerationMemberPostsIdApprove, + postContentModerationMemberPostsIdReject, + postContentModerationMemberPostsIdRemove, + putContentChannelsOrder, + putContentMeetupsIdAttendance, + putContentPostsIdPin, + putContentSeriesIdPublished, + putContentVideosIdPublished, + putContentVideosIdSeries, +} from "../client/sdk.gen"; +import { fail } from "../lib/api"; +import { booleanFlag, wholeNumber } from "../lib/input"; +import { list, op, orNull } from "./op"; + +/** + * Community management from contracts 1.26-1.36 (channels, posts, videos and + * series, live streams, meetups, moderation). The CRUD verbs go through + * registerResource in program.ts; these are the verbs that take a flag-built + * body, a second id or no id at all. + */ + +const PAGE: [string, string, (input: string) => number] = [ + "--page ", + "0-based page", + wholeNumber("--page"), +]; + +/** Extras of `ft content-posts`: pin/unpin. */ +export function extendContentPosts(root: Command): void { + for (const [name, pinned] of [ + ["pin", true], + ["unpin", false], + ] as const) + op(root, { + name: `${name} `, + describe: pinned + ? "Pin a published post (unpins the previous one)" + : "Unpin a post", + call: ([id]) => putContentPostsIdPin({ path: { id }, body: { pinned } }), + }); +} + +/** Extras of `ft content-videos`: publish/unpublish and series. */ +export function extendContentVideos(root: Command): void { + for (const [name, published] of [ + ["publish", true], + ["unpublish", false], + ] as const) + op(root, { + name: `${name} `, + describe: published + ? "Publish a video to the community feed (members are notified once, so it asks; --yes skips)" + : "Take a video out of the feed", + // Publishing notifies every member; unpublishing notifies nobody. + confirm: published + ? ([id]) => `Publish video ${id}? Community members get notified.` + : undefined, + call: ([id]) => + putContentVideosIdPublished({ path: { id }, body: { published } }), + }); + op(root, { + name: "set-series ", + describe: "Move a video into a series, or out of it with --series none", + required: [["--series ", 'series id, or "none"']], + call: ([id], o) => + putContentVideosIdSeries({ + path: { id }, + body: { seriesId: orNull(o.series) }, + }), + }); +} + +/** Extras of `ft content-series`: publish/unpublish. */ +export function extendContentSeries(root: Command): void { + for (const [name, published] of [ + ["publish", true], + ["unpublish", false], + ] as const) + op(root, { + name: `${name} `, + describe: `${published ? "Publish" : "Unpublish"} a video series`, + call: ([id]) => + putContentSeriesIdPublished({ path: { id }, body: { published } }), + }); +} + +/** Extras of `ft content-lives`: chat and reset-key. */ +export function extendContentLives(root: Command): void { + op(root, { + name: "chat ", + describe: "Chat history of a live stream", + call: ([id]) => getContentLivesIdChat({ path: { id } }), + pick: (body, o) => (o.json ? body.data : body.data?.messages), + }); + op(root, { + name: "reset-key ", + describe: + "Rotate the stream key (the old one stops working and an encoder on air is cut off); prints the new secret key", + confirm: ([id]) => + `Rotate the stream key of live ${id}? An encoder using the current key is cut off.`, + call: ([id]) => postContentLivesIdResetKey({ path: { id } }), + }); +} + +/** Extras of `ft content-channels`: list and order. */ +export function extendContentChannels(root: Command): void { + op(root, { + name: "list", + describe: "Active community channels in display order", + call: () => getContentChannels({}), + columns: ["id", "kind", "name", "slug", "whoCanPost", "requiresApproval"], + }); + op(root, { + name: "order ", + describe: + "Reorder the channels: EVERY active channel id, comma-separated, Announcements first", + call: ([ids]) => + putContentChannelsOrder({ body: { orderedIds: list(ids) ?? [] } }), + }); +} + +/** Extras of `ft content-meetups`: list, publish, rsvp, attendance. */ +export function extendContentMeetups(root: Command): void { + op(root, { + name: "list", + describe: "Community meetups", + call: () => getContentMeetups({}), + columns: [ + "id", + "title", + "format", + "status", + "startsAt", + "city", + "goingCount", + "pendingCount", + ], + }); + op(root, { + name: "publish ", + describe: + "Publish a draft meetup (queues a notification to the whole community)", + confirm: ([id]) => + `Publish meetup ${id}? The whole community gets notified.`, + call: ([id]) => postContentMeetupsIdPublish({ path: { id } }), + }); + op(root, { + name: "rsvp ", + describe: "Approve or reject an RSVP request (the member gets an email)", + options: [ + ["--approve", "approve the request"], + ["--reject", "reject the request"], + ], + check: (_args, o) => { + if (!o.approve === !o.reject) + fail("Pass exactly one of --approve or --reject."); + }, + confirm: ([id, rsvpId], o) => + `${o.approve ? "Approve" : "Reject"} RSVP ${rsvpId} of meetup ${id}? The member gets an email.`, + call: ([id, rsvpId], o) => + patchContentMeetupsIdRsvpsRsvpId({ + path: { id, rsvpId }, + body: { decision: o.approve ? "APPROVE" : "REJECT" }, + }), + }); + op(root, { + name: "attendance ", + describe: + "Mark (or with --attended false, unmark) an attendee as checked in", + options: [ + [ + "--attended ", + "true | false (default true)", + booleanFlag("--attended"), + ], + ], + call: ([id, rsvpId], o) => + putContentMeetupsIdAttendance({ + path: { id }, + body: { rsvpId, attended: o.attended ?? true }, + }), + }); +} + +/** `ft content-moderation …`, `ft content-comments …`, `ft content-members …` */ +export function registerModeration(program: Command): void { + const mod = program + .command("content-moderation") + .description("Community moderation: reported comments, member posts, bans"); + + op(mod, { + name: "queue", + describe: "Reported comments, most reported first (50 per page)", + options: [PAGE], + call: (_a, o) => getContentModerationQueue({ query: { page: o.page } }), + columns: ["commentId", "openReportCount", "hidden", "deleted", "body"], + }); + op(mod, { + name: "bans", + describe: "Members banned from the community (latest 200)", + call: () => getContentModerationBans({}), + columns: ["id", "customerName", "reason", "createdAt"], + }); + op(mod, { + name: "member-posts", + describe: "Member posts awaiting review (or recently published)", + options: [["--status ", "PENDING_REVIEW | PUBLISHED"], PAGE], + call: (_a, o) => + getContentModerationMemberPosts({ + query: { status: o.status, page: o.page }, + }), + columns: ["postId", "status", "channelName", "updatedAt", "content"], + }); + op(mod, { + name: "approve ", + describe: + "Publish a pending member post (author and mentioned members are notified)", + required: [ + [ + "--expected-updated-at ", + "the post's updatedAt from `member-posts` (409 if edited since)", + ], + ], + call: ([id], o) => + postContentModerationMemberPostsIdApprove({ + path: { id }, + body: { expectedUpdatedAt: o.expectedUpdatedAt }, + }), + }); + for (const [name, fn, what] of [ + ["reject", postContentModerationMemberPostsIdReject, "Reject a pending"], + ["remove", postContentModerationMemberPostsIdRemove, "Remove a published"], + ] as const) + op(mod, { + name: `${name} `, + describe: `${what} member post (--ban-author also bans its author)`, + options: [ + ["--reason ", "reason shown to the author"], + ["--ban-author", "also ban the author from the community"], + ], + confirm: ([id], o) => + `${name === "reject" ? "Reject" : "Remove"} member post ${id}${o.banAuthor ? " and ban its author" : ""}?`, + call: ([id], o) => + fn({ + path: { id }, + body: { reason: o.reason, banAuthor: Boolean(o.banAuthor) }, + }), + }); + + const comments = program + .command("content-comments") + .description("Community comments (moderation)"); + for (const [name, fn, describe] of [ + [ + "hide", + postContentModerationCommentsIdHide, + "Hide a comment (reversible)", + ], + ["unhide", postContentModerationCommentsIdUnhide, "Show a hidden comment"], + [ + "ignore-reports", + postContentModerationCommentsIdIgnoreReports, + "Dismiss the open reports of a comment", + ], + ] as const) + op(comments, { + name: `${name} `, + describe, + call: ([id]) => fn({ path: { id } }), + }); + op(comments, { + name: "delete ", + describe: + "Delete a comment and its replies (irreversible; `hide` is the reversible one)", + confirm: ([id]) => `Delete comment ${id} and its replies?`, + call: ([id]) => deleteContentCommentsId({ path: { id } }), + }); + + const members = program + .command("content-members") + .description("Community members (bans)"); + op(members, { + name: "ban ", + describe: + "Ban a member from posting, commenting and RSVPing (cancels their upcoming RSVPs)", + required: [["--comment ", "comment of theirs the ban comes from"]], + options: [ + ["--reason ", "reason"], + ["--hide-all-comments", "hide all their comments in this workspace"], + ], + confirm: ([id]) => + `Ban member ${id} from the community? Their upcoming RSVPs are cancelled.`, + call: ([id], o) => + postContentMembersIdBan({ + path: { id }, + body: { + commentId: o.comment, + reason: o.reason, + hideAllComments: Boolean(o.hideAllComments), + }, + }), + }); + op(members, { + name: "unban ", + describe: "Lift a member's community ban", + call: ([id]) => deleteContentMembersIdBan({ path: { id } }), + }); +} diff --git a/src/commands/lineup.test.ts b/src/commands/lineup.test.ts new file mode 100644 index 0000000..754eb7d --- /dev/null +++ b/src/commands/lineup.test.ts @@ -0,0 +1,153 @@ +import { Command } from "commander"; +import { + afterEach, + beforeEach, + describe, + expect, + it, + type MockInstance, + vi, +} from "vitest"; + +const sdk = vi.hoisted(() => ({ + getEventsId: vi.fn(), + putEventsIdArtists: vi.fn(), + getArtists: vi.fn(), +})); + +vi.mock("../client/sdk.gen", async (importOriginal) => ({ + ...(await importOriginal()), + ...sdk, +})); + +vi.mock("../lib/api", async (importOriginal) => ({ + ...(await importOriginal()), + configureClient: vi.fn(), +})); + +const { registerArtists, registerEventLineup } = await import("./lineup"); + +const ok = (data: unknown, extra: Record = {}) => ({ + data: { data, ...extra }, + response: new Response(), +}); + +function build(): Command { + const program = new Command().exitOverride(); + registerEventLineup(program.command("events")); + registerArtists(program); + return program; +} + +const run = (...args: string[]) => build().parseAsync(["node", "ft", ...args]); + +describe("ft events artists set", () => { + const tty = process.stdin.isTTY; + let stderr: MockInstance; + + beforeEach(() => { + Object.defineProperty(process.stdin, "isTTY", { + value: false, + configurable: true, + }); + stderr = vi.spyOn(console, "error").mockImplementation(() => {}); + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(process.stdout, "write").mockImplementation(() => true); + vi.spyOn(process, "exit").mockImplementation((() => { + throw new Error("exited"); + }) as never); + sdk.putEventsIdArtists.mockResolvedValue(ok({ artists: [] })); + }); + + afterEach(() => { + Object.defineProperty(process.stdin, "isTTY", { + value: tty, + configurable: true, + }); + vi.restoreAllMocks(); + for (const fn of Object.values(sdk)) fn.mockReset(); + }); + + it("sends the full lineup in order and skips confirmation when nobody drops out", async () => { + sdk.getEventsId.mockResolvedValue( + ok({ artists: [{ id: "a1", name: "Uno" }] }), + ); + await run("events", "artists", "set", "evt_1", "--artist", "a2", "a1"); + expect(sdk.putEventsIdArtists).toHaveBeenCalledWith({ + path: { id: "evt_1" }, + body: { artistIds: ["a2", "a1"], inviteEmails: undefined }, + }); + }); + + it("refuses without --yes when an artist would be removed, naming them", async () => { + sdk.getEventsId.mockResolvedValue( + ok({ artists: [{ id: "a1", name: "Uno" }] }), + ); + await expect( + run("events", "artists", "set", "evt_1", "--artist", "a2"), + ).rejects.toThrow("exited"); + expect(stderr.mock.calls[0]?.[0]).toMatch(/Refusing: Remove Uno/); + expect(sdk.putEventsIdArtists).not.toHaveBeenCalled(); + }); + + it("refuses to clear the lineup without --yes, even if it is already empty", async () => { + sdk.getEventsId.mockResolvedValue(ok({ artists: [] })); + await expect(run("events", "artists", "set", "evt_1")).rejects.toThrow( + "exited", + ); + expect(sdk.putEventsIdArtists).not.toHaveBeenCalled(); + }); + + it("--yes skips the lookup and prints ARTIST_IDS_IGNORED warnings", async () => { + sdk.putEventsIdArtists.mockResolvedValue( + ok( + { artists: [] }, + { + warnings: [ + { code: "ARTIST_IDS_IGNORED", message: "Ignored", ids: ["bad"] }, + ], + }, + ), + ); + await run( + "events", + "artists", + "set", + "evt_1", + "--artist", + "bad", + "--invite", + "x@y.co", + "--yes", + ); + expect(sdk.getEventsId).not.toHaveBeenCalled(); + expect(sdk.putEventsIdArtists).toHaveBeenCalledWith({ + path: { id: "evt_1" }, + body: { artistIds: ["bad"], inviteEmails: ["x@y.co"] }, + }); + expect(stderr.mock.calls[0]?.[0]).toMatch(/ARTIST_IDS_IGNORED.*bad/); + }); + + it("artists search passes q, limit and cursor", async () => { + sdk.getArtists.mockResolvedValue( + ok([], { page: { nextCursor: null, hasMore: false } }), + ); + await run("artists", "search", "bad bunny", "--limit", "5", "--json"); + expect(sdk.getArtists).toHaveBeenCalledWith({ + query: { q: "bad bunny", limit: 5, cursor: undefined }, + }); + }); +}); + +describe("lineup command tree", () => { + it("registers artists set|remove and invitations list|resend|cancel under events", () => { + const events = build().commands.find((c) => c.name() === "events"); + const sub = (n: string) => + events?.commands + .find((c) => c.name() === n) + ?.commands.map((c) => c.name()) + .sort(); + expect(sub("artists")).toEqual(["remove", "set"]); + expect(sub("invitations")).toEqual(["cancel", "list", "resend"]); + }); +}); diff --git a/src/commands/lineup.ts b/src/commands/lineup.ts new file mode 100644 index 0000000..9589221 --- /dev/null +++ b/src/commands/lineup.ts @@ -0,0 +1,215 @@ +import chalk from "chalk"; +import type { Command } from "commander"; +import { + deleteEventsIdArtistInvitationsInvitationId, + deleteEventsIdArtistsOrganizationId, + getArtists, + getEventsId, + getEventsIdArtistInvitations, + postEventsIdArtistInvitationsInvitationIdResend, + putEventsIdArtists, +} from "../client/sdk.gen"; +import { configureClient, unwrap } from "../lib/api"; +import { confirmOrExit, parseLimit } from "../lib/input"; +import { print, printNextCursor } from "../lib/output"; + +/** Prints API `warnings[]` (e.g. ARTIST_IDS_IGNORED) on stderr, keeping stdout clean for --json. */ +function printWarnings( + warnings?: { code: string; message: string; ids?: string[] }[], +): void { + for (const w of warnings ?? []) + console.error( + chalk.yellow( + `warning [${w.code}]: ${w.message}${w.ids?.length ? ` (${w.ids.join(", ")})` : ""}`, + ), + ); +} + +/** + * `ft artists search ` — resolves registered artist workspaces (across + * FreeTicket, not just yours) to the ids `ft events artists set` takes. + */ +export function registerArtists(program: Command): void { + const root = program + .command("artists") + .description("Artists registered on FreeTicket (to build event lineups)"); + + root + .command("search ") + .description("Search registered artists by name (2+ characters)") + .option("--limit ", "results per page (1-100)", parseLimit, 20) + .option("--cursor ", "pagination cursor") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (q, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await getArtists({ + query: { q, limit: opts.limit, cursor: opts.cursor }, + }), + ); + print(body.data, { + json: opts.json, + columns: ["id", "name", "slug"], + }); + if (!opts.json) printNextCursor(body.page); + }); +} + +/** + * `ft events artists set|remove` and `ft events invitations list|resend|cancel` + * — the event lineup (contract 1.25.0). Hooked under `ft events` through + * registerResource's `extend`, because the paths take two ids. + */ +export function registerEventLineup(events: Command): void { + const artists = events + .command("artists") + .description("Event lineup: the artists linked to an event"); + + artists + .command("set ") + .description( + "Replace the lineup with --artist ids, in order (unlisted artists are unlinked; no --artist clears it)", + ) + .option( + "--artist ", + "artist workspace id (from `ft artists search`), in lineup order", + ) + .option( + "--invite ", + "invite artists without an account (additive; sends them an email, so it asks)", + ) + .option( + "--yes", + "skip confirmation (asked when artists would be removed or invitations emailed)", + ) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, opts) => { + configureClient(opts.workspace); + const artistIds: string[] = opts.artist ?? []; + const invites: string[] = opts.invite ?? []; + if (!opts.yes) { + // The PUT replaces the whole lineup: name who drops out before asking. + const current = unwrap(await getEventsId({ path: { id: eventId } })); + const removed = (current.data.artists ?? []).filter( + (a) => !artistIds.includes(a.id), + ); + const asks: string[] = []; + if (artistIds.length === 0) + asks.push( + `Clear the lineup of event ${eventId}${removed.length ? ` (removes ${removed.map((a) => a.name).join(", ")})` : ""}`, + ); + else if (removed.length > 0) + asks.push( + `Remove ${removed.map((a) => a.name).join(", ")} from event ${eventId}`, + ); + // Each invitation is an email to someone outside FreeTicket. + if (invites.length > 0) + asks.push(`email an invitation to ${invites.join(", ")}`); + const question = asks.join(" and "); + if (question) + await confirmOrExit( + `${question[0]?.toUpperCase()}${question.slice(1)}?`, + false, + ); + } + const body = unwrap( + await putEventsIdArtists({ + path: { id: eventId }, + body: { artistIds, inviteEmails: opts.invite }, + }), + ); + printWarnings(body.warnings); + print(opts.json ? body : body.data.artists, { + json: opts.json, + columns: ["id", "name", "slug", "type"], + }); + }); + + artists + .command("remove ") + .description( + "Unlink one artist from an event (owner, or the artist itself)", + ) + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, organizationId, opts) => { + await confirmOrExit( + `Remove artist ${organizationId} from event ${eventId}?`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await deleteEventsIdArtistsOrganizationId({ + path: { id: eventId, organizationId }, + }), + ); + print(body.data, { json: opts.json }); + }); + + const invitations = events + .command("invitations") + .description( + "Pending/expired invitations sent to artists without an account", + ); + + invitations + .command("list ") + .description("List an event's artist invitations (newest first)") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await getEventsIdArtistInvitations({ path: { id: eventId } }), + ); + print(body.data, { + json: opts.json, + columns: ["id", "email", "status", "expiresAt", "createdAt"], + }); + }); + + invitations + .command("resend ") + .description( + "Resend an invitation email and renew it for 14 days (asks; --yes skips)", + ) + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, invitationId, opts) => { + await confirmOrExit( + `Resend invitation ${invitationId} of event ${eventId}? The artist gets another email.`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await postEventsIdArtistInvitationsInvitationIdResend({ + path: { id: eventId, invitationId }, + }), + ); + print(body.data, { json: opts.json }); + }); + + invitations + .command("cancel ") + .description("Cancel (delete) a pending artist invitation") + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, invitationId, opts) => { + await confirmOrExit( + `Cancel invitation ${invitationId} of event ${eventId}?`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await deleteEventsIdArtistInvitationsInvitationId({ + path: { id: eventId, invitationId }, + }), + ); + print(body.data, { json: opts.json }); + }); +} diff --git a/src/commands/op.ts b/src/commands/op.ts new file mode 100644 index 0000000..81f9f41 --- /dev/null +++ b/src/commands/op.ts @@ -0,0 +1,91 @@ +// biome-ignore-all lint/suspicious/noExplicitAny: generated SDK boundary — signatures vary by operation. +import type { Command } from "commander"; +import { configureClient, unwrap } from "../lib/api"; +import { confirmOrExit, parseData } from "../lib/input"; +import { print } from "../lib/output"; + +type SdkResult = Promise<{ data?: any; error?: unknown; response: Response }>; +type Opts = Record; +/** Positional args in signature order (typed non-empty so `[id]` is a string). */ +type Args = [string, string, ...string[]]; + +/** + * One command bound to one contract operation, for the shapes registerResource + * cannot model: nested ids (` `), flag-built bodies, plain + * (unpaginated) lists, singleton resources. Every command gets `--workspace` + * and `--json`; `--account` is added globally by program.ts. + */ +export interface OpSpec { + /** Commander signature, e.g. `"remove "`. */ + name: string; + describe: string; + /** + * Optional flags: [flags, description, default or parser?]. A parser (e.g. + * `wholeNumber("--price")` from lib/input) runs while commander parses argv, + * so a bad value exits 1 before the confirmation and the request. + */ + options?: [string, string, (string | ((input: string) => unknown))?][]; + /** Required flags: [flags, description]. */ + required?: [string, string][]; + /** `--data ` body (inline or @file): "required" or "optional". */ + data?: "required" | "optional"; + /** + * Destructive, sends email or otherwise hard to take back: ask first, with + * `--yes` to skip; without a TTY and without `--yes` it refuses (exit 1) + * before any request. + */ + confirm?: (args: Args, opts: Opts) => string; + /** Validate flags before anything else (call `fail` to abort). */ + check?: (args: Args, opts: Opts) => void; + /** The SDK call. `data` is the parsed `--data` body, when passed. */ + call: (args: Args, opts: Opts, data: unknown) => SdkResult; + /** Table columns for array output (or a function of the flags). */ + columns?: string[] | ((opts: Opts) => string[] | undefined); + /** What to print from the unwrapped body (default: `body.data ?? body`). */ + pick?: (body: any, opts: Opts) => unknown; +} + +export function op(parent: Command, spec: OpSpec): Command { + const cmd = parent.command(spec.name).description(spec.describe); + for (const [flags, describe] of spec.required ?? []) + cmd.requiredOption(flags, describe); + for (const [flags, describe, defOrParse] of spec.options ?? []) + cmd.option(flags, describe, defOrParse as never); + if (spec.data === "required") + cmd.requiredOption("--data ", "JSON body (inline or @file.json)"); + else if (spec.data === "optional") + cmd.option("--data ", "JSON body (inline or @file.json)"); + if (spec.confirm) cmd.option("--yes", "skip confirmation"); + cmd + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output"); + + cmd.action(async (...received: unknown[]) => { + // commander passes the positional args, then opts, then the command. + const opts = received[received.length - 2] as Opts; + const args = received.slice(0, -2) as Args; + spec.check?.(args, opts); + // Parse before asking: a typo in --data should not cost a confirmation. + const data = opts.data !== undefined ? parseData(opts.data) : undefined; + if (spec.confirm) await confirmOrExit(spec.confirm(args, opts), opts.yes); + configureClient(opts.workspace); + const body = unwrap(await spec.call(args, opts, data)); + const out = spec.pick ? spec.pick(body, opts) : (body?.data ?? body); + const columns = + typeof spec.columns === "function" ? spec.columns(opts) : spec.columns; + print(out ?? { ok: true }, { json: opts.json, columns }); + }); + return cmd; +} + +/** `"none"` clears a nullable field; anything else is sent as is. */ +export const orNull = (v: string) => (v === "none" ? null : v); + +/** Comma-separated flag to a trimmed list, `undefined` when not passed. */ +export const list = (v: string | undefined) => + v === undefined + ? undefined + : v + .split(",") + .map((s) => s.trim()) + .filter(Boolean); diff --git a/src/commands/ops.test.ts b/src/commands/ops.test.ts new file mode 100644 index 0000000..436bf61 --- /dev/null +++ b/src/commands/ops.test.ts @@ -0,0 +1,149 @@ +import { Command } from "commander"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const sdk = vi.hoisted(() => ({ + postEventsIdSchedule: vi.fn(), + patchPresaleWindowsId: vi.fn(), + postTicketTypesIdPresaleWindows: vi.fn(), + postSalesIdItemsItemIdTransfer: vi.fn(), + getEventDatesIdCourtesySeats: vi.fn(), +})); + +vi.mock("../client/sdk.gen", async (importOriginal) => ({ + ...(await importOriginal()), + ...sdk, +})); + +vi.mock("../lib/api", async (importOriginal) => ({ + ...(await importOriginal()), + configureClient: vi.fn(), +})); + +const ops = await import("./ops"); + +const ok = (data: unknown) => ({ data: { data }, response: new Response() }); + +function run(...args: string[]) { + const program = new Command().exitOverride(); + ops.registerEventSchedule(program.command("events")); + ops.registerPresaleWindows(program); + ops.registerSaleOps(program.command("sales")); + ops.registerCourtesySeats(program.command("event-dates")); + return program.parseAsync(["node", "ft", ...args]); +} + +beforeEach(() => { + vi.spyOn(console, "error").mockImplementation(() => {}); + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(process.stdout, "write").mockImplementation(() => true); + vi.spyOn(process, "exit").mockImplementation((() => { + throw new Error("exited"); + }) as never); + for (const fn of Object.values(sdk)) fn.mockResolvedValue(ok({})); +}); + +afterEach(() => { + vi.restoreAllMocks(); + for (const fn of Object.values(sdk)) fn.mockReset(); +}); + +describe("ft events schedule set", () => { + it("sends only publishAt", async () => { + await run( + "events", + "schedule", + "set", + "evt_1", + "--publish-at", + "2027-01-01T00:00:00Z", + ); + expect(sdk.postEventsIdSchedule).toHaveBeenCalledWith({ + path: { id: "evt_1" }, + body: { publishAt: "2027-01-01T00:00:00Z" }, + }); + }); + + it.each([ + [[]], + [ + [ + "--publish-at", + "2027-01-01T00:00:00Z", + "--sale-starts-at", + "2027-01-02T00:00:00Z", + ], + ], + ])("rejects %j: exactly one flag is required", async (flags) => { + await expect( + run("events", "schedule", "set", "evt_1", ...flags), + ).rejects.toThrow("exited"); + expect(sdk.postEventsIdSchedule).not.toHaveBeenCalled(); + }); +}); + +describe("ft presale-windows", () => { + it("create maps flags to the contract body", async () => { + await run( + "presales", + "create", + "tt_1", + "--plan", + "plan_1", + "--starts-at", + "2027-01-01T00:00:00Z", + "--ends-at", + "2027-01-02T00:00:00Z", + "--capacity", + "50", + ); + expect(sdk.postTicketTypesIdPresaleWindows).toHaveBeenCalledWith({ + path: { id: "tt_1" }, + body: { + planId: "plan_1", + presaleStartsAt: "2027-01-01T00:00:00Z", + presaleEndsAt: "2027-01-02T00:00:00Z", + presaleCapacity: 50, + }, + }); + }); + + it("update sends only the flags passed; --capacity none clears the cap", async () => { + await run( + "presale-windows", + "update", + "pw_1", + "--capacity", + "none", + "--active", + "false", + ); + expect(sdk.patchPresaleWindowsId).toHaveBeenCalledWith({ + path: { id: "pw_1" }, + body: { presaleCapacity: null, isActive: false }, + }); + }); +}); + +it("ft sales transfer --yes sends the recipient email", async () => { + await run( + "sales", + "transfer", + "sale_1", + "item_1", + "--email", + "a@b.co", + "--yes", + ); + expect(sdk.postSalesIdItemsItemIdTransfer).toHaveBeenCalledWith({ + path: { id: "sale_1", itemId: "item_1" }, + body: { email: "a@b.co" }, + }); +}); + +it("ft event-dates courtesy-seats reads the date", async () => { + sdk.getEventDatesIdCourtesySeats.mockResolvedValue(ok({ ticketTypes: [] })); + await run("event-dates", "courtesy-seats", "date_1", "--json"); + expect(sdk.getEventDatesIdCourtesySeats).toHaveBeenCalledWith({ + path: { id: "date_1" }, + }); +}); diff --git a/src/commands/ops.ts b/src/commands/ops.ts new file mode 100644 index 0000000..a826df2 --- /dev/null +++ b/src/commands/ops.ts @@ -0,0 +1,296 @@ +import type { Command } from "commander"; +import { + deleteEventsIdSchedule, + deletePresaleWindowsId, + deleteTicketsTicketCodeCheckin, + getEventDatesIdCourtesySeats, + getTicketTypesIdPresaleWindows, + patchPresaleWindowsId, + patchSalesIdRecipient, + postEventsIdSchedule, + postSalesIdItemsItemIdTransfer, + postTicketTypesIdPresaleWindows, +} from "../client/sdk.gen"; +import { configureClient, fail, unwrap } from "../lib/api"; +import { + booleanFlag, + confirmOrExit, + noneToNull, + wholeNumberOrNone, +} from "../lib/input"; +import { print } from "../lib/output"; + +/** + * Dashboard-parity operations from contract 1.25.0: scheduled publication, + * presale windows, ticket transfer, check-in undo, courtesy recipient and + * courtesy seats. Each hooks into the family it belongs to (`ft events`, + * `ft sales`, `ft tickets`, `ft event-dates`) because their paths take + * nested ids or no body that registerResource could model. + */ + +const PRESALE_COLUMNS = [ + "id", + "planId", + "presaleStartsAt", + "presaleEndsAt", + "presaleCapacity", + "isActive", +]; + +/** Presale window flags, already typed by the commander parsers below. */ +interface PresaleOpts { + plan?: string; + startsAt?: string; + endsAt?: string; + capacity?: number | "none"; + active?: boolean; +} + +/** Presale window body from flags; only the flags passed are sent. */ +function presaleBody(opts: PresaleOpts) { + const body: Record = {}; + if (opts.plan) body.planId = opts.plan; + if (opts.startsAt) body.presaleStartsAt = opts.startsAt; + if (opts.endsAt) body.presaleEndsAt = opts.endsAt; + if (opts.capacity !== undefined) + body.presaleCapacity = noneToNull(opts.capacity); + if (opts.active !== undefined) body.isActive = opts.active; + return body; +} + +// Parsed while commander reads argv: `--capacity 1,000` or `--active yes` +// exit 1 before any request instead of sending 1 or false. +const capacity = wholeNumberOrNone("--capacity"); +const active = booleanFlag("--active"); + +/** `ft events schedule set|clear ` */ +export function registerEventSchedule(events: Command): void { + const schedule = events + .command("schedule") + .description("Scheduled publication of a draft event"); + + schedule + .command("set ") + .description( + "Schedule a DRAFT: --publish-at publishes it later; --sale-starts-at publishes now and opens sales later (exactly one)", + ) + .option("--publish-at ", "publish automatically at this UTC instant") + .option( + "--sale-starts-at ", + "publish now; open sales on every upcoming ticket type at this UTC instant", + ) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, opts) => { + if (!opts.publishAt === !opts.saleStartsAt) + fail("Pass exactly one of --publish-at or --sale-starts-at."); + configureClient(opts.workspace); + const body = unwrap( + await postEventsIdSchedule({ + path: { id: eventId }, + body: opts.publishAt + ? { publishAt: opts.publishAt } + : { saleStartsAt: opts.saleStartsAt }, + }), + ); + print(body.data, { json: opts.json }); + }); + + schedule + .command("clear ") + .description( + "Cancel a pending --publish-at (does not undo --sale-starts-at: edit the ticket types)", + ) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (eventId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await deleteEventsIdSchedule({ path: { id: eventId } }), + ); + print(body.data, { json: opts.json }); + }); +} + +/** `ft presale-windows list|create|update|delete` (alias `presales`). */ +export function registerPresaleWindows(program: Command): void { + const root = program + .command("presale-windows") + .alias("presales") + .description( + "Membership presale windows on a ticket type (one window per plan)", + ); + + root + .command("list ") + .description("List a ticket type's presale windows") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (ticketTypeId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await getTicketTypesIdPresaleWindows({ path: { id: ticketTypeId } }), + ); + print(body.data, { json: opts.json, columns: PRESALE_COLUMNS }); + }); + + root + .command("create ") + .description("Open a presale window for the members of one plan") + .requiredOption("--plan ", "membership plan of this workspace") + .requiredOption("--starts-at ", "presale start (UTC)") + .requiredOption("--ends-at ", "presale end (UTC, after start)") + .option( + "--capacity ", + 'max tickets sold in the presale (whole number, or "none")', + capacity, + ) + .option("--active ", "true | false (default true)", active) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (ticketTypeId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await postTicketTypesIdPresaleWindows({ + path: { id: ticketTypeId }, + body: presaleBody(opts) as never, + }), + ); + print(body.data, { json: opts.json }); + }); + + root + .command("update ") + .description("Edit a presale window (only the flags passed change)") + .option("--plan ", "membership plan of this workspace") + .option("--starts-at ", "presale start (UTC)") + .option("--ends-at ", "presale end (UTC)") + .option( + "--capacity ", + 'max tickets (whole number), or "none" to remove the cap', + capacity, + ) + .option("--active ", "true | false", active) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (windowId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await patchPresaleWindowsId({ + path: { id: windowId }, + body: presaleBody(opts), + }), + ); + print(body.data, { json: opts.json }); + }); + + root + .command("delete ") + .description("Delete a presale window (members lose that access now)") + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (windowId, opts) => { + await confirmOrExit(`Delete presale window ${windowId}?`, opts.yes); + configureClient(opts.workspace); + const body = unwrap( + await deletePresaleWindowsId({ path: { id: windowId } }), + ); + print(body.data, { json: opts.json }); + }); +} + +/** `ft sales transfer` and `ft sales recipient set`. */ +export function registerSaleOps(sales: Command): void { + sales + .command("transfer ") + .description( + "Transfer one ticket to a registered buyer (voids the old QR; once per ticket, until the show starts)", + ) + .requiredOption("--email ", "recipient's verified FreeTicket email") + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (saleId, itemId, opts) => { + await confirmOrExit( + `Transfer ticket ${itemId} of sale ${saleId} to ${opts.email}? The current QR stops working.`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await postSalesIdItemsItemIdTransfer({ + path: { id: saleId, itemId }, + body: { email: opts.email }, + }), + ); + print(body.data, { json: opts.json }); + }); + + sales + .command("recipient") + .description("Recipient of a courtesy sale") + .command("set ") + .description( + "Correct a courtesy's recipient and resend its tickets (a new email voids the old QRs)", + ) + .requiredOption("--name ", "recipient name") + .requiredOption("--email ", "recipient email") + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (saleId, opts) => { + await confirmOrExit( + `Set the recipient of courtesy ${saleId} to ${opts.name} <${opts.email}> and resend? If the email changes, the QRs already sent stop working.`, + opts.yes, + ); + configureClient(opts.workspace); + const body = unwrap( + await patchSalesIdRecipient({ + path: { id: saleId }, + body: { name: opts.name, email: opts.email }, + }), + ); + print(body.data, { json: opts.json }); + }); +} + +/** `ft tickets checkin-undo ` */ +export function registerCheckinUndo(tickets: Command): void { + tickets + .command("checkin-undo ") + .description( + "Undo a door check-in so the ticket is valid again (ADMIN; idempotent)", + ) + .option("--yes", "skip confirmation") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (code, opts) => { + await confirmOrExit(`Undo the check-in of ticket ${code}?`, opts.yes); + configureClient(opts.workspace); + const body = unwrap( + await deleteTicketsTicketCodeCheckin({ path: { ticketCode: code } }), + ); + print(body.data, { json: opts.json }); + }); +} + +/** `ft event-dates courtesy-seats ` */ +export function registerCourtesySeats(eventDates: Command): void { + eventDates + .command("courtesy-seats ") + .description( + "Blocked seats of a numbered date that can be issued as courtesies", + ) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (dateId, opts) => { + configureClient(opts.workspace); + const body = unwrap( + await getEventDatesIdCourtesySeats({ path: { id: dateId } }), + ); + print(opts.json ? body.data : body.data.ticketTypes, { + json: opts.json, + columns: ["ticketTypeId", "name", "labels"], + }); + }); +} diff --git a/src/commands/resource.ts b/src/commands/resource.ts index 69a1555..b141432 100644 --- a/src/commands/resource.ts +++ b/src/commands/resource.ts @@ -54,7 +54,13 @@ interface ResourceSpec { /** Columns to show in list table / CSV output. */ columns?: string[]; /** Extra list flags -> query entries. Example: status, eventDateId. */ - listFlags?: { flag: string; describe: string; query: string }[]; + listFlags?: { + flag: string; + describe: string; + query: string; + /** Commander parser (e.g. `booleanFlag`), run before any request. */ + parse?: (input: string) => unknown; + }[]; /** Commands that don't fit the CRUD shape (extra args, non-JSON responses). */ extend?: (root: Command) => void; } @@ -88,7 +94,9 @@ export function registerResource(program: Command, spec: ResourceSpec): void { .option("--csv", "CSV output (for spreadsheets/accounting)") .option("--json", "raw JSON output (data only)") .option("--raw", "raw JSON output including pagination metadata (page)"); - for (const f of spec.listFlags ?? []) cmd.option(f.flag, f.describe); + for (const f of spec.listFlags ?? []) + if (f.parse) cmd.option(f.flag, f.describe, f.parse); + else cmd.option(f.flag, f.describe); cmd.action(async (opts) => { let columns = resolveColumns(opts, spec.columns); opts.limit = parseLimit(opts.limit); diff --git a/src/commands/storefront.ts b/src/commands/storefront.ts new file mode 100644 index 0000000..0ed6618 --- /dev/null +++ b/src/commands/storefront.ts @@ -0,0 +1,131 @@ +import type { Command } from "commander"; +import { + getMerchCatalog, + getOrganizationProfile, + getProducts, + getWebsite, + patchOrganization, + patchOrganizationAnalytics, + patchOrganizationProfile, + postProductsIdStatus, + putWebsite, + putWebsitePublished, +} from "../client/sdk.gen"; +import { fail } from "../lib/api"; +import { op, orNull } from "./op"; + +/** + * Workspace identity and storefront from contracts 1.26-1.36: organization and + * profile, the public website, digital products and the merch catalog. + */ + +/** Extras of `ft products`: list and status. */ +export function extendProducts(root: Command): void { + op(root, { + name: "list", + describe: "Digital products and courses", + call: () => getProducts({}), + columns: [ + "id", + "name", + "type", + "status", + "price", + "currency", + "salesCount", + ], + }); + op(root, { + name: "status ", + describe: "Publish or unpublish a product", + required: [["--status ", "DRAFT | PUBLISHED"]], + check: (_a, o) => { + if (!["DRAFT", "PUBLISHED"].includes(o.status)) + fail("--status must be DRAFT or PUBLISHED."); + }, + call: ([id], o) => + postProductsIdStatus({ path: { id }, body: { status: o.status } }), + }); +} + +/** `ft organization update|analytics|profile` (alias `org`). */ +export function registerOrganization(program: Command): void { + const root = program + .command("organization") + .alias("org") + .description("The active workspace's identity, profile and analytics"); + + op(root, { + name: "update", + describe: "Update the public identity (name, logoUrl, coverUrl)", + data: "required", + call: (_a, _o, data) => patchOrganization({ body: data as never }), + }); + op(root, { + name: "analytics ", + describe: 'Set the GA4 property (G-XXXXXXX), or "none" to remove it', + call: ([id]) => + patchOrganizationAnalytics({ body: { ga4MeasurementId: orNull(id) } }), + }); + + const profile = root + .command("profile") + .description("Workspace profile (artist, visual, contact, social)"); + op(profile, { + name: "get", + describe: "Get the workspace profile", + call: () => getOrganizationProfile({}), + }); + op(profile, { + name: "update", + describe: + "Update the profile (partial: --data with artist/visual/contact/social)", + data: "required", + call: (_a, _o, data) => patchOrganizationProfile({ body: data as never }), + }); +} + +/** `ft website get|set|publish|unpublish` */ +export function registerWebsite(program: Command): void { + const root = program + .command("website") + .description("The workspace's public website"); + + op(root, { + name: "get", + describe: "Get the website configuration", + call: () => getWebsite({}), + }); + op(root, { + name: "set", + describe: + "Save the whole website configuration (FULL replace: start from `ft website get --json`; asks, --yes skips)", + data: "required", + // A PUT of the whole config: a partial --data wipes every section left out. + confirm: () => + "Replace the whole website configuration of this workspace? Sections missing from --data are removed.", + call: (_a, _o, data) => putWebsite({ body: data as never }), + }); + for (const [name, published] of [ + ["publish", true], + ["unpublish", false], + ] as const) + op(root, { + name, + describe: `${published ? "Publish" : "Unpublish"} the public profile`, + call: () => putWebsitePublished({ body: { published } }), + }); +} + +/** `ft merch catalog` */ +export function registerMerch(program: Command): void { + const root = program + .command("merch") + .description("Merch store of an enterprise landing"); + op(root, { + name: "catalog", + describe: + "Store settings and published products with live stock (needs an enterprise service key)", + call: () => getMerchCatalog({}), + }); +} diff --git a/src/commands/wire.test.ts b/src/commands/wire.test.ts new file mode 100644 index 0000000..e2c73c1 --- /dev/null +++ b/src/commands/wire.test.ts @@ -0,0 +1,644 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import { client } from "../client/client.gen"; + +/** + * Wire-level checks for the riskiest commands: the real generated SDK runs + * and only `fetch` is faked, so each test sees the HTTP method, the final URL + * (with every id in the slot the contract gives it) and the JSON body that + * would leave the machine. Two distinct ids per call catch a swapped pair. + */ +vi.mock("../lib/api", async (importOriginal) => ({ + ...(await importOriginal()), + configureClient: vi.fn(() => + client.setConfig({ baseUrl: "https://ft.test/api/v1", fetch: fetchMock }), + ), +})); + +const fetchMock = vi.hoisted(() => vi.fn()); +const { program } = await import("../program"); + +interface Sent { + method: string; + path: string; + body: unknown; +} + +async function send(...args: string[]): Promise { + await program.parseAsync(["node", "ft", ...args, "--json"]); + expect(fetchMock).toHaveBeenCalledTimes(1); + const req = fetchMock.mock.calls[0]?.[0] as Request; + const url = new URL(req.url); + const text = await req.text(); + return { + method: req.method, + path: `${url.pathname.replace("/api/v1", "")}${url.search}`, + body: text ? JSON.parse(text) : undefined, + }; +} + +beforeEach(() => { + vi.spyOn(console, "error").mockImplementation(() => {}); + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(process.stdout, "write").mockImplementation(() => true); + vi.spyOn(process, "exit").mockImplementation((() => { + throw new Error("exited"); + }) as never); + fetchMock.mockImplementation( + async () => + new Response(JSON.stringify({ data: {} }), { + status: 200, + headers: { "Content-Type": "application/json" }, + }), + ); +}); + +afterEach(() => { + vi.restoreAllMocks(); + fetchMock.mockReset(); +}); + +describe("tickets and sales", () => { + it("sales transfer: sale id, then item id, email in the body", async () => { + expect( + await send( + "sales", + "transfer", + "sale_A", + "item_B", + "--email", + "to@b.co", + "--yes", + ), + ).toEqual({ + method: "POST", + path: "/sales/sale_A/items/item_B/transfer", + body: { email: "to@b.co" }, + }); + }); + + it("sales recipient set: name and email only", async () => { + expect( + await send( + "sales", + "recipient", + "set", + "sale_A", + "--name", + "Ana", + "--email", + "ana@b.co", + "--yes", + ), + ).toEqual({ + method: "PATCH", + path: "/sales/sale_A/recipient", + body: { name: "Ana", email: "ana@b.co" }, + }); + }); + + it("tickets checkin-undo: DELETE on the ticket code, no body", async () => { + expect(await send("tickets", "checkin-undo", "TKT-9", "--yes")).toEqual({ + method: "DELETE", + path: "/tickets/TKT-9/checkin", + body: undefined, + }); + }); + + it("sales abandon: POST, no body", async () => { + expect(await send("sales", "abandon", "sale_A", "--yes")).toEqual({ + method: "POST", + path: "/sales/sale_A/abandon", + body: undefined, + }); + }); +}); + +describe("staff access", () => { + it("builds the full-replace body from flags", async () => { + expect( + await send( + "staff", + "access", + "stf_A", + "--type", + "personalizado", + "--sections", + "eventos, validar", + "--validator-events", + "evt_1,evt_2", + "--expires-at", + "2027-01-31", + "--yes", + ), + ).toEqual({ + method: "PUT", + path: "/staff/stf_A/access", + body: { + accessType: "personalizado", + sections: ["eventos", "validar"], + validatorEventIds: ["evt_1", "evt_2"], + expiresAt: "2027-01-31", + }, + }); + }); + + it("--expires-at none sends null (permanent)", async () => { + const sent = await send( + "staff", + "access", + "stf_A", + "--type", + "lectura", + "--viewer-events", + "evt_1", + "--expires-at", + "none", + "--yes", + ); + expect(sent.body).toEqual({ + accessType: "lectura", + viewerEventIds: ["evt_1"], + expiresAt: null, + }); + }); + + it("--data replaces the flags", async () => { + const sent = await send( + "staff", + "access", + "stf_A", + "--data", + '{"accessType":"validador","validatorEventIds":[]}', + "--yes", + ); + expect(sent.body).toEqual({ + accessType: "validador", + validatorEventIds: [], + }); + }); + + it("rejects an unknown --type before any request", async () => { + await expect( + program.parseAsync([ + "node", + "ft", + "staff", + "access", + "stf_A", + "--type", + "owner", + "--yes", + ]), + ).rejects.toThrow("exited"); + expect(fetchMock).not.toHaveBeenCalled(); + }); + + it("resend-invite: POST, no body", async () => { + expect(await send("staff", "resend-invite", "stf_A", "--yes")).toEqual({ + method: "POST", + path: "/staff/stf_A/resend-invite", + body: undefined, + }); + }); +}); + +describe("event viewers and validators", () => { + it("viewers add: email in the body", async () => { + expect( + await send( + "events", + "viewers", + "add", + "evt_A", + "--email", + "v@b.co", + "--yes", + ), + ).toEqual({ + method: "POST", + path: "/events/evt_A/viewers", + body: { email: "v@b.co" }, + }); + }); + + it("viewers remove: event id, then viewer (access) id", async () => { + expect( + await send("events", "viewers", "remove", "evt_A", "vw_B", "--yes"), + ).toEqual({ + method: "DELETE", + path: "/events/evt_A/viewers/vw_B", + body: undefined, + }); + }); + + it("viewers list: GET", async () => { + fetchMock.mockResolvedValueOnce( + new Response(JSON.stringify({ data: [] }), { + headers: { "Content-Type": "application/json" }, + }), + ); + expect(await send("events", "viewers", "list", "evt_A")).toEqual({ + method: "GET", + path: "/events/evt_A/viewers", + body: undefined, + }); + }); + + it("validators add: name and email", async () => { + expect( + await send( + "events", + "validators", + "add", + "evt_A", + "--name", + "Door 1", + "--email", + "d@b.co", + "--yes", + ), + ).toEqual({ + method: "POST", + path: "/events/evt_A/validators", + body: { name: "Door 1", email: "d@b.co" }, + }); + }); +}); + +describe("door and box office", () => { + it("access-close sign sends the required confirm flag", async () => { + expect( + await send("event-dates", "access-close", "sign", "date_A", "--yes"), + ).toEqual({ + method: "POST", + path: "/event-dates/date_A/access-close", + body: { confirm: true }, + }); + }); + + it("master-qrs deactivate", async () => { + expect(await send("master-qrs", "deactivate", "mq_A")).toEqual({ + method: "PUT", + path: "/master-qrs/mq_A/active", + body: { active: false }, + }); + }); + + it("ticket-templates instantiate: template id in the path, date in the body", async () => { + expect( + await send( + "ticket-templates", + "instantiate", + "tpl_A", + "--event-date", + "date_B", + "--price", + "50000", + ), + ).toEqual({ + method: "POST", + path: "/ticket-templates/tpl_A/instantiate", + body: { eventDateId: "date_B", price: 50000 }, + }); + }); + + it("sales intents: query filters", async () => { + fetchMock.mockResolvedValueOnce( + new Response(JSON.stringify({ data: { rows: [], funnel: {} } }), { + headers: { "Content-Type": "application/json" }, + }), + ); + expect( + await send("sales", "intents", "--event", "evt_A", "--only-abandoned"), + ).toEqual({ + method: "GET", + path: "/payment-intents?event=evt_A&onlyAbandoned=true", + body: undefined, + }); + }); +}); + +describe("community", () => { + it("meetups rsvp: meetup id, then rsvp id, decision in the body", async () => { + expect( + await send( + "content-meetups", + "rsvp", + "mt_A", + "rsvp_B", + "--reject", + "--yes", + ), + ).toEqual({ + method: "PATCH", + path: "/content/meetups/mt_A/rsvps/rsvp_B", + body: { decision: "REJECT" }, + }); + }); + + it("members ban: customer id in the path, comment in the body", async () => { + expect( + await send( + "content-members", + "ban", + "cus_A", + "--comment", + "cmt_B", + "--yes", + ), + ).toEqual({ + method: "POST", + path: "/content/members/cus_A/ban", + body: { commentId: "cmt_B", hideAllComments: false }, + }); + }); +}); + +/** Runs argv expecting exit 1; returns what went to stderr. */ +async function refused(...args: string[]): Promise { + await expect(program.parseAsync(["node", "ft", ...args])).rejects.toThrow( + "exited", + ); + expect(process.exit).toHaveBeenCalledWith(1); + return vi + .mocked(console.error) + .mock.calls.map((c) => String(c[0])) + .join("\n"); +} + +/** Everything written to stdout (where print sends --json and tables). */ +const stdout = () => + [ + ...vi.mocked(process.stdout.write).mock.calls.map((c) => String(c[0])), + ...vi.mocked(console.log).mock.calls.map((c) => String(c[0])), + ].join("\n"); + +const json = (body: unknown, status = 200) => + new Response(JSON.stringify(body), { + status, + headers: { "Content-Type": "application/json" }, + }); + +describe("typed flags: a malformed number or boolean exits 1 before any request", () => { + // Number("50.000") === 50 and NaN serializes as null: these used to reach + // the API as fifty pesos, or as a capacity silently cleared. + it.each([ + [ + ["ticket-templates", "instantiate", "tpl_A", "--event-date", "date_B"], + ["--price", "50.000"], + ], + [ + ["ticket-templates", "instantiate", "tpl_A", "--event-date", "date_B"], + ["--capacity", "abc"], + ], + [ + ["ticket-templates", "instantiate", "tpl_A", "--event-date", "date_B"], + ["--price", "-5"], + ], + [ + ["presale-windows", "update", "pw_A"], + ["--capacity", "1,000"], + ], + [ + ["presale-windows", "update", "pw_A"], + ["--active", "yes"], + ], + [ + [ + "presale-windows", + "create", + "tt_A", + "--plan", + "plan_B", + "--starts-at", + "2027-01-01T00:00:00Z", + "--ends-at", + "2027-01-02T00:00:00Z", + ], + ["--capacity", "abc"], + ], + [ + ["content-meetups", "attendance", "mt_A", "rsvp_B"], + ["--attended", "si"], + ], + [ + ["content-moderation", "queue"], + ["--page", "1.5"], + ], + [ + ["discounts", "list", "--workspace", "ws_A"], + ["--active", "yes"], + ], + [ + ["sales", "intents", "--event", "evt_A"], + ["--limit", "1e1"], + ], + [ + ["artists", "search", "rock"], + ["--limit", "abc"], + ], + ])("ft %j %j", async (args, [flag, value]) => { + const err = await refused(...args, flag as string, value as string); + expect(err).toContain(`Invalid ${flag}: ${value}`); + expect(fetchMock).not.toHaveBeenCalled(); + }); + + it("presale --capacity none still clears the cap and --active false is false", async () => { + const sent = await send( + "presale-windows", + "update", + "pw_A", + "--capacity", + "none", + "--active", + "false", + ); + expect(sent.body).toEqual({ presaleCapacity: null, isActive: false }); + }); + + it("instantiate sends whole numbers as numbers", async () => { + const sent = await send( + "ticket-templates", + "instantiate", + "tpl_A", + "--event-date", + "date_B", + "--price", + "50000", + "--capacity", + "1000", + ); + expect(sent.body).toEqual({ + eventDateId: "date_B", + price: 50000, + capacity: 1000, + }); + }); +}); + +describe("staff access: --data or flags, never both", () => { + it("--data with --type exits 1 before any request", async () => { + const err = await refused( + "staff", + "access", + "stf_A", + "--data", + '{"accessType":"admin"}', + "--type", + "lectura", + "--sections", + "eventos", + "--yes", + ); + expect(err).toContain( + "Pass either --data or the flags, not both (got --data and --type, --sections)", + ); + expect(fetchMock).not.toHaveBeenCalled(); + }); +}); + +describe("master-qrs: the secret code and url", () => { + const qr = { + id: "mq_A", + label: "Taquilla", + mode: "EVENT", + eventId: "evt_B", + ticketTypeId: null, + active: true, + scans: 3, + lastScanAt: null, + createdAt: "2026-11-01T00:00:00Z", + code: "SECRETCODE42", + url: "https://t.test/mq/SECRETCODE42", + }; + + it("list --json leaves code and url out", async () => { + fetchMock.mockResolvedValueOnce(json({ data: [qr] })); + await send("master-qrs", "list"); + expect(stdout()).toContain("mq_A"); + expect(stdout()).not.toContain("SECRETCODE42"); + }); + + it("list as a table leaves them out too", async () => { + fetchMock.mockResolvedValueOnce(json({ data: [qr] })); + await program.parseAsync(["node", "ft", "master-qrs", "list"]); + expect(stdout()).toContain("mq_A"); + expect(stdout()).not.toContain("SECRETCODE42"); + }); + + it("list --full --json shows them", async () => { + fetchMock.mockResolvedValueOnce(json({ data: [qr] })); + await send("master-qrs", "list", "--full"); + expect(stdout()).toContain("SECRETCODE42"); + expect(stdout()).toContain("https://t.test/mq/SECRETCODE42"); + }); + + it("update --json redacts the QR it answers with", async () => { + fetchMock.mockResolvedValueOnce(json({ data: qr })); + expect( + await send("master-qrs", "update", "mq_A", "--data", '{"label":"B"}'), + ).toEqual({ + method: "PATCH", + path: "/master-qrs/mq_A", + body: { label: "B" }, + }); + expect(stdout()).toContain("Taquilla"); + expect(stdout()).not.toContain("SECRETCODE42"); + }); + + it("create prints the secret (needed to print the QR) and says so in --help", async () => { + fetchMock.mockResolvedValueOnce(json({ data: qr })); + await send("master-qrs", "create", "--data", '{"label":"Taquilla"}'); + expect(stdout()).toContain("SECRETCODE42"); + const create = program.commands + .find((c) => c.name() === "master-qrs") + ?.commands.find((c) => c.name() === "create"); + expect(create?.description()).toMatch(/SECRET code and url/); + }); +}); + +describe("two ids in the right slots", () => { + it("events artists remove: event, then artist workspace", async () => { + expect( + await send("events", "artists", "remove", "evt_A", "org_B", "--yes"), + ).toEqual({ + method: "DELETE", + path: "/events/evt_A/artists/org_B", + body: undefined, + }); + }); + + it("events invitations cancel: event, then invitation", async () => { + expect( + await send("events", "invitations", "cancel", "evt_A", "inv_B", "--yes"), + ).toEqual({ + method: "DELETE", + path: "/events/evt_A/artist-invitations/inv_B", + body: undefined, + }); + }); + + it("events invitations resend: event, then invitation", async () => { + expect( + await send("events", "invitations", "resend", "evt_A", "inv_B", "--yes"), + ).toEqual({ + method: "POST", + path: "/events/evt_A/artist-invitations/inv_B/resend", + body: undefined, + }); + }); + + it("content-meetups attendance: meetup in the path, rsvp id in the body", async () => { + expect( + await send("content-meetups", "attendance", "mt_A", "rsvp_B"), + ).toEqual({ + method: "PUT", + path: "/content/meetups/mt_A/attendance", + body: { rsvpId: "rsvp_B", attended: true }, + }); + }); + + it("content-meetups attendance --attended false unmarks", async () => { + const sent = await send( + "content-meetups", + "attendance", + "mt_A", + "rsvp_B", + "--attended", + "false", + ); + expect(sent.body).toEqual({ rsvpId: "rsvp_B", attended: false }); + }); +}); + +describe("API errors exit 1 with the message on stderr", () => { + const notFound = () => + json( + { error: { code: "NOT_FOUND", message: "Event evt_A not found" } }, + 404, + ); + const serverError = () => + new Response("upstream exploded", { + status: 500, + headers: { "Content-Type": "text/plain" }, + }); + + it.each([ + ["op()", ["events", "viewers", "list", "evt_A"]], + ["ops.ts", ["presale-windows", "list", "tt_A"]], + ])("404 through %s", async (_via, args) => { + fetchMock.mockResolvedValueOnce(notFound()); + const err = await refused(...args); + expect(err).toContain("Error 404 [NOT_FOUND]: Event evt_A not found"); + expect(err).toContain("does not exist or belongs to another workspace"); + }); + + it.each([ + ["op()", ["events", "viewers", "list", "evt_A"]], + ["ops.ts", ["presale-windows", "list", "tt_A"]], + ])("500 without a JSON body through %s", async (_via, args) => { + fetchMock.mockResolvedValueOnce(serverError()); + const err = await refused(...args); + expect(err).toContain("The API responded with 500 without a readable body"); + }); +}); diff --git a/src/commands/workspace-header.test.ts b/src/commands/workspace-header.test.ts new file mode 100644 index 0000000..12a06c4 --- /dev/null +++ b/src/commands/workspace-header.test.ts @@ -0,0 +1,81 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +/** + * Nothing mocked but `fetch`: the real program, the real `configureClient` + * and the real config resolution, fed by a fake environment (FT_API_KEY, and + * FT_API_URL pointing at a closed local port from src/test/setup.ts). wire.test + * replaces `configureClient`, so a command that stopped calling it, or called + * it before reading `--workspace`, would still pass there. Here the request + * has to carry the key and the workspace the user asked for. + */ +const fetchMock = vi.fn(); +const { program } = await import("../program"); + +beforeEach(() => { + vi.stubEnv("FT_API_KEY", "ft_test_key"); + vi.stubGlobal("fetch", fetchMock); + fetchMock.mockImplementation( + async () => + new Response(JSON.stringify({ data: [] }), { + headers: { "Content-Type": "application/json" }, + }), + ); + vi.spyOn(console, "error").mockImplementation(() => {}); + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(process.stdout, "write").mockImplementation(() => true); + vi.spyOn(process, "exit").mockImplementation((() => { + throw new Error("exited"); + }) as never); +}); + +afterEach(() => { + vi.unstubAllEnvs(); + vi.unstubAllGlobals(); + vi.restoreAllMocks(); + fetchMock.mockReset(); +}); + +async function request(...args: string[]): Promise { + await program.parseAsync(["node", "ft", ...args, "--json"]); + expect(fetchMock).toHaveBeenCalledTimes(1); + return fetchMock.mock.calls[0]?.[0] as Request; +} + +describe("X-Workspace-Id and the API key reach the wire", () => { + it.each([ + ["op()", ["events", "viewers", "list", "evt_A"], "/events/evt_A/viewers"], + [ + "ops.ts", + ["presale-windows", "list", "tt_A"], + "/ticket-types/tt_A/presale-windows", + ], + [ + "lineup.ts", + ["events", "invitations", "list", "evt_A"], + "/events/evt_A/artist-invitations", + ], + ])("%s: --workspace becomes the header", async (_via, args, path) => { + const req = await request(...args, "--workspace", "ws_FLAG"); + expect(req.url).toBe(`http://127.0.0.1:9/api/v1${path}`); + expect(req.headers.get("X-Workspace-Id")).toBe("ws_FLAG"); + expect(req.headers.get("Authorization")).toBe("Bearer ft_test_key"); + }); + + it("FT_WORKSPACE_ID applies when no --workspace is passed", async () => { + vi.stubEnv("FT_WORKSPACE_ID", "ws_ENV"); + const req = await request("events", "viewers", "list", "evt_A"); + expect(req.headers.get("X-Workspace-Id")).toBe("ws_ENV"); + }); + + it("--workspace beats FT_WORKSPACE_ID", async () => { + vi.stubEnv("FT_WORKSPACE_ID", "ws_ENV"); + const req = await request( + "presale-windows", + "list", + "tt_A", + "--workspace", + "ws_FLAG", + ); + expect(req.headers.get("X-Workspace-Id")).toBe("ws_FLAG"); + }); +}); diff --git a/src/coverage.test.ts b/src/coverage.test.ts new file mode 100644 index 0000000..04f45b1 --- /dev/null +++ b/src/coverage.test.ts @@ -0,0 +1,167 @@ +import { readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; +import { describe, expect, it } from "vitest"; + +/** + * Contract sweep, ported from freeticket-mcp's coverage.test.ts: every + * operation of the spec either has a command, or is excluded here with its + * reason. Without it, a new endpoint arrives through `sync-openapi` and stays + * command-less forever, because nothing fails. + * + * The match is by operationId against the command sources: the generated SDK + * exports one function per operationId, so if the name shows up outside the + * imports, a command uses it. Operations the CLI reaches without the SDK (signed downloads stop + * at the 302, see `signedDownload`) are in DIRECT with the path they build. + */ + +interface Operation { + id: string; + /** `GET /events/{id}`, for readable failures. */ + where: string; + path: string; +} + +function operations(file: string): Operation[] { + const spec = JSON.parse(readFileSync(file, "utf8")) as { + paths: Record>; + }; + return Object.entries(spec.paths).flatMap(([path, ops]) => + Object.entries(ops) + .filter(([, op]) => typeof op?.operationId === "string") + .map(([method, op]) => ({ + id: op.operationId as string, + where: `${method.toUpperCase()} ${path}`, + path, + })), + ); +} + +/** Concatenated source of the files that hold commands (no tests). */ +function commandSource(): string { + const dir = join("src", "commands"); + return [ + ...readdirSync(dir) + .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts")) + .map((f) => join(dir, f)), + join("src", "program.ts"), + ] + .map((f) => readFileSync(f, "utf8")) + .join("\n"); +} + +/** + * Paths kept out of the CLI as a whole. The buyer API (`/customer/*`) runs on + * a buyer session minted by a device grant or an enterprise exchange; the CLI + * authenticates staff with workspace API keys and has no buyer login. + */ +const EXCLUDED_PREFIXES: Record = { + "/customer/": + "buyer API: needs a buyer session, the CLI only holds staff API keys", +}; + +/** Single operations kept out of the CLI, each with its reason. */ +const EXCLUDED: Record = { + postApiCustomerAuthEnterpriseExchange: + "mints buyer sessions from a one-time token: server-to-server between free-admin and the integrator", + // Headless merch store of an enterprise landing (contract 1.36): the buyer + // side. The catalog is a command (`ft merch catalog`). + postMerchOrders: + "places a buyer's order (ID document, phone, stock hold): landing page checkout", + postMerchOrdersLookup: + "a buyer looking up their own order by code + email: landing page flow", + postMerchOrdersCodePaymentCard: + "charges a Payment Brick card token: card data never passes through the CLI", +}; + +/** + * Operations the CLI reaches with a hand-built path instead of the SDK + * function, with a string that must appear in the source. `ft settlements + * document` stops at the 302 so the file is not pulled into memory. + */ +const DIRECT: Record = { + getSettlementsIdDocument: { + reason: "signedDownload: stops at the 302 and prints the signed URL", + needle: `\`/settlements/\${id}/document\``, + }, + getSettlementsIdProofsFileName: { + reason: "signedDownload: stops at the 302 and prints the signed URL", + needle: `\`/settlements/\${id}/proofs/\${encodeURIComponent(opts.proof)}\``, + }, +}; + +const excludedWhy = (o: Operation): string | undefined => + EXCLUDED[o.id] ?? + Object.entries(EXCLUDED_PREFIXES).find(([p]) => o.path.startsWith(p))?.[1]; + +/** + * One row per contract. `admin-openapi.json` (superadmin, `ft admin`) joins + * with its own row, minimum and exclusions in the admin PR; its commands live + * in the same sources, so `commandSource` does not change. + */ +const SPECS: [label: string, file: string, minOps: number][] = [ + ["B2B /api/v1", "openapi.json", 200], +]; + +/** + * The source without its import statements: an import alone is not a command, + * and the SDK import list outlives the call it was for (removing the call + * leaves the import, which biome flags but this test would not). + */ +const withoutImports = (text: string) => + text.replace(/^import\b[\s\S]*?from\s+"[^"]+";$/gm, ""); + +describe.each(SPECS)("contract %s", (_label, file, minOps) => { + const ops = operations(file); + const source = commandSource(); + const body = withoutImports(source); + + it("did not shrink abruptly (a truncated spec would pass every other check)", () => { + expect(ops.length).toBeGreaterThanOrEqual(minOps); + }); + + it("has a command for every operation, or excludes it with a reason", () => { + const uncovered = ops + .filter((o) => !excludedWhy(o) && !DIRECT[o.id]) + .filter((o) => !new RegExp(`\\b${o.id}\\b`).test(body)) + .map((o) => `${o.where} [${o.id}]`); + expect(uncovered).toEqual([]); + }); + + it("reaches every DIRECT operation through the path it names", () => { + const missing = ops + .filter((o) => DIRECT[o.id]) + .filter((o) => !source.includes(DIRECT[o.id]?.needle as string)) + .map((o) => `${o.where} [${o.id}]`); + expect(missing).toEqual([]); + }); + + it("calls no excluded operation", () => { + // The coverage rule accepts a bare mention (a comment counts); this looks + // for a call, or an aliased import that would hide the call. + const leaked = ops + .filter((o) => excludedWhy(o)) + .filter((o) => new RegExp(`\\b${o.id}(\\s*\\(|\\s+as\\b)`).test(source)) + .map((o) => `${o.where} [${o.id}] — ${excludedWhy(o)}`); + expect(leaked).toEqual([]); + }); +}); + +it("carries no exclusions for operations or paths the contracts no longer have", () => { + // An orphaned exclusion is a rule nobody has looked at again. + const all = SPECS.flatMap(([, file]) => operations(file)); + const ids = new Set(all.map((o) => o.id)); + expect( + [...Object.keys(EXCLUDED), ...Object.keys(DIRECT)].filter( + (id) => !ids.has(id), + ), + ).toEqual([]); + expect( + Object.keys(EXCLUDED_PREFIXES).filter( + (p) => !all.some((o) => o.path.startsWith(p)), + ), + ).toEqual([]); +}); + +it("does not both exclude an operation and reach it directly", () => { + expect(Object.keys(DIRECT).filter((id) => EXCLUDED[id])).toEqual([]); +}); diff --git a/src/destructive-confirm.test.ts b/src/destructive-confirm.test.ts index e6a6e61..e3bd118 100644 --- a/src/destructive-confirm.test.ts +++ b/src/destructive-confirm.test.ts @@ -1,3 +1,5 @@ +import { readFileSync } from "node:fs"; +import type { Command } from "commander"; import { afterEach, beforeEach, @@ -12,26 +14,73 @@ import { * End-to-end through commander: a destructive command run without a TTY and * without --yes must exit 1 BEFORE the SDK call. The generated SDK functions * are mocked so nothing could reach the network even if the gate regressed. + * + * Each CASES row is checked both ways: refused without --yes, and with --yes + * its SDK function is called exactly once. Without the second half a row + * could point at a function its command never calls (or at another command's + * function) and the "never calls" assertion would pass vacuously. */ const sdk = vi.hoisted(() => ({ postEventsIdCancel: vi.fn(), deleteStaffId: vi.fn(), + deleteEventsIdArtistsOrganizationId: vi.fn(), + deleteEventsIdArtistInvitationsInvitationId: vi.fn(), + deletePresaleWindowsId: vi.fn(), + postSalesIdItemsItemIdTransfer: vi.fn(), + patchSalesIdRecipient: vi.fn(), + deleteTicketsTicketCodeCheckin: vi.fn(), + deleteEventsIdViewersViewerId: vi.fn(), + putStaffIdAccess: vi.fn(), + deleteContentLivesId: vi.fn(), + postEventDatesIdAccessClose: vi.fn(), + postSalesIdAbandon: vi.fn(), + deleteContentPostsId: vi.fn(), + deleteContentCommentsId: vi.fn(), + postContentChannelsIdArchive: vi.fn(), + postContentModerationMemberPostsIdReject: vi.fn(), + postContentModerationMemberPostsIdRemove: vi.fn(), + postContentMembersIdBan: vi.fn(), + postContentMeetupsIdCancel: vi.fn(), + deleteProductsId: vi.fn(), + deleteContentVideosId: vi.fn(), + deleteContentSeriesId: vi.fn(), + postContentLivesIdResetKey: vi.fn(), + deleteTicketTemplatesId: vi.fn(), + deleteMasterQrsId: vi.fn(), + postEventsIdViewers: vi.fn(), + postEventsIdValidators: vi.fn(), + postStaffIdResendInvite: vi.fn(), + postContentMeetupsIdPublish: vi.fn(), + patchContentMeetupsIdRsvpsRsvpId: vi.fn(), + postEventsIdArtistInvitationsInvitationIdResend: vi.fn(), + putEventsIdArtists: vi.fn(), + putContentVideosIdPublished: vi.fn(), + putWebsite: vi.fn(), + // Read by `events artists set` before it asks (who would drop out). + getEventsId: vi.fn(), deleteWorkspacesId: vi.fn(), })); +const { deleteWorkspacesId, ...b2b } = sdk; + vi.mock("./client/sdk.gen", async (importOriginal) => ({ ...(await importOriginal()), - postEventsIdCancel: sdk.postEventsIdCancel, - deleteStaffId: sdk.deleteStaffId, + ...b2b, })); vi.mock("./admin-client/sdk.gen", async (importOriginal) => ({ ...(await importOriginal()), - deleteWorkspacesId: sdk.deleteWorkspacesId, + deleteWorkspacesId, })); const { program } = await import("./program"); +/** A 200 the commands can print (lineup `set` reads `data.artists`). */ +const ok = () => ({ + data: { data: { artists: [] } }, + response: new Response(), +}); + describe("destructive commands refuse without a TTY and without --yes", () => { const tty = process.stdin.isTTY; let exit: MockInstance; @@ -43,9 +92,23 @@ describe("destructive commands refuse without a TTY and without --yes", () => { configurable: true, }); stderr = vi.spyOn(console, "error").mockImplementation(() => {}); + vi.spyOn(console, "log").mockImplementation(() => {}); + vi.spyOn(process.stdout, "write").mockImplementation(() => true); exit = vi.spyOn(process, "exit").mockImplementation((() => { throw new Error("exited"); }) as never); + // Credentials, so the only thing that can stop a command is the gate (the + // SDK is mocked: they never reach a network). Commands that configure the + // client before asking (`events artists set`) need them for the refusal. + vi.stubEnv("FT_API_KEY", "ft_test_key"); + vi.stubEnv("FT_ADMIN_SESSION", "test-session"); + for (const fn of Object.values(sdk)) fn.mockResolvedValue(ok()); + // The lineup already has org_1, so `set --artist org_1 --invite …` removes + // nobody: what it asks about is the invitation email alone. + sdk.getEventsId.mockResolvedValue({ + data: { data: { artists: [{ id: "org_1", name: "Artist One" }] } }, + response: new Response(), + }); }); afterEach(() => { @@ -54,14 +117,11 @@ describe("destructive commands refuse without a TTY and without --yes", () => { configurable: true, }); vi.restoreAllMocks(); + vi.unstubAllEnvs(); for (const fn of Object.values(sdk)) fn.mockReset(); }); - it.each([ - [["events", "cancel", "evt_1"], sdk.postEventsIdCancel], - [["staff", "delete", "stf_1"], sdk.deleteStaffId], - [["admin", "workspaces", "delete", "ws_1"], sdk.deleteWorkspacesId], - ])("ft %j exits 1 and never calls the SDK", async (args, fn) => { + it.each(CASES)("ft %j exits 1 and never calls the SDK", async (args, fn) => { await expect( program.parseAsync(["node", "ft", ...(args as string[])]), ).rejects.toThrow("exited"); @@ -70,4 +130,261 @@ describe("destructive commands refuse without a TTY and without --yes", () => { expect(stderr.mock.calls[0]?.[0]).toMatch(/^Refusing: .*no TTY to confirm/); expect(fn).not.toHaveBeenCalled(); }); + + it.each( + CASES, + )("ft %j --yes calls its SDK function exactly once", async (args, fn) => { + await program.parseAsync(["node", "ft", ...(args as string[]), "--yes"]); + expect(exit).not.toHaveBeenCalled(); + expect(fn).toHaveBeenCalledTimes(1); + }); + + it("covers every operation the contract marks x-ft-destructive", () => { + const spec = JSON.parse(readFileSync("openapi.json", "utf8")); + const destructive = Object.values(spec.paths).flatMap((ops) => + Object.values(ops as Record>) + .filter((op) => op?.["x-ft-destructive"] === true) + .map((op) => op.operationId as string), + ); + const gated = Object.entries(sdk) + .filter(([, fn]) => CASES.some(([, f]) => f === fn)) + .map(([name]) => name); + expect(destructive.length).toBeGreaterThan(0); + expect(destructive.filter((id) => !gated.includes(id))).toEqual([]); + }); +}); + +const CASES: [string[], (typeof sdk)[keyof typeof sdk]][] = [ + [["events", "cancel", "evt_1"], sdk.postEventsIdCancel], + [["staff", "delete", "stf_1"], sdk.deleteStaffId], + [["admin", "workspaces", "delete", "ws_1"], sdk.deleteWorkspacesId], + [ + ["events", "artists", "remove", "evt_1", "org_1"], + sdk.deleteEventsIdArtistsOrganizationId, + ], + [ + ["events", "invitations", "cancel", "evt_1", "inv_1"], + sdk.deleteEventsIdArtistInvitationsInvitationId, + ], + [["presale-windows", "delete", "pw_1"], sdk.deletePresaleWindowsId], + [ + ["sales", "transfer", "sale_1", "item_1", "--email", "a@b.co"], + sdk.postSalesIdItemsItemIdTransfer, + ], + [ + [ + "sales", + "recipient", + "set", + "sale_1", + "--name", + "Ana", + "--email", + "a@b.co", + ], + sdk.patchSalesIdRecipient, + ], + [["tickets", "checkin-undo", "TKT1"], sdk.deleteTicketsTicketCodeCheckin], + // Contracts 1.26-1.36. + [ + ["events", "viewers", "remove", "evt_1", "vw_1"], + sdk.deleteEventsIdViewersViewerId, + ], + [["staff", "access", "stf_1", "--type", "lectura"], sdk.putStaffIdAccess], + [ + ["event-dates", "access-close", "sign", "date_1"], + sdk.postEventDatesIdAccessClose, + ], + [["sales", "abandon", "sale_1"], sdk.postSalesIdAbandon], + [["content-lives", "delete", "live_1"], sdk.deleteContentLivesId], + [["content-lives", "reset-key", "live_1"], sdk.postContentLivesIdResetKey], + [["content-posts", "delete", "post_1"], sdk.deleteContentPostsId], + [["content-videos", "delete", "vid_1"], sdk.deleteContentVideosId], + [["content-series", "delete", "ser_1"], sdk.deleteContentSeriesId], + [["content-comments", "delete", "cmt_1"], sdk.deleteContentCommentsId], + [["content-channels", "archive", "ch_1"], sdk.postContentChannelsIdArchive], + [ + ["content-moderation", "reject", "post_1"], + sdk.postContentModerationMemberPostsIdReject, + ], + [ + ["content-moderation", "remove", "post_1"], + sdk.postContentModerationMemberPostsIdRemove, + ], + [ + ["content-members", "ban", "cus_1", "--comment", "cmt_1"], + sdk.postContentMembersIdBan, + ], + [["content-meetups", "cancel", "mt_1"], sdk.postContentMeetupsIdCancel], + [["products", "delete", "prd_1"], sdk.deleteProductsId], + [["ticket-templates", "delete", "tpl_1"], sdk.deleteTicketTemplatesId], + [["master-qrs", "delete", "mq_1"], sdk.deleteMasterQrsId], + // Not x-ft-destructive, but they send email or notify a whole community: + // same gate, so a script cannot fire them by accident. + [ + ["events", "viewers", "add", "evt_1", "--email", "a@b.co"], + sdk.postEventsIdViewers, + ], + [ + [ + "events", + "validators", + "add", + "evt_1", + "--name", + "Ana", + "--email", + "a@b.co", + ], + sdk.postEventsIdValidators, + ], + [["staff", "resend-invite", "stf_1"], sdk.postStaffIdResendInvite], + [["content-meetups", "publish", "mt_1"], sdk.postContentMeetupsIdPublish], + [ + ["content-meetups", "rsvp", "mt_1", "rsvp_1", "--approve"], + sdk.patchContentMeetupsIdRsvpsRsvpId, + ], + [ + ["events", "invitations", "resend", "evt_1", "inv_1"], + sdk.postEventsIdArtistInvitationsInvitationIdResend, + ], + [ + [ + "events", + "artists", + "set", + "evt_1", + "--artist", + "org_1", + "--invite", + "a@b.co", + ], + sdk.putEventsIdArtists, + ], + [["content-videos", "publish", "vid_1"], sdk.putContentVideosIdPublished], + // Not an email, but a FULL replace: a partial --data wipes the rest. + [["website", "set", "--data", '{"sections":[]}'], sdk.putWebsite], +]; + +/** Every leaf of the command tree, as `"events artists set"`. */ +function leaves(cmd: Command, path: string[] = []): [string, Command][] { + if (cmd.commands.length === 0) return [[path.join(" "), cmd]]; + return cmd.commands.flatMap((sub) => leaves(sub, [...path, sub.name()])); +} +/** The command path that argv resolves to (subcommand names, no args). */ +function commandPath(args: string[]): string { + const path: string[] = []; + let cmd: Command = program; + for (const arg of args) { + const sub = cmd.commands.find( + (c) => c.name() === arg || c.aliases().includes(arg), + ); + if (!sub) break; + path.push(sub.name()); + cmd = sub; + } + return path.join(" "); +} +const hasYes = (cmd: Command) => cmd.options.some((o) => o.long === "--yes"); + +/** + * Writes that notify someone and still run without asking, on purpose. If one + * of them gains a gate, or disappears, the sweep below fails and this list is + * revisited instead of rotting. + */ +const UNGATED_ON_PURPOSE: Record = { + "content-moderation approve": + "approving IS the reviewer's decision, and --expected-updated-at already pins the exact version read; the author's notification is the point", + "tickets resend": + "one email to the ticket's own buyer, the same QR again: the command exists to send it", + "content-posts create": + "the --data body is the message itself; with community_v2 members are notified like in the dashboard (no draft step to confirm separately)", + "products update": + "only new lessons on a published course notify its buyers, like the dashboard; the body is a full tree read just before", +}; + +describe("confirmation gates across the whole command tree", () => { + it("exactly these commands accept --yes", () => { + // A new destructive or notifying command that forgets its gate, or a gate + // dropped by a refactor, changes this list: update it on purpose. + expect( + leaves(program) + .filter(([, cmd]) => hasYes(cmd)) + .map(([path]) => path) + .sort(), + ).toEqual([ + "admin feature-flags set", + "admin impersonate", + "admin tokens revoke", + "admin workspaces delete", + "admin workspaces plan", + "admin workspaces plan-show", + "admin workspaces restore", + "admin workspaces suspend", + "api-keys revoke", + "content-channels archive", + "content-comments delete", + "content-lives delete", + "content-lives reset-key", + "content-meetups cancel", + "content-meetups publish", + "content-meetups rsvp", + "content-members ban", + "content-moderation reject", + "content-moderation remove", + "content-posts delete", + "content-series delete", + "content-videos delete", + "content-videos publish", + "discounts delete", + "event-dates access-close sign", + "event-dates delete", + "events artists remove", + "events artists set", + "events cancel", + "events delete", + "events invitations cancel", + "events invitations resend", + "events validators add", + "events viewers add", + "events viewers remove", + "master-qrs delete", + "plans delete", + "presale-windows delete", + "products delete", + "sales abandon", + "sales recipient set", + "sales transfer", + "staff access", + "staff delete", + "staff resend-invite", + "ticket-templates delete", + "ticket-types delete", + "tickets checkin-undo", + "venues delete", + "webhooks delete", + "website set", + ]); + }); + + it("every CASES row is a gated command of the tree", () => { + const gated = new Set( + leaves(program) + .filter(([, cmd]) => hasYes(cmd)) + .map(([path]) => path), + ); + const rows = CASES.map(([args]) => commandPath(args)); + expect(rows.filter((r) => !gated.has(r))).toEqual([]); + }); + + it.each( + Object.entries(UNGATED_ON_PURPOSE), + )("%s still exists and still runs without a gate", (path) => { + const leaf = leaves(program).find(([p]) => p === path); + expect( + leaf, + `${path} is gone: drop it from UNGATED_ON_PURPOSE`, + ).toBeDefined(); + expect(hasYes(leaf?.[1] as Command)).toBe(false); + }); }); diff --git a/src/lib/input.ts b/src/lib/input.ts index d24d607..ea3b40f 100644 --- a/src/lib/input.ts +++ b/src/lib/input.ts @@ -9,7 +9,8 @@ import { fail } from "./api"; */ export function parseLimit(input: string): number { const n = Number(input); - if (!Number.isInteger(n) || n < 1 || n > 100) + // The regex too: Number() also takes "5.0", "1e1" and " 20". + if (!/^\d+$/.test(input) || n < 1 || n > 100) fail( `Invalid --limit: ${input}. Use an integer from 1 to 100.`, "For more rows, add --all to walk every page.", @@ -17,6 +18,55 @@ export function parseLimit(input: string): number { return n; } +/** + * Commander option parsers for typed flags. They run while commander parses + * argv, so a bad value exits 1 before any confirmation prompt or request. + * + * `Number()` was not enough: `Number("50.000") === 50` turned a COP price + * typed with a thousands separator into fifty pesos, and `Number("abc")` is + * NaN, which `JSON.stringify` sends as `null` (a capacity cleared by a typo). + * Booleans were `v === "true"`, so `--active yes` silently meant false. + */ +export function wholeNumber(flag: string): (input: string) => number { + return (input) => { + if (!/^\d+$/.test(input)) + fail( + `Invalid ${flag}: ${input}. Use a whole number with no separators or decimals (e.g. 50000).`, + ); + return Number(input); + }; +} + +/** + * `wholeNumber`, or `"none"` to clear a nullable field. Returns `"none"`, not + * null: commander turns a parser's null into "" (map it with `noneToNull`). + */ +export function wholeNumberOrNone( + flag: string, +): (input: string) => number | "none" { + return (input) => { + if (input === "none") return "none"; + if (!/^\d+$/.test(input)) + fail( + `Invalid ${flag}: ${input}. Use a whole number with no separators or decimals (e.g. 50000), or "none".`, + ); + return Number(input); + }; +} + +/** The body value of a `wholeNumberOrNone` flag. */ +export const noneToNull = (v: T | "none"): T | null => + v === "none" ? null : v; + +/** `"true"` / `"false"` only; anything else (yes, 1, si) exits 1. */ +export function booleanFlag(flag: string): (input: string) => boolean { + return (input) => { + if (input !== "true" && input !== "false") + fail(`Invalid ${flag}: ${input}. Use true or false.`); + return input === "true"; + }; +} + /** * Parses a `--data` value into a JSON body. Accepts inline JSON (`'{"x":1}'`) * or `@path/to/file.json` to read from disk. Aborts on missing/invalid input. diff --git a/src/program.ts b/src/program.ts index 93cd02d..dd523af 100644 --- a/src/program.ts +++ b/src/program.ts @@ -2,17 +2,26 @@ import { Command } from "commander"; // Version synced with package.json at build time (tsup injects it via import). import pkg from "../package.json" with { type: "json" }; import { + deleteContentLivesId, + deleteContentPostsId, + deleteContentSeriesId, + deleteContentVideosId, deleteDiscountsId, deleteEventsId, deleteEventsIdDatesDateId, + deleteMasterQrsId, deleteMembershipPlansId, + deleteProductsId, deleteStaffId, + deleteTicketTemplatesId, deleteTicketTypesId, deleteVenuesId, deleteWebhooksId, getContentLives, getContentLivesId, + getContentMeetupsId, getContentPosts, + getContentSeries, getContentVideos, getDiscounts, getEvents, @@ -21,6 +30,7 @@ import { getMembershipPlans, getMembershipPlansId, getMembershipPlansIdSubscribers, + getProductsId, getSales, getSalesId, getSalesIdAttempts, @@ -35,27 +45,44 @@ import { getVenuesId, getWaitlist, getWebhooks, + patchContentChannelsId, + patchContentLivesId, + patchContentMeetupsId, + patchContentPostsId, + patchContentSeriesId, + patchContentVideosId, patchDiscountsId, patchEventsId, patchEventsIdDatesDateId, patchMembershipPlansId, + patchProductsId, patchStaffIdRole, + patchTicketTemplatesId, patchTicketTypesId, patchVenuesId, patchWebhooksId, + postContentChannels, + postContentChannelsIdArchive, + postContentLives, + postContentMeetups, + postContentMeetupsIdCancel, postContentPlaybackToken, postContentPosts, + postContentSeries, postDiscounts, postEvents, postEventsIdCancel, postEventsIdDates, postEventsIdPublish, postMembershipPlans, + postProducts, postSales, + postSalesIdAbandon, postSalesIdCancel, postSalesIdRefund, postStaff, postSubscriptionsIdCancel, + postTicketTemplates, postTicketTypes, postVenues, postWaitlist, @@ -65,9 +92,41 @@ import { registerAccount } from "./commands/account"; import { registerAdmin } from "./commands/admin"; import { registerApiKeys } from "./commands/api-keys"; import { registerAuth } from "./commands/auth"; +import { + extendMasterQrs, + extendTicketTemplates, + registerAccessClose, + registerEventAccess, + registerLiveAttendance, + registerPaymentIntents, + registerStaffAccess, +} from "./commands/box-office"; +import { + extendContentChannels, + extendContentLives, + extendContentMeetups, + extendContentPosts, + extendContentSeries, + extendContentVideos, + registerModeration, +} from "./commands/community"; import { registerEventDates } from "./commands/event-dates"; +import { registerArtists, registerEventLineup } from "./commands/lineup"; +import { + registerCheckinUndo, + registerCourtesySeats, + registerEventSchedule, + registerPresaleWindows, + registerSaleOps, +} from "./commands/ops"; import { registerReports } from "./commands/reports"; import { registerResource } from "./commands/resource"; +import { + extendProducts, + registerMerch, + registerOrganization, + registerWebsite, +} from "./commands/storefront"; import { registerTickets } from "./commands/tickets"; import { registerWorkspace } from "./commands/workspace"; import { @@ -77,7 +136,7 @@ import { unwrap, } from "./lib/api"; import { banner } from "./lib/banner"; -import { parseData } from "./lib/input"; +import { booleanFlag, parseData } from "./lib/input"; import { print } from "./lib/output"; /** @@ -132,8 +191,15 @@ registerResource(program, { query: "withTotal", }, ], + extend: (root) => { + registerEventLineup(root); + registerEventSchedule(root); + registerEventAccess(root); + }, }); +registerArtists(program); + // Read-only: settlements are created by FreeTicket, never by the organizer. // The PDF and the payment proofs download through `ft settlements document` // (contract 1.7.0): the API answers 302 with a 5-minute signed URL. @@ -212,6 +278,15 @@ registerResource(program, { "Payment attempt history of a sale (declines, approvals, refunds)", fn: getSalesIdAttempts, }, + { + // PENDING sale whose payment never started -> ABANDONED (terminal); its + // stock goes back on sale. Confirmed sales use `cancel` (contract 1.30). + name: "abandon", + describe: + "Mark a pending sale as abandoned and release its stock (terminal)", + fn: postSalesIdAbandon, + confirm: true, + }, ], columns: ["id", "reference", "status", "total", "currency", "createdAt"], listFlags: [ @@ -244,6 +319,10 @@ registerResource(program, { }, { flag: "--to ", describe: "created to (ISO 8601)", query: "to" }, ], + extend: (root) => { + registerSaleOps(root); + registerPaymentIntents(root); + }, }); registerResource(program, { @@ -296,6 +375,7 @@ registerResource(program, { flag: "--active ", describe: "filter by active (true/false)", query: "active", + parse: booleanFlag("--active"), }, ], }); @@ -352,6 +432,7 @@ registerResource(program, { }, ], columns: ["id", "name", "email", "role", "workspaceName"], + extend: registerStaffAccess, listFlags: [ { flag: "--workspace-ids ", @@ -371,7 +452,22 @@ registerResource(program, { name: "content-videos", describe: "Organization videos", list: getContentVideos, + update: patchContentVideosId, + del: deleteContentVideosId, columns: ["id", "title", "publishedAt", "memberOnly"], + extend: extendContentVideos, +}); + +registerResource(program, { + name: "content-series", + describe: "Video series", + list: getContentSeries, + create: postContentSeries, + update: patchContentSeriesId, + // Deleting a series keeps its videos (they move out of it). + del: deleteContentSeriesId, + columns: ["id", "title", "published", "videoCount", "memberOnly"], + extend: extendContentSeries, }); registerResource(program, { @@ -381,7 +477,10 @@ registerResource(program, { // type=ARTICLE needs title + body (Markdown); TEXT/IMAGE need content or // imageUrl. Minimum role ADMIN (contract 1.19). create: postContentPosts, + update: patchContentPostsId, + del: deleteContentPostsId, columns: ["id", "title", "publishedAt", "memberOnly"], + extend: extendContentPosts, }); registerResource(program, { @@ -389,8 +488,13 @@ registerResource(program, { describe: "Organization live streams", list: getContentLives, get: getContentLivesId, + // create answers the RTMPS server and the SECRET stream key, once. + create: postContentLives, + update: patchContentLivesId, + del: deleteContentLivesId, columns: ["id", "title", "status", "startsAt", "memberOnly"], extend: (root) => { + extendContentLives(root); root .command("playback-token") .description( @@ -411,6 +515,76 @@ registerResource(program, { }, }); +registerResource(program, { + name: "content-channels", + describe: "Community channels", + create: postContentChannels, + update: patchContentChannelsId, + actions: [ + { + name: "archive", + describe: "Archive a channel (no unarchive; its posts stay under All)", + fn: postContentChannelsIdArchive, + confirm: true, + }, + ], + extend: extendContentChannels, +}); + +registerResource(program, { + name: "content-meetups", + describe: "Community meetups", + get: getContentMeetupsId, + create: postContentMeetups, + update: patchContentMeetupsId, + actions: [ + { + name: "cancel", + describe: "Cancel a meetup (confirmed members are notified by email)", + fn: postContentMeetupsIdCancel, + confirm: true, + }, + ], + extend: extendContentMeetups, +}); + +registerModeration(program); + +registerResource(program, { + name: "products", + describe: "Digital products and courses", + get: getProductsId, + create: postProducts, + update: patchProductsId, + del: deleteProductsId, + extend: extendProducts, +}); + +// Master box-office QRs (contract 1.33): one printed QR opens the sale flow of +// an event (or of today's shows). `code`/`url` are secret and never rotate, so +// list/create/update live in extendMasterQrs, which redacts them. +registerResource(program, { + name: "master-qrs", + describe: "Master box-office QR codes", + del: deleteMasterQrsId, + extend: extendMasterQrs, +}); + +registerResource(program, { + name: "ticket-templates", + describe: "Reusable ticket type templates", + create: postTicketTemplates, + update: patchTicketTemplatesId, + del: deleteTicketTemplatesId, + extend: extendTicketTemplates, +}); + +registerOrganization(program); +registerWebsite(program); +registerMerch(program); + +registerPresaleWindows(program); + // Per-city waitlist of an enterprise landing (contract 1.24). `list` is the // staff export (ADMIN, personal data); `create` needs an enterprise service key. registerResource(program, { @@ -429,7 +603,14 @@ registerResource(program, { }); registerTickets(program); +// Commands added to existing families (contract 1.25.0, see commands/ops.ts). +const family = (name: string) => + program.commands.find((c) => c.name() === name) as Command; +registerCheckinUndo(family("tickets")); +registerCourtesySeats(family("event-dates")); +registerAccessClose(family("event-dates")); registerReports(program); +registerLiveAttendance(family("reports")); registerApiKeys(program); registerAdmin(program); diff --git a/src/test/setup.test.ts b/src/test/setup.test.ts new file mode 100644 index 0000000..8634786 --- /dev/null +++ b/src/test/setup.test.ts @@ -0,0 +1,17 @@ +import { homedir, tmpdir } from "node:os"; +import { describe, expect, it } from "vitest"; + +/** The global guard of src/test/setup.ts is actually wired (vitest.config.ts). */ +describe("test setup guard", () => { + it("fetch throws instead of reaching the network", async () => { + await expect( + fetch("https://admin.appfreeticket.com/api/v1/me"), + ).rejects.toThrow(/Unexpected network call in a test/); + }); + + it("HOME is a temp dir and FT_API_URL a closed local port", () => { + expect(homedir().startsWith(tmpdir())).toBe(true); + expect(process.env.FT_API_URL).toBe("http://127.0.0.1:9"); + expect(process.env.FT_API_KEY).toBeUndefined(); + }); +}); diff --git a/src/test/setup.ts b/src/test/setup.ts new file mode 100644 index 0000000..5e2efb5 --- /dev/null +++ b/src/test/setup.ts @@ -0,0 +1,32 @@ +import { mkdtempSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +/** + * Global guard for every test file (vitest `setupFiles`, runs before the file + * imports anything): + * + * - `HOME` points at a fresh temp dir, so `~/.freeticket/config.json` (and the + * update-check cache) are never the developer's real accounts. config.ts + * reads `homedir()` at import time, which is why this has to run first. + * - `FT_API_URL` is a closed local port, and the FT_* credentials of the shell + * are dropped: a test that forgets to mock still cannot authenticate against + * a real backend. + * - `fetch` throws. A test that needs the network stubs it (`vi.stubGlobal`, + * or a `fetch` in the client config); restoring the stub comes back here, + * not to the real fetch. + */ +const home = mkdtempSync(join(tmpdir(), "ft-cli-test-")); +process.env.HOME = home; +process.env.USERPROFILE = home; +process.env.FT_API_URL = "http://127.0.0.1:9"; +for (const name of ["FT_API_KEY", "FT_WORKSPACE_ID", "FT_ADMIN_SESSION"]) + delete process.env[name]; +process.env.FT_NO_UPDATE_CHECK = "1"; + +globalThis.fetch = (async (input: unknown) => { + const url = input instanceof Request ? input.url : String(input); + throw new Error( + `Unexpected network call in a test: ${url}. Stub fetch (vi.stubGlobal) or mock the SDK.`, + ); +}) as typeof fetch; diff --git a/vitest.config.ts b/vitest.config.ts new file mode 100644 index 0000000..3f5eec5 --- /dev/null +++ b/vitest.config.ts @@ -0,0 +1,8 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + // Network and filesystem guard for every test file (see the file). + setupFiles: ["src/test/setup.ts"], + }, +});