diff --git a/.changeset/merch-products.md b/.changeset/merch-products.md new file mode 100644 index 0000000..26fbaf8 --- /dev/null +++ b/.changeset/merch-products.md @@ -0,0 +1,5 @@ +--- +"@freeticket/cli": minor +--- + +`ft merch products list|create|publish|unpublish` (contrato 1.38): carga productos de la tienda de merch sin el panel. `create` arma una variante por talla (`--sizes`), sube las fotos locales (`--image`, repetible) por la URL firmada y acepta `--from-json` para varios productos en una corrida. `ft merch products images ` repara las fotos de un producto; con `--json`, `create` devuelve `{ created, failed }`. diff --git a/README.md b/README.md index ca836f5..591dc41 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,10 @@ ft sales list --status CONFIRMED --json | `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 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 merch products list` | Merch store products of the workspace's organization, DRAFT and PUBLISHED, with variants (Legend plan) | ADMIN / MERCH_MANAGER | +| `ft merch products create` | Create product(s) as DRAFT: `--name` `--price ` `--sizes XS,S,M` `--stock ` `--image ` (repeatable, uploaded through a signed URL) `--publish`; `--from-json ` for several (image paths relative to the file, no symlinks). The whole batch is validated first; `--json` prints `{ created, failed }` | ADMIN / MERCH_MANAGER | +| `ft merch products images --image …` | Replace a product's photos with local files (repairs a partial `create`) | ADMIN / MERCH_MANAGER | +| `ft merch products publish ` · `unpublish ` | Show / hide a product in the store (publishing needs the store setup done and an active variant) | ADMIN / MERCH_MANAGER | | `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 | diff --git a/openapi.json b/openapi.json index 6c277ee..390d618 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.38.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,611 +11410,16560 @@ } } } - } - } - }, - "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/products": { + "get": { + "operationId": "getMerchProducts", + "tags": [ + "merch" + ], + "summary": "List the merch store's products (all statuses)", + "description": "Roles: `ADMIN`, `SUPER_ADMIN` or `MERCH_MANAGER` in the active workspace (`X-Workspace-Id`). The store is ALWAYS the one of the workspace's organization. Returns every non-deleted product, DRAFT and PUBLISHED, with its non-deleted variants (active or not), in display order. Prices are COP integers, VAT included; `stock` is the units available right now.\n\nErrors (`error.code`):\n- 403 `FORBIDDEN`: the key's role cannot manage the store catalog (allowed: `ADMIN`, `SUPER_ADMIN`, `MERCH_MANAGER`).\n- 403 `MERCH_STORE_LOCKED`: the brand's settlement workspace has no active Legend plan.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `STORE_NOT_FOUND`: the workspace's organization has no merch store yet (it is created from the dashboard).", + "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/MerchAdminProduct" + } + } + }, + "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" + } + } + } + } + } + }, + "post": { + "operationId": "postMerchProducts", + "tags": [ + "merch" + ], + "summary": "Create a merch product with its options and variants", + "description": "Roles: `ADMIN`, `SUPER_ADMIN` or `MERCH_MANAGER` (write key). Same action as the dashboard's product creator: the product, its options and the FULL variant matrix are created in one transaction (all or nothing). The product is ALWAYS created as `DRAFT`; publish it with `PATCH /merch/products/{id}/status`. The variant labels are built by the server from the options. Photos: upload them first with `POST /merch/products/images/upload-url` and pass the `publicUrl`s in `imageUrls`, or set them afterwards with `PUT /merch/products/{id}/images`. Returns the created product.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: a dashboard rule failed (variants that do not match the options, repeated SKU, `compareAtPrice` not greater than `price`, invalid slug or SKU characters…); `message` says which.\n- 409 `SLUG_TAKEN`: the slug already exists in the store.\n- 409 `SKU_TAKEN`: a SKU is already used by another product of the store.\n- 422 `INVALID_IMAGE_URL`: an image URL is not a photo uploaded for this organization.\n- 403 `FORBIDDEN`: the key's role cannot manage the store catalog (allowed: `ADMIN`, `SUPER_ADMIN`, `MERCH_MANAGER`).\n- 403 `MERCH_STORE_LOCKED`: the brand's settlement workspace has no active Legend plan.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `STORE_NOT_FOUND`: the workspace's organization has no merch store yet (it is created from the dashboard).", + "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/MerchProductCreate" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MerchAdminProduct" + } + }, + "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": "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" + } + } + } + } + } + } + }, + "/merch/products/{id}/status": { + "patch": { + "operationId": "patchMerchProductsIdStatus", + "tags": [ + "merch" + ], + "summary": "Publish or unpublish a merch product", + "description": "Roles: `ADMIN`, `SUPER_ADMIN` or `MERCH_MANAGER` (write key). Same rules as the dashboard: idempotent (setting the current status is a no-op 200); publishing requires the store onboarding to be complete and at least one active variant. A PUBLISHED product shows up in `GET /merch/catalog`; `DRAFT` hides it (existing orders are kept).\n\nErrors (`error.code`):\n- 404 `PRODUCT_NOT_FOUND`: no such product in this store.\n- 409 `STORE_NOT_ONBOARDED`: finish the store setup in the dashboard before publishing.\n- 409 `NO_ACTIVE_VARIANT`: the product has no active variant.\n- 403 `FORBIDDEN`: the key's role cannot manage the store catalog (allowed: `ADMIN`, `SUPER_ADMIN`, `MERCH_MANAGER`).\n- 403 `MERCH_STORE_LOCKED`: the brand's settlement workspace has no active Legend plan.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `STORE_NOT_FOUND`: the workspace's organization has no merch store yet (it is created from the dashboard).", + "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/MerchProductStatusUpdate" + } + } + } + }, + "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": "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" + } + } + } + } + } + } + }, + "/merch/products/{id}/images": { + "put": { + "operationId": "putMerchProductsIdImages", + "tags": [ + "merch" + ], + "summary": "Set the ordered photos of a merch product", + "description": "Roles: `ADMIN`, `SUPER_ADMIN` or `MERCH_MANAGER` (write key). Replaces the product's photos with `imageUrls` (in order; the first is the cover; max 10, no repeats). Each URL must be a `publicUrl` returned by `POST /merch/products/images/upload-url` for this organization, or one the product already has: the server never downloads an external URL. Photos removed from the list are deleted from storage. `[]` clears them.\n\nErrors (`error.code`):\n- 400 `BAD_REQUEST`: more than 10 photos, repeated or malformed URLs.\n- 404 `PRODUCT_NOT_FOUND`: no such product in this store.\n- 422 `INVALID_IMAGE_URL`: a URL is not a photo uploaded for this organization.\n- 403 `FORBIDDEN`: the key's role cannot manage the store catalog (allowed: `ADMIN`, `SUPER_ADMIN`, `MERCH_MANAGER`).\n- 403 `MERCH_STORE_LOCKED`: the brand's settlement workspace has no active Legend plan.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `STORE_NOT_FOUND`: the workspace's organization has no merch store yet (it is created from the dashboard).", + "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/MerchProductImagesUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "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": "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/products/images/upload-url": { + "post": { + "operationId": "postMerchProductsImagesUploadUrl", + "tags": [ + "merch" + ], + "summary": "Get a signed upload URL for a merch product photo", + "description": "Roles: `ADMIN`, `SUPER_ADMIN` or `MERCH_MANAGER` (write key). Returns a single-use signed `uploadUrl` in the organization's merch folder and the photo's final `publicUrl`. Flow: call this, `PUT` the file bytes to `uploadUrl` with header `Content-Type: ` (no Authorization header), then pass `publicUrl` in `imageUrls` of `POST /merch/products` or `PUT /merch/products/{id}/images`. JPG, PNG or WebP, up to 6 MB. Rate limited to 30 URLs per 5 minutes per user (shared with the dashboard).\n\nErrors (`error.code`):\n- 429 `RATE_LIMITED`: too many uploads; retry after `Retry-After`.\n- 502 `UPLOAD_URL_FAILED`: storage did not sign the URL; retry.\n- 403 `FORBIDDEN`: the key's role cannot manage the store catalog (allowed: `ADMIN`, `SUPER_ADMIN`, `MERCH_MANAGER`).\n- 403 `MERCH_STORE_LOCKED`: the brand's settlement workspace has no active Legend plan.\n- 403 `EVENT_SCOPE_FORBIDDEN`: the key is restricted to specific events.\n- 404 `STORE_NOT_FOUND`: the workspace's organization has no merch store yet (it is created from the dashboard).", + "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/MerchImageUploadRequest" + } + } + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MerchImageUpload" + } + }, + "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" + } + } + } + }, + "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" + } + } + } + } + } + } + }, + "/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": { - "type": "string" - }, - "message": { + "id": { "type": "string" }, - "field": { + "code": { "type": "string" }, - "activeWorkspaceId": { - "type": "string" + "type": { + "$ref": "#/components/schemas/DiscountType" }, - "activeWorkspaceName": { - "type": "string" + "value": { + "type": "number" }, - "accessibleWorkspaces": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "eventId": { + "type": [ + "string", + "null" + ] }, - "suggestedWorkspaceId": { - "type": "string" + "active": { + "type": "boolean" }, - "suggestedWorkspaceName": { - "type": "string" - } - }, - "required": [ - "code", - "message" - ], - "additionalProperties": false - }, - "Page": { - "type": "object", - "properties": { - "nextCursor": { + "maxUses": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "hasMore": { - "type": "boolean" - }, - "total": { + "uses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 - } - }, - "required": [ - "nextCursor", - "hasMore" - ], - "additionalProperties": false - }, - "Workspace": { - "type": "object", - "properties": { - "id": { - "type": "string" }, - "name": { - "type": "string" + "startsAt": { + "type": [ + "string", + "null" + ] }, - "slug": { + "endsAt": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { "type": "string" } }, "required": [ "id", - "name", - "slug" + "code", + "type", + "value", + "eventId", + "active", + "maxUses", + "uses", + "startsAt", + "endsAt", + "createdAt" ], "additionalProperties": false }, - "WorkspaceAccess": { + "DiscountCreate": { "type": "object", "properties": { - "id": { - "type": "string" + "code": { + "type": "string", + "minLength": 1 }, - "name": { - "type": "string" + "type": { + "$ref": "#/components/schemas/DiscountType" }, - "slug": { - "type": "string" + "value": { + "type": "number", + "exclusiveMinimum": 0 }, - "role": { - "type": "string", - "enum": [ - "SUPER_ADMIN", - "ADMIN", - "STAFF", - "VIEWER", - "MINCULTURA" - ], - "description": "The user's effective role IN THIS workspace." + "eventId": { + "anyOf": [ + { + "type": "string", + "minLength": 1 + }, + { + "type": "null" + } + ] + }, + "maxUses": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "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" + } + ] }, - "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" + "code", + "type", + "value" ], "additionalProperties": false }, - "Me": { + "DiscountUpdate": { "type": "object", "properties": { - "userId": { - "type": "string" - }, - "name": { - "type": "string" + "active": { + "type": "boolean" }, - "email": { - "type": "string" + "value": { + "type": "number", + "exclusiveMinimum": 0 }, - "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." + "maxUses": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] }, - "activeWorkspaceId": { + "startsAt": { "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" } ] }, - "workspaces": { - "type": "array", - "items": { - "$ref": "#/components/schemas/WorkspaceAccess" - } + "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": [ - "userId", - "name", - "email", - "role", - "activeWorkspaceId", - "workspaces" - ], "additionalProperties": false }, - "SignupRequest": { + "Webhook": { "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 + "id": { + "type": "string" }, - "workspaceName": { - "type": "string", - "minLength": 2, - "maxLength": 80 - } - }, - "required": [ - "email", - "name" - ], - "additionalProperties": false - }, - "SignupResponse": { - "type": "object", - "properties": { - "user_id": { + "url": { "type": "string" }, - "status": { - "type": "string", - "const": "pending_verification" + "events": { + "type": "array", + "items": { + "type": "string" + } }, - "verification_sent_to": { + "active": { + "type": "boolean" + }, + "lastDeliveryAt": { + "type": [ + "string", + "null" + ] + }, + "lastDeliveryStatus": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "failureCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "createdAt": { + "type": "string" + }, + "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" + } + }, + "required": [ + "id", + "ticketCode", + "ticketTypeId", + "ticketTypeName", + "quantity", + "seatLabel", + "checkedInAt", + "refundedAt", + "refundAmount", + "seatBlocked" + ], + "additionalProperties": false + }, + "PaymentAttempt": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "organizationId": { - "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" ] }, - "seatsioChartKey": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "declineReason": { + "type": [ + "string", + "null" + ] + }, + "amount": { + "type": [ + "number", + "null" ] }, - "createdAt": { + "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 + }, + "ticketTypeId": { + "type": "string", + "minLength": 1 + }, + "seatLabel": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false + }, + "ResendTicket": { + "type": "object", + "properties": { + "ticketCode": { + "type": "string" + }, + "sentTo": { + "type": "string" + }, + "sentAt": { "type": "string" } }, "required": [ - "id", - "name", - "slug", - "address", - "city", - "country", - "latitude", - "longitude", - "capacity", - "googlePlaceId", - "portalVisible", - "organizationId", - "seatsioChartKey", - "createdAt" + "ticketCode", + "sentTo", + "sentAt" ], "additionalProperties": false }, - "EventNextDate": { + "CheckinResult": { "type": "object", "properties": { - "id": { + "ticketCode": { "type": "string" }, - "label": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "checkedInAt": { + "type": [ + "string", + "null" ] }, - "startsAt": { - "type": "string" + "checkedInBy": { + "type": [ + "string", + "null" + ] }, - "endsAt": { + "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" } ] - }, - "timezone": { + } + }, + "additionalProperties": false + }, + "CheckinUndoResult": { + "type": "object", + "properties": { + "ticketCode": { "type": "string" }, - "status": { - "type": "string", - "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" + "undone": { + "type": "boolean", + "description": "true when this call reverted the check-in; false when the ticket was not checked in (idempotent no-op)." + }, + "previousCheckedInAt": { + "type": [ + "string", + "null" + ] + }, + "previousCheckedInBy": { + "type": [ + "string", + "null" ] } }, "required": [ - "id", - "label", - "startsAt", - "endsAt", - "timezone", - "status" + "ticketCode", + "undone", + "previousCheckedInAt", + "previousCheckedInBy" ], "additionalProperties": false }, - "EventArtist": { + "TicketAccess": { "type": "object", "properties": { - "id": { + "ticketCode": { "type": "string" }, - "name": { - "type": "string" + "valid": { + "type": "boolean" }, - "slug": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "status": { + "type": "string", + "enum": [ + "VALID", + "USED", + "INVALID" ] }, - "type": { + "saleStatus": { "type": "string", "enum": [ - "ARTIST", - "VENUE", - "ORGANIZER" + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] + }, + "eventId": { + "type": "string" + }, + "eventName": { + "type": "string" + }, + "eventDateId": { + "type": "string" + }, + "startsAt": { + "type": "string" + }, + "ticketTypeName": { + "type": "string" + }, + "checkedInAt": { + "type": [ + "string", + "null" ] } }, "required": [ - "id", - "name", - "slug", - "type" + "ticketCode", + "valid", + "status", + "saleStatus", + "eventId", + "eventName", + "eventDateId", + "startsAt", + "ticketTypeName", + "checkedInAt" ], "additionalProperties": false }, - "Event": { + "ApiKeyScope": { + "type": "string", + "enum": [ + "read", + "write" + ] + }, + "ApiKey": { "type": "object", "properties": { "id": { @@ -12347,569 +27972,644 @@ "name": { "type": "string" }, - "slug": { - "type": "string" - }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "scope": { + "$ref": "#/components/schemas/ApiKeyScope" }, - "status": { - "type": "string", - "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" - ] + "keyPrefix": { + "type": "string" }, - "coverImageUrl": { + "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" } ] }, - "bannerImageUrl": { + "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" } ] }, - "squareImageUrl": { + "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" } ] }, - "storyImageUrl": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "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))$" + } + }, + "required": [ + "id", + "name", + "scope", + "keyPrefix", + "lastUsedAt", + "expiresAt", + "revokedAt", + "createdAt" + ], + "additionalProperties": false + }, + "ApiKeyCreated": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "organizationId": { + "name": { "type": "string" }, - "venueId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "scope": { + "$ref": "#/components/schemas/ApiKeyScope" }, - "venue": { + "keyPrefix": { + "type": "string" + }, + "lastUsedAt": { "anyOf": [ { - "$ref": "#/components/schemas/Venue" + "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" } ] }, - "externalTicketUrl": { + "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" } ] }, - "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": { + "revokedAt": { "anyOf": [ { - "$ref": "#/components/schemas/EventNextDate" + "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" } ] }, - "artists": { - "type": "array", - "items": { - "$ref": "#/components/schemas/EventArtist" - } - }, "createdAt": { - "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))$" }, - "updatedAt": { + "key": { "type": "string" } }, "required": [ "id", "name", - "slug", - "description", - "status", - "coverImageUrl", - "bannerImageUrl", - "squareImageUrl", - "storyImageUrl", - "organizationId", - "venueId", - "venue", - "externalTicketUrl", - "access", + "scope", + "keyPrefix", + "lastUsedAt", + "expiresAt", + "revokedAt", "createdAt", - "updatedAt" + "key" ], "additionalProperties": false }, - "TicketPriceStage": { + "ApiKeyCreate": { "type": "object", "properties": { - "id": { - "type": "string" - }, "name": { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 120 }, - "price": { - "type": "number" + "scope": { + "default": "read", + "$ref": "#/components/schemas/ApiKeyScope" }, - "sortOrder": { + "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 - }, - "endsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Closes once this date passes (ISO 8601). null = no date cutoff." + "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,}$" }, - "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." + "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/*." }, - "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." + "expires_in": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Session lifetime, in seconds." } }, "required": [ - "id", - "name", - "price", - "sortOrder", - "endsAt", - "quantity", - "isCurrent" + "session_token", + "expires_in" ], "additionalProperties": false }, - "TicketType": { + "CustomerMe": { "type": "object", "properties": { "id": { "type": "string" }, - "eventDateId": { + "email": { "type": "string" }, "name": { "type": "string" }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "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": { + "emailVerified": { "type": "boolean" }, - "maxPerOrder": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "saleStartsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "saleEndsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "isVisible": { - "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" }, - "organizerAbsorbsFee": { - "type": "boolean" + "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" + "email": { + "type": "string" + }, + "name": { + "type": "string" + }, + "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." }, - "doorsOpenAt": { + "membership": { "anyOf": [ { - "type": "string" + "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." }, - "timezone": { + "planId": { + "type": "string" + } + }, + "required": [ + "checkoutUrl", + "planId" + ], + "additionalProperties": false + }, + "CustomerSubscriptionCancelResult": { + "type": "object", + "properties": { + "id": { "type": "string" - }, - "venueId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "venue": { - "anyOf": [ - { - "$ref": "#/components/schemas/Venue" - }, - { - "type": "null" - } - ] - }, - "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." }, "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 +28619,489 @@ }, "additionalProperties": false }, - "EventDateCreate": { + "PurchaseSessionCreateRequest": { "type": "object", "properties": { - "label": { - "anyOf": [ - { - "type": "string", - "maxLength": 200 - }, - { - "type": "null" - } + "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." + } + }, + "required": [ + "eventDateId", + "deviceKey" + ], + "additionalProperties": false + }, + "PurchaseSessionCreated": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "eventDateId": { + "type": "string" + }, + "state": { + "type": "string", + "const": "live" + }, + "seated": { + "type": "boolean", + "description": "true = the event date has a seats.io map." + }, + "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" ] }, - "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" - } + "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" ] }, - "doorsOpenAt": { + "budgetSeconds": { "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": "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" }, - "timezone": { - "default": "America/Bogota", + "state": { "type": "string", - "minLength": 1 + "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`)." }, - "venueId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "seatsDeadline": { + "type": [ + "string", + "null" ] }, - "streamType": { - "default": "PRESENCIAL", - "type": "string", - "enum": [ - "PRESENCIAL", - "ONLINE", - "HIBRIDO" + "orderId": { + "description": "Sale created with this session, if any.", + "type": [ + "string", + "null" ] } }, "required": [ - "startsAt", - "timezone" + "id", + "state", + "seatsDeadline", + "orderId" ], "additionalProperties": false }, - "EventDateUpdate": { + "CustomerOrderCreateResult": { "type": "object", "properties": { - "label": { - "anyOf": [ - { - "type": "string", - "maxLength": 200 - }, - { - "type": "null" - } - ] + "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." }, - "startsAt": { + "reference": { "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": "Sale reference (FT-…). Always identifies the purchase." }, - "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" - } + "saleId": { + "description": "Sale id. null when `free` is true.", + "type": [ + "string", + "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" - } + "total": { + "description": "Amount to charge. null when `free` is true.", + "type": [ + "number", + "null" ] }, - "timezone": { - "type": "string", - "minLength": 1 + "currency": { + "type": [ + "string", + "null" + ] }, - "venueId": { + "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" + "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" } - ] - }, - "streamType": { - "type": "string", - "enum": [ - "PRESENCIAL", - "ONLINE", - "HIBRIDO" - ] - }, - "status": { - "type": "string", - "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" - ] + ], + "description": "The purchase the buyer left unfinished for this event date, or null if there is none." } }, + "required": [ + "order" + ], "additionalProperties": false }, - "TicketTypeCreate": { + "CustomerOrderRelease": { "type": "object", "properties": { - "eventDateId": { - "type": "string", - "minLength": 1 - }, - "name": { - "type": "string", - "minLength": 1 - }, - "description": { - "type": "string" - }, - "price": { - "type": "number", - "minimum": 0 - }, - "currency": { - "default": "COP", + "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", - "enum": [ - "COP" - ] + "description": "Merchant reference = `reference`." }, - "capacity": { + "amount": { "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Whole pesos, no decimals." }, - "maxPerOrder": { - "default": 10, - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "currency": { + "type": "string" }, - "isVisible": { - "default": true, - "type": "boolean" + "apiKey": { + "type": "string", + "description": "Bold IDENTITY key (public, sent to the browser)." }, - "organizerAbsorbsFee": { - "default": false, - "type": "boolean" + "integritySignature": { + "type": "string", + "description": "SHA256 that binds the charge to the amount. Computed on the server." }, - "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" - } - ] + "renderMode": { + "type": "string", + "const": "embedded" }, - "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" - } - ] + "redirectionUrl": { + "type": "string" }, - "seatsioCategoryKey": { - "anyOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "null" - } - ] + "description": { + "type": "string" + }, + "expirationDate": { + "type": "number", + "description": "Epoch in NANOSECONDS (what the Bold library expects)." } }, "required": [ - "eventDateId", - "name", - "price", + "orderId", + "amount", "currency", - "capacity", - "maxPerOrder", - "isVisible", - "organizerAbsorbsFee" + "apiKey", + "integritySignature", + "renderMode", + "redirectionUrl", + "description", + "expirationDate" ], "additionalProperties": false }, - "TicketTypeUpdate": { + "CustomerOrderMercadoPagoConfig": { "type": "object", "properties": { - "name": { + "publicKey": { "type": "string", - "minLength": 1 - }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "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`)." }, - "price": { + "amount": { "type": "number", - "minimum": 0 + "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": { - "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" - } - ] + "type": "string" }, - "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" - } - ] + "reference": { + "type": "string", + "description": "Sale reference (FT-…)." }, - "seatsioCategoryKey": { - "anyOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "null" - } - ] + "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": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "seatLabel": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "refundedAt": { - "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": [ - "id", - "ticketTypeId", - "quantity", - "unitPrice", - "subtotal", - "ticketCode", - "checkedInAt", - "seatLabel", - "refundedAt" + "token", + "paymentMethodId", + "installments" ], "additionalProperties": false }, - "Sale": { + "CustomerOrderMercadoPagoChargeResult": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "reference": { - "type": "string" - }, "status": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] + "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." }, - "channel": { + "reference": { "type": "string" }, - "subtotal": { - "type": "number" + "message": { + "description": "Human-readable message for the buyer. Only present with `rejected`.", + "type": "string" }, - "discountAmount": { - "type": "number" + "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": [ + "status", + "reference" + ], + "additionalProperties": false + }, + "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": { + "reference": { + "type": "string" }, - "serviceFee": { - "type": "number" + "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." }, - "iva": { - "type": "number" + "saleStatus": { + "type": "string", + "description": "Internal sale status (PENDING, CONFIRMED, …)." }, "total": { "type": "number" @@ -13351,2838 +29109,3581 @@ "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" + ] + }, + "idNumber": { + "type": "string", + "minLength": 5, + "maxLength": 20 }, - { - "type": "null" + "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": { + "title": { "type": "string" }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" + "description": { + "type": [ + "string", + "null" ] }, - "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": { + "durationSeconds": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "buyerDocumentType": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "posterUrl": { + "type": [ + "string", + "null" ] }, - "buyerDocumentNumber": { + "series": { "anyOf": [ { - "type": "string" + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "title": { + "type": "string" + } + }, + "required": [ + "id", + "title" + ], + "additionalProperties": false }, { "type": "null" } ] }, - "organizationId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "memberOnly": { + "type": "boolean", + "description": "true = only current members of the organization can play it." }, - "paymentProvider": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "publishedAt": { + "type": [ + "string", + "null" ] - }, - "paymentRef": { - "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" ] }, - "confirmedAt": { + "content": { + "type": "string", + "maxLength": 5000 + }, + "imageUrl": { + "description": "ARTICLE posts: the cover image. null removes it.", "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 2048, + "format": "uri" }, { "type": "null" } ] }, - "createdAt": { - "type": "string" + "locked": { + "type": "boolean" }, - "failureReason": { + "eventId": { + "description": "null unlinks the event.", "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1 }, { "type": "null" } ] }, - "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": { + "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" } ] }, - "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" + "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))$" + }, + "title": { + "type": "string", + "minLength": 1, + "maxLength": 140 }, - "organizationId": { + "subtitle": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 280 }, { "type": "null" } ] }, - "name": { - "type": "string" + "body": { + "type": "string", + "minLength": 1, + "maxLength": 100000 }, - "description": { + "slug": { + "description": "ARTICLE only. null re-derives it from the title.", "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 200 }, { "type": "null" } ] - }, - "price": { - "type": "number" - }, - "currency": { + } + }, + "additionalProperties": false + }, + "ContentPostPin": { + "type": "object", + "properties": { + "pinned": { + "type": "boolean" + } + }, + "required": [ + "pinned" + ], + "additionalProperties": false + }, + "ContentPostPinned": { + "type": "object", + "properties": { + "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" ] - }, - "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" + "pinnedAt" ], "additionalProperties": false }, - "MembershipPlanCreate": { + "ContentCommentDeleted": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "description": { + "id": { "type": "string" }, - "price": { - "type": "number", - "minimum": 0 + "deleted": { + "type": "boolean", + "const": true }, - "currency": { - "default": "COP", + "deletedIds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The comment plus its live replies (top-level comments)." + } + }, + "required": [ + "id", + "deleted", + "deletedIds" + ], + "additionalProperties": false + }, + "CommunityChannel": { + "type": "object", + "properties": { + "id": { "type": "string" }, - "billingCycle": { + "kind": { "type": "string", "enum": [ - "MONTHLY", - "QUARTERLY", - "SEMIANNUAL", - "ANNUAL", - "LIFETIME" + "ANNOUNCEMENTS", + "GENERAL", + "CITY", + "CUSTOM" ] }, - "benefitPresale": { - "default": false, - "type": "boolean" + "name": { + "type": "string" }, - "benefitFreeTicket": { - "default": false, - "type": "boolean" + "slug": { + "type": "string", + "description": "Tab URL slug. Does not change on rename." }, - "benefitDiscount": { - "default": false, - "type": "boolean" + "description": { + "type": [ + "string", + "null" + ] }, - "benefitExclusiveContent": { - "default": false, - "type": "boolean" + "city": { + "type": [ + "string", + "null" + ] }, - "benefitMerch": { - "default": false, - "type": "boolean" + "whoCanPost": { + "type": "string", + "enum": [ + "STAFF", + "MEMBERS" + ] }, - "isActive": { - "default": true, + "requiresApproval": { "type": "boolean" }, - "sortOrder": { - "default": 0, + "position": { "type": "integer", - "minimum": 0, + "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ + "id", + "kind", "name", - "price", - "currency", - "billingCycle", - "benefitPresale", - "benefitFreeTicket", - "benefitDiscount", - "benefitExclusiveContent", - "benefitMerch", - "isActive", - "sortOrder" + "slug", + "description", + "city", + "whoCanPost", + "requiresApproval", + "position" ], "additionalProperties": false }, - "MembershipPlanUpdate": { + "CommunityChannelCreate": { "type": "object", "properties": { + "kind": { + "type": "string", + "enum": [ + "CITY", + "CUSTOM" + ] + }, "name": { "type": "string", - "minLength": 1 + "minLength": 1, + "maxLength": 40 }, "description": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 200 }, { "type": "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 + "description": "Required when kind=CITY; ignored otherwise.", + "anyOf": [ + { + "type": "string", + "maxLength": 60 + }, + { + "type": "null" + } + ] }, - "latitude": { - "type": "number", - "minimum": -90, - "maximum": 90 + "whoCanPost": { + "default": "STAFF", + "type": "string", + "enum": [ + "STAFF", + "MEMBERS" + ] }, - "longitude": { - "type": "number", - "minimum": -180, - "maximum": 180 + "requiresApproval": { + "default": true, + "type": "boolean" } }, "required": [ + "kind", "name", - "address", - "city", - "country" + "whoCanPost", + "requiresApproval" ], "additionalProperties": false }, - "VenueUpdate": { + "CommunityChannelUpdate": { "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 + "minLength": 1, + "maxLength": 40 }, - "capacity": { + "description": { "anyOf": [ { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "type": "string", + "maxLength": 200 }, { "type": "null" } ] }, - "latitude": { + "city": { "anyOf": [ { - "type": "number", - "minimum": -90, - "maximum": 90 + "type": "string", + "maxLength": 60 }, { "type": "null" } ] }, - "longitude": { - "anyOf": [ - { - "type": "number", - "minimum": -180, - "maximum": 180 - }, - { - "type": "null" - } + "whoCanPost": { + "type": "string", + "enum": [ + "STAFF", + "MEMBERS" ] }, - "portalVisible": { + "requiresApproval": { "type": "boolean" } }, "additionalProperties": false }, - "StaffUser": { + "CommunityChannelOrder": { + "type": "object", + "properties": { + "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": [ + "orderedIds" + ], + "additionalProperties": false + }, + "ModerationQueueItem": { + "type": "object", + "properties": { + "commentId": { + "type": "string" + }, + "body": { + "type": "string" + }, + "createdAt": { + "type": "string" + }, + "isReply": { + "type": "boolean" + }, + "hidden": { + "type": "boolean" + }, + "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 + }, + "author": { + "type": "object", + "properties": { + "customerId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "image": { + "type": [ + "string", + "null" + ] + }, + "banned": { + "type": "boolean" + } + }, + "required": [ + "customerId", + "name", + "image", + "banned" + ], + "additionalProperties": false + }, + "post": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "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" }, - "name": { + "customerName": { "type": "string" }, - "email": { + "customerImage": { + "type": [ + "string", + "null" + ] + }, + "reason": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "customerName", + "customerImage", + "reason", + "createdAt" + ], + "additionalProperties": false + }, + "MemberPostQueueItem": { + "type": "object", + "properties": { + "postId": { "type": "string" }, - "role": { + "status": { "type": "string", "enum": [ - "SUPER_ADMIN", - "ADMIN", - "STAFF", - "VIEWER", - "MINCULTURA" + "PENDING_REVIEW", + "PUBLISHED" ] }, - "organizationId": { - "anyOf": [ - { + "content": { + "type": [ + "string", + "null" + ] + }, + "imageUrl": { + "description": "PENDING_REVIEW: short-lived signed URL (the image lives in a private bucket until approved).", + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" + }, + "publishedAt": { + "type": "string" + }, + "updatedAt": { + "type": "string", + "description": "Version read by the moderator: pass it as `expectedUpdatedAt` to approve." + }, + "channelName": { + "type": [ + "string", + "null" + ] + }, + "author": { + "type": "object", + "properties": { + "customerId": { "type": "string" }, - { - "type": "null" + "displayName": { + "type": "string" + }, + "handle": { + "type": [ + "string", + "null" + ] + }, + "avatarUrl": { + "type": [ + "string", + "null" + ] + }, + "banned": { + "type": "boolean" } - ] + }, + "required": [ + "customerId", + "displayName", + "handle", + "avatarUrl", + "banned" + ], + "additionalProperties": false + }, + "openReportCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "postId", + "status", + "content", + "imageUrl", + "createdAt", + "publishedAt", + "updatedAt", + "channelName", + "author", + "openReportCount" + ], + "additionalProperties": false + }, + "CommentModerated": { + "type": "object", + "properties": { + "commentId": { + "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)." }, - "workspaceId": { - "type": "string" + "reason": { + "type": "string", + "maxLength": 500 }, - "workspaceName": { + "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" }, - "createdAt": { - "type": "string" + "banned": { + "type": "boolean" } }, "required": [ - "id", - "name", - "email", - "role", - "organizationId", - "createdAt" + "customerId", + "banned" ], "additionalProperties": false }, - "StaffCreate": { + "MemberPostApprove": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1 - }, - "email": { + "expectedUpdatedAt": { "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,}$" + "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": [ - "name", - "email" + "expectedUpdatedAt" ], "additionalProperties": false }, - "RoleUpdate": { + "MemberPostDecision": { "type": "object", "properties": { - "role": { + "reason": { + "description": "Shown to the author in their inbox.", "type": "string", - "enum": [ - "SUPER_ADMIN", - "ADMIN", - "STAFF", - "VIEWER", - "MINCULTURA" - ] + "maxLength": 1000 + }, + "banAuthor": { + "default": false, + "description": "Also bans the author from the community. Requires ADMIN.", + "type": "boolean" } }, "required": [ - "role" + "banAuthor" ], "additionalProperties": false }, - "ReportSummary": { + "MemberPostReviewed": { "type": "object", "properties": { - "period": { - "type": "string" - }, - "currency": { + "postId": { "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 + "status": { + "type": "string", + "enum": [ + "PUBLISHED", + "REJECTED", + "REMOVED" + ] } }, "required": [ - "period", - "currency", - "revenue", - "ticketsSold", - "salesCount", - "activeMemberships" + "postId", + "status" ], "additionalProperties": false }, - "MatchStatus": { - "type": "string", - "enum": [ - "OK", - "MISSING_INVOICE", - "MISSING_CUFE", - "AMOUNT_MISMATCH", - "MISSING_PAYMENT" - ] - }, - "InventoryRow": { + "CommunityMeetupCreate": { "type": "object", "properties": { - "eventId": { - "type": "string" + "title": { + "type": "string", + "minLength": 3, + "maxLength": 120 }, - "eventName": { - "type": "string" + "description": { + "type": "string", + "maxLength": 5000 }, - "eventStatus": { + "format": { "type": "string", "enum": [ - "DRAFT", - "PUBLISHED", - "SOLD_OUT", - "CANCELLED", - "COMPLETED" + "IN_PERSON", + "ONLINE" ] }, - "eventDateId": { + "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" + }, + "city": { + "type": "string", + "maxLength": 80 + }, + "locationName": { + "type": "string", + "maxLength": 120 + }, + "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" } ] }, + "requiresApproval": { + "description": "true = the staff approves each RSVP request.", + "type": "boolean" + } + }, + "required": [ + "title", + "format", + "startsAt" + ], + "additionalProperties": false + }, + "CommunityMeetupUpdate": { + "type": "object", + "properties": { + "title": { + "type": "string", + "minLength": 3, + "maxLength": 120 + }, + "description": { + "type": "string", + "maxLength": 5000 + }, + "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" + }, + "city": { + "type": "string", + "maxLength": 80 + }, + "locationName": { + "type": "string", + "maxLength": 120 + }, + "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" } ] }, - "ticketTypeId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "requiresApproval": { + "description": "true = the staff approves each RSVP request.", + "type": "boolean" + } + }, + "additionalProperties": false + }, + "CommunityMeetup": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "title": { + "type": "string" + }, + "format": { + "type": "string", + "enum": [ + "IN_PERSON", + "ONLINE" ] }, - "ticketTypeName": { + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED", + "CANCELLED" + ] + }, + "startsAt": { + "type": "string" + }, + "city": { + "type": [ + "string", + "null" + ] + }, + "capacity": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "capacity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "sold": { + "goingCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, - "reserved": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "requiresApproval": { + "type": "boolean" }, - "available": { + "pendingCount": { "type": "integer", "minimum": -9007199254740991, - "maximum": 9007199254740991 + "maximum": 9007199254740991, + "description": "PENDING RSVP requests." } }, "required": [ - "eventId", - "eventName", - "eventStatus", - "eventDateId", + "id", + "title", + "format", + "status", "startsAt", - "ticketTypeId", - "ticketTypeName", + "city", "capacity", - "sold", - "reserved", - "available" + "goingCount", + "requiresApproval", + "pendingCount" ], "additionalProperties": false }, - "ReconciliationRow": { + "CommunityMeetupDetail": { "type": "object", "properties": { - "sale_reference": { + "id": { "type": "string" }, - "sale_status": { + "title": { + "type": "string" + }, + "format": { + "type": "string", + "enum": [ + "IN_PERSON", + "ONLINE" + ] + }, + "status": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" + "DRAFT", + "PUBLISHED", + "CANCELLED" ] }, - "sale_amount": { - "type": "number" + "startsAt": { + "type": "string" }, - "mp_payment_ref": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "city": { + "type": [ + "string", + "null" ] }, - "mp_provider": { + "capacity": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "mp_amount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } + "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" ] }, - "siigo_invoice_name": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "publishedAt": { + "type": [ + "string", + "null" ] }, - "siigo_invoice_status": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "cancelledAt": { + "type": [ + "string", + "null" ] }, - "siigo_cufe": { - "anyOf": [ - { + "local": { + "type": "object", + "properties": { + "title": { "type": "string" }, - { - "type": "null" - } - ] - }, - "match_status": { - "$ref": "#/components/schemas/MatchStatus" - }, - "event_id": { - "anyOf": [ - { + "description": { "type": "string" }, - { - "type": "null" - } - ] - }, - "event_name": { - "anyOf": [ - { + "format": { + "type": "string", + "enum": [ + "IN_PERSON", + "ONLINE" + ] + }, + "startsAt": { "type": "string" }, - { - "type": "null" - } - ] - }, - "event_date_id": { - "anyOf": [ - { + "endsAt": { "type": "string" }, - { - "type": "null" + "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" + ], + "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", + "title", + "format", + "status", + "startsAt", + "city", + "capacity", + "goingCount", + "requiresApproval", + "pendingCount", + "endsAt", + "publishedAt", + "cancelledAt", + "local", + "attendees", + "requests" + ], + "additionalProperties": false + }, + "CommunityMeetupRsvpReview": { + "type": "object", + "properties": { + "decision": { + "type": "string", + "enum": [ + "APPROVE", + "REJECT" ] } }, "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" + "decision" ], "additionalProperties": false }, - "ExportSaleItem": { + "CommunityMeetupRsvpReviewed": { "type": "object", "properties": { - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" - }, - "eventDateId": { + "rsvpId": { "type": "string" }, - "eventDateStartsAt": { - "type": "string" + "status": { + "type": "string", + "enum": [ + "GOING", + "DECLINED" + ] + } + }, + "required": [ + "rsvpId", + "status" + ], + "additionalProperties": false + }, + "CommunityMeetupAttendance": { + "type": "object", + "properties": { + "rsvpId": { + "type": "string", + "minLength": 1, + "maxLength": 64 }, - "ticketTypeId": { + "attended": { + "type": "boolean" + } + }, + "required": [ + "rsvpId", + "attended" + ], + "additionalProperties": false + }, + "CommunityMeetupAttendanceResult": { + "type": "object", + "properties": { + "rsvpId": { "type": "string" }, - "ticketTypeName": { - "type": "string" + "attended": { + "type": "boolean" }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "changed": { + "type": "boolean", + "description": "false = already in that state, or the RSVP is not GOING / the meetup is cancelled." } }, "required": [ - "eventId", - "eventName", - "eventDateId", - "eventDateStartsAt", - "ticketTypeId", - "ticketTypeName", - "quantity" + "rsvpId", + "attended", + "changed" ], "additionalProperties": false }, - "ExportBuyer": { + "ContentPost": { "type": "object", "properties": { - "reference": { + "id": { "type": "string" }, - "name": { - "type": "string" + "type": { + "type": "string", + "enum": [ + "TEXT", + "IMAGE", + "VIDEO", + "ARTICLE" + ] + }, + "content": { + "type": [ + "string", + "null" + ] }, - "email": { - "type": "string" + "imageUrl": { + "description": "ARTICLE post: also serves as the article's cover image.", + "type": [ + "string", + "null" + ] }, - "phone": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "videoId": { + "description": "VIDEO post: id of the ContentVideo, to cross-reference with `GET /content/videos`.", + "type": [ + "string", + "null" ] }, - "documentType": { + "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": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } - ] + ], + "description": "ARTICLE posts only. Not redacted when `locked`: it does not leak content, only its length." }, - "documentNumber": { + "link": { "anyOf": [ { - "type": "string" + "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 }, { "type": "null" } - ] - }, - "total": { - "type": "number" - }, - "currency": { - "type": "string" + ], + "description": "Open Graph snapshot of the first link in the text. Always null for ARTICLE posts." }, - "saleStatus": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] + "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." }, - "createdAt": { + "publishedAt": { "type": "string" - }, - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExportSaleItem" - } } }, "required": [ - "reference", - "name", - "email", - "phone", - "documentType", - "documentNumber", - "total", - "currency", - "saleStatus", - "createdAt", - "items" + "id", + "type", + "content", + "imageUrl", + "videoId", + "eventId", + "locked", + "title", + "subtitle", + "slug", + "body", + "readingMinutes", + "link", + "commentsCount", + "publishedAt" ], "additionalProperties": false }, - "ExportAttendee": { + "ContentPostCreate": { "type": "object", "properties": { - "reference": { - "type": "string" - }, - "name": { - "type": "string" + "type": { + "default": "TEXT", + "type": "string", + "enum": [ + "TEXT", + "IMAGE", + "ARTICLE" + ] }, - "email": { - "type": "string" + "content": { + "type": "string", + "maxLength": 5000 }, - "phone": { + "imageUrl": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 2048, + "format": "uri" }, { "type": "null" } ] }, - "documentType": { + "title": { + "description": "Required when type=ARTICLE.", + "type": "string", + "minLength": 1, + "maxLength": 140 + }, + "subtitle": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 280 }, { "type": "null" } ] }, - "documentNumber": { + "slug": { + "description": "Manual; if omitted it is derived from the title.", "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 200 }, { "type": "null" } ] }, - "ticketCode": { - "type": "string" - }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "body": { + "description": "Markdown. Required when type=ARTICLE.", + "type": "string", + "minLength": 1, + "maxLength": 100000 }, - "checkedInAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "locked": { + "default": false, + "description": "true = restricted to current members.", + "type": "boolean" }, - "checkedInSource": { + "eventId": { "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1 }, { "type": "null" } ] }, - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" - }, - "eventDateId": { - "type": "string" - }, - "eventDateStartsAt": { - "type": "string" - }, - "ticketTypeId": { - "type": "string" - }, - "ticketTypeName": { - "type": "string" - }, - "saleStatus": { + "publishedAt": { "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - }, - "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": [ - "reference", - "name", - "email", - "phone", - "documentType", - "documentNumber", - "ticketCode", - "quantity", - "checkedInAt", - "checkedInSource", - "eventId", - "eventName", - "eventDateId", - "eventDateStartsAt", - "ticketTypeId", - "ticketTypeName", - "saleStatus", - "createdAt" + "type", + "locked" ], "additionalProperties": false }, - "ExportSubscriber": { + "ContentMediaDeleted": { "type": "object", "properties": { - "name": { + "id": { "type": "string" }, - "email": { + "deleted": { + "type": "boolean", + "const": true + } + }, + "required": [ + "id", + "deleted" + ], + "additionalProperties": false + }, + "ContentVideoUpdate": { + "type": "object", + "properties": { + "title": { "type": "string" }, - "plan": { + "description": { + "description": "`null` or empty clears the description.", + "type": [ + "string", + "null" + ] + }, + "memberOnly": { + "description": "true = only current members can play it.", + "type": "boolean" + } + }, + "additionalProperties": false + }, + "ContentVideoSummary": { + "type": "object", + "properties": { + "id": { "type": "string" }, - "status": { + "title": { "type": "string" }, - "since": { + "description": { + "type": [ + "string", + "null" + ] + }, + "memberOnly": { + "type": "boolean" + } + }, + "required": [ + "id", + "title", + "description", + "memberOnly" + ], + "additionalProperties": false + }, + "ContentVideoPublish": { + "type": "object", + "properties": { + "published": { + "type": "boolean" + } + }, + "required": [ + "published" + ], + "additionalProperties": false + }, + "ContentVideoPublished": { + "type": "object", + "properties": { + "id": { "type": "string" }, - "expiresAt": { + "published": { + "type": "boolean" + } + }, + "required": [ + "id", + "published" + ], + "additionalProperties": false + }, + "ContentVideoSeriesAssign": { + "type": "object", + "properties": { + "seriesId": { "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1 }, { "type": "null" } - ] + ], + "description": "Series to put the video in; `null` removes it from its series." } }, "required": [ - "name", - "email", - "plan", - "status", - "since", - "expiresAt" + "seriesId" ], "additionalProperties": false }, - "PurchaseSessionCreateRequest": { + "ContentVideoSeriesResult": { "type": "object", "properties": { - "eventDateId": { - "type": "string", - "minLength": 1, - "maxLength": 64 + "id": { + "type": "string" }, - "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." + "seriesId": { + "type": [ + "string", + "null" + ] } }, "required": [ - "eventDateId", - "deviceKey" + "id", + "seriesId" ], "additionalProperties": false }, - "PurchaseSessionCreated": { + "ContentSeries": { "type": "object", "properties": { "id": { "type": "string" }, - "eventDateId": { + "title": { "type": "string" }, - "state": { - "type": "string", - "const": "live" + "description": { + "type": [ + "string", + "null" + ] }, - "seated": { - "type": "boolean", - "description": "true = the event date has a seats.io map." + "coverImageUrl": { + "type": [ + "string", + "null" + ] }, - "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." + "memberOnly": { + "type": "boolean" }, - "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." + "published": { + "type": "boolean" }, - "budgetSeconds": { - "anyOf": [ - { - "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." + "publishedAt": { + "type": [ + "string", + "null" + ] }, - "replacedSessionId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Live session that this one replaced (now `superseded`), or null. That tab can no longer create an order or start a new payment." + "videoCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Videos in the series (published or not, course videos excluded)." + }, + "createdAt": { + "type": "string" } }, "required": [ "id", - "eventDateId", - "state", - "seated", - "holdToken", - "seatsDeadline", - "budgetSeconds", - "replacedSessionId" + "title", + "description", + "coverImageUrl", + "memberOnly", + "published", + "publishedAt", + "videoCount", + "createdAt" ], "additionalProperties": false }, - "PurchaseSessionStatus": { + "ContentSeriesCreate": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "state": { + "title": { "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`)." + "description": "1–120 characters." }, - "seatsDeadline": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "description": { + "description": "Up to 2000 characters.", + "type": [ + "string", + "null" ] }, - "orderId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Sale created with this session, if any." + "coverImageUrl": { + "description": "Absolute URL of the cover.", + "type": [ + "string", + "null" + ] + }, + "memberOnly": { + "description": "Default true.", + "type": "boolean" } }, "required": [ - "id", - "state", - "seatsDeadline", - "orderId" + "title" ], "additionalProperties": false }, - "CustomerTicketItem": { + "ContentSeriesUpdate": { "type": "object", "properties": { - "ticketTypeName": { + "title": { "type": "string" }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "description": { + "description": "`null` clears it.", + "type": [ + "string", + "null" + ] }, - "ticketCode": { + "coverImageUrl": { + "description": "`null` clears it.", + "type": [ + "string", + "null" + ] + }, + "memberOnly": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "ContentSeriesPublish": { + "type": "object", + "properties": { + "published": { + "type": "boolean" + } + }, + "required": [ + "published" + ], + "additionalProperties": false + }, + "ContentLiveCreate": { + "type": "object", + "properties": { + "title": { "type": "string", - "description": "Opaque ticket code. The QR code must encode the validator URL (`https://admin.appfreeticket.com/dashboard/tickets/validar?code=`)." + "description": "1–120 characters." }, - "seatLabel": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Exact seat for seated events (seats.io), or null." + "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" + ] + }, + "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": [ - "ticketTypeName", - "quantity", - "ticketCode", - "seatLabel" + "title" ], "additionalProperties": false }, - "CustomerSale": { + "ContentLiveCreated": { "type": "object", "properties": { "id": { "type": "string" }, - "reference": { - "type": "string" - }, - "status": { + "title": { "type": "string" }, - "event": { - "type": "object", - "properties": { - "name": { - "type": "string" - }, - "slug": { - "type": "string" - } - }, - "required": [ - "name", - "slug" - ], - "additionalProperties": false + "memberOnly": { + "type": "boolean" }, - "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 + "scheduledAt": { + "description": "UTC ISO 8601.", + "type": [ + "string", + "null" + ] }, - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerTicketItem" - } + "eventDateId": { + "type": [ + "string", + "null" + ] }, - "total": { - "type": "number" + "rtmpUrl": { + "type": "string", + "description": "RTMPS ingest server for OBS / the encoder." }, - "currency": { - "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": [ "id", - "reference", - "status", - "event", - "eventDate", - "items", - "total", - "currency" + "title", + "memberOnly", + "scheduledAt", + "eventDateId", + "rtmpUrl", + "streamKey" ], "additionalProperties": false }, - "CustomerOrderCreateResult": { + "ContentLiveStreamKey": { "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." + "id": { + "type": "string" }, - "reference": { + "rtmpUrl": { + "type": "string" + }, + "streamKey": { "type": "string", - "description": "Sale reference (FT-…). Always identifies the purchase." + "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", + "rtmpUrl", + "streamKey" + ], + "additionalProperties": false + }, + "ContentLiveUpdate": { + "type": "object", + "properties": { + "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" + ] }, - "saleId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Sale id. null when `free` is true." + "memberOnly": { + "type": "boolean" + } + }, + "additionalProperties": false + }, + "ContentLiveSettings": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "total": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } - ], - "description": "Amount to charge. null when `free` is true." + "memberOnly": { + "type": "boolean" }, - "currency": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "scheduledAt": { + "description": "UTC ISO 8601.", + "type": [ + "string", + "null" ] - }, - "expiresAt": { - "anyOf": [ - { - "type": "string" - }, - { - "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" + "id", + "memberOnly", + "scheduledAt" ], "additionalProperties": false }, - "CustomerOrderCurrent": { + "ContentLiveChat": { "type": "object", "properties": { - "order": { - "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 - } - } + "messages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "required": [ - "saleId", - "reference", - "total", - "currency", - "expiresAt", - "paymentOpened", - "items" - ], - "additionalProperties": false + "authorId": { + "type": "string" + }, + "name": { + "type": "string" + }, + "text": { + "type": "string" + }, + "sentAt": { + "type": "string" + }, + "host": { + "description": "Present (true) on messages sent by the organization.", + "type": "boolean" + } }, - { - "type": "null" - } + "required": [ + "id", + "authorId", + "name", + "text", + "sentAt" + ], + "additionalProperties": false + } + }, + "truncated": { + "type": "boolean", + "description": "true if the history cap was reached and the oldest messages are missing." + } + }, + "required": [ + "messages", + "truncated" + ], + "additionalProperties": false + }, + "ContentLive": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "title": { + "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "IDLE", + "ACTIVE", + "COMPLETED", + "DISABLED" ], - "description": "The purchase the buyer left unfinished for this event date, or null if there is none." + "description": "ACTIVE = streaming right now (live banner)." + }, + "memberOnly": { + "type": "boolean" + }, + "startedAt": { + "type": [ + "string", + "null" + ] + }, + "endedAt": { + "type": [ + "string", + "null" + ] + }, + "hasRecording": { + "type": "boolean", + "description": "true if a playable recording remains after the stream." } }, "required": [ - "order" + "id", + "title", + "status", + "memberOnly", + "startedAt", + "endedAt", + "hasRecording" ], "additionalProperties": false }, - "CustomerOrderRelease": { + "ContentPlaybackTokenRequest": { "type": "object", "properties": { - "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`." + "kind": { + "type": "string", + "enum": [ + "video", + "live" + ] + }, + "id": { + "type": "string", + "minLength": 1 } }, "required": [ - "released" + "kind", + "id" ], "additionalProperties": false }, - "CustomerOrderPayment": { + "ContentPlaybackToken": { "type": "object", "properties": { - "orderId": { - "type": "string", - "description": "Merchant reference = `reference`." - }, - "amount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Whole pesos, no decimals." - }, - "currency": { + "playbackId": { "type": "string" }, - "apiKey": { + "tokens": { + "type": "object", + "properties": { + "playback": { + "type": "string" + }, + "drm": { + "type": "string" + }, + "thumbnail": { + "type": "string" + }, + "storyboard": { + "type": "string" + } + }, + "required": [ + "playback", + "drm" + ], + "additionalProperties": false + } + }, + "required": [ + "playbackId", + "tokens" + ], + "additionalProperties": false + }, + "WaitlistEntryCreate": { + "type": "object", + "properties": { + "city": { "type": "string", - "description": "Bold IDENTITY key (public, sent to the browser)." + "minLength": 1, + "maxLength": 60 }, - "integritySignature": { + "name": { "type": "string", - "description": "SHA256 that binds the charge to the amount. Computed on the server." + "minLength": 1, + "maxLength": 80 }, - "renderMode": { + "contact": { "type": "string", - "const": "embedded" + "minLength": 1, + "maxLength": 120 }, - "redirectionUrl": { + "source": { + "type": "string", + "maxLength": 40 + } + }, + "required": [ + "city", + "name", + "contact" + ], + "additionalProperties": false + }, + "WaitlistEntryResult": { + "type": "object", + "properties": { + "id": { "type": "string" }, - "description": { + "city": { "type": "string" }, - "expirationDate": { - "type": "number", - "description": "Epoch in NANOSECONDS (what the Bold library expects)." + "created": { + "type": "boolean" } }, "required": [ - "orderId", - "amount", - "currency", - "apiKey", - "integritySignature", - "renderMode", - "redirectionUrl", - "description", - "expirationDate" + "id", + "city", + "created" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoConfig": { + "WaitlistEntry": { "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`)." + "id": { + "type": "string" }, - "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." + "city": { + "type": "string" }, - "currency": { + "name": { "type": "string" }, - "reference": { - "type": "string", - "description": "Sale reference (FT-…)." + "contact": { + "type": "string" }, - "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." + "customerId": { + "type": [ + "string", + "null" + ] + }, + "source": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": "string" } }, "required": [ - "publicKey", - "amount", - "currency", - "reference", - "payerEmail" + "id", + "city", + "name", + "contact", + "customerId", + "source", + "createdAt" ], "additionalProperties": false }, - "CustomerOrderStartPayment": { - "anyOf": [ - { - "$ref": "#/components/schemas/CustomerOrderPayment" - }, - { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoConfig" - } - ] - }, - "CustomerOrderMercadoPagoChargeRequest": { + "LiveAttendance": { "type": "object", "properties": { - "token": { - "type": "string", - "minLength": 1, - "description": "Card token returned by the Payment Brick when tokenizing." + "eventDateId": { + "type": "string" }, - "paymentMethodId": { - "type": "string", - "minLength": 1, - "description": "`payment_method_id` returned by the Brick (e.g. `visa`, `debmaster`)." + "eventId": { + "type": "string" }, - "installments": { - "default": 1, + "eventName": { + "type": "string" + }, + "city": { + "type": [ + "string", + "null" + ] + }, + "imageUrl": { + "type": [ + "string", + "null" + ] + }, + "sold": { "type": "integer", - "minimum": 1, + "minimum": -9007199254740991, "maximum": 9007199254740991 }, - "issuerId": { - "description": "`issuer_id` returned by the Brick. Some BINs require it.", - "type": "string" + "validated": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "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 + "validatedPct": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 } }, "required": [ - "token", - "paymentMethodId", - "installments" + "eventDateId", + "eventId", + "eventName", + "city", + "imageUrl", + "sold", + "validated", + "validatedPct" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoChargeResult": { + "AccessCloseStatus": { "type": "object", "properties": { + "eventDateId": { + "type": "string" + }, + "eventId": { + "type": "string" + }, + "eventName": { + "type": "string" + }, + "venueName": { + "type": [ + "string", + "null" + ] + }, + "label": { + "type": "string" + }, "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." + "manual", + "auto" + ] }, - "reference": { - "type": "string" + "closed": { + "type": "boolean" }, - "message": { - "description": "Human-readable message for the buyer. Only present with `rejected`.", + "signable": { + "type": "boolean" + }, + "signableFromLabel": { "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" + "closedByName": { + "type": [ + "string", + "null" + ] + }, + "closedAtLabel": { + "type": [ + "string", + "null" + ] + }, + "closedCheckins": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "live": { + "type": "object", + "properties": { + "issued": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "checkins": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + } + }, + "required": [ + "issued", + "checkins" + ], + "additionalProperties": false } }, "required": [ + "eventDateId", + "eventId", + "eventName", + "venueName", + "label", "status", - "reference" + "closed", + "signable", + "signableFromLabel", + "closedByName", + "closedAtLabel", + "closedCheckins", + "live" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoPse": { + "AccessCloseSignRequest": { "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." + "confirm": { + "type": "boolean", + "const": true } }, "required": [ - "redirectUrl" + "confirm" ], "additionalProperties": false }, - "CustomerOrderStatus": { + "AccessCloseSigned": { "type": "object", "properties": { - "reference": { + "eventDateId": { + "type": "string" + }, + "eventId": { "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." + "const": "manual" }, - "saleStatus": { - "type": "string", - "description": "Internal sale status (PENDING, CONFIRMED, …)." + "closedAt": { + "type": "string" }, - "total": { - "type": "number" + "checkins": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "currency": { + "closedByName": { "type": "string" - }, - "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." } }, "required": [ - "reference", + "eventDateId", + "eventId", "status", - "saleStatus", - "total", - "currency", - "tickets" + "closedAt", + "checkins", + "closedByName" ], "additionalProperties": false }, - "CustomerOrderItem": { + "PaymentIntentRow": { "type": "object", "properties": { - "ticketTypeId": { - "type": "string", - "minLength": 1 + "threadId": { + "type": "string" }, - "quantity": { - "type": "integer", - "minimum": 1, - "maximum": 30 + "deviceTag": { + "type": "string" + }, + "hasAccount": { + "type": "boolean" + }, + "customerId": { + "type": [ + "string", + "null" + ] + }, + "personName": { + "type": [ + "string", + "null" + ] + }, + "personEmail": { + "type": [ + "string", + "null" + ] + }, + "personSource": { + "anyOf": [ + { + "type": "string", + "enum": [ + "account", + "checkout" + ] + }, + { + "type": "null" + } + ] }, "seats": { - "description": "seats.io labels. Only for seated events.", - "maxItems": 30, "type": "array", "items": { - "type": "string", - "minLength": 1, - "maxLength": 120 + "type": "string" } - } - }, - "required": [ - "ticketTypeId", - "quantity" - ], - "additionalProperties": false - }, - "CustomerOrderCreateRequest": { - "type": "object", - "properties": { + }, + "category": { + "type": [ + "string", + "null" + ] + }, "eventDateId": { - "type": "string", - "minLength": 1 + "type": [ + "string", + "null" + ] }, - "items": { - "minItems": 1, - "maxItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerOrderItem" - } + "firstAt": { + "type": "string" }, - "holdToken": { - "description": "Hold token of the seats.io map session. Required if seats are sent.", + "lastAt": { + "type": "string" + }, + "stage": { "type": "string", - "maxLength": 120 + "enum": [ + "seatmap", + "seats", + "continue", + "checkout", + "payment", + "purchased" + ] }, - "discountCode": { + "outcome": { "type": "string", - "maxLength": 40 + "enum": [ + "NO_SALE", + "REJECTED", + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] }, - "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 + "reason": { + "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." + "paymentStatus": { + "type": [ + "string", + "null" + ] + }, + "mapFailed": { + "type": "boolean" + }, + "saleId": { + "type": [ + "string", + "null" + ] + }, + "saleReference": { + "type": [ + "string", + "null" + ] + }, + "saleTotal": { + "type": [ + "number", + "null" + ] } }, "required": [ + "threadId", + "deviceTag", + "hasAccount", + "customerId", + "personName", + "personEmail", + "personSource", + "seats", + "category", "eventDateId", - "items", - "buyer", - "returnUrl" + "firstAt", + "lastAt", + "stage", + "outcome", + "reason", + "paymentStatus", + "mapFailed", + "saleId", + "saleReference", + "saleTotal" ], "additionalProperties": false }, - "SaleCreate": { + "PaymentIntentsPage": { "type": "object", "properties": { - "buyer": { + "event": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1 + "id": { + "type": "string" }, - "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" }, - "phone": { - "type": "string", - "minLength": 1 + "city": { + "type": [ + "string", + "null" + ] } }, "required": [ + "id", "name", - "email" + "city" ], "additionalProperties": false }, - "items": { - "minItems": 1, + "dates": { "type": "array", "items": { "type": "object", "properties": { - "ticketTypeId": { - "type": "string", - "minLength": 1 + "id": { + "type": "string" }, - "quantity": { - "type": "integer", - "minimum": 1, - "maximum": 9007199254740991 + "startsAt": { + "type": "string" }, - "seats": { - "type": "array", - "items": { - "type": "string", - "minLength": 1 - } + "timezone": { + "type": "string" + }, + "label": { + "type": [ + "string", + "null" + ] } }, "required": [ - "ticketTypeId", - "quantity" + "id", + "startsAt", + "timezone", + "label" ], "additionalProperties": false } }, - "channel": { - "default": "ADMIN", - "type": "string", - "enum": [ - "WEB", - "MOBILE", - "POS", - "ADMIN" + "selectedDateId": { + "type": [ + "string", + "null" ] }, - "comp": { - "default": false, - "type": "boolean" + "funnel": { + "type": "object", + "properties": { + "threads": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "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 }, - "notes": { - "type": "string" + "rows": { + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentIntentRow" + } + }, + "nextCursor": { + "type": [ + "string", + "null" + ] } }, "required": [ - "buyer", - "items", - "channel", - "comp" + "event", + "dates", + "selectedDateId", + "funnel", + "rows", + "nextCursor" ], "additionalProperties": false }, - "SaleCancelRequest": { + "ProductLessonResourceInput": { "type": "object", "properties": { - "acknowledge_open_payment": { - "type": "boolean" + "id": { + "description": "Id of a saved resource; absent/null creates a new one.", + "type": [ + "string", + "null" + ] + }, + "kind": { + "type": "string", + "enum": [ + "FILE", + "LINK" + ] + }, + "label": { + "type": "string" + }, + "url": { + "description": "LINK only: http(s) URL.", + "type": [ + "string", + "null" + ] + }, + "filePath": { + "description": "FILE only: path in the private product files bucket, under this workspace.", + "type": [ + "string", + "null" + ] + }, + "fileName": { + "type": [ + "string", + "null" + ] + }, + "fileSize": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] } }, + "required": [ + "kind", + "label" + ], "additionalProperties": false }, - "SaleRefundRequest": { + "ProductLessonQuiz": { "type": "object", "properties": { - "acknowledge_manual": { - "type": "boolean" - }, - "items": { - "minItems": 1, - "maxItems": 200, + "questions": { "type": "array", "items": { - "type": "string", - "minLength": 1, - "maxLength": 64 + "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 } }, - "block_seats": { + "passScore": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Minimum score to pass, 0–100." + }, + "showAnswers": { "type": "boolean" } }, + "required": [ + "questions", + "passScore", + "showAnswers" + ], "additionalProperties": false }, - "SaleRefundResult": { + "ProductLessonInput": { "type": "object", "properties": { "id": { - "type": "string" - }, - "reference": { - "type": "string" - }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" + "description": "Id of a saved lesson; absent/null creates a new one. Keep ids on edit so buyers keep their progress.", + "type": [ + "string", + "null" ] }, - "channel": { + "title": { "type": "string" }, - "subtotal": { - "type": "number" - }, - "discountAmount": { - "type": "number" - }, - "serviceFee": { - "type": "number" - }, - "iva": { - "type": "number" - }, - "total": { - "type": "number" + "description": { + "type": [ + "string", + "null" + ] }, - "currency": { - "type": "string" + "isLive": { + "type": "boolean" }, - "buyerName": { - "type": "string" + "content": { + "type": "string", + "enum": [ + "VIDEO", + "FILE", + "TEXT", + "QUIZ" + ] }, - "buyerEmail": { - "type": "string" + "body": { + "description": "Markdown; TEXT lessons only.", + "type": [ + "string", + "null" + ] }, - "buyerPhone": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "thumbnailUrl": { + "type": [ + "string", + "null" ] }, - "buyerDocumentType": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "videoId": { + "description": "Course video id; VIDEO lessons only. Uploading a video is not available through the API.", + "type": [ + "string", + "null" ] }, - "buyerDocumentNumber": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "fileName": { + "type": [ + "string", + "null" ] }, - "organizationId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "filePath": { + "type": [ + "string", + "null" ] }, - "paymentProvider": { + "resources": { + "description": "Absent keeps the saved resources; [] removes them all.", + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductLessonResourceInput" + } + }, + "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": [ { - "type": "string" + "$ref": "#/components/schemas/ProductLessonQuiz" }, { "type": "null" } ] + } + }, + "required": [ + "title", + "isLive", + "content" + ], + "additionalProperties": false + }, + "ProductModuleInput": { + "type": "object", + "properties": { + "id": { + "description": "Id of a saved module; absent/null creates a new one.", + "type": [ + "string", + "null" + ] }, - "paymentRef": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "title": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" ] }, - "confirmedAt": { + "unlockAfterDays": { + "description": "Drip by days after purchase (unlockMode DAYS).", "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "createdAt": { - "type": "string" + "unlockAt": { + "description": "Drip by date, ISO 8601 with offset (unlockMode DATE).", + "type": [ + "string", + "null" + ] }, - "failureReason": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "lessons": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProductLessonInput" + } + } + }, + "required": [ + "title", + "lessons" + ], + "additionalProperties": false + }, + "ProductCourseMeta": { + "type": "object", + "properties": { + "learn": { + "description": "\"What you will learn\": empty, or 3 to 8 items.", + "type": "array", + "items": { + "type": "string" + } + }, + "audience": { + "type": [ + "string", + "null" ] }, - "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." + "requirements": { + "type": [ + "string", + "null" + ] }, - "declineCode": { + "level": { "anyOf": [ { - "type": "string" + "type": "string", + "enum": [ + "BEGINNER", + "INTERMEDIATE", + "ADVANCED" + ] }, { "type": "null" } ] - }, - "refund": { - "type": "object", - "properties": { - "amount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "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 }, - "ReportByEventRow": { + "ProductCreate": { "type": "object", "properties": { - "eventId": { + "type": { + "type": "string", + "enum": [ + "DOWNLOADABLE", + "COURSE" + ] + }, + "name": { "type": "string" }, - "eventName": { + "description": { + "default": "", "type": "string" }, - "revenue": { - "type": "number" + "coverImageUrl": { + "default": null, + "type": [ + "string", + "null" + ] }, - "ticketsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "price": { + "type": "number", + "description": "COP: integer. USD: up to 2 decimals." }, - "salesCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "currency": { + "default": "COP", + "type": "string", + "enum": [ + "COP", + "USD" + ] }, - "available": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - } - }, - "required": [ - "eventId", - "eventName", - "revenue", - "ticketsSold", - "salesCount", - "available" - ], - "additionalProperties": false - }, - "ReportTimeseriesRow": { - "type": "object", - "properties": { - "bucket": { - "type": "string" + "access": { + "default": "PUBLIC", + "type": "string", + "enum": [ + "PUBLIC", + "SUBSCRIBERS" + ] }, - "revenue": { - "type": "number" + "includedInMembership": { + "default": false, + "type": "boolean", + "description": "Members of the workspace get it at no cost." }, - "ticketsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "fileName": { + "default": null, + "type": [ + "string", + "null" + ] }, - "salesCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "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": [ + { + "$ref": "#/components/schemas/ProductCourseMeta" + }, + { + "type": "null" + } + ] + }, + "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": [ - "bucket", - "revenue", - "ticketsSold", - "salesCount" + "type", + "name", + "description", + "coverImageUrl", + "price", + "currency", + "access", + "includedInMembership", + "fileName", + "filePath", + "sampleName", + "samplePath", + "modules", + "publish" ], "additionalProperties": false }, - "ReportFinancialsRow": { + "ProductUpdate": { "type": "object", "properties": { - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" + "type": { + "type": "string", + "enum": [ + "DOWNLOADABLE", + "COURSE" + ] }, - "eventDateId": { + "name": { "type": "string" }, - "startsAt": { + "description": { "type": "string" }, - "past": { - "type": "boolean" + "coverImageUrl": { + "type": [ + "string", + "null" + ] }, - "unitsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "price": { + "type": "number", + "description": "COP: integer. USD: up to 2 decimals." }, - "gross": { - "type": "number" + "currency": { + "type": "string", + "enum": [ + "COP", + "USD" + ] }, - "platformFee": { - "type": "number" + "access": { + "type": "string", + "enum": [ + "PUBLIC", + "SUBSCRIBERS" + ] }, - "facial": { - "type": "number" + "includedInMembership": { + "type": "boolean", + "description": "Members of the workspace get it at no cost." }, - "paymentFee": { - "type": "number" + "fileName": { + "type": [ + "string", + "null" + ] }, - "wompiSalesWithoutRate": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "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" + ] }, - "gmf": { - "type": "number" + "sampleName": { + "type": [ + "string", + "null" + ] }, - "net": { - "type": "number" + "samplePath": { + "type": [ + "string", + "null" + ] }, - "currency": { - "type": "string" + "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" + } }, - "settlementStatus": { + "courseMeta": { + "description": "COURSE only. Absent keeps the saved one; null clears it.", "anyOf": [ { - "type": "string", - "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" - ] + "$ref": "#/components/schemas/ProductCourseMeta" }, { "type": "null" } ] }, - "settlementId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "unlockMode": { + "description": "COURSE drip rule. Absent keeps the saved one (OPEN on create).", + "type": "string", + "enum": [ + "OPEN", + "SEQUENTIAL", + "DAYS", + "DATE" ] - }, - "settlementAmount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } + } + }, + "additionalProperties": false + }, + "ProductStatusUpdate": { + "type": "object", + "properties": { + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED" ] } }, "required": [ - "eventId", - "eventName", - "eventDateId", - "startsAt", - "past", - "unitsSold", - "gross", - "platformFee", - "facial", - "paymentFee", - "wompiSalesWithoutRate", - "gmf", - "net", - "currency", - "settlementStatus", - "settlementId", - "settlementAmount" + "status" ], "additionalProperties": false }, - "Settlement": { + "Product": { "type": "object", "properties": { "id": { "type": "string" }, - "reference": { + "name": { "type": "string" }, - "label": { - "type": "string" + "type": { + "type": "string", + "enum": [ + "DOWNLOADABLE", + "COURSE" + ] }, "status": { "type": "string", "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" + "DRAFT", + "PUBLISHED" ] }, - "amount": { + "price": { "type": "number" }, - "grossAmount": { - "anyOf": [ - { - "type": "number" - }, - { - "type": "null" - } + "currency": { + "type": "string", + "enum": [ + "COP", + "USD" ] }, - "unitsSold": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - { - "type": "null" - } + "coverImageUrl": { + "type": [ + "string", + "null" ] }, - "currency": { + "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 + }, + "ProductLesson": { + "type": "object", + "properties": { + "id": { "type": "string" }, - "notes": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "title": { + "type": "string" + }, + "description": { + "type": [ + "string", + "null" ] }, - "rejectionReason": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "isLive": { + "type": "boolean" + }, + "content": { + "type": "string", + "enum": [ + "VIDEO", + "FILE", + "TEXT", + "QUIZ" ] }, - "event": { - "anyOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "required": [ - "id", - "name" - ], - "additionalProperties": false - }, - { - "type": "null" - } + "body": { + "description": "Markdown; TEXT lessons only.", + "type": [ + "string", + "null" ] }, - "eventDate": { - "anyOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "startsAt": { - "type": "string" - } - }, - "required": [ - "id", - "startsAt" - ], - "additionalProperties": false - }, - { - "type": "null" - } + "thumbnailUrl": { + "type": [ + "string", + "null" ] }, - "hasDocument": { - "type": "boolean" + "videoId": { + "description": "Course video id; VIDEO lessons only. Uploading a video is not available through the API.", + "type": [ + "string", + "null" + ] + }, + "fileName": { + "type": [ + "string", + "null" + ] }, - "paymentProofs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "fileName": { - "type": "string" - } - }, - "required": [ - "fileName" - ], - "additionalProperties": false - } + "filePath": { + "type": [ + "string", + "null" + ] }, - "allocations": { + "resources": { "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 + "$ref": "#/components/schemas/ProductLessonResourceInput" } }, - "requestedAt": { + "isPreview": { + "type": "boolean" + }, + "quiz": { + "description": "Only for ADMIN keys (it includes the correct answers).", "anyOf": [ { - "type": "string" + "$ref": "#/components/schemas/ProductLessonQuiz" }, { "type": "null" } ] }, - "paidAt": { + "videoStatus": { "anyOf": [ { - "type": "string" + "type": "string", + "enum": [ + "DRAFT", + "PROCESSING", + "READY", + "ERROR" + ] }, { "type": "null" } ] }, - "createdAt": { - "type": "string" + "durationSeconds": { + "type": [ + "number", + "null" + ] } }, "required": [ "id", - "reference", - "label", - "status", - "amount", - "grossAmount", - "unitsSold", - "currency", - "notes", - "rejectionReason", - "event", - "eventDate", - "hasDocument", - "paymentProofs", - "allocations", - "requestedAt", - "paidAt", - "createdAt" + "title", + "isLive", + "content", + "resources", + "isPreview", + "videoStatus", + "durationSeconds" ], "additionalProperties": false }, - "DiscountType": { - "type": "string", - "enum": [ - "PERCENT", - "FIXED" - ] - }, - "Discount": { + "ProductModule": { "type": "object", "properties": { "id": { "type": "string" }, - "code": { + "title": { "type": "string" }, - "type": { - "$ref": "#/components/schemas/DiscountType" - }, - "value": { - "type": "number" - }, - "eventId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "description": { + "type": [ + "string", + "null" ] }, - "active": { - "type": "boolean" - }, - "maxUses": { + "unlockAfterDays": { + "description": "Drip by days after purchase (unlockMode DAYS).", "anyOf": [ { "type": "integer", @@ -16194,839 +32695,1208 @@ } ] }, - "uses": { + "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 + }, + "ProductDetail": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "DOWNLOADABLE", + "COURSE" + ] + }, + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED" + ] + }, + "price": { + "type": "number" + }, + "currency": { + "type": "string", + "enum": [ + "COP", + "USD" + ] + }, + "coverImageUrl": { + "type": [ + "string", + "null" + ] + }, + "salesCount": { "type": "integer", "minimum": -9007199254740991, - "maximum": 9007199254740991 + "maximum": 9007199254740991, + "description": "CONFIRMED purchases." }, - "startsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "revenue": { + "type": "number", + "description": "Sum of CONFIRMED purchase amounts." + }, + "includedInMembership": { + "type": "boolean" + }, + "description": { + "type": "string" + }, + "access": { + "type": "string", + "enum": [ + "PUBLIC", + "SUBSCRIBERS" ] }, - "endsAt": { + "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" } ] }, - "createdAt": { - "type": "string" + "unlockMode": { + "type": "string", + "enum": [ + "OPEN", + "SEQUENTIAL", + "DAYS", + "DATE" + ] } }, "required": [ "id", - "code", + "name", "type", - "value", - "eventId", - "active", - "maxUses", - "uses", - "startsAt", - "endsAt", - "createdAt" + "status", + "price", + "currency", + "coverImageUrl", + "salesCount", + "revenue", + "includedInMembership", + "description", + "access", + "fileName", + "filePath", + "sampleName", + "samplePath", + "modules", + "courseMeta", + "unlockMode" ], "additionalProperties": false }, - "DiscountCreate": { + "Website": { "type": "object", "properties": { - "code": { + "slug": { "type": "string", - "minLength": 1 + "description": "Public slug (organization subdomain)." }, - "type": { - "$ref": "#/components/schemas/DiscountType" + "name": { + "type": "string" }, - "value": { - "type": "number", - "exclusiveMinimum": 0 + "tagline": { + "type": [ + "string", + "null" + ] }, - "eventId": { - "anyOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "null" - } + "bio": { + "type": [ + "string", + "null" ] }, - "maxUses": { - "anyOf": [ - { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 - }, - { - "type": "null" - } + "accentColor": { + "type": [ + "string", + "null" ] }, - "startsAt": { + "webTemplate": { + "type": [ + "string", + "null" + ] + }, + "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" ] }, - "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" - } + "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": [ - "code", - "type", - "value" + "slug", + "name", + "tagline", + "bio", + "accentColor", + "webTemplate", + "webSections", + "instagramUrl", + "tiktokUrl", + "youtubeUrl", + "customLandingEnabled", + "published", + "canPublish", + "profileListable" ], "additionalProperties": false }, - "DiscountUpdate": { + "WebsiteUpdate": { "type": "object", "properties": { - "active": { - "type": "boolean" - }, - "value": { - "type": "number", - "exclusiveMinimum": 0 + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 }, - "maxUses": { + "tagline": { "anyOf": [ { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "type": "string", + "maxLength": 200 }, { "type": "null" } ] }, - "startsAt": { + "bio": { "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": 5000 }, { "type": "null" } ] }, - "endsAt": { + "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" } ] - } - }, - "additionalProperties": false - }, - "Webhook": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "url": { - "type": "string" - }, - "events": { - "type": "array", - "items": { - "type": "string" - } }, - "active": { - "type": "boolean" - }, - "lastDeliveryAt": { + "tiktokUrl": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 500 }, { "type": "null" } ] }, - "lastDeliveryStatus": { + "youtubeUrl": { "anyOf": [ { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "type": "string", + "maxLength": 500 }, { "type": "null" } ] }, - "failureCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "accentColor": { + "type": "string", + "pattern": "^#[0-9a-fA-F]{6}$", + "description": "#RRGGBB." }, - "createdAt": { - "type": "string" + "webTemplate": { + "type": "string", + "minLength": 1, + "maxLength": 32 }, - "updatedAt": { - "type": "string" + "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": [ - "id", - "url", - "events", - "active", - "lastDeliveryAt", - "lastDeliveryStatus", - "failureCount", - "createdAt", - "updatedAt" + "name", + "tagline", + "bio", + "instagramUrl", + "tiktokUrl", + "youtubeUrl", + "accentColor", + "webTemplate", + "webSections" ], "additionalProperties": false }, - "WebhookUpdate": { + "WebsitePublished": { "type": "object", "properties": { - "url": { - "type": "string", - "format": "uri" - }, - "events": { - "minItems": 1, - "type": "array", - "items": { - "type": "string", - "enum": [ - "sale.confirmed", - "sale.refunded" - ] - } - }, - "active": { + "published": { "type": "boolean" } }, + "required": [ + "published" + ], "additionalProperties": false }, - "WebhookCreated": { + "OrganizationProfile": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Workspace id." }, - "url": { - "type": "string" + "name": { + "type": "string", + "description": "Workspace name." }, - "events": { - "type": "array", - "items": { - "type": "string" - } + "brandName": { + "type": "string", + "description": "Public brand name (from the umbrella organization)." }, - "active": { - "type": "boolean" + "slug": { + "type": "string" }, - "lastDeliveryAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "bio": { + "type": [ + "string", + "null" ] }, - "lastDeliveryStatus": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - { - "type": "null" - } + "type": { + "type": "string", + "enum": [ + "ARTIST", + "VENUE", + "ORGANIZER" ] }, - "failureCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "createdAt": { + "country": { "type": "string" }, - "updatedAt": { + "timezone": { "type": "string" }, - "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" + "logoUrl": { + "type": [ + "string", + "null" + ] }, - "events": { - "minItems": 1, - "type": "array", - "items": { - "type": "string", - "enum": [ - "sale.confirmed", - "sale.refunded" - ] - }, - "description": "Subset of: sale.confirmed, sale.refunded" + "coverUrl": { + "type": [ + "string", + "null" + ] }, - "secret": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "url", - "events" - ], - "additionalProperties": false - }, - "Subscriber": { - "type": "object", - "properties": { - "id": { - "type": "string" + "email": { + "type": [ + "string", + "null" + ] }, - "customerName": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "phone": { + "type": [ + "string", + "null" ] }, - "customerEmail": { - "type": "string" + "website": { + "type": [ + "string", + "null" + ] }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" + "instagramUrl": { + "type": [ + "string", + "null" + ] + }, + "facebookUrl": { + "type": [ + "string", + "null" + ] + }, + "twitterUrl": { + "type": [ + "string", + "null" + ] + }, + "spotifyUrl": { + "type": [ + "string", + "null" ] }, - "startedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "youtubeUrl": { + "type": [ + "string", + "null" ] }, - "currentPeriodEnd": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "tiktokUrl": { + "type": [ + "string", + "null" ] } }, "required": [ "id", - "customerName", - "customerEmail", - "status", - "startedAt", - "currentPeriodEnd" + "name", + "brandName", + "slug", + "bio", + "type", + "country", + "timezone", + "logoUrl", + "coverUrl", + "email", + "phone", + "website", + "instagramUrl", + "facebookUrl", + "twitterUrl", + "spotifyUrl", + "youtubeUrl", + "tiktokUrl" ], "additionalProperties": false }, - "SubscriptionCancelResult": { + "OrganizationProfileUpdate": { "type": "object", "properties": { - "id": { - "type": "string" + "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 }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] + "visual": { + "description": "Brand profile photo and cover (stored on the umbrella organization).", + "type": "object", + "properties": { + "logoUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "coverUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false }, - "cancelledAt": { - "anyOf": [ - { - "type": "string" + "contact": { + "type": "object", + "properties": { + "email": { + "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" + } + ] }, - { - "type": "null" + "phone": { + "anyOf": [ + { + "type": "string", + "maxLength": 40 + }, + { + "type": "null" + } + ] + }, + "website": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] } - ] + }, + "additionalProperties": false + }, + "social": { + "type": "object", + "properties": { + "instagramUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "facebookUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "twitterUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "spotifyUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "youtubeUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + }, + "tiktokUrl": { + "anyOf": [ + { + "type": "string", + "maxLength": 500, + "format": "uri" + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false } }, - "required": [ - "id", - "status", - "cancelledAt" - ], "additionalProperties": false }, - "SaleTicket": { + "Organization": { "type": "object", "properties": { "id": { - "type": "string" + "type": "string", + "description": "Umbrella organization id." }, - "ticketCode": { + "name": { "type": "string" }, - "ticketTypeId": { + "slug": { "type": "string" }, - "ticketTypeName": { - "type": "string" + "logoUrl": { + "type": [ + "string", + "null" + ] }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "coverUrl": { + "type": [ + "string", + "null" + ] }, - "seatLabel": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "ga4MeasurementId": { + "type": [ + "string", + "null" ] + } + }, + "required": [ + "id", + "name", + "slug", + "logoUrl", + "coverUrl", + "ga4MeasurementId" + ], + "additionalProperties": false + }, + "OrganizationUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 80 }, - "checkedInAt": { + "logoUrl": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 500, + "format": "uri" }, { "type": "null" } ] }, - "refundedAt": { + "coverUrl": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 500, + "format": "uri" }, { "type": "null" } ] - }, - "refundAmount": { + } + }, + "additionalProperties": false + }, + "OrganizationAnalyticsUpdate": { + "type": "object", + "properties": { + "ga4MeasurementId": { "anyOf": [ { - "type": "number" + "type": "string", + "maxLength": 32 }, { "type": "null" } - ] - }, - "seatBlocked": { - "type": "boolean" + ], + "description": "GA4 Measurement ID (G-XXXXXXXXXX); null disconnects it." } }, "required": [ - "id", - "ticketCode", - "ticketTypeId", - "ticketTypeName", - "quantity", - "seatLabel", - "checkedInAt", - "refundedAt", - "refundAmount", - "seatBlocked" + "ga4MeasurementId" ], "additionalProperties": false }, - "PaymentAttempt": { + "OrganizationAnalytics": { "type": "object", "properties": { "id": { "type": "string" }, - "provider": { - "type": "string" - }, - "status": { + "ga4MeasurementId": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "ga4MeasurementId" + ], + "additionalProperties": false + }, + "TicketTemplateCreate": { + "type": "object", + "properties": { + "name": { "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." + "minLength": 1, + "maxLength": 100 }, - "declineCode": { + "description": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 500 }, { "type": "null" } ] }, - "declineReason": { + "price": { + "type": "number", + "minimum": 0 + }, + "currency": { + "default": "COP", + "type": "string", + "minLength": 3, + "maxLength": 3 + }, + "capacity": { "anyOf": [ { - "type": "string" + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "amount": { + "maxPerOrder": { + "default": 10, + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + "accentColor": { + "type": [ + "string", + "null" + ] + }, + "includes": { "anyOf": [ { - "type": "number" + "type": "string", + "maxLength": 500 }, { "type": "null" } ] }, - "externalRef": { + "instructions": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 2000 }, { "type": "null" } ] }, - "createdAt": { - "type": "string" - } - }, - "required": [ - "id", - "provider", - "status", - "declineCode", - "declineReason", - "amount", - "externalRef", - "createdAt" - ], - "additionalProperties": false - }, - "TicketReassign": { - "type": "object", - "properties": { - "eventDateId": { - "type": "string", - "minLength": 1 - }, - "ticketTypeId": { - "type": "string", - "minLength": 1 - }, - "seatLabel": { - "type": "string", - "minLength": 1 - } - }, - "additionalProperties": false - }, - "ResendTicket": { - "type": "object", - "properties": { - "ticketCode": { - "type": "string" - }, - "sentTo": { - "type": "string" - }, - "sentAt": { - "type": "string" - } - }, - "required": [ - "ticketCode", - "sentTo", - "sentAt" - ], - "additionalProperties": false - }, - "CheckinResult": { - "type": "object", - "properties": { - "ticketCode": { - "type": "string" + "organizerAbsorbsFee": { + "default": false, + "type": "boolean" }, - "checkedInAt": { + "discount": { "anyOf": [ { - "type": "string" + "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." }, - "checkedInBy": { + "membersOnlyPlanId": { "anyOf": [ { - "type": "string" + "type": "string", + "minLength": 1, + "maxLength": 50 }, { "type": "null" } - ] + ], + "description": "Members-only gate plan; null = open to everyone." }, - "alreadyCheckedIn": { + "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": [ - "ticketCode", - "checkedInAt", - "checkedInBy", - "alreadyCheckedIn" + "name", + "price", + "currency", + "maxPerOrder", + "organizerAbsorbsFee", + "isActive", + "sortOrder", + "fields" ], "additionalProperties": false }, - "CheckinRequest": { + "TicketTemplateUpdate": { "type": "object", "properties": { - "source": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 100 + }, + "description": { "anyOf": [ { "type": "string", - "enum": [ - "pdf", - "web", - "apple", - "google" - ] + "maxLength": 500 }, { "type": "null" } ] - } - }, - "additionalProperties": false - }, - "TicketAccess": { - "type": "object", - "properties": { - "ticketCode": { - "type": "string" }, - "valid": { - "type": "boolean" + "price": { + "type": "number", + "minimum": 0 }, - "status": { + "currency": { "type": "string", - "enum": [ - "VALID", - "USED", - "INVALID" - ] + "minLength": 3, + "maxLength": 3 }, - "saleStatus": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" + "capacity": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } ] }, - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" - }, - "eventDateId": { - "type": "string" - }, - "startsAt": { - "type": "string" - }, - "ticketTypeName": { - "type": "string" + "maxPerOrder": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 }, - "checkedInAt": { + "accentColor": { + "type": [ + "string", + "null" + ] + }, + "includes": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 500 }, { "type": "null" } ] - } - }, - "required": [ - "ticketCode", - "valid", - "status", - "saleStatus", - "eventId", - "eventName", - "eventDateId", - "startsAt", - "ticketTypeName", - "checkedInAt" - ], - "additionalProperties": false - }, - "ApiKeyScope": { - "type": "string", - "enum": [ - "read", - "write" - ] - }, - "ApiKey": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "scope": { - "$ref": "#/components/schemas/ApiKeyScope" - }, - "keyPrefix": { - "type": "string" }, - "lastUsedAt": { + "instructions": { "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": 2000 }, { "type": "null" } ] }, - "expiresAt": { + "organizerAbsorbsFee": { + "type": "boolean" + }, + "discount": { "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", + "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." }, - "revokedAt": { + "membersOnlyPlanId": { "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))$" + "minLength": 1, + "maxLength": 50 }, { "type": "null" } - ] + ], + "description": "Members-only gate plan; null = open to everyone." }, - "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))$" + "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" + } + }, + "required": [ + "label", + "fieldType", + "isRequired" + ], + "additionalProperties": false + }, + "description": "Buyer form fields; the list is replaced as a whole." } }, - "required": [ - "id", - "name", - "scope", - "keyPrefix", - "lastUsedAt", - "expiresAt", - "revokedAt", - "createdAt" - ], "additionalProperties": false }, - "ApiKeyCreated": { + "TicketTemplate": { "type": "object", "properties": { "id": { @@ -17035,540 +33905,774 @@ "name": { "type": "string" }, - "scope": { - "$ref": "#/components/schemas/ApiKeyScope" + "description": { + "type": [ + "string", + "null" + ] }, - "keyPrefix": { + "price": { + "type": "number" + }, + "currency": { "type": "string" }, - "lastUsedAt": { + "capacity": { "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": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "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" - } + "maxPerOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "accentColor": { + "type": [ + "string", + "null" ] }, - "revokedAt": { + "includes": { + "type": [ + "string", + "null" + ] + }, + "instructions": { + "type": [ + "string", + "null" + ] + }, + "organizerAbsorbsFee": { + "type": "boolean" + }, + "discount": { "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", + "properties": { + "planId": { + "type": "string" + }, + "percent": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "planId", + "percent" + ], + "additionalProperties": false }, { "type": "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))$" - }, - "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 + "membersOnlyPlanId": { + "type": [ + "string", + "null" + ] }, - "scope": { - "default": "read", - "$ref": "#/components/schemas/ApiKeyScope" + "isActive": { + "type": "boolean" }, - "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))$" + "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 + } + }, + "required": [ + "id", + "label", + "fieldType", + "options", + "isRequired", + "sortOrder" + ], + "additionalProperties": false + } } }, "required": [ + "id", "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-z]{2,}$" - } - }, - "required": [ - "email" + "description", + "price", + "currency", + "capacity", + "maxPerOrder", + "accentColor", + "includes", + "instructions", + "organizerAbsorbsFee", + "discount", + "membersOnlyPlanId", + "isActive", + "fields" ], "additionalProperties": false }, - "CustomerAuthRequestResult": { + "TicketTemplateInstantiate": { "type": "object", "properties": { - "status": { + "eventDateId": { "type": "string", - "const": "sent" + "minLength": 1, + "description": "Event date of this workspace." }, - "sent_to": { + "name": { "type": "string", - "description": "Masked email (`c***@mail.com`). Never the full address." + "minLength": 1, + "maxLength": 100 }, - "expires_in": { + "price": { + "type": "number", + "minimum": 0 + }, + "capacity": { + "description": "Required when the template has no capacity.", "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Code lifetime, in seconds." + "exclusiveMinimum": 0, + "maximum": 9007199254740991 } }, "required": [ - "status", - "sent_to", - "expires_in" + "eventDateId" ], "additionalProperties": false }, - "CustomerAuthVerify": { + "TicketTemplateInstance": { "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,}$" + "ticketTypeId": { + "type": "string" }, - "code": { - "type": "string", - "minLength": 6, - "maxLength": 6 + "eventId": { + "type": "string" + }, + "eventDateId": { + "type": "string" } }, "required": [ - "email", - "code" + "ticketTypeId", + "eventId", + "eventDateId" ], "additionalProperties": false }, - "CustomerAuthVerifyResult": { + "MasterQr": { "type": "object", "properties": { - "session_token": { + "id": { + "type": "string" + }, + "label": { + "type": "string" + }, + "mode": { "type": "string", - "description": "Usable as-is as the `X-Customer-Session` header on /api/v1/customer/*." + "enum": [ + "EVENT", + "TODAY" + ], + "description": "EVENT: opens the event page (or the tenant listings when org-wide). TODAY: jumps to today's show." }, - "expires_in": { + "eventId": { + "description": "null = org-wide QR (all shows of the workspace).", + "type": [ + "string", + "null" + ] + }, + "ticketTypeId": { + "type": [ + "string", + "null" + ] + }, + "active": { + "type": "boolean" + }, + "scans": { "type": "integer", "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Session lifetime, in seconds." + "maximum": 9007199254740991 + }, + "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": [ - "session_token", - "expires_in" + "id", + "label", + "mode", + "eventId", + "ticketTypeId", + "active", + "scans", + "lastScanAt", + "createdAt", + "code", + "url" ], "additionalProperties": false }, - "CustomerMe": { + "MasterQrCreate": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "email": { - "type": "string" + "label": { + "type": "string", + "minLength": 1, + "maxLength": 80 }, - "name": { - "type": "string" + "mode": { + "type": "string", + "enum": [ + "EVENT", + "TODAY" + ] }, - "emailVerified": { - "type": "boolean" + "eventId": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 60 + }, + { + "type": "null" + } + ] }, - "expiresAt": { - "type": "string", - "description": "Buyer session expiry (ISO 8601)." + "ticketTypeId": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 60 + }, + { + "type": "null" + } + ] } }, "required": [ - "id", - "email", - "name", - "emailVerified", - "expiresAt" + "label", + "mode" ], "additionalProperties": false }, - "CustomerTicketCancelResult": { + "MasterQrUpdate": { "type": "object", "properties": { - "id": { - "type": "string" + "label": { + "type": "string", + "minLength": 1, + "maxLength": 80 }, - "reference": { - "type": "string" + "mode": { + "type": "string", + "enum": [ + "EVENT", + "TODAY" + ] }, - "status": { - "type": "string" + "eventId": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 60 + }, + { + "type": "null" + } + ] + }, + "ticketTypeId": { + "anyOf": [ + { + "type": "string", + "minLength": 1, + "maxLength": 60 + }, + { + "type": "null" + } + ] } }, - "required": [ - "id", - "reference", - "status" - ], "additionalProperties": false }, - "CustomerLogout": { + "MasterQrActive": { "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)." + "active": { + "type": "boolean" } }, "required": [ - "revoked" + "active" ], "additionalProperties": false }, - "EnterpriseExchangeRequest": { + "WorkspaceConfigDeleted": { "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)." + "id": { + "type": "string" + }, + "deleted": { + "type": "boolean", + "const": true } }, "required": [ - "token" + "id", + "deleted" ], "additionalProperties": false }, - "EnterpriseExchangeResponse": { + "MerchOrderCreate": { "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)." - }, - "customer": { + "buyer": { "type": "object", "properties": { - "id": { - "type": "string" + "name": { + "type": "string", + "minLength": 2, + "maxLength": 120 }, - "email": { - "type": "string" + "phone": { + "type": "string", + "pattern": "^\\+?[0-9 -]{7,20}$" }, - "name": { - "type": "string" + "documentType": { + "type": "string", + "enum": [ + "CC", + "CE", + "PP", + "NIT", + "TI", + "PEP" + ] }, - "email_verified": { - "type": "boolean" + "document": { + "type": "string", + "minLength": 3, + "maxLength": 20 } }, "required": [ - "id", - "email", "name", - "email_verified" + "phone", + "documentType", + "document" ], "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": [ + "delivery": { + "oneOf": [ { "type": "object", "properties": { - "id": { - "type": "string" + "kind": { + "type": "string", + "const": "SHIPPING" }, - "status": { + "departmentCode": { "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] + "pattern": "^\\d{2}$" }, - "plan": { - "$ref": "#/components/schemas/MembershipPlan" + "department": { + "type": "string", + "minLength": 1, + "maxLength": 80 }, - "startedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "cityCode": { + "type": "string", + "pattern": "^\\d{5}$" }, - "expiresAt": { + "city": { + "type": "string", + "minLength": 1, + "maxLength": 80 + }, + "address": { + "type": "string", + "minLength": 5, + "maxLength": 200 + }, + "addressExtra": { "anyOf": [ { - "type": "string" + "type": "string", + "maxLength": 200 }, { "type": "null" } - ], - "description": "null = LIFETIME or a membership with no expiry." - }, - "autoRenew": { - "type": "boolean" + ] } }, "required": [ - "id", - "status", - "plan", - "startedAt", - "expiresAt", - "autoRenew" + "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": [ - "active", - "membership" + "buyer", + "delivery", + "items" ], "additionalProperties": false }, - "CustomerSubscribeRequest": { + "MerchOrderLookup": { "type": "object", "properties": { - "planId": { + "code": { "type": "string", - "minLength": 1, - "description": "Id of an active MembershipPlan in the key's workspace." + "minLength": 3, + "maxLength": 20 } }, "required": [ - "planId" + "code" ], "additionalProperties": false }, - "CustomerSubscribeResult": { + "MerchCardPayment": { "type": "object", "properties": { - "checkoutUrl": { + "token": { "type": "string", - "description": "Membership checkout URL on the canonical host. The landing page must redirect the buyer there." - }, - "planId": { - "type": "string" - } - }, - "required": [ - "checkoutUrl", - "planId" - ], - "additionalProperties": false - }, - "CustomerSubscriptionCancelResult": { - "type": "object", - "properties": { - "id": { - "type": "string" + "minLength": 1, + "description": "Card token returned by the Payment Brick when tokenizing." }, - "status": { + "paymentMethodId": { "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] + "minLength": 1, + "description": "`payment_method_id` returned by the Brick (e.g. `visa`, `debmaster`)." }, - "cancelledAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" + "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": [ - "id", - "status", - "cancelledAt" + "token", + "paymentMethodId", + "installments" ], "additionalProperties": false }, - "CustomerSubscriptionCancelRequest": { + "MerchCardPaymentResult": { "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.", + "status": { "type": "string", - "minLength": 1 - } - }, - "additionalProperties": false - }, - "CustomerProfile": { - "type": "object", - "properties": { - "id": { - "type": "string" + "enum": [ + "approved", + "pending", + "rejected" + ], + "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." }, - "email": { + "code": { "type": "string" }, - "name": { + "message": { + "description": "Human-readable message. Only present with `rejected`.", "type": "string" - }, - "phone": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] } }, "required": [ - "id", - "email", - "name", - "phone" + "status", + "code" ], "additionalProperties": false }, - "CustomerProfileUpdate": { + "MerchOrder": { "type": "object", "properties": { - "name": { + "code": { + "type": "string" + }, + "status": { "type": "string", - "minLength": 1, - "maxLength": 120 + "enum": [ + "PENDING", + "PAID", + "PREPARING", + "SHIPPED", + "DELIVERED", + "READY_FOR_PICKUP", + "PICKED_UP", + "CANCELLED", + "REFUNDED" + ] }, - "phone": { - "description": "null or an empty string clears the phone.", - "anyOf": [ - { - "type": "string", - "maxLength": 30 - }, - { - "type": "null" - } + "currency": { + "type": "string", + "const": "COP" + }, + "reservedUntil": { + "type": [ + "string", + "null" ] - } - }, - "additionalProperties": false - }, - "ContentVideo": { - "type": "object", - "properties": { - "id": { - "type": "string" }, - "title": { + "createdAt": { "type": "string" }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "paidAt": { + "type": [ + "string", + "null" ] }, - "durationSeconds": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "buyer": { + "type": "object", + "properties": { + "email": { + "type": "string" }, - { - "type": "null" + "name": { + "type": "string" + }, + "phone": { + "type": "string" } + }, + "required": [ + "email", + "name", + "phone" + ], + "additionalProperties": false + }, + "fulfillment": { + "type": "string", + "enum": [ + "SHIPPING", + "PICKUP" ] }, - "posterUrl": { + "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" } ] }, - "series": { + "pickupPoint": { "anyOf": [ { "type": "object", @@ -17576,13 +34680,31 @@ "id": { "type": "string" }, - "title": { + "name": { + "type": "string" + }, + "address": { "type": "string" + }, + "city": { + "type": [ + "string", + "null" + ] + }, + "schedule": { + "type": [ + "string", + "null" + ] } }, "required": [ "id", - "title" + "name", + "address", + "city", + "schedule" ], "additionalProperties": false }, @@ -17591,276 +34713,493 @@ } ] }, - "memberOnly": { - "type": "boolean", - "description": "true = only current members of the organization can play it." - }, - "publishedAt": { - "anyOf": [ - { - "type": "string" + "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 + } }, - { - "type": "null" - } - ] - } - }, - "required": [ - "id", - "title", - "description", - "durationSeconds", - "posterUrl", - "series", - "memberOnly", - "publishedAt" - ], - "additionalProperties": false - }, - "ContentPost": { - "type": "object", - "properties": { - "id": { - "type": "string" + "required": [ + "variantId", + "productName", + "variantLabel", + "sku", + "quantity", + "unitPrice" + ], + "additionalProperties": false + } }, - "type": { - "type": "string", - "enum": [ - "TEXT", - "IMAGE", - "VIDEO", - "ARTICLE" - ] + "subtotal": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "content": { + "shippingFee": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "total": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "tracking": { "anyOf": [ { - "type": "string" + "type": "object", + "properties": { + "carrier": { + "type": [ + "string", + "null" + ] + }, + "carrierName": { + "type": [ + "string", + "null" + ] + }, + "carrierLabel": { + "type": [ + "string", + "null" + ] + }, + "trackingNumber": { + "type": [ + "string", + "null" + ] + }, + "trackingUrl": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "carrier", + "carrierName", + "carrierLabel", + "trackingNumber", + "trackingUrl" + ], + "additionalProperties": false }, { "type": "null" } ] }, - "imageUrl": { - "anyOf": [ - { - "type": "string" + "statusDates": { + "type": "object", + "properties": { + "paidAt": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" - } - ], - "description": "ARTICLE post: also serves as the article's cover image." - }, - "videoId": { - "anyOf": [ - { - "type": "string" + "preparingAt": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" - } - ], - "description": "VIDEO post: id of the ContentVideo, to cross-reference with `GET /content/videos`." - }, - "eventId": { - "anyOf": [ - { - "type": "string" + "shippedAt": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" - } - ] - }, - "locked": { - "type": "boolean", - "description": "true = post restricted to current members; its content arrives redacted." - }, - "title": { - "anyOf": [ - { - "type": "string" + "deliveredAt": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" - } - ], - "description": "ARTICLE posts only; null for every other type." - }, - "subtitle": { - "anyOf": [ - { - "type": "string" + "readyForPickupAt": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" - } - ], - "description": "ARTICLE posts only." - }, - "slug": { - "anyOf": [ - { - "type": "string" + "pickedUpAt": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" + "cancelledAt": { + "type": [ + "string", + "null" + ] + }, + "refundedAt": { + "type": [ + "string", + "null" + ] } + }, + "required": [ + "paidAt", + "preparingAt", + "shippedAt", + "deliveredAt", + "readyForPickupAt", + "pickedUpAt", + "cancelledAt", + "refundedAt" ], - "description": "ARTICLE posts only. Permalink at /comunidades/articulos/{slug}, unique per organization." + "additionalProperties": false }, - "body": { - "anyOf": [ - { + "mpPublicKey": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "code", + "status", + "currency", + "reservedUntil", + "createdAt", + "paidAt", + "buyer", + "fulfillment", + "shipping", + "pickupPoint", + "items", + "subtotal", + "shippingFee", + "total", + "tracking", + "statusDates", + "mpPublicKey" + ], + "additionalProperties": false + }, + "MerchCatalog": { + "type": "object", + "properties": { + "store": { + "type": "object", + "properties": { + "brandName": { "type": "string" }, - { - "type": "null" - } - ], - "description": "ARTICLE posts only. Body in Markdown." - }, - "readingMinutes": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "brandLogoUrl": { + "type": [ + "string", + "null" + ] }, - { - "type": "null" - } - ], - "description": "ARTICLE posts only. Not redacted when `locked`: it does not leak content, only its length." - }, - "link": { - "anyOf": [ - { + "landingUrl": { + "type": [ + "string", + "null" + ] + }, + "support": { "type": "object", "properties": { - "url": { - "type": "string" - }, - "title": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "phone": { + "type": [ + "string", + "null" ] }, - "description": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "isWhatsapp": { + "type": "boolean" + }, + "email": { + "type": [ + "string", + "null" ] + } + }, + "required": [ + "phone", + "isWhatsapp", + "email" + ], + "additionalProperties": false + }, + "shipping": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" }, - "imageUrl": { + "feeBogota": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "feeNational": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "freeShippingThreshold": { "anyOf": [ { - "type": "string" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] - }, - "domain": { - "type": "string" } }, "required": [ - "url", - "title", - "description", - "imageUrl", - "domain" + "enabled", + "feeBogota", + "feeNational", + "freeShippingThreshold" ], "additionalProperties": false }, - { - "type": "null" + "pickupEnabled": { + "type": "boolean" } + }, + "required": [ + "brandName", + "brandLogoUrl", + "landingUrl", + "support", + "shipping", + "pickupEnabled" ], - "description": "Open Graph snapshot of the first link in the text. Always null for ARTICLE posts." + "additionalProperties": false }, - "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." + "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 + } }, - "publishedAt": { - "type": "string" + "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 + } + }, + "currency": { + "type": "string", + "const": "COP" + }, + "mpPublicKey": { + "type": [ + "string", + "null" + ] } }, "required": [ - "id", - "type", - "content", - "imageUrl", - "videoId", - "eventId", - "locked", - "title", - "subtitle", - "slug", - "body", - "readingMinutes", - "link", - "commentsCount", - "publishedAt" + "store", + "products", + "pickupPoints", + "currency", + "mpPublicKey" ], "additionalProperties": false }, - "ContentPostCreate": { + "MerchProductCreate": { "type": "object", "properties": { - "type": { - "default": "TEXT", - "type": "string", - "enum": [ - "TEXT", - "IMAGE", - "ARTICLE" - ] - }, - "content": { - "type": "string", - "maxLength": 5000 - }, - "imageUrl": { - "anyOf": [ - { - "type": "string", - "maxLength": 2048, - "format": "uri" - }, - { - "type": "null" - } - ] - }, - "title": { - "description": "Required when type=ARTICLE.", + "name": { "type": "string", "minLength": 1, - "maxLength": 140 + "maxLength": 120 }, - "subtitle": { + "description": { "anyOf": [ { "type": "string", - "maxLength": 280 + "maxLength": 5000 }, { "type": "null" @@ -17868,262 +35207,355 @@ ] }, "slug": { - "description": "Manual; if omitted it is derived from the title.", - "anyOf": [ - { - "type": "string", - "maxLength": 200 - }, - { - "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 - }, - { - "type": "null" - } - ] - }, - "publishedAt": { + "description": "Lowercase letters, digits and dashes. Omitted: derived from the name (first free one in the store).", "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" + "maxLength": 60 }, - "status": { - "type": "string", - "enum": [ - "IDLE", - "ACTIVE", - "COMPLETED", - "DISABLED" - ], - "description": "ACTIVE = streaming right now (live banner)." + "maxPerOrder": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "description": "Maximum units of this product per order." }, - "memberOnly": { - "type": "boolean" + "sortOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "startedAt": { - "anyOf": [ - { - "type": "string" + "options": { + "description": "Up to 3 options (Talla, Color…). The variants must be EXACTLY the combinations of their values, each once (at most 100). No options = one variant with empty `attributes`.", + "maxItems": 3, + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 40, + "description": "Option name, e.g. `Talla`." + }, + "values": { + "minItems": 1, + "maxItems": 30, + "type": "array", + "items": { + "type": "string", + "minLength": 1, + "maxLength": 60 + }, + "description": "Option values in display order, e.g. `[\"S\", \"M\", \"L\"]`." + } }, - { - "type": "null" - } - ] + "required": [ + "name", + "values" + ], + "additionalProperties": false + } }, - "endedAt": { - "anyOf": [ - { - "type": "string" + "variants": { + "minItems": 1, + "maxItems": 100, + "type": "array", + "items": { + "type": "object", + "properties": { + "attributes": { + "description": "One value per option, keyed by option name: `{ \"Talla\": \"M\" }`.", + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + }, + "sku": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "description": "Unique in the whole store (case-insensitive). Letters, digits, `.`, `-`, `_`." + }, + "price": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "COP, integer, VAT included." + }, + "compareAtPrice": { + "description": "Strikethrough price; must be greater than `price`.", + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "stock": { + "type": "integer", + "minimum": 0, + "maximum": 9007199254740991 + }, + "isActive": { + "type": "boolean" + } }, - { - "type": "null" - } - ] + "required": [ + "sku", + "price", + "stock" + ], + "additionalProperties": false + } }, - "hasRecording": { - "type": "boolean", - "description": "true if a playable recording remains after the stream." + "imageUrls": { + "description": "Ordered photos (the first is the cover). Each must be a `publicUrl` returned by `POST /merch/products/images/upload-url` for this organization. External URLs are rejected (they are never fetched).", + "maxItems": 10, + "type": "array", + "items": { + "type": "string" + } } }, "required": [ - "id", - "title", - "status", - "memberOnly", - "startedAt", - "endedAt", - "hasRecording" + "name", + "maxPerOrder", + "variants" ], "additionalProperties": false }, - "ContentPlaybackTokenRequest": { + "MerchProductStatusUpdate": { "type": "object", "properties": { - "kind": { + "status": { "type": "string", "enum": [ - "video", - "live" + "DRAFT", + "PUBLISHED" ] - }, - "id": { - "type": "string", - "minLength": 1 } }, "required": [ - "kind", - "id" + "status" ], "additionalProperties": false }, - "ContentPlaybackToken": { + "MerchProductImagesUpdate": { "type": "object", "properties": { - "playbackId": { - "type": "string" - }, - "tokens": { - "type": "object", - "properties": { - "playback": { - "type": "string" - }, - "drm": { - "type": "string" - }, - "thumbnail": { - "type": "string" - }, - "storyboard": { - "type": "string" - } + "imageUrls": { + "maxItems": 10, + "type": "array", + "items": { + "type": "string" }, - "required": [ - "playback", - "drm" - ], - "additionalProperties": false + "description": "Full ordered list (replaces the current one; the first is the cover). Each URL must be a `publicUrl` from `POST /merch/products/images/upload-url` for this organization, or one the product already has. Photos that leave the list are deleted from storage." } }, "required": [ - "playbackId", - "tokens" + "imageUrls" ], "additionalProperties": false }, - "WaitlistEntryCreate": { + "MerchImageUploadRequest": { "type": "object", "properties": { - "city": { - "type": "string", - "minLength": 1, - "maxLength": 60 - }, - "name": { - "type": "string", - "minLength": 1, - "maxLength": 80 - }, - "contact": { + "mimeType": { "type": "string", - "minLength": 1, - "maxLength": 120 + "enum": [ + "image/jpeg", + "image/png", + "image/webp" + ] }, - "source": { - "type": "string", - "maxLength": 40 + "sizeBytes": { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 6291456, + "description": "File size in bytes (max 6 MB)." } }, "required": [ - "city", - "name", - "contact" + "mimeType", + "sizeBytes" ], "additionalProperties": false }, - "WaitlistEntryResult": { + "MerchImageUpload": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "city": { - "type": "string" + "uploadUrl": { + "type": "string", + "description": "Signed storage URL. `PUT` the raw file bytes to it with the same `Content-Type` as `mimeType`, no auth header. Single use." }, - "created": { - "type": "boolean" + "publicUrl": { + "type": "string", + "description": "Final public URL of the photo once uploaded. Pass it in `imageUrls`." } }, "required": [ - "id", - "city", - "created" + "uploadUrl", + "publicUrl" ], "additionalProperties": false }, - "WaitlistEntry": { + "MerchAdminProduct": { "type": "object", "properties": { "id": { "type": "string" }, - "city": { + "slug": { "type": "string" }, "name": { "type": "string" }, - "contact": { - "type": "string" + "description": { + "type": [ + "string", + "null" + ] }, - "customerId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "status": { + "type": "string", + "enum": [ + "DRAFT", + "PUBLISHED" ] }, - "source": { - "anyOf": [ - { - "type": "string" + "imageUrls": { + "type": "array", + "items": { + "type": "string" + } + }, + "options": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "values": { + "type": "array", + "items": { + "type": "string" + } + } }, - { - "type": "null" - } + "required": [ + "name", + "values" + ], + "additionalProperties": false + } + }, + "maxPerOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "sortOrder": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "publishedAt": { + "type": [ + "string", + "null" ] }, "createdAt": { "type": "string" + }, + "updatedAt": { + "type": "string" + }, + "variants": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "sku": { + "type": "string" + }, + "label": { + "type": "string" + }, + "attributes": { + "type": "object", + "propertyNames": { + "type": "string" + }, + "additionalProperties": { + "type": "string" + } + }, + "price": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "compareAtPrice": { + "anyOf": [ + { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "stock": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "isActive": { + "type": "boolean" + } + }, + "required": [ + "id", + "sku", + "label", + "attributes", + "price", + "compareAtPrice", + "stock", + "isActive" + ], + "additionalProperties": false + } } }, "required": [ "id", - "city", + "slug", "name", - "contact", - "customerId", - "source", - "createdAt" + "description", + "status", + "imageUrls", + "options", + "maxPerOrder", + "sortOrder", + "publishedAt", + "createdAt", + "updatedAt", + "variants" ], "additionalProperties": false } diff --git a/src/commands/merch.test.ts b/src/commands/merch.test.ts new file mode 100644 index 0000000..5639913 --- /dev/null +++ b/src/commands/merch.test.ts @@ -0,0 +1,535 @@ +import { + mkdirSync, + mkdtempSync, + readFileSync, + statSync, + symlinkSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { Command } from "commander"; +import { afterEach, describe, expect, it, vi } from "vitest"; +import type { MerchAdminProduct } from "../client/types.gen"; +import { + buildProductBody, + checkImage, + createProduct, + type MerchDeps, + MerchStepError, + parseProductsFile, + registerMerch, + skuBaseFrom, + sniffImage, + validateBatch, + validateSpec, +} from "./merch"; + +vi.mock("../lib/api", async (importOriginal) => ({ + ...(await importOriginal()), + // No real account/client in tests: the commands only need it not to throw. + configureClient: vi.fn(), +})); + +const JPEG = [0xff, 0xd8, 0xff, 0xe0, 1, 2, 3, 4]; +const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0]; +const WEBP = [...Buffer.from("RIFF"), 0, 0, 0, 0, ...Buffer.from("WEBPVP8 ")]; + +const res = (data: T, status = 200) => ({ + data, + response: new Response(null, { status }), +}); +const err = ( + status: number, + code: string, + message: string, + headers: Record = {}, +) => ({ + error: { error: { code, message } }, + response: new Response(null, { status, headers }), +}); + +const product = (over: Partial = {}): MerchAdminProduct => ({ + id: "p_1", + slug: "camiseta-tour", + name: "Camiseta Tour", + description: null, + status: "DRAFT", + imageUrls: [], + options: [], + maxPerOrder: 10, + sortOrder: 0, + publishedAt: null, + createdAt: "2026-11-03T00:00:00.000Z", + updatedAt: "2026-11-03T00:00:00.000Z", + variants: [ + { + id: "v", + sku: "X", + label: "S", + attributes: {}, + price: 1, + compareAtPrice: null, + stock: 1, + isActive: true, + }, + ], + ...over, +}); + +function tmp(): string { + return mkdtempSync(join(tmpdir(), "ft-merch-")); +} + +/** Real image files on disk (checkImage stats and sniffs them). */ +function images(dir = tmp()): [string, string] { + const a = join(dir, "front.jpg"); + const b = join(dir, "back.png"); + writeFileSync(a, Buffer.from(JPEG)); + writeFileSync(b, Buffer.from(PNG)); + return [a, b]; +} + +function deps(over: Partial = {}): MerchDeps { + let n = 0; + let id = 0; + return { + create: vi.fn(async (body) => { + id += 1; + return res({ data: product({ id: `p_${id}`, name: body.name }) }, 201); + }), + uploadUrl: vi.fn(async () => { + n += 1; + return res( + { + data: { + uploadUrl: `https://store.test/sign/${n}?token=t`, + publicUrl: `https://store.test/public/merch/org_1/${n}.jpg`, + }, + }, + 201, + ); + }), + setImages: vi.fn(async (id, imageUrls) => res({ data: { id, imageUrls } })), + setStatus: vi.fn(async (id, status) => res({ data: { id, status } })), + readFile: vi.fn((p: string) => readFileSync(p)), + put: vi.fn(async () => new Response(null, { status: 200 })), + sleep: vi.fn(async () => {}), + ...over, + }; +} + +afterEach(() => vi.restoreAllMocks()); + +describe("buildProductBody", () => { + it("sizes become one option and one variant per size, with SKUs and stock", () => { + const body = buildProductBody({ + name: "Camiseta Tour Ñandú", + price: 80_000, + sizes: ["XS", "S", "2XL"], + stock: 10, + }); + expect(body.options).toEqual([ + { name: "Talla", values: ["XS", "S", "2XL"] }, + ]); + expect(body.variants).toEqual([ + { + attributes: { Talla: "XS" }, + sku: "CAMISETA-TOUR-NANDU-XS", + price: 80_000, + compareAtPrice: null, + stock: 10, + }, + expect.objectContaining({ sku: "CAMISETA-TOUR-NANDU-S", stock: 10 }), + expect.objectContaining({ sku: "CAMISETA-TOUR-NANDU-2XL", stock: 10 }), + ]); + }); + + it("without sizes: a single variant and no options", () => { + const body = buildProductBody({ name: "Gorra", price: 50_000, stock: 3 }); + expect(body.options).toEqual([]); + expect(body.variants).toEqual([ + { + attributes: {}, + sku: "GORRA", + price: 50_000, + compareAtPrice: null, + stock: 3, + }, + ]); + }); + + it("stock per size, unknown size rejected", () => { + const body = buildProductBody({ + name: "X", + price: 1, + sizes: ["S", "M"], + stock: { M: 4 }, + sku: "CAM", + }); + expect(body.variants.map((v) => [v.sku, v.stock])).toEqual([ + ["CAM-S", 0], + ["CAM-M", 4], + ]); + expect(() => + buildProductBody({ name: "X", price: 1, sizes: ["S"], stock: { L: 1 } }), + ).toThrow(/unknown size/); + }); + + it("skuBaseFrom mirrors the dashboard", () => { + expect(skuBaseFrom("Camiseta Tour 2026!")).toBe("CAMISETA-TOUR-2026"); + expect(skuBaseFrom("¡¡!!")).toBe("SKU"); + }); +}); + +describe("validateSpec (runtime shape of an untyped row)", () => { + it("rejects wrong types with a field message, never a TypeError", () => { + const cases: [unknown, RegExp][] = [ + [{ name: "A", price: 1, images: "a.jpg" }, /"images" must be an array/], + [{ name: "A", price: 1, sizes: "S,M" }, /"sizes" must be an array/], + [{ name: "A", price: 1, stock: -1 }, /"stock" must be/], + [{ name: "A", price: 1, stock: { S: -2 } }, /"stock" must be/], + [{ name: "A", price: 1.5 }, /"price" must be/], + [{ price: 1 }, /"name" must be/], + [{ name: "A", price: 1, publish: "yes" }, /"publish"/], + ["nope", /must be an object/], + ]; + for (const [spec, msg] of cases) { + expect(() => validateSpec(spec, "row")).toThrow(msg); + try { + validateSpec(spec, "row"); + } catch (e) { + expect(e).not.toBeInstanceOf(TypeError); + } + } + }); + + it("more than 10 photos is rejected up front", () => { + const imgs = Array.from({ length: 11 }, (_, i) => `${i}.jpg`); + expect(() => + validateSpec({ name: "A", price: 1, images: imgs }, "row"), + ).toThrow(/at most 10/); + }); +}); + +describe("checkImage (magic bytes)", () => { + it("detects JPEG, PNG and WebP by content, not by extension", () => { + expect(sniffImage(Uint8Array.from(JPEG))).toBe("image/jpeg"); + expect(sniffImage(Uint8Array.from(PNG))).toBe("image/png"); + expect(sniffImage(Uint8Array.from(WEBP))).toBe("image/webp"); + const dir = tmp(); + const disguised = join(dir, "photo.jpg"); + writeFileSync(disguised, Buffer.from(PNG)); + expect(checkImage(disguised)).toBe("image/png"); + }); + + it("rejects a non-image renamed .jpg, empty files, >6 MB and missing files", () => { + const dir = tmp(); + const fake = join(dir, "fake.jpg"); + writeFileSync(fake, "not an image"); + expect(() => checkImage(fake)).toThrow(/JPG, PNG or WebP/); + const empty = join(dir, "empty.png"); + writeFileSync(empty, ""); + expect(() => checkImage(empty)).toThrow(/empty/); + const big = join(dir, "big.png"); + writeFileSync( + big, + Buffer.concat([Buffer.from(PNG), Buffer.alloc(6 * 1024 * 1024)]), + ); + expect(() => checkImage(big)).toThrow(/6 MB/); + expect(() => checkImage(join(dir, "nope.png"))).toThrow(/cannot read/); + }); +}); + +describe("parseProductsFile (paths)", () => { + function catalog() { + const dir = tmp(); + mkdirSync(join(dir, "img")); + writeFileSync(join(dir, "img", "a.jpg"), Buffer.from(JPEG)); + return { dir, file: join(dir, "products.json") }; + } + const parse = (file: string, images: string[]) => + parseProductsFile( + JSON.stringify({ products: [{ name: "A", price: 1, images }] }), + file, + ); + + it("resolves relative images inside the file's folder", () => { + const { dir, file } = catalog(); + expect(parse(file, ["img/a.jpg"])[0]?.images).toEqual([ + join(dir, "img", "a.jpg"), + ]); + }); + + it("rejects absolute paths and `..` out of the folder", () => { + const { file } = catalog(); + expect(() => parse(file, ["/etc/passwd"])).toThrow(/must be relative/); + expect(() => parse(file, ["../secret.jpg"])).toThrow(/outside/); + expect(() => parse(file, ["img/../../x.jpg"])).toThrow(/outside/); + }); + + it("rejects a symlink, even one pointing inside the folder", () => { + const { dir, file } = catalog(); + symlinkSync(join(dir, "img", "a.jpg"), join(dir, "img", "link.jpg")); + expect(() => parse(file, ["img/link.jpg"])).toThrow(/symlink/); + }); + + it("accepts a bare array, rejects empty or invalid JSON", () => { + expect( + parseProductsFile('[{"name":"A","price":1}]', "x.json"), + ).toHaveLength(1); + expect(() => parseProductsFile("[]", "x.json")).toThrow(/at least one/); + expect(() => parseProductsFile("{", "x.json")).toThrow(/Invalid JSON/); + }); +}); + +describe("createProduct", () => { + it("creates DRAFT, uploads each photo with its real size, then sets the list", async () => { + const d = deps(); + const [a, b] = images(); + const out = await createProduct( + { name: "Camiseta Tour", price: 80_000, sizes: ["S"], images: [a, b] }, + d, + ); + // sizeBytes is the size of the file on disk, bytes actually PUT. + expect(d.uploadUrl).toHaveBeenNthCalledWith(1, { + mimeType: "image/jpeg", + sizeBytes: statSync(a).size, + }); + expect(d.uploadUrl).toHaveBeenNthCalledWith(2, { + mimeType: "image/png", + sizeBytes: statSync(b).size, + }); + const [url, sent, type] = (d.put as ReturnType).mock + .calls[0] as [string, Uint8Array, string]; + expect(url).toBe("https://store.test/sign/1?token=t"); + expect(Buffer.from(sent)).toEqual(readFileSync(a)); + expect(type).toBe("image/jpeg"); + expect(d.setImages).toHaveBeenCalledWith("p_1", [ + "https://store.test/public/merch/org_1/1.jpg", + "https://store.test/public/merch/org_1/2.jpg", + ]); + expect(out.status).toBe("DRAFT"); + }); + + it("409 SKU_TAKEN on a re-run says how to recover", async () => { + const d = deps({ + create: vi.fn(async () => + err(409, "SKU_TAKEN", 'El SKU "CAM-S" ya existe en la tienda.'), + ) as never, + }); + const e = await createProduct({ name: "Cam", price: 1 }, d).catch((x) => x); + expect(e).toBeInstanceOf(MerchStepError); + expect(e.step).toBe("create"); + expect(e.message).toMatch(/SKU_TAKEN/); + expect(e.message).toMatch(/ft merch products list/); + expect(e.message).toMatch(/ft merch products images /); + expect(d.uploadUrl).not.toHaveBeenCalled(); + }); + + it("429 mid-upload: waits Retry-After and retries once, then goes on", async () => { + let calls = 0; + const base = deps(); + const d = deps({ + uploadUrl: vi.fn(async (body) => { + calls += 1; + if (calls === 2) + return err(429, "RATE_LIMITED", "Espera.", { "Retry-After": "7" }); + return base.uploadUrl(body); + }) as never, + }); + const [a, b] = images(); + const out = await createProduct({ name: "X", price: 1, images: [a, b] }, d); + expect(d.sleep).toHaveBeenCalledWith(7000); + expect(d.uploadUrl).toHaveBeenCalledTimes(3); + expect(out.imageUrls).toHaveLength(2); + }); + + it("a second 429 is not retried again: fails at upload-url with the product id", async () => { + const d = deps({ + uploadUrl: vi.fn(async () => + err(429, "RATE_LIMITED", "Espera.", { "Retry-After": "1" }), + ) as never, + }); + const [a] = images(); + const e = await createProduct( + { name: "X", price: 1, images: [a] }, + d, + ).catch((x) => x); + expect(d.uploadUrl).toHaveBeenCalledTimes(2); + expect(e.step).toBe("upload-url"); + expect(e.productId).toBe("p_1"); + expect(d.setImages).not.toHaveBeenCalled(); + }); + + it("a failed storage PUT stops before setting images", async () => { + const d = deps({ + put: vi.fn(async () => new Response(null, { status: 403 })), + }); + const [a] = images(); + const e = await createProduct( + { name: "X", price: 1, images: [a] }, + d, + ).catch((x) => x); + expect(e.step).toBe("upload"); + expect(e.message).toMatch(/storage answered 403/); + expect(d.setImages).not.toHaveBeenCalled(); + }); +}); + +describe("validateBatch", () => { + it("one bad row (photo or shape) aborts before any request", () => { + const [a] = images(); + expect(() => + validateBatch([ + { name: "A", price: 1, images: [a] }, + { name: "B", price: 1, images: ["/nope/x.png"] }, + ]), + ).toThrow(/cannot read/); + expect(() => + validateBatch([ + { name: "A", price: 1 }, + { name: "B", price: 1, sizes: "S" } as never, + ]), + ).toThrow(/"sizes" must be an array/); + }); +}); + +/** Runs `ft merch products …` against injected deps, capturing output/exit. */ +async function run(argv: string[], d: MerchDeps) { + let stdout = ""; + let stderr = ""; + vi.spyOn(process.stdout, "write").mockImplementation((c) => { + stdout += String(c); + return true; + }); + vi.spyOn(console, "log").mockImplementation((...a) => { + stdout += `${a.join(" ")}\n`; + }); + vi.spyOn(console, "error").mockImplementation((...a) => { + stderr += `${a.join(" ")}\n`; + }); + const exit = vi.spyOn(process, "exit").mockImplementation((( + code?: number, + ) => { + throw new Error(`exit ${code}`); + }) as never); + const program = new Command().exitOverride(); + registerMerch(program, d); + let code = 0; + try { + await program.parseAsync(["node", "ft", "merch", "products", ...argv]); + } catch (e) { + code = Number(/exit (\d+)/.exec((e as Error).message)?.[1] ?? 1); + } + exit.mockRestore(); + return { stdout, stderr, code }; +} + +describe("ft merch products create --from-json", () => { + function file(products: unknown[]) { + const dir = tmp(); + const f = join(dir, "p.json"); + writeFileSync(f, JSON.stringify({ products })); + return f; + } + + it("1 of 3 fails: exit 1, stdout has the two created, stderr names the failure", async () => { + const base = deps(); + const d = deps({ + create: vi.fn(async (body) => + body.name === "B" + ? err(409, "SKU_TAKEN", 'El SKU "B" ya existe en la tienda.') + : base.create(body), + ) as never, + }); + const f = file([ + { name: "A", price: 1 }, + { name: "B", price: 1 }, + { name: "C", price: 1 }, + ]); + const out = await run(["create", "--from-json", f, "--json"], d); + expect(out.code).toBe(1); + const parsed = JSON.parse(out.stdout); + expect(parsed.created.map((p: { name: string }) => p.name)).toEqual([ + "A", + "C", + ]); + expect(parsed.failed).toEqual([ + expect.objectContaining({ name: "B", step: "create" }), + ]); + expect(out.stderr).toMatch(/1 of 3 product\(s\) failed/); + expect(out.stderr).toMatch(/SKU_TAKEN/); + }); + + it("a failure after create reports the product id in --json", async () => { + const d = deps({ + put: vi.fn(async () => new Response(null, { status: 500 })), + }); + const dir = tmp(); + writeFileSync(join(dir, "a.jpg"), Buffer.from(JPEG)); + const f = join(dir, "p.json"); + writeFileSync( + f, + JSON.stringify([{ name: "A", price: 1, images: ["a.jpg"] }]), + ); + const out = await run(["create", "--from-json", f, "--json"], d); + expect(out.code).toBe(1); + expect(JSON.parse(out.stdout).failed[0]).toMatchObject({ + name: "A", + productId: "p_1", + step: "upload", + }); + }); + + it("a bad row anywhere creates nothing", async () => { + const d = deps(); + const f = file([ + { name: "A", price: 1 }, + { name: "B", price: 1, stock: -1 }, + ]); + const out = await run(["create", "--from-json", f], d); + expect(out.code).toBe(1); + expect(out.stderr).toMatch(/"stock"/); + expect(d.create).not.toHaveBeenCalled(); + }); +}); + +describe("ft merch products images ", () => { + it("uploads the files and replaces the product's photos", async () => { + const d = deps(); + const [a, b] = images(); + const out = await run( + ["images", "p_9", "--image", a, "--image", b, "--json"], + d, + ); + expect(out.code).toBe(0); + expect(d.create).not.toHaveBeenCalled(); + expect(d.setImages).toHaveBeenCalledWith("p_9", [ + "https://store.test/public/merch/org_1/1.jpg", + "https://store.test/public/merch/org_1/2.jpg", + ]); + }); +}); + +describe("registerMerch", () => { + it("wires merch products list|create|images|publish|unpublish", () => { + const program = new Command(); + registerMerch(program, deps()); + const products = program.commands + .find((c) => c.name() === "merch") + ?.commands.find((c) => c.name() === "products") as Command; + expect(products.commands.map((c) => c.name()).sort()).toEqual([ + "create", + "images", + "list", + "publish", + "unpublish", + ]); + const create = products.commands.find( + (c) => c.name() === "create", + ) as Command; + create.parseOptions(["--image", "a.jpg", "--image", "b.jpg"]); + expect(create.opts().image).toEqual(["a.jpg", "b.jpg"]); + }); +}); diff --git a/src/commands/merch.ts b/src/commands/merch.ts new file mode 100644 index 0000000..647398e --- /dev/null +++ b/src/commands/merch.ts @@ -0,0 +1,739 @@ +import { + closeSync, + lstatSync, + openSync, + readFileSync, + readSync, + statSync, +} from "node:fs"; +import { dirname, isAbsolute, relative, resolve } from "node:path"; +import type { Command } from "commander"; +import { + getMerchProducts, + patchMerchProductsIdStatus, + postMerchProducts, + postMerchProductsImagesUploadUrl, + putMerchProductsIdImages, +} from "../client/sdk.gen"; +import type { + MerchAdminProduct, + MerchImageUploadRequest, + MerchProductCreate, +} from "../client/types.gen"; +import { configureClient, describeError, fail, unwrap } from "../lib/api"; +import { print } from "../lib/output"; + +// `ft merch products ...` — the merch store catalog of the key's organization +// (contract 1.38). Products are always born DRAFT; photos only enter through +// the signed upload (the backend never downloads a URL), so `create` uploads +// each local file and then sets the ordered list. + +/** Same limits as the backend (`POST /merch/products/images/upload-url`). */ +const MAX_IMAGE_BYTES = 6 * 1024 * 1024; +const MAX_IMAGES = 10; + +const LIST_COLUMNS = ["id", "name", "status", "variants", "stock", "price"]; + +/** One product as the CLI describes it (flags or one entry of --from-json). */ +export interface MerchProductSpec { + name: string; + description?: string | null; + /** COP, integer, VAT included. Same for every size. */ + price: number; + /** Strikethrough price (must be greater than `price`). */ + compareAtPrice?: number | null; + /** Size values in order. Empty/absent: a single variant without options. */ + sizes?: string[]; + /** Name of the size option (default `Talla`). */ + optionName?: string; + /** Units per variant: one number for all, or per size (`{ "M": 4 }`). */ + stock?: number | Record; + /** SKU prefix; each size appends `-`. Default: derived from the name. */ + sku?: string; + maxPerOrder?: number; + slug?: string; + /** Local image paths, in order (the first is the cover). */ + images?: string[]; + /** Publish right after creating (default false: stays DRAFT). */ + publish?: boolean; +} + +/** Same derivation as the dashboard (`skuBaseFrom`): "Camiseta Tour" → "CAMISETA-TOUR". */ +export function skuPart(value: string): string { + return value + .toLowerCase() + .normalize("NFD") + .replace(/[̀-ͯ]/g, "") + .replace(/[^a-z0-9\s-]/g, "") + .replace(/\s+/g, "-") + .replace(/-+/g, "-") + .replace(/^-|-$/g, "") + .toUpperCase(); +} + +export function skuBaseFrom(name: string): string { + return skuPart(name).slice(0, 40).replace(/-+$/, "") || "SKU"; +} + +function stockFor(spec: MerchProductSpec, size?: string): number { + const { stock } = spec; + if (stock === undefined) return 0; + if (typeof stock === "number") return stock; + if (size === undefined) { + throw new Error( + `"${spec.name}": stock per size needs "sizes"; use a number instead.`, + ); + } + return stock[size] ?? 0; +} + +/** + * Body of `POST /merch/products`: one option with the sizes and the full + * variant matrix (one variant per size), or a single variant without options. + * Throws on input the backend would reject anyway, with a clearer message. + */ +export function buildProductBody(spec: MerchProductSpec): MerchProductCreate { + if (!spec.name?.trim()) throw new Error("A product needs a name."); + if (!Number.isInteger(spec.price) || spec.price < 0) { + throw new Error(`"${spec.name}": price must be an integer in COP.`); + } + const sizes = (spec.sizes ?? []).map((s) => s.trim()).filter(Boolean); + const upper = sizes.map((s) => s.toLocaleUpperCase("es")); + if (new Set(upper).size !== upper.length) { + throw new Error(`"${spec.name}": repeated size.`); + } + if (spec.stock && typeof spec.stock === "object") { + const unknown = Object.keys(spec.stock).filter((k) => !sizes.includes(k)); + if (unknown.length > 0) { + throw new Error( + `"${spec.name}": stock for unknown size(s): ${unknown.join(", ")}.`, + ); + } + } + const base = spec.sku ? spec.sku.trim() : skuBaseFrom(spec.name); + const optionName = spec.optionName?.trim() || "Talla"; + const variant = (sku: string, stock: number, attributes = {}) => ({ + attributes, + sku, + price: spec.price, + compareAtPrice: spec.compareAtPrice ?? null, + stock, + }); + return { + name: spec.name.trim(), + ...(spec.description ? { description: spec.description } : {}), + ...(spec.slug ? { slug: spec.slug } : {}), + maxPerOrder: spec.maxPerOrder ?? 10, + options: sizes.length > 0 ? [{ name: optionName, values: sizes }] : [], + variants: + sizes.length > 0 + ? sizes.map((size) => + variant(`${base}-${skuPart(size) || size}`, stockFor(spec, size), { + [optionName]: size, + }), + ) + : [variant(base, stockFor(spec))], + }; +} + +const JPEG = [0xff, 0xd8, 0xff]; +const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]; + +/** MIME type from the file's magic bytes (not its extension), or null. */ +export function sniffImage( + head: Uint8Array, +): MerchImageUploadRequest["mimeType"] | null { + const starts = (sig: number[], at = 0) => + sig.every((b, i) => head[at + i] === b); + if (starts(JPEG)) return "image/jpeg"; + if (starts(PNG)) return "image/png"; + // RIFF....WEBP + if (starts([0x52, 0x49, 0x46, 0x46]) && starts([0x57, 0x45, 0x42, 0x50], 8)) + return "image/webp"; + return null; +} + +function readHead(path: string): Uint8Array { + const fd = openSync(path, "r"); + try { + const buf = new Uint8Array(12); + const n = readSync(fd, buf, 0, 12, 0); + return buf.subarray(0, n); + } finally { + closeSync(fd); + } +} + +/** + * Checks a local image before anything is created: a regular readable file, + * 1 byte to 6 MB, and JPEG/PNG/WebP by its magic bytes. Returns its MIME type. + */ +export function checkImage(path: string): MerchImageUploadRequest["mimeType"] { + let size: number; + let head: Uint8Array; + try { + const st = statSync(path); + if (!st.isFile()) throw new Error("not a file"); + size = st.size; + head = readHead(path); + } catch { + throw new Error(`${path}: cannot read the file.`); + } + if (size === 0) throw new Error(`${path}: the file is empty.`); + if (size > MAX_IMAGE_BYTES) { + throw new Error(`${path}: the photo cannot exceed 6 MB.`); + } + const mime = sniffImage(head); + if (!mime) { + throw new Error(`${path}: the photo must be a JPG, PNG or WebP file.`); + } + return mime; +} + +const isInt = (v: unknown, min = 0) => + typeof v === "number" && Number.isInteger(v) && v >= min; +const optString = (v: unknown) => v === undefined || typeof v === "string"; + +/** + * Runtime shape check of one spec (a --from-json row is untyped input): a + * clear message per field instead of a TypeError half-way through the batch. + */ +export function validateSpec(raw: unknown, label: string): MerchProductSpec { + if (!raw || typeof raw !== "object" || Array.isArray(raw)) { + throw new Error(`${label}: must be an object.`); + } + const p = raw as Record; + const bad = (field: string, want: string) => + new Error(`${label}: "${field}" must be ${want}.`); + if (typeof p.name !== "string" || !p.name.trim()) + throw bad("name", "a non-empty string"); + if (!isInt(p.price)) throw bad("price", "a non-negative integer (COP)"); + if (p.compareAtPrice != null && !isInt(p.compareAtPrice)) + throw bad("compareAtPrice", "a non-negative integer or null"); + if (p.description != null && typeof p.description !== "string") + throw bad("description", "a string"); + for (const f of ["optionName", "sku", "slug"] as const) + if (!optString(p[f])) throw bad(f, "a string"); + if (p.maxPerOrder !== undefined && !isInt(p.maxPerOrder, 1)) + throw bad("maxPerOrder", "an integer of at least 1"); + if ( + p.sizes !== undefined && + (!Array.isArray(p.sizes) || !p.sizes.every((s) => typeof s === "string")) + ) + throw bad("sizes", "an array of strings"); + if ( + p.stock !== undefined && + !isInt(p.stock) && + !( + p.stock && + typeof p.stock === "object" && + !Array.isArray(p.stock) && + Object.values(p.stock).every((n) => isInt(n)) + ) + ) + throw bad( + "stock", + "a non-negative integer or { size: non-negative integer }", + ); + if ( + p.images !== undefined && + (!Array.isArray(p.images) || !p.images.every((s) => typeof s === "string")) + ) + throw bad("images", "an array of paths"); + if (((p.images as string[] | undefined)?.length ?? 0) > MAX_IMAGES) + throw new Error(`${label}: at most ${MAX_IMAGES} photos.`); + if (p.publish !== undefined && typeof p.publish !== "boolean") + throw bad("publish", "true or false"); + return p as unknown as MerchProductSpec; +} + +/** + * A --from-json image path: relative, inside the file's folder (no absolute + * paths, no `..` out of it) and not a symlink, so a shared catalog file + * cannot make the CLI upload something else from the disk. + */ +export function resolveJsonImage( + dir: string, + img: string, + label: string, +): string { + if (isAbsolute(img)) { + throw new Error( + `${label}: image "${img}" must be relative to the JSON file.`, + ); + } + const full = resolve(dir, img); + const rel = relative(dir, full); + if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) { + throw new Error( + `${label}: image "${img}" is outside the JSON file's folder.`, + ); + } + let link = false; + try { + link = lstatSync(full).isSymbolicLink(); + } catch { + throw new Error(`${label}: image "${img}": cannot read the file.`); + } + if (link) throw new Error(`${label}: image "${img}" is a symlink.`); + return full; +} + +/** + * Parses a --from-json file: `{ "products": [ ... ] }` or a bare array of + * product specs. Every row is shape-checked and its image paths resolved + * against the file's folder (see resolveJsonImage). + */ +export function parseProductsFile( + raw: string, + file: string, +): MerchProductSpec[] { + let parsed: unknown; + try { + parsed = JSON.parse(raw); + } catch { + throw new Error(`Invalid JSON in ${file}.`); + } + const list = Array.isArray(parsed) + ? parsed + : (parsed as { products?: unknown })?.products; + if (!Array.isArray(list) || list.length === 0) { + throw new Error( + `${file}: expected { "products": [ ... ] } or an array with at least one product.`, + ); + } + const dir = dirname(resolve(file)); + return list.map((p, i) => { + const label = `${file}: product #${i + 1}`; + const spec = validateSpec(p, label); + return { + ...spec, + images: (spec.images ?? []).map((img) => + resolveJsonImage(dir, img, label), + ), + }; + }); +} + +/** + * Checks a whole batch before the first request: shape, body, photo count and + * every photo. One bad row aborts the run with nothing created. + */ +export function validateBatch(specs: MerchProductSpec[]): void { + for (const [i, s] of specs.entries()) { + validateSpec(s, `product #${i + 1}`); + buildProductBody(s); + for (const img of s.images ?? []) checkImage(img); + } +} + +type SdkResult = { data?: T; error?: unknown; response: Response }; + +/** The calls `createProduct` makes. Injected so tests run without network. */ +export interface MerchDeps { + create( + body: MerchProductCreate, + ): Promise>; + uploadUrl( + body: MerchImageUploadRequest, + ): Promise>; + setImages( + id: string, + imageUrls: string[], + ): Promise>; + setStatus( + id: string, + status: "DRAFT" | "PUBLISHED", + ): Promise>; + readFile(path: string): Uint8Array; + put(url: string, body: Uint8Array, contentType: string): Promise; + sleep(ms: number): Promise; +} + +export type MerchStep = + | "create" + | "upload-url" + | "upload" + | "set-images" + | "publish"; + +/** A product that did not finish: which step, and its id if it exists. */ +export class MerchStepError extends Error { + constructor( + readonly step: MerchStep, + message: string, + readonly productId?: string, + ) { + super(message); + } +} + +const errorCode = (res: SdkResult) => + (res.error as { error?: { code?: string } } | undefined)?.error?.code; + +function ok( + res: SdkResult, + step: MerchStep, + what: string, + productId?: string, +): T { + if (res.data !== undefined) return res.data; + throw new MerchStepError(step, `${what}: ${describeError(res)}`, productId); +} + +/** Tope de la espera de un 429 (el backend pide 300 s). */ +const MAX_RETRY_AFTER_MS = 10 * 60_000; + +/** Seconds of a `Retry-After` header (delta-seconds or HTTP date). */ +export function retryAfterMs(res: Response | undefined): number { + const raw = res?.headers.get("Retry-After"); + if (!raw) return 60_000; + const secs = Number(raw); + const ms = Number.isFinite(secs) + ? secs * 1000 + : Math.max(0, Date.parse(raw) - Date.now()); + return Math.min(Number.isNaN(ms) ? 60_000 : ms, MAX_RETRY_AFTER_MS); +} + +/** + * Uploads local photos in order: signed URL (one retry after `Retry-After` + * on a 429) → PUT of the bytes. `sizeBytes` is the length of the bytes + * actually sent. Returns the public URLs. + */ +export async function uploadImages( + paths: string[], + deps: MerchDeps, + at: string, + productId?: string, +): Promise { + const urls: string[] = []; + for (const path of paths) { + const mimeType = checkImage(path); + const bytes = deps.readFile(path); + const body = { mimeType, sizeBytes: bytes.byteLength }; + let res = await deps.uploadUrl(body); + if (res.data === undefined && res.response?.status === 429) { + const wait = retryAfterMs(res.response); + console.error( + `Rate limited asking for an upload URL; retrying in ${Math.ceil(wait / 1000)} s…`, + ); + await deps.sleep(wait); + res = await deps.uploadUrl(body); + } + const signed = ok( + res, + "upload-url", + `${at} upload-url for ${path}`, + productId, + ).data; + const put = await deps.put(signed.uploadUrl, bytes, mimeType); + if (!put.ok) { + throw new MerchStepError( + "upload", + `${at} uploading ${path}: storage answered ${put.status}`, + productId, + ); + } + urls.push(signed.publicUrl); + } + return urls; +} + +const RECOVER_HINT = + "Probably created by an earlier run: find it with `ft merch products list`, then `ft merch products images --image …` and `ft merch products publish `; or use another --sku / slug for a new product."; + +/** + * Creates one product: POST (always DRAFT) → upload each photo → set the + * ordered list → optionally publish. Inputs are expected to have passed + * `validateBatch`. A failure throws MerchStepError with the step and, once the + * product exists, its id: re-running `create` would then hit 409 SKU_TAKEN, + * so the fix is `ft merch products images ` / `publish `, not a retry. + */ +export async function createProduct( + spec: MerchProductSpec, + deps: MerchDeps, +): Promise { + const body = buildProductBody(spec); + const images = spec.images ?? []; + + const res = await deps.create(body); + if (res.data === undefined) { + const code = errorCode(res); + const hint = + code === "SKU_TAKEN" || code === "SLUG_TAKEN" ? ` ${RECOVER_HINT}` : ""; + throw new MerchStepError( + "create", + `"${spec.name}" create: ${describeError(res)}.${hint}`, + ); + } + const product = res.data.data; + const at = `"${spec.name}" (created as ${product.id}, DRAFT)`; + + if (images.length > 0) { + const urls = await uploadImages(images, deps, at, product.id); + ok( + await deps.setImages(product.id, urls), + "set-images", + `${at} set images`, + product.id, + ); + product.imageUrls = urls; + } + + if (spec.publish) { + ok( + await deps.setStatus(product.id, "PUBLISHED"), + "publish", + `${at} publish`, + product.id, + ); + product.status = "PUBLISHED"; + } + return product; +} + +export type MerchFailure = { + name: string; + productId?: string; + step: MerchStep | "validate"; + error: string; +}; + +/** Runs a batch one product after another; a failure does not stop the rest. */ +export async function createBatch( + specs: MerchProductSpec[], + deps: MerchDeps, +): Promise<{ created: MerchAdminProduct[]; failed: MerchFailure[] }> { + const created: MerchAdminProduct[] = []; + const failed: MerchFailure[] = []; + for (const spec of specs) { + try { + created.push(await createProduct(spec, deps)); + } catch (err) { + const e = err as Error; + failed.push({ + name: spec.name, + ...(err instanceof MerchStepError && err.productId + ? { productId: err.productId } + : {}), + step: err instanceof MerchStepError ? err.step : "validate", + error: e.message, + }); + } + } + return { created, failed }; +} + +const sdkDeps: MerchDeps = { + create: (body) => postMerchProducts({ body }) as never, + uploadUrl: (body) => postMerchProductsImagesUploadUrl({ body }) as never, + setImages: (id, imageUrls) => + putMerchProductsIdImages({ path: { id }, body: { imageUrls } }) as never, + setStatus: (id, status) => + patchMerchProductsIdStatus({ path: { id }, body: { status } }) as never, + readFile: (path) => readFileSync(path), + // Signed storage URL: no Authorization header, the token is in the URL. + put: (url, body, contentType) => + fetch(url, { + method: "PUT", + headers: { "Content-Type": contentType }, + body: body as unknown as Blob, + }), + sleep: (ms) => new Promise((r) => setTimeout(r, ms)), +}; + +/** Table row of `products list`: stock summed, price range. */ +export function summarize(p: MerchAdminProduct) { + const prices = p.variants.map((v) => v.price); + const min = Math.min(...prices); + const max = Math.max(...prices); + return { + id: p.id, + name: p.name, + status: p.status, + variants: p.variants.map((v) => v.label).join(" "), + stock: p.variants.reduce((n, v) => n + v.stock, 0), + price: prices.length === 0 ? null : min === max ? min : `${min}-${max}`, + }; +} + +const collect = (value: string, prev: string[] = []) => [...prev, value]; + +function intFlag(name: string) { + return (value: string) => { + const n = Number(value); + if (!Number.isInteger(n) || n < 0) { + fail(`${name} must be a non-negative integer (got "${value}").`); + } + return n; + }; +} + +export function registerMerch(program: Command, deps: MerchDeps = sdkDeps) { + const merch = program + .command("merch") + .description("Merch store (Legend plan): products, photos, publishing"); + const products = merch + .command("products") + .description("Merch store products of the workspace's organization"); + + products + .command("list") + .description("List every product (DRAFT and PUBLISHED) with its variants") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (opts) => { + configureClient(opts.workspace); + const body = unwrap(await getMerchProducts()); + const rows = body.data ?? []; + print(opts.json ? rows : rows.map(summarize), { + json: opts.json, + columns: LIST_COLUMNS, + }); + }); + + products + .command("create") + .description( + "Create product(s) as DRAFT: sizes become variants, local photos are uploaded", + ) + .option("--name ", "product name") + .option("--description ", "description") + .option( + "--price ", + "price in COP (integer, VAT included)", + intFlag("--price"), + ) + .option( + "--compare-at ", + "strikethrough price in COP (greater than --price)", + intFlag("--compare-at"), + ) + .option("--sizes ", "comma-separated sizes, e.g. XS,S,M,L,XL,2XL") + .option("--option-name ", "name of the size option", "Talla") + .option("--stock ", "units per variant", intFlag("--stock")) + .option( + "--sku ", + "SKU prefix (default: from the name); sizes append -", + ) + .option( + "--max-per-order ", + "max units per order (default 10)", + intFlag("--max-per-order"), + ) + .option("--slug ", "URL slug (default: from the name)") + .option( + "--image ", + "local photo, repeatable (first = cover)", + collect, + ) + .option("--publish", "publish right after creating") + .option("--from-json ", "create several products from a JSON file") + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (opts) => { + let specs: MerchProductSpec[]; + try { + if (opts.fromJson) { + if (opts.name) fail("Use either --from-json or --name, not both."); + let raw: string; + try { + raw = readFileSync(opts.fromJson, "utf8"); + } catch { + fail(`Cannot read file: ${opts.fromJson}`); + } + specs = parseProductsFile(raw, opts.fromJson); + } else { + if (!opts.name || opts.price === undefined) { + fail( + "Missing --name or --price (or pass --from-json ).", + 'Example: ft merch products create --name "Camiseta Tour" --price 80000 --sizes S,M,L --stock 10 --image front.jpg', + ); + } + specs = [ + { + name: opts.name, + description: opts.description, + price: opts.price, + compareAtPrice: opts.compareAt, + sizes: opts.sizes ? String(opts.sizes).split(",") : undefined, + optionName: opts.optionName, + stock: opts.stock, + sku: opts.sku, + maxPerOrder: opts.maxPerOrder, + slug: opts.slug, + images: opts.image ?? [], + publish: Boolean(opts.publish), + }, + ]; + } + // The whole batch is checked before the first request: a bad row + // never leaves the run half-applied. + validateBatch(specs); + } catch (err) { + fail((err as Error).message); + } + + configureClient(opts.workspace); + const { created, failed } = await createBatch(specs, deps); + // stdout always carries what DID get created (also with --json), so a + // partial run is recoverable; failures go to stderr and exit 1. + if (opts.json) print({ created, failed }, { json: true }); + else if (created.length > 0) + print(created.map(summarize), { columns: LIST_COLUMNS }); + if (failed.length > 0) { + fail( + `${failed.length} of ${specs.length} product(s) failed:\n${failed.map((f) => ` · [${f.step}] ${f.error}`).join("\n")}`, + ); + } + }); + + products + .command("images ") + .description( + "Replace a product's photos with local files (in order; first = cover)", + ) + .requiredOption( + "--image ", + "local photo, repeatable (first = cover)", + collect, + ) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (id, opts) => { + const paths: string[] = opts.image; + try { + if (paths.length > MAX_IMAGES) { + throw new Error(`At most ${MAX_IMAGES} photos.`); + } + for (const img of paths) checkImage(img); + } catch (err) { + fail((err as Error).message); + } + configureClient(opts.workspace); + let urls: string[]; + try { + urls = await uploadImages(paths, deps, `Product ${id}`, id); + } catch (err) { + fail((err as Error).message); + } + const body = unwrap(await deps.setImages(id, urls)); + print(body.data ?? body, { json: opts.json }); + }); + + for (const [name, status, describe] of [ + ["publish", "PUBLISHED", "Publish a product (shows it in the store)"], + ["unpublish", "DRAFT", "Unpublish a product (back to DRAFT)"], + ] as const) { + products + .command(`${name} `) + .description(describe) + .option("--workspace ", "workspace override") + .option("--json", "raw JSON output") + .action(async (id, opts) => { + configureClient(opts.workspace); + const body = unwrap(await deps.setStatus(id, status)); + print(body.data ?? body, { json: opts.json }); + }); + } +} diff --git a/src/program.ts b/src/program.ts index 93cd02d..2d7ba19 100644 --- a/src/program.ts +++ b/src/program.ts @@ -66,6 +66,7 @@ import { registerAdmin } from "./commands/admin"; import { registerApiKeys } from "./commands/api-keys"; import { registerAuth } from "./commands/auth"; import { registerEventDates } from "./commands/event-dates"; +import { registerMerch } from "./commands/merch"; import { registerReports } from "./commands/reports"; import { registerResource } from "./commands/resource"; import { registerTickets } from "./commands/tickets"; @@ -428,6 +429,10 @@ registerResource(program, { ], }); +// Merch store catalog (contract 1.38): products are born DRAFT; local photos +// go through the signed upload URL, never as a URL the backend downloads. +registerMerch(program); + registerTickets(program); registerReports(program); registerApiKeys(program);