From 3210cb675f99a62ec2e8f29a40035dd0f8e92a78 Mon Sep 17 00:00:00 2001 From: Lucas-FullStackX Date: Sun, 1 Nov 2026 15:11:42 -0500 Subject: [PATCH 1/2] fix(list): validar --limit 1-100 en vez de mandarlo tal cual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --limit 500 o --limit abc llegaban a la API y volvían en silencio con la página por defecto de 20. parseLimit() falla con exit 1 y un mensaje claro; aplicado en resource list, admin list y api-keys list. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Fo7cm6n2VPy94zeSbmhgt8 --- .changeset/validate-limit.md | 5 +++++ src/commands/admin.ts | 4 ++-- src/commands/api-keys.ts | 4 ++-- src/commands/resource.ts | 5 +++-- src/lib/input.test.ts | 22 +++++++++++++++++++++- src/lib/input.ts | 15 +++++++++++++++ 6 files changed, 48 insertions(+), 7 deletions(-) create mode 100644 .changeset/validate-limit.md diff --git a/.changeset/validate-limit.md b/.changeset/validate-limit.md new file mode 100644 index 0000000..0693cd1 --- /dev/null +++ b/.changeset/validate-limit.md @@ -0,0 +1,5 @@ +--- +"@freeticket/cli": patch +--- + +`--limit` en los comandos `list` ahora se valida (entero de 1 a 100) y falla con un mensaje claro, en vez de mandarse tal cual y volver en silencio con la página por defecto de 20. diff --git a/src/commands/admin.ts b/src/commands/admin.ts index e6012fd..fd99a4e 100644 --- a/src/commands/admin.ts +++ b/src/commands/admin.ts @@ -30,7 +30,7 @@ import { } from "../admin-client/sdk.gen"; import { configureAdminClient, unwrap } from "../lib/api"; import { CONFIG_PATH, loadConfig, saveConfig } from "../lib/config"; -import { confirmOrExit, parseData } from "../lib/input"; +import { confirmOrExit, parseData, parseLimit } from "../lib/input"; import { print, printNextCursor, resolveColumns, toCsv } from "../lib/output"; type SdkFn = ( @@ -327,7 +327,7 @@ function registerAdminResource(parent: Command, spec: AdminResource): void { configureAdminClient(); const query: Record = {}; if (!spec.noPaging) { - query.limit = Number(opts.limit); + query.limit = parseLimit(opts.limit); query.cursor = opts.cursor; } for (const f of spec.listFlags ?? []) { diff --git a/src/commands/api-keys.ts b/src/commands/api-keys.ts index f14ec0d..0bca3c8 100644 --- a/src/commands/api-keys.ts +++ b/src/commands/api-keys.ts @@ -3,7 +3,7 @@ import type { Command } from "commander"; import { deleteApiKeysId, getApiKeys, postApiKeys } from "../client/sdk.gen"; import type { ApiKeyScope } from "../client/types.gen"; import { configureClient, fail, unwrap } from "../lib/api"; -import { confirmOrExit } from "../lib/input"; +import { confirmOrExit, parseLimit } from "../lib/input"; import { print, printEmptyScope, @@ -98,7 +98,7 @@ export function registerApiKeys(program: Command): void { configureClient(opts.workspace); const columns = resolveColumns(opts, COLUMNS); const query: Record = { - limit: opts.limit, + limit: parseLimit(opts.limit), cursor: opts.cursor, }; diff --git a/src/commands/resource.ts b/src/commands/resource.ts index 84808c9..69a1555 100644 --- a/src/commands/resource.ts +++ b/src/commands/resource.ts @@ -11,7 +11,7 @@ import { tagRow, unwrap, } from "../lib/api"; -import { confirmOrExit, parseData } from "../lib/input"; +import { confirmOrExit, parseData, parseLimit } from "../lib/input"; import { print, printEmptyScope, @@ -91,8 +91,9 @@ export function registerResource(program: Command, spec: ResourceSpec): void { for (const f of spec.listFlags ?? []) cmd.option(f.flag, f.describe); cmd.action(async (opts) => { let columns = resolveColumns(opts, spec.columns); + opts.limit = parseLimit(opts.limit); const query: Record = { - limit: Number(opts.limit), + limit: opts.limit, cursor: opts.cursor, }; for (const f of spec.listFlags ?? []) { diff --git a/src/lib/input.test.ts b/src/lib/input.test.ts index 469a40c..94bcdf1 100644 --- a/src/lib/input.test.ts +++ b/src/lib/input.test.ts @@ -1,5 +1,5 @@ import { afterEach, describe, expect, it, vi } from "vitest"; -import { confirmOrExit } from "./input"; +import { confirmOrExit, parseLimit } from "./input"; /** Issue #24: aborting a destructive command must not exit 0. */ describe("confirmOrExit", () => { @@ -42,3 +42,23 @@ describe("confirmOrExit", () => { expect(exit).not.toHaveBeenCalled(); }); }); + +/** `--limit 500` used to reach the API and silently come back as 20 rows. */ +describe("parseLimit", () => { + afterEach(() => vi.restoreAllMocks()); + + it("accepts integers 1-100", () => { + expect(parseLimit("1")).toBe(1); + expect(parseLimit("20")).toBe(20); + expect(parseLimit("100")).toBe(100); + }); + + it.each(["0", "101", "500", "abc", "2.5", ""])("exits 1 on %j", (bad) => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const exit = vi.spyOn(process, "exit").mockImplementation((() => { + throw new Error("exited"); + }) as never); + expect(() => parseLimit(bad)).toThrow("exited"); + expect(exit).toHaveBeenCalledWith(1); + }); +}); diff --git a/src/lib/input.ts b/src/lib/input.ts index 3077805..d24d607 100644 --- a/src/lib/input.ts +++ b/src/lib/input.ts @@ -2,6 +2,21 @@ import { readFileSync } from "node:fs"; import * as readline from "node:readline"; import { fail } from "./api"; +/** + * Validates `--limit`: an integer 1-100, as the contract allows. Without this + * `--limit 500` or `--limit abc` went to the API as-is and came back as the + * default page of 20, silently. + */ +export function parseLimit(input: string): number { + const n = Number(input); + if (!Number.isInteger(n) || n < 1 || n > 100) + fail( + `Invalid --limit: ${input}. Use an integer from 1 to 100.`, + "For more rows, add --all to walk every page.", + ); + return n; +} + /** * Parses a `--data` value into a JSON body. Accepts inline JSON (`'{"x":1}'`) * or `@path/to/file.json` to read from disk. Aborts on missing/invalid input. From aae6701e2678d80895042b5ee236b5910a0a16ee Mon Sep 17 00:00:00 2001 From: Lucas-FullStackX Date: Sun, 1 Nov 2026 15:16:14 -0500 Subject: [PATCH 2/2] feat(waitlist): ft waitlist list|create (contrato 1.24) Sincroniza openapi.json a 1.24.0 y cablea GET/POST /waitlist, el unico endpoint B2B del spec de prod que el CLI no exponia. `list` filtra con --city y hereda --workspace/--account/--all/--csv del patron resource. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Fo7cm92jLJxUttSHQHWMAk --- .changeset/waitlist.md | 5 + README.md | 1 + openapi.json | 9737 +++++++++++++++++++++------------------- src/program.test.ts | 9 + src/program.ts | 19 + 5 files changed, 5188 insertions(+), 4583 deletions(-) create mode 100644 .changeset/waitlist.md diff --git a/.changeset/waitlist.md b/.changeset/waitlist.md new file mode 100644 index 0000000..cc4bea4 --- /dev/null +++ b/.changeset/waitlist.md @@ -0,0 +1,5 @@ +--- +"@freeticket/cli": minor +--- + +Nuevo `ft waitlist list|create`: lista de espera por ciudad de las landings enterprise (contrato 1.24). `list` filtra con `--city`. diff --git a/README.md b/README.md index 3c9db65..ca836f5 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,7 @@ ft sales list --status CONFIRMED --json | `ft reports reconciliation` · `financials` | CFO reconciliation (Mercado Pago vs sale vs Siigo invoice) · per-function P&L | ADMIN | | `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 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 2fdb8dd..6c277ee 100644 --- a/openapi.json +++ b/openapi.json @@ -2,8 +2,8 @@ "openapi": "3.1.0", "info": { "title": "FreeTicket B2B API", - "version": "1.20.0", - "description": "FreeTicket B2B REST API for integrations and the CLI. 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)." + "version": "1.24.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": [ { @@ -224,124 +224,84 @@ } } }, - "/auth/device/code": { - "post": { - "operationId": "postAuthDeviceCode", + "/customer/orders": { + "get": { + "operationId": "getCustomerOrders", "tags": [ - "auth" + "customer", + "orders" ], - "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" - } - } - } + "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": [] }, - "429": { - "description": "Too many requests from the same IP (anti-flood).", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "eventDateId", + "in": "query", + "required": false, + "description": "Required. The event date being queried.", + "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" - } - } + { + "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" } } - } - } - }, - "/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.", + "description": "OK", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeviceTokenResponse" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerOrderCurrent" + } + }, + "required": [ + "data" + ] } } } }, - "400": { - "description": "RFC 8628 status: authorization_pending | slow_down | expired_token | access_denied | invalid_request.", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/DeviceTokenError" + "$ref": "#/components/schemas/Error" } } } - } - } - } - }, - "/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.", + }, + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SignupResponse" + "$ref": "#/components/schemas/Error" } } } }, - "422": { - "description": "Invalid body (email, name or workspaceName).", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -350,8 +310,8 @@ } } }, - "429": { - "description": "Too many attempts from the same IP or the same email.", + "422": { + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -361,16 +321,15 @@ } } } - } - }, - "/workspaces": { + }, "post": { - "operationId": "postWorkspaces", + "operationId": "postCustomerOrders", "tags": [ - "me" + "customer", + "orders" ], - "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": "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": [] @@ -388,6 +347,15 @@ "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": { @@ -395,7 +363,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WorkspaceCreate" + "$ref": "#/components/schemas/CustomerOrderCreateRequest" } } } @@ -409,7 +377,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/WorkspaceAccess" + "$ref": "#/components/schemas/CustomerOrderCreateResult" } }, "required": [ @@ -460,7 +428,38 @@ } }, "422": { - "description": "Operation error.", + "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": { @@ -472,14 +471,15 @@ } } }, - "/me": { + "/customer/purchase-sessions/{id}": { "get": { - "operationId": "getMe", + "operationId": "getCustomerPurchaseSessionsId", "tags": [ - "me" + "customer", + "purchase-sessions" ], - "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": "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": [] @@ -489,6 +489,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -508,7 +516,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Me" + "$ref": "#/components/schemas/PurchaseSessionStatus" } }, "required": [ @@ -823,62 +831,28 @@ } } }, - "/events/{id}": { - "get": { - "operationId": "getEventsId", + "/auth/device/code": { + "post": { + "operationId": "postAuthDeviceCode", "tags": [ - "events" - ], - "summary": "Get an event", - "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" - } - } + "auth" ], + "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": "OK", + "description": "Flow started: device_code (polled by the CLI) + user_code (approved by the user in the browser).", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/Event" - } - }, - "required": [ - "data" - ] + "$ref": "#/components/schemas/DeviceCodeResponse" } } } }, - "401": { - "description": "Missing or invalid credential.", + "429": { + "description": "Too many requests from the same IP (anti-flood).", "content": { "application/json": { "schema": { @@ -887,8 +861,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "503": { + "description": "Could not generate a unique device_code/user_code after retrying (persistent collision).", "content": { "application/json": { "schema": { @@ -896,19 +870,95 @@ } } } + } + } + } + }, + "/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" + } + } + } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "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" + } + } + } + } + } + } + }, + "/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/SignupResponse" } } } }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Invalid body (email, name or workspaceName).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "429": { + "description": "Too many attempts from the same IP or the same email.", "content": { "application/json": { "schema": { @@ -918,14 +968,16 @@ } } } - }, - "patch": { - "operationId": "patchEventsId", + } + }, + "/workspaces": { + "post": { + "operationId": "postWorkspaces", "tags": [ - "events" + "me" ], - "summary": "Update 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": [] @@ -935,14 +987,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -958,13 +1002,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/EventUpdate" + "$ref": "#/components/schemas/WorkspaceCreate" } } } }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -972,7 +1016,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Event" + "$ref": "#/components/schemas/WorkspaceAccess" } }, "required": [ @@ -1012,8 +1056,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": { @@ -1023,14 +1077,16 @@ } } } - }, - "delete": { - "operationId": "deleteEventsId", + } + }, + "/me": { + "get": { + "operationId": "getMe", "tags": [ - "events" + "me" ], - "summary": "Delete an event (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -1040,14 +1096,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -1064,7 +1112,15 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Me" + } + }, + "required": [ + "data" + ] } } } @@ -1112,14 +1168,14 @@ } } }, - "/events/{id}/publish": { - "post": { - "operationId": "postEventsIdPublish", + "/events/{id}": { + "get": { + "operationId": "getEventsId", "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": "Get an event", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -1196,16 +1252,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": { @@ -1215,28 +1261,16 @@ } } } - }, - "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", + }, + "patch": { + "operationId": "patchEventsId", "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": "Update an event", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -1264,6 +1298,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EventUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -1324,16 +1368,14 @@ } } } - } - }, - "/events/{id}/dates/{dateId}": { - "patch": { - "operationId": "patchEventsIdDatesDateId", + }, + "delete": { + "operationId": "deleteEventsId", "tags": [ "events" ], - "summary": "Update an event date", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -1351,14 +1393,6 @@ "type": "string" } }, - { - "name": "dateId", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -1369,31 +1403,13 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/EventDateUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/EventDate" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -1428,6 +1444,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": { @@ -1439,14 +1465,16 @@ } } } - }, - "delete": { - "operationId": "deleteEventsIdDatesDateId", + } + }, + "/events/{id}/publish": { + "post": { + "operationId": "postEventsIdPublish", "tags": [ "events" ], - "summary": "Delete an event date", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -1464,14 +1492,6 @@ "type": "string" } }, - { - "name": "dateId", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -1488,7 +1508,15 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Event" + } + }, + "required": [ + "data" + ] } } } @@ -1542,18 +1570,28 @@ } } } + }, + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/ticket-types": { - "get": { - "operationId": "getTicketTypes", + "/events/{id}/cancel": { + "post": { + "operationId": "postEventsIdCancel", "tags": [ - "ticket-types" + "events" ], - "summary": "List workspace ticket types", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -1564,28 +1602,9 @@ ], "parameters": [ { - "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, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -1609,18 +1628,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/TicketType" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/Event" } }, "required": [ - "data", - "page" + "data" ] } } @@ -1667,13 +1679,15 @@ } } } - }, - "post": { - "operationId": "postTicketTypes", + } + }, + "/events/{id}/dates/{dateId}": { + "patch": { + "operationId": "patchEventsIdDatesDateId", "tags": [ - "ticket-types" + "events" ], - "summary": "Create a ticket type", + "summary": "Update an event date", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -1684,6 +1698,22 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "dateId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -1699,13 +1729,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/TicketTypeCreate" + "$ref": "#/components/schemas/EventDateUpdate" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -1713,7 +1743,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketType" + "$ref": "#/components/schemas/EventDate" } }, "required": [ @@ -1764,16 +1794,14 @@ } } } - } - }, - "/ticket-types/{id}": { - "get": { - "operationId": "getTicketTypesId", + }, + "delete": { + "operationId": "deleteEventsIdDatesDateId", "tags": [ - "ticket-types" + "events" ], - "summary": "Get a ticket type", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Delete an event date", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -1791,6 +1819,14 @@ "type": "string" } }, + { + "name": "dateId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -1807,15 +1843,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/TicketType" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -1850,6 +1878,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": { @@ -1861,14 +1899,16 @@ } } } - }, - "patch": { - "operationId": "patchTicketTypesId", + } + }, + "/ticket-types": { + "get": { + "operationId": "getTicketTypes", "tags": [ "ticket-types" ], - "summary": "Update a ticket type", - "description": "Minimum role: `ADMIN`. 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": [] @@ -1879,9 +1919,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" } @@ -1896,16 +1955,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/TicketTypeUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -1915,11 +1964,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketType" + "type": "array", + "items": { + "$ref": "#/components/schemas/TicketType" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -1955,16 +2011,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": { @@ -1977,12 +2023,12 @@ } } }, - "delete": { - "operationId": "deleteTicketTypesId", + "post": { + "operationId": "postTicketTypes", "tags": [ "ticket-types" ], - "summary": "Delete a ticket type (soft delete)", + "summary": "Create a ticket type", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -1993,14 +2039,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -2011,13 +2049,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketTypeCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TicketType" + } + }, + "required": [ + "data" + ] } } } @@ -2052,16 +2108,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": { @@ -2075,13 +2121,13 @@ } } }, - "/sales": { + "/ticket-types/{id}": { "get": { - "operationId": "getSales", + "operationId": "getTicketTypesId", "tags": [ - "sales" + "ticket-types" ], - "summary": "List workspace sales", + "summary": "Get a ticket type", "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -2093,104 +2139,9 @@ ], "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", - "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, + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -2214,39 +2165,16 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Sale" - } - }, - "page": { - "$ref": "#/components/schemas/Page" - }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" - } + "$ref": "#/components/schemas/TicketType" } }, "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": { @@ -2289,13 +2217,13 @@ } } }, - "post": { - "operationId": "postSales", + "patch": { + "operationId": "patchTicketTypesId", "tags": [ - "sales" + "ticket-types" ], - "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": "Update a ticket type", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -2306,19 +2234,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" } @@ -2329,13 +2256,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SaleCreate" + "$ref": "#/components/schemas/TicketTypeUpdate" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -2343,7 +2270,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SaleDetail" + "$ref": "#/components/schemas/TicketType" } }, "required": [ @@ -2402,28 +2329,16 @@ } } } - }, - "502": { - "description": "The external provider failed to complete the operation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } - } - }, - "/sales/{id}": { - "get": { - "operationId": "getSalesId", + }, + "delete": { + "operationId": "deleteTicketTypesId", "tags": [ - "sales" + "ticket-types" ], - "summary": "Get a sale with its items", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Delete a ticket type (soft delete)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -2457,15 +2372,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/SaleDetail" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -2500,6 +2407,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": { @@ -2513,15 +2430,15 @@ } } }, - "/sales/{id}/cancel": { - "post": { - "operationId": "postSalesIdCancel", + "/sales": { + "get": { + "operationId": "getSales", "tags": [ "sales" ], - "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": [ + "summary": "List workspace sales", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "security": [ { "apiKey": [] }, @@ -2531,9 +2448,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" } @@ -2548,16 +2560,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/SaleCancelRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -2567,18 +2569,31 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Sale" + "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": { @@ -2587,8 +2602,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -2597,8 +2612,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -2607,8 +2622,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -2628,16 +2643,14 @@ } } } - } - }, - "/sales/{id}/refund": { + }, "post": { - "operationId": "postSalesIdRefund", + "operationId": "postSales", "tags": [ "sales" ], - "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": "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.", "security": [ { "apiKey": [] @@ -2648,18 +2661,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" } @@ -2670,13 +2684,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/SaleRefundRequest" + "$ref": "#/components/schemas/SaleCreate" } } } }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -2684,7 +2698,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SaleRefundResult" + "$ref": "#/components/schemas/SaleDetail" } }, "required": [ @@ -2735,7 +2749,7 @@ } }, "422": { - "description": "Operation error.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -2753,28 +2767,18 @@ } } } - }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } } }, - "/membership-plans": { + "/sales/{id}": { "get": { - "operationId": "getMembershipPlans", + "operationId": "getSalesId", "tags": [ - "membership-plans" + "sales" ], - "summary": "List the workspace's membership plans", - "description": "Minimum role: `VIEWER`. 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": [] @@ -2785,19 +2789,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" } @@ -2821,18 +2815,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/MembershipPlan" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/SaleDetail" } }, "required": [ - "data", - "page" + "data" ] } } @@ -2879,14 +2866,16 @@ } } } - }, + } + }, + "/sales/{id}/cancel": { "post": { - "operationId": "postMembershipPlans", + "operationId": "postSalesIdCancel", "tags": [ - "membership-plans" + "sales" ], - "summary": "Create a membership plan", - "description": "Minimum role: `ADMIN`. 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": [] @@ -2896,6 +2885,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -2911,13 +2908,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MembershipPlanCreate" + "$ref": "#/components/schemas/SaleCancelRequest" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -2925,7 +2922,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/MembershipPlan" + "$ref": "#/components/schemas/Sale" } }, "required": [ @@ -2965,95 +2962,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - } - }, - "/membership-plans/{id}": { - "get": { - "operationId": "getMembershipPlansId", - "tags": [ - "membership-plans" - ], - "summary": "Get a membership plan", - "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/MembershipPlan" - } - }, - "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.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -3073,14 +2983,16 @@ } } } - }, - "patch": { - "operationId": "patchMembershipPlansId", + } + }, + "/sales/{id}/refund": { + "post": { + "operationId": "postSalesIdRefund", "tags": [ - "membership-plans" + "sales" ], - "summary": "Update a membership plan", - "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": [] @@ -3113,7 +3025,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MembershipPlanUpdate" + "$ref": "#/components/schemas/SaleRefundRequest" } } } @@ -3127,7 +3039,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/MembershipPlan" + "$ref": "#/components/schemas/SaleRefundResult" } }, "required": [ @@ -3167,75 +3079,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - } - } - }, - "delete": { - "operationId": "deleteMembershipPlansId", - "tags": [ - "membership-plans" - ], - "summary": "Delete a membership plan (soft delete)", - "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" - } - } - } - }, - "401": { - "description": "Missing or invalid credential.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "403": { - "description": "Insufficient role or resource not accessible.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -3244,8 +3089,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "422": { + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -3254,8 +3099,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "502": { + "description": "The external provider failed to complete the operation.", "content": { "application/json": { "schema": { @@ -3264,8 +3109,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "503": { + "description": "Service unavailable: an external dependency is down or initialization failed.", "content": { "application/json": { "schema": { @@ -3277,13 +3122,13 @@ } } }, - "/venues": { + "/membership-plans": { "get": { - "operationId": "getVenues", + "operationId": "getMembershipPlans", "tags": [ - "venues" + "membership-plans" ], - "summary": "List workspace venues", + "summary": "List the workspace's membership plans", "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3333,7 +3178,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Venue" + "$ref": "#/components/schemas/MembershipPlan" } }, "page": { @@ -3391,11 +3236,11 @@ } }, "post": { - "operationId": "postVenues", + "operationId": "postMembershipPlans", "tags": [ - "venues" + "membership-plans" ], - "summary": "Create a venue", + "summary": "Create a membership plan", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3421,7 +3266,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/VenueCreate" + "$ref": "#/components/schemas/MembershipPlanCreate" } } } @@ -3435,7 +3280,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Venue" + "$ref": "#/components/schemas/MembershipPlan" } }, "required": [ @@ -3488,13 +3333,13 @@ } } }, - "/venues/{id}": { + "/membership-plans/{id}": { "get": { - "operationId": "getVenuesId", + "operationId": "getMembershipPlansId", "tags": [ - "venues" + "membership-plans" ], - "summary": "Get a venue", + "summary": "Get a membership plan", "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3532,7 +3377,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Venue" + "$ref": "#/components/schemas/MembershipPlan" } }, "required": [ @@ -3585,11 +3430,11 @@ } }, "patch": { - "operationId": "patchVenuesId", + "operationId": "patchMembershipPlansId", "tags": [ - "venues" + "membership-plans" ], - "summary": "Update a venue", + "summary": "Update a membership plan", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3623,7 +3468,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/VenueUpdate" + "$ref": "#/components/schemas/MembershipPlanUpdate" } } } @@ -3637,7 +3482,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Venue" + "$ref": "#/components/schemas/MembershipPlan" } }, "required": [ @@ -3690,11 +3535,11 @@ } }, "delete": { - "operationId": "deleteVenuesId", + "operationId": "deleteMembershipPlansId", "tags": [ - "venues" + "membership-plans" ], - "summary": "Delete a venue (soft delete)", + "summary": "Delete a membership plan (soft delete)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3764,6 +3609,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": { @@ -3777,14 +3632,14 @@ } } }, - "/staff": { + "/venues": { "get": { - "operationId": "getStaff", + "operationId": "getVenues", "tags": [ - "staff" + "venues" ], - "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 workspace venues", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -3813,17 +3668,8 @@ } }, { - "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", + "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": { @@ -3842,7 +3688,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/StaffUser" + "$ref": "#/components/schemas/Venue" } }, "page": { @@ -3900,11 +3746,11 @@ } }, "post": { - "operationId": "postStaff", + "operationId": "postVenues", "tags": [ - "staff" + "venues" ], - "summary": "Create a staff user in the workspace", + "summary": "Create a venue", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -3930,7 +3776,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/StaffCreate" + "$ref": "#/components/schemas/VenueCreate" } } } @@ -3944,7 +3790,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StaffUser" + "$ref": "#/components/schemas/Venue" } }, "required": [ @@ -3984,16 +3830,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": { @@ -4003,28 +3839,18 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } } }, - "/staff/{id}": { + "/venues/{id}": { "get": { - "operationId": "getStaffId", + "operationId": "getVenuesId", "tags": [ - "staff" + "venues" ], - "summary": "Get a staff member", - "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": [] @@ -4061,7 +3887,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/StaffUser" + "$ref": "#/components/schemas/Venue" } }, "required": [ @@ -4113,13 +3939,13 @@ } } }, - "delete": { - "operationId": "deleteStaffId", + "patch": { + "operationId": "patchVenuesId", "tags": [ - "staff" + "venues" ], - "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 venue", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4147,13 +3973,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" + ] } } } @@ -4188,16 +4032,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": { @@ -4209,15 +4043,13 @@ } } } - } - }, - "/staff/{id}/role": { - "patch": { - "operationId": "patchStaffIdRole", + }, + "delete": { + "operationId": "deleteVenuesId", "tags": [ - "staff" + "venues" ], - "summary": "Change a staff user's role", + "summary": "Delete a venue (soft delete)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4246,31 +4078,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" } } } @@ -4305,16 +4119,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": { @@ -4328,14 +4132,14 @@ } } }, - "/reports/summary": { + "/staff": { "get": { - "operationId": "getReportsSummary", + "operationId": "getStaff", "tags": [ - "reports" + "staff" ], - "summary": "Workspace KPIs (revenue, tickets, sales, memberships)", - "description": "Minimum role: `VIEWER`. 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": [] @@ -4346,19 +4150,30 @@ ], "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" + } + }, + { + "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" } }, { @@ -4380,11 +4195,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ReportSummary" + "type": "array", + "items": { + "$ref": "#/components/schemas/StaffUser" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -4431,16 +4253,14 @@ } } } - } - }, - "/reports/inventory": { - "get": { - "operationId": "getReportsInventory", + }, + "post": { + "operationId": "postStaff", "tags": [ - "reports" + "staff" ], - "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 staff user in the workspace", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -4451,106 +4271,56 @@ ], "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" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StaffCreate" + } } - }, - { - "name": "from", - "in": "query", - "required": false, - "description": "Event date start ≥ (ISO 8601)", - "schema": { - "type": "string" + } + }, + "responses": { + "201": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/StaffUser" + } + }, + "required": [ + "data" + ] + } + } } }, - { - "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" - } - } - ], - "responses": { - "200": { - "description": "OK", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/InventoryRow" - } - }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" - } - } - }, - "required": [ - "data" - ] + "$ref": "#/components/schemas/Error" } } } }, - "401": { - "description": "Missing or invalid credential.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -4559,8 +4329,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -4569,8 +4339,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": { @@ -4588,17 +4358,38 @@ } } } + }, + "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/reconciliation": { + "/staff/{id}": { "get": { - "operationId": "getReportsReconciliation", + "operationId": "getStaffId", "tags": [ - "reports" + "staff" ], - "summary": "CFO financial reconciliation (MP ↔ sale ↔ Siigo invoice)", + "summary": "Get a staff member", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4610,86 +4401,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", @@ -4709,10 +4427,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ReconciliationRow" - } + "$ref": "#/components/schemas/StaffUser" } }, "required": [ @@ -4763,16 +4478,14 @@ } } } - } - }, - "/reports/exports/reconciliation": { - "get": { - "operationId": "getReportsExportsReconciliation", + }, + "delete": { + "operationId": "deleteStaffId", "tags": [ - "reports" + "staff" ], - "summary": "CSV export of the CFO financial reconciliation", - "description": "Minimum role: `ADMIN`. 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": [] @@ -4783,62 +4496,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" } @@ -4894,8 +4554,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -4903,17 +4563,27 @@ } } } - } - } - } + }, + "422": { + "description": "Request body/parameter validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } }, - "/reports/exports/attendees": { - "get": { - "operationId": "getReportsExportsAttendees", + "/staff/{id}/role": { + "patch": { + "operationId": "patchStaffIdRole", "tags": [ - "reports" + "staff" ], - "summary": "Export attendees per ticket, with filters (max 5000)", + "summary": "Change a staff user's role", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -4925,57 +4595,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", @@ -4986,6 +4612,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoleUpdate" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -4995,18 +4631,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExportAttendee" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/StaffUser" } }, "required": [ - "data", - "page" + "data" ] } } @@ -5042,6 +4671,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": { @@ -5055,14 +4694,14 @@ } } }, - "/reports/exports/buyers": { + "/reports/summary": { "get": { - "operationId": "getReportsExportsBuyers", + "operationId": "getReportsSummary", "tags": [ "reports" ], - "summary": "Export buyers, with filters (max 5000)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Workspace KPIs (revenue, tickets, sales, memberships)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5073,55 +4712,19 @@ ], "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", + "name": "period", "in": "query", "required": false, - "description": "PENDING|CONFIRMED|ABANDONED|CANCELLED|REFUNDED (default CONFIRMED)", + "description": "7d | 30d (default) | 90d | 1y", "schema": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] + "7d", + "30d", + "90d", + "1y" + ], + "default": "30d" } }, { @@ -5143,18 +4746,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ExportBuyer" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/ReportSummary" } }, "required": [ - "data", - "page" + "data" ] } } @@ -5203,14 +4799,14 @@ } } }, - "/reports/exports/subscribers": { + "/reports/inventory": { "get": { - "operationId": "getReportsExportsSubscribers", + "operationId": "getReportsInventory", "tags": [ "reports" ], - "summary": "Export subscribers (max 5000)", - "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": [] @@ -5220,6 +4816,67 @@ } ], "parameters": [ + { + "name": "eventId", + "in": "query", + "required": false, + "description": "Filter by event", + "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", @@ -5241,7 +4898,13 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ExportSubscriber" + "$ref": "#/components/schemas/InventoryRow" + } + }, + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" } } }, @@ -5295,14 +4958,14 @@ } } }, - "/reports/by-event": { + "/reports/reconciliation": { "get": { - "operationId": "getReportsByEvent", + "operationId": "getReportsReconciliation", "tags": [ "reports" ], - "summary": "Sales KPIs per workspace event", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "CFO financial reconciliation (MP ↔ sale ↔ Siigo invoice)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5313,39 +4976,86 @@ ], "parameters": [ { - "name": "from", + "name": "date_from", "in": "query", - "required": false, - "description": "ISO 8601, filters Sale.created_at (gte)", + "required": true, + "description": "ISO 8601 (start, on Sale.created_at)", "schema": { "type": "string" } }, { - "name": "to", + "name": "date_to", "in": "query", - "required": false, - "description": "ISO 8601, filters Sale.created_at (lte)", + "required": true, + "description": "ISO 8601 (end)", "schema": { "type": "string" } }, { - "name": "status", + "name": "match_status", "in": "query", "required": false, - "description": "PENDING|CONFIRMED (default)|ABANDONED|CANCELLED|REFUNDED", + "description": "Filter by flag: OK|MISSING_INVOICE|MISSING_CUFE|AMOUNT_MISMATCH|MISSING_PAYMENT", "schema": { "type": "string", "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" + "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", @@ -5367,7 +5077,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ReportByEventRow" + "$ref": "#/components/schemas/ReconciliationRow" } } }, @@ -5378,16 +5088,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -5431,14 +5131,14 @@ } } }, - "/reports/timeseries": { + "/reports/exports/reconciliation": { "get": { - "operationId": "getReportsTimeseries", + "operationId": "getReportsExportsReconciliation", "tags": [ "reports" ], - "summary": "Time series of CONFIRMED sales per bucket (day|week|month)", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "summary": "CSV export of the CFO financial reconciliation", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5449,42 +5149,62 @@ ], "parameters": [ { - "name": "interval", + "name": "date_from", "in": "query", "required": true, - "description": "day | week | month", + "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": [ - "day", - "week", - "month" + "OK", + "MISSING_INVOICE", + "MISSING_CUFE", + "AMOUNT_MISMATCH", + "MISSING_PAYMENT" ] } }, { - "name": "from", + "name": "provider", "in": "query", "required": false, - "description": "ISO 8601, filters Sale.created_at (gte)", + "description": "Filter by payment_provider (e.g. mercadopago)", "schema": { "type": "string" } }, { - "name": "to", + "name": "event", "in": "query", "required": false, - "description": "ISO 8601, filters Sale.created_at (lte)", + "description": "Filter by event id", "schema": { "type": "string" } }, { - "name": "event", + "name": "eventDate", "in": "query", "required": false, - "description": "Workspace event ID (optional)", + "description": "Filter by event date id (takes precedence over `event`)", "schema": { "type": "string" } @@ -5505,28 +5225,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ReportTimeseriesRow" - } - } - }, - "required": [ - "data" - ] - } - } - } - }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" + "type": "object" } } } @@ -5574,14 +5273,14 @@ } } }, - "/reports/financials": { + "/reports/exports/attendees": { "get": { - "operationId": "getReportsFinancials", + "operationId": "getReportsExportsAttendees", "tags": [ "reports" ], - "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": "Export attendees per ticket, with filters (max 5000)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5595,21 +5294,51 @@ "name": "event", "in": "query", "required": false, - "description": "Filter by event id", + "description": "Filter by Event.id", "schema": { "type": "string" } }, { - "name": "past", + "name": "eventDate", "in": "query", "required": false, - "description": "true = only event dates that already took place (settleable); false = upcoming ones", + "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": [ - "true", - "false" + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" ] } }, @@ -5634,33 +5363,21 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ReportFinancialsRow" + "$ref": "#/components/schemas/ExportAttendee" } }, - "warnings": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Warning" - } + "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": { @@ -5704,14 +5421,14 @@ } } }, - "/settlements": { + "/reports/exports/buyers": { "get": { - "operationId": "getSettlements", + "operationId": "getReportsExportsBuyers", "tags": [ - "settlements" + "reports" ], - "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": "Export buyers, with filters (max 5000)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5725,44 +5442,54 @@ "name": "event", "in": "query", "required": false, - "description": "Filter by event id", + "description": "Filter by Event.id", "schema": { "type": "string" } }, { - "name": "status", + "name": "eventDate", "in": "query", "required": false, - "description": "SENT|AWAITING_PAYMENT|PAID", + "description": "Filter by EventDate.id", "schema": { - "type": "string", - "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" - ] + "type": "string" } }, { - "name": "limit", + "name": "from", "in": "query", "required": false, - "description": "1..100 (default 20)", + "description": "ISO 8601 — from (on Sale.created_at)", "schema": { - "type": "integer", - "default": 20 + "type": "string" } }, { - "name": "cursor", + "name": "to", "in": "query", "required": false, - "description": "Id of the last row of the previous page", + "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", @@ -5784,7 +5511,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Settlement" + "$ref": "#/components/schemas/ExportBuyer" } }, "page": { @@ -5799,16 +5526,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -5852,14 +5569,14 @@ } } }, - "/settlements/{id}": { + "/reports/exports/subscribers": { "get": { - "operationId": "getSettlementsId", + "operationId": "getReportsExportsSubscribers", "tags": [ - "settlements" + "reports" ], - "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": "Export subscribers (max 5000)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5869,14 +5586,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -5896,7 +5605,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Settlement" + "type": "array", + "items": { + "$ref": "#/components/schemas/ExportSubscriber" + } } }, "required": [ @@ -5949,14 +5661,14 @@ } } }, - "/settlements/{id}/document": { + "/reports/by-event": { "get": { - "operationId": "getSettlementsIdDocument", + "operationId": "getReportsByEvent", "tags": [ - "settlements" + "reports" ], - "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`.", + "summary": "Sales KPIs per workspace event", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -5967,13 +5679,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", @@ -5985,11 +5723,29 @@ } ], "responses": { - "302": { - "description": "Redirect to the signed URL (5 min TTL) of the PDF, with Content-Disposition: attachment." + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ReportByEventRow" + } + } + }, + "required": [ + "data" + ] + } + } + } }, - "401": { - "description": "Invalid or missing credential.", + "400": { + "description": "Bad request: malformed parameters.", "content": { "application/json": { "schema": { @@ -5998,8 +5754,8 @@ } } }, - "403": { - "description": "Insufficient role (< ADMIN).", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -6008,8 +5764,8 @@ } } }, - "404": { - "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no document yet.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -6018,8 +5774,8 @@ } } }, - "502": { - "description": "Could not sign the storage URL.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -6028,8 +5784,8 @@ } } }, - "503": { - "description": "Storage is not configured.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -6041,14 +5797,14 @@ } } }, - "/settlements/{id}/proofs/{fileName}": { + "/reports/timeseries": { "get": { - "operationId": "getSettlementsIdProofsFileName", + "operationId": "getReportsTimeseries", "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": "Time series of CONFIRMED sales per bucket (day|week|month)", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -6059,17 +5815,42 @@ ], "parameters": [ { - "name": "id", - "in": "path", + "name": "interval", + "in": "query", "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": "fileName", - "in": "path", - "required": true, + "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" } @@ -6085,11 +5866,29 @@ } ], "responses": { - "302": { - "description": "Redirect to the signed URL (5 min TTL) of the payment proof, with Content-Disposition: attachment." + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ReportTimeseriesRow" + } + } + }, + "required": [ + "data" + ] + } + } + } }, - "401": { - "description": "Invalid or missing credential.", + "400": { + "description": "Bad request: malformed parameters.", "content": { "application/json": { "schema": { @@ -6098,8 +5897,8 @@ } } }, - "403": { - "description": "Insufficient role (< ADMIN).", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -6108,8 +5907,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": { @@ -6118,8 +5917,8 @@ } } }, - "502": { - "description": "Could not sign the storage URL.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -6128,8 +5927,8 @@ } } }, - "503": { - "description": "Storage is not configured.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -6141,14 +5940,14 @@ } } }, - "/discounts": { + "/reports/financials": { "get": { - "operationId": "getDiscounts", + "operationId": "getReportsFinancials", "tags": [ - "discounts" + "reports" ], - "summary": "List workspace discount codes", - "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": [] @@ -6162,36 +5961,22 @@ "name": "event", "in": "query", "required": false, - "description": "event id to filter by", + "description": "Filter by event id", "schema": { "type": "string" } }, { - "name": "active", + "name": "past", "in": "query", "required": false, - "description": "true|false", + "description": "true = only event dates that already took place (settleable); false = upcoming ones", "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" + "type": "string", + "enum": [ + "true", + "false" + ] } }, { @@ -6215,21 +6000,33 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/Discount" + "$ref": "#/components/schemas/ReportFinancialsRow" } }, - "page": { - "$ref": "#/components/schemas/Page" + "warnings": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Warning" + } } }, "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": { @@ -6271,14 +6068,16 @@ } } } - }, - "post": { - "operationId": "postDiscounts", + } + }, + "/settlements": { + "get": { + "operationId": "getSettlements", "tags": [ - "discounts" + "settlements" ], - "summary": "Create a discount code", - "description": "Minimum role: `ADMIN`. 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": [] @@ -6288,6 +6087,48 @@ } ], "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", + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -6298,18 +6139,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DiscountCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -6317,18 +6148,25 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Discount" + "type": "array", + "items": { + "$ref": "#/components/schemas/Settlement" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } } }, - "401": { - "description": "Missing or invalid credential.", + "400": { + "description": "Bad request: malformed parameters.", "content": { "application/json": { "schema": { @@ -6337,8 +6175,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "401": { + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -6347,8 +6185,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "403": { + "description": "Insufficient role or resource not accessible.", "content": { "application/json": { "schema": { @@ -6357,8 +6195,8 @@ } } }, - "409": { - "description": "Conflict: the resource does not allow this operation in its current state.", + "404": { + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -6380,14 +6218,14 @@ } } }, - "/discounts/{id}": { - "patch": { - "operationId": "patchDiscountsId", + "/settlements/{id}": { + "get": { + "operationId": "getSettlementsId", "tags": [ - "discounts" + "settlements" ], - "summary": "Update a discount code", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -6415,16 +6253,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/DiscountUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -6434,7 +6262,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Discount" + "$ref": "#/components/schemas/Settlement" } }, "required": [ @@ -6485,14 +6313,16 @@ } } } - }, - "delete": { - "operationId": "deleteDiscountsId", + } + }, + "/settlements/{id}/document": { + "get": { + "operationId": "getSettlementsIdDocument", "tags": [ - "discounts" + "settlements" ], - "summary": "Delete a discount code (soft delete)", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -6521,18 +6351,21 @@ } ], "responses": { - "200": { - "description": "OK", + "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": { - "type": "object" + "$ref": "#/components/schemas/Error" } } } }, - "401": { - "description": "Missing or invalid credential.", + "403": { + "description": "Insufficient role (< ADMIN).", "content": { "application/json": { "schema": { @@ -6541,8 +6374,8 @@ } } }, - "403": { - "description": "Insufficient role or resource not accessible.", + "404": { + "description": "Settlement does not exist, belongs to another organization, is out of scope, or has no document yet.", "content": { "application/json": { "schema": { @@ -6551,8 +6384,8 @@ } } }, - "404": { - "description": "Resource does not exist or is out of scope.", + "502": { + "description": "Could not sign the storage URL.", "content": { "application/json": { "schema": { @@ -6561,8 +6394,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "503": { + "description": "Storage is not configured.", "content": { "application/json": { "schema": { @@ -6574,14 +6407,14 @@ } } }, - "/webhooks": { + "/settlements/{id}/proofs/{fileName}": { "get": { - "operationId": "getWebhooks", + "operationId": "getSettlementsIdProofsFileName", "tags": [ - "webhooks" + "settlements" ], - "summary": "List workspace webhooks", - "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": [] @@ -6592,19 +6425,17 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", + "name": "id", + "in": "path", + "required": true, "schema": { - "type": "integer", - "default": 20 + "type": "string" } }, { - "name": "cursor", - "in": "query", - "required": false, + "name": "fileName", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -6620,33 +6451,11 @@ } ], "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Webhook" - } - }, - "page": { - "$ref": "#/components/schemas/Page" - } - }, - "required": [ - "data", - "page" - ] - } - } - } + "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": { @@ -6656,7 +6465,7 @@ } }, "403": { - "description": "Insufficient role or resource not accessible.", + "description": "Insufficient role (< ADMIN).", "content": { "application/json": { "schema": { @@ -6666,7 +6475,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 payment proof with that name.", "content": { "application/json": { "schema": { @@ -6675,8 +6484,18 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "502": { + "description": "Could not sign the storage URL.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "503": { + "description": "Storage is not configured.", "content": { "application/json": { "schema": { @@ -6686,13 +6505,15 @@ } } } - }, - "post": { - "operationId": "postWebhooks", + } + }, + "/discounts": { + "get": { + "operationId": "getDiscounts", "tags": [ - "webhooks" + "discounts" ], - "summary": "Create a webhook (returns the signingSecret only once)", + "summary": "List workspace discount codes", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -6703,6 +6524,42 @@ } ], "parameters": [ + { + "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" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -6713,18 +6570,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/WebhookCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -6732,11 +6579,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/WebhookCreated" + "type": "array", + "items": { + "$ref": "#/components/schemas/Discount" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -6783,15 +6637,13 @@ } } } - } - }, - "/webhooks/{id}": { - "delete": { - "operationId": "deleteWebhooksId", + }, + "post": { + "operationId": "postDiscounts", "tags": [ - "webhooks" + "discounts" ], - "summary": "Delete a workspace webhook", + "summary": "Create a discount code", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -6802,14 +6654,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -6820,13 +6664,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DiscountCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Discount" + } + }, + "required": [ + "data" + ] } } } @@ -6861,6 +6723,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": { @@ -6872,14 +6744,16 @@ } } } - }, + } + }, + "/discounts/{id}": { "patch": { - "operationId": "patchWebhooksId", + "operationId": "patchDiscountsId", "tags": [ - "webhooks" + "discounts" ], - "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": "Update a discount code", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -6912,7 +6786,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/WebhookUpdate" + "$ref": "#/components/schemas/DiscountUpdate" } } } @@ -6926,7 +6800,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/Webhook" + "$ref": "#/components/schemas/Discount" } }, "required": [ @@ -6977,16 +6851,13 @@ } } } - } - }, - "/membership-plans/{id}/subscribers": { - "get": { - "operationId": "getMembershipPlansIdSubscribers", + }, + "delete": { + "operationId": "deleteDiscountsId", "tags": [ - "membership-plans", - "subscriptions" + "discounts" ], - "summary": "List subscribers of a membership plan", + "summary": "Delete a discount code (soft delete)", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7005,40 +6876,6 @@ "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", - "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", @@ -7055,22 +6892,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/Subscriber" - } - }, - "page": { - "$ref": "#/components/schemas/Page" - } - }, - "required": [ - "data", - "page" - ] + "type": "object" } } } @@ -7118,14 +6940,13 @@ } } }, - "/subscriptions/{id}/cancel": { - "post": { - "operationId": "postSubscriptionsIdCancel", + "/webhooks": { + "get": { + "operationId": "getWebhooks", "tags": [ - "subscriptions", - "membership-plans" + "webhooks" ], - "summary": "Cancel a membership subscription", + "summary": "List workspace webhooks", "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { @@ -7137,9 +6958,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" } @@ -7163,11 +6994,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SubscriptionCancelResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/Webhook" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -7212,28 +7050,16 @@ } } } - }, - "502": { - "description": "The external provider failed to complete the operation.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } - } - }, - "/sales/{id}/tickets": { - "get": { - "operationId": "getSalesIdTickets", + }, + "post": { + "operationId": "postWebhooks", "tags": [ - "sales" + "webhooks" ], - "summary": "List the individual tickets of a sale", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Create a webhook (returns the signingSecret only once)", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7243,14 +7069,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -7261,8 +7079,18 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -7270,10 +7098,7 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/SaleTicket" - } + "$ref": "#/components/schemas/WebhookCreated" } }, "required": [ @@ -7326,14 +7151,14 @@ } } }, - "/sales/{id}/attempts": { - "get": { - "operationId": "getSalesIdAttempts", + "/webhooks/{id}": { + "delete": { + "operationId": "deleteWebhooksId", "tags": [ - "sales" + "webhooks" ], - "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": "Delete a workspace webhook", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7367,18 +7192,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/PaymentAttempt" - } - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -7424,16 +7238,14 @@ } } } - } - }, - "/tickets/{ticketCode}": { + }, "patch": { - "operationId": "patchTicketsTicketCode", + "operationId": "patchWebhooksId", "tags": [ - "tickets" + "webhooks" ], - "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": "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": [] @@ -7444,7 +7256,7 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", "in": "path", "required": true, "schema": { @@ -7466,7 +7278,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/TicketReassign" + "$ref": "#/components/schemas/WebhookUpdate" } } } @@ -7480,7 +7292,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/SaleItem" + "$ref": "#/components/schemas/Webhook" } }, "required": [ @@ -7520,28 +7332,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.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -7553,14 +7345,15 @@ } } }, - "/tickets/{ticketCode}/checkin": { - "post": { - "operationId": "postTicketsTicketCodeCheckin", + "/membership-plans/{id}/subscribers": { + "get": { + "operationId": "getMembershipPlansIdSubscribers", "tags": [ - "tickets" + "membership-plans", + "subscriptions" ], - "summary": "Check in a ticket at the door", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "List subscribers of a membership plan", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7571,13 +7364,47 @@ ], "parameters": [ { - "name": "ticketCode", + "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", + "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", @@ -7588,16 +7415,6 @@ } } ], - "requestBody": { - "required": false, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CheckinRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -7607,11 +7424,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CheckinResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/Subscriber" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -7647,16 +7471,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": { @@ -7670,14 +7484,15 @@ } } }, - "/tickets/{ticketCode}/access": { - "get": { - "operationId": "getTicketsTicketCodeAccess", + "/subscriptions/{id}/cancel": { + "post": { + "operationId": "postSubscriptionsIdCancel", "tags": [ - "tickets" + "subscriptions", + "membership-plans" ], - "summary": "Check a ticket's validity without consuming it", - "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "summary": "Cancel a membership subscription", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7688,7 +7503,7 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", "in": "path", "required": true, "schema": { @@ -7714,7 +7529,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/TicketAccess" + "$ref": "#/components/schemas/SubscriptionCancelResult" } }, "required": [ @@ -7763,18 +7578,28 @@ } } } + }, + "502": { + "description": "The external provider failed to complete the operation.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/api-keys": { + "/sales/{id}/tickets": { "get": { - "operationId": "getApiKeys", + "operationId": "getSalesIdTickets", "tags": [ - "api-keys" + "sales" ], - "summary": "List my API keys", - "description": "Lists the authenticated user's API keys (never the hash or the plaintext secret).", + "summary": "List the individual tickets of a sale", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -7785,19 +7610,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" } @@ -7823,16 +7638,12 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/ApiKey" + "$ref": "#/components/schemas/SaleTicket" } - }, - "page": { - "$ref": "#/components/schemas/Page" } }, "required": [ - "data", - "page" + "data" ] } } @@ -7879,14 +7690,16 @@ } } } - }, - "post": { - "operationId": "postApiKeys", - "tags": [ - "api-keys" + } + }, + "/sales/{id}/attempts": { + "get": { + "operationId": "getSalesIdAttempts", + "tags": [ + "sales" ], - "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": "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": [] @@ -7896,6 +7709,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -7906,18 +7727,8 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ApiKeyCreate" - } - } - } - }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -7925,7 +7736,10 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ApiKeyCreated" + "type": "array", + "items": { + "$ref": "#/components/schemas/PaymentAttempt" + } } }, "required": [ @@ -7978,14 +7792,14 @@ } } }, - "/api-keys/{id}": { - "delete": { - "operationId": "deleteApiKeysId", + "/tickets/{ticketCode}": { + "patch": { + "operationId": "patchTicketsTicketCode", "tags": [ - "api-keys" + "tickets" ], - "summary": "Revoke one of my API keys", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -7996,7 +7810,7 @@ ], "parameters": [ { - "name": "id", + "name": "ticketCode", "in": "path", "required": true, "schema": { @@ -8013,13 +7827,31 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TicketReassign" + } + } + } + }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/SaleItem" + } + }, + "required": [ + "data" + ] } } } @@ -8054,8 +7886,28 @@ } } }, + "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": { @@ -8067,28 +7919,43 @@ } } }, - "/customer/auth/request": { + "/tickets/{ticketCode}/resend": { "post": { - "operationId": "postCustomerAuthRequest", + "operationId": "postTicketsTicketCodeResend", "tags": [ - "customer", - "auth" + "tickets" ], - "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" - } + "summary": "Resend the confirmation email with the ticket", + "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "ticketCode", + "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": { - "202": { + "200": { "description": "OK", "content": { "application/json": { @@ -8096,7 +7963,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerAuthRequestResult" + "$ref": "#/components/schemas/ResendTicket" } }, "required": [ @@ -8136,8 +8003,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": "Operation error.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -8146,8 +8023,8 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "502": { + "description": "The external provider failed to complete the operation.", "content": { "application/json": { "schema": { @@ -8159,22 +8036,47 @@ } } }, - "/customer/auth/verify": { + "/tickets/{ticketCode}/checkin": { "post": { - "operationId": "postCustomerAuthVerify", + "operationId": "postTicketsTicketCodeCheckin", "tags": [ - "customer", - "auth" + "tickets" + ], + "summary": "Check in a ticket at the door", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", + "security": [ + { + "apiKey": [] + }, + { + "apiKeyHeader": [] + } + ], + "parameters": [ + { + "name": "ticketCode", + "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, + "required": false, "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomerAuthVerify" + "$ref": "#/components/schemas/CheckinRequest" } } } @@ -8188,7 +8090,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerAuthVerifyResult" + "$ref": "#/components/schemas/CheckinResult" } }, "required": [ @@ -8199,7 +8101,7 @@ } }, "401": { - "description": "Operation error.", + "description": "Missing or invalid credential.", "content": { "application/json": { "schema": { @@ -8228,8 +8130,8 @@ } } }, - "422": { - "description": "Operation error.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -8238,8 +8140,8 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -8251,14 +8153,14 @@ } } }, - "/customer/me": { + "/tickets/{ticketCode}/access": { "get": { - "operationId": "getCustomerMe", + "operationId": "getTicketsTicketCodeAccess", "tags": [ - "customer" + "tickets" ], - "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": "Check a ticket's validity without consuming it", + "description": "Minimum role: `STAFF`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8268,6 +8170,14 @@ } ], "parameters": [ + { + "name": "ticketCode", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -8287,7 +8197,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerMe" + "$ref": "#/components/schemas/TicketAccess" } }, "required": [ @@ -8340,14 +8250,14 @@ } } }, - "/customer/tickets": { + "/api-keys": { "get": { - "operationId": "getCustomerTickets", + "operationId": "getApiKeys", "tags": [ - "customer" + "api-keys" ], - "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 my API keys", + "description": "Lists the authenticated user's API keys (never the hash or the plaintext secret).", "security": [ { "apiKey": [] @@ -8396,7 +8306,7 @@ "data": { "type": "array", "items": { - "$ref": "#/components/schemas/CustomerSale" + "$ref": "#/components/schemas/ApiKey" } }, "page": { @@ -8452,16 +8362,14 @@ } } } - } - }, - "/customer/tickets/{id}": { - "get": { - "operationId": "getCustomerTicketsId", + }, + "post": { + "operationId": "postApiKeys", "tags": [ - "customer" + "api-keys" ], - "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": "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": [] @@ -8471,14 +8379,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -8489,8 +8389,18 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiKeyCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -8498,7 +8408,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSale" + "$ref": "#/components/schemas/ApiKeyCreated" } }, "required": [ @@ -8551,14 +8461,14 @@ } } }, - "/customer/tickets/{id}/cancel": { - "post": { - "operationId": "postCustomerTicketsIdCancel", + "/api-keys/{id}": { + "delete": { + "operationId": "deleteApiKeysId", "tags": [ - "customer" + "api-keys" ], - "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": "Revoke one of my API keys", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -8592,15 +8502,7 @@ "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/CustomerTicketCancelResult" - } - }, - "required": [ - "data" - ] + "type": "object" } } } @@ -8635,16 +8537,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": { @@ -8658,35 +8550,28 @@ } } }, - "/customer/logout": { + "/customer/auth/request": { "post": { - "operationId": "postCustomerLogout", + "operationId": "postCustomerAuthRequest", "tags": [ - "customer" - ], - "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": [] - }, - { - "apiKeyHeader": [] - } + "customer", + "auth" ], - "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" + } } } - ], + }, "responses": { - "200": { + "202": { "description": "OK", "content": { "application/json": { @@ -8694,7 +8579,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerLogout" + "$ref": "#/components/schemas/CustomerAuthRequestResult" } }, "required": [ @@ -8735,120 +8620,59 @@ } }, "422": { - "description": "Request body/parameter validation failed.", + "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" + } } } } } }, - "/api/customer-auth/enterprise-exchange": { + "/customer/auth/verify": { "post": { - "operationId": "postApiCustomerAuthEnterpriseExchange", + "operationId": "postCustomerAuthVerify", "tags": [ - "customer" - ], - "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": [] - }, - { - "apiKeyHeader": [] - } - ], - "servers": [ - { - "url": "/", - "description": "Canonical host (outside /api/v1)" - } - ], - "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" - } - } + "customer", + "auth" ], + "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/EnterpriseExchangeRequest" + "$ref": "#/components/schemas/CustomerAuthVerify" } } } }, - "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", @@ -8858,7 +8682,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerMembershipState" + "$ref": "#/components/schemas/CustomerAuthVerifyResult" } }, "required": [ @@ -8869,7 +8693,7 @@ } }, "401": { - "description": "Missing or invalid credential.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -8907,19 +8731,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" + } + } } } } }, - "/customer/subscriptions": { - "post": { - "operationId": "postCustomerSubscriptions", + "/customer/me": { + "get": { + "operationId": "getCustomerMe", "tags": [ - "customer", - "subscriptions" + "customer" ], - "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": "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": [] @@ -8939,16 +8783,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerSubscribeRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -8958,7 +8792,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSubscribeResult" + "$ref": "#/components/schemas/CustomerMe" } }, "required": [ @@ -8998,16 +8832,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": { @@ -9021,15 +8845,14 @@ } } }, - "/customer/subscriptions/cancel": { - "post": { - "operationId": "postCustomerSubscriptionsCancel", + "/customer/tickets": { + "get": { + "operationId": "getCustomerTickets", "tags": [ - "customer", - "subscriptions" + "customer" ], - "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": "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": [] @@ -9039,6 +8862,24 @@ } ], "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", @@ -9049,16 +8890,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerSubscriptionCancelRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -9068,11 +8899,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerSubscriptionCancelResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerSale" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -9099,7 +8937,7 @@ } }, "404": { - "description": "Operation error.", + "description": "Resource does not exist or is out of scope.", "content": { "application/json": { "schema": { @@ -9109,17 +8947,7 @@ } }, "422": { - "description": "Operation error.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, - "502": { - "description": "The external provider failed to complete the operation.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -9131,14 +8959,14 @@ } } }, - "/customer/profile": { + "/customer/tickets/{id}": { "get": { - "operationId": "getCustomerProfile", + "operationId": "getCustomerTicketsId", "tags": [ "customer" ], - "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": "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": [] @@ -9148,6 +8976,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9167,7 +9003,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerProfile" + "$ref": "#/components/schemas/CustomerSale" } }, "required": [ @@ -9218,14 +9054,16 @@ } } } - }, - "patch": { - "operationId": "patchCustomerProfile", + } + }, + "/customer/tickets/{id}/cancel": { + "post": { + "operationId": "postCustomerTicketsIdCancel", "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.", + "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": [] @@ -9235,6 +9073,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -9245,16 +9091,6 @@ } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerProfileUpdate" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -9264,7 +9100,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerProfile" + "$ref": "#/components/schemas/CustomerTicketCancelResult" } }, "required": [ @@ -9304,6 +9140,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": { @@ -9317,15 +9163,14 @@ } } }, - "/customer/purchase-sessions": { + "/customer/logout": { "post": { - "operationId": "postCustomerPurchaseSessions", + "operationId": "postCustomerLogout", "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": "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": [] @@ -9345,36 +9190,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": { @@ -9382,7 +9199,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionCreated" + "$ref": "#/components/schemas/CustomerLogout" } }, "required": [ @@ -9431,39 +9248,18 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "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" - } - } - } } } } }, - "/customer/purchase-sessions/{id}": { - "get": { - "operationId": "getCustomerPurchaseSessionsId", + "/api/customer-auth/enterprise-exchange": { + "post": { + "operationId": "postApiCustomerAuthEnterpriseExchange", "tags": [ - "customer", - "purchase-sessions" + "customer" ], - "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": "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": [] @@ -9472,15 +9268,13 @@ "apiKeyHeader": [] } ], - "parameters": [ + "servers": [ { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, + "url": "/", + "description": "Canonical host (outside /api/v1)" + } + ], + "parameters": [ { "name": "X-Workspace-Id", "in": "header", @@ -9491,38 +9285,107 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EnterpriseExchangeRequest" + } + } + } + }, "responses": { "200": { - "description": "OK", + "description": "Buyer session exchanged.", "content": { "application/json": { "schema": { - "type": "object", - "properties": { - "data": { - "$ref": "#/components/schemas/PurchaseSessionStatus" - } - }, - "required": [ - "data" - ] + "$ref": "#/components/schemas/EnterpriseExchangeResponse" } } } }, "401": { - "description": "Missing or invalid credential.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } + "description": "Missing or invalid API key, or invalid/expired token." }, "403": { - "description": "Insufficient role or resource not accessible.", - "content": { + "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", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomerMembershipState" + } + }, + "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" @@ -9541,7 +9404,7 @@ } }, "422": { - "description": "Request body/parameter validation failed.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -9553,15 +9416,15 @@ } } }, - "/customer/purchase-sessions/{id}/release": { + "/customer/subscriptions": { "post": { - "operationId": "postCustomerPurchaseSessionsIdRelease", + "operationId": "postCustomerSubscriptions", "tags": [ "customer", - "purchase-sessions" + "subscriptions" ], - "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.", + "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": [] @@ -9571,14 +9434,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -9589,6 +9444,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerSubscribeRequest" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -9598,7 +9463,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/PurchaseSessionStatus" + "$ref": "#/components/schemas/CustomerSubscribeResult" } }, "required": [ @@ -9638,8 +9503,8 @@ } } }, - "422": { - "description": "Request body/parameter validation failed.", + "409": { + "description": "Conflict: the resource does not allow this operation in its current state.", "content": { "application/json": { "schema": { @@ -9648,8 +9513,8 @@ } } }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "422": { + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -9661,14 +9526,15 @@ } } }, - "/content/videos": { - "get": { - "operationId": "getContentVideos", + "/customer/subscriptions/cancel": { + "post": { + "operationId": "postCustomerSubscriptionsCancel", "tags": [ - "content" + "customer", + "subscriptions" ], - "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": "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": [] @@ -9678,24 +9544,6 @@ } ], "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", @@ -9706,6 +9554,16 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerSubscriptionCancelRequest" + } + } + } + }, "responses": { "200": { "description": "OK", @@ -9715,18 +9573,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentVideo" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/CustomerSubscriptionCancelResult" } }, "required": [ - "data", - "page" + "data" ] } } @@ -9753,7 +9604,7 @@ } }, "404": { - "description": "Resource does not exist or is out of scope.", + "description": "Operation error.", "content": { "application/json": { "schema": { @@ -9763,7 +9614,17 @@ } }, "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": { @@ -9775,14 +9636,14 @@ } } }, - "/content/posts": { + "/customer/profile": { "get": { - "operationId": "getContentPosts", + "operationId": "getCustomerProfile", "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": "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": [] @@ -9792,24 +9653,6 @@ } ], "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", @@ -9829,18 +9672,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentPost" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/CustomerProfile" } }, "required": [ - "data", - "page" + "data" ] } } @@ -9888,13 +9724,13 @@ } } }, - "post": { - "operationId": "postContentPosts", + "patch": { + "operationId": "patchCustomerProfile", "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": "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": [] @@ -9919,13 +9755,13 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ContentPostCreate" + "$ref": "#/components/schemas/CustomerProfileUpdate" } } } }, "responses": { - "201": { + "200": { "description": "OK", "content": { "application/json": { @@ -9933,7 +9769,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentPost" + "$ref": "#/components/schemas/CustomerProfile" } }, "required": [ @@ -9943,16 +9779,6 @@ } } }, - "400": { - "description": "Bad request: malformed parameters.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } - }, "401": { "description": "Missing or invalid credential.", "content": { @@ -9983,18 +9809,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": { @@ -10006,14 +9822,15 @@ } } }, - "/content/lives": { - "get": { - "operationId": "getContentLives", + "/customer/orders/{id}/payment": { + "post": { + "operationId": "postCustomerOrdersIdPayment", "tags": [ - "content" + "customer", + "orders" ], - "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": "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": [] @@ -10024,28 +9841,27 @@ ], "parameters": [ { - "name": "limit", - "in": "query", - "required": false, - "description": "1-100, default 20", + "name": "id", + "in": "path", + "required": true, "schema": { - "type": "integer", - "default": 20 + "type": "string" } }, { - "name": "cursor", - "in": "query", + "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": "X-Purchase-Session", "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": "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" } @@ -10060,18 +9876,11 @@ "type": "object", "properties": { "data": { - "type": "array", - "items": { - "$ref": "#/components/schemas/ContentLive" - } - }, - "page": { - "$ref": "#/components/schemas/Page" + "$ref": "#/components/schemas/CustomerOrderStartPayment" } }, "required": [ - "data", - "page" + "data" ] } } @@ -10107,6 +9916,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": { @@ -10116,18 +9935,40 @@ } } } + }, + "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/lives/{id}": { - "get": { - "operationId": "getContentLivesId", + "/customer/orders/{id}/payment/card": { + "post": { + "operationId": "postCustomerOrdersIdPaymentCard", "tags": [ - "content" + "customer", + "orders" ], - "summary": "Live stream status", - "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -10153,8 +9994,27 @@ "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", @@ -10164,7 +10024,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentLive" + "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeResult" } }, "required": [ @@ -10204,27 +10064,59 @@ } } }, + "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" + } + } + } + }, + "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/playback-token": { + "/customer/orders/{id}/payment/pse": { "post": { - "operationId": "postContentPlaybackToken", + "operationId": "postCustomerOrdersIdPaymentPse", "tags": [ - "content" + "customer", + "orders" ], - "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 (otherwise 403 `MEMBERSHIP_REQUIRED`). Content from another organization responds 404. Short-lived tokens: 30 minutes for live streams, 1 hour for videos.", + "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": [] @@ -10234,6 +10126,14 @@ } ], "parameters": [ + { + "name": "id", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, { "name": "X-Workspace-Id", "in": "header", @@ -10242,18 +10142,17 @@ "schema": { "type": "string" } - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ContentPlaybackTokenRequest" - } + }, + { + "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", @@ -10263,7 +10162,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ContentPlaybackToken" + "$ref": "#/components/schemas/CustomerOrderMercadoPagoPse" } }, "required": [ @@ -10303,6 +10202,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": { @@ -10313,27 +10222,39 @@ } } }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization 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" + } } } } } }, - "/tickets/{ticketCode}/resend": { + "/customer/orders/{id}/release": { "post": { - "operationId": "postTicketsTicketCodeResend", + "operationId": "postCustomerOrdersIdRelease", "tags": [ - "tickets" + "customer", + "orders" ], - "summary": "Resend the confirmation email with the ticket", - "description": "Minimum role: `ADMIN`. Active workspace via the `X-Workspace-Id` header.", + "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": [] @@ -10344,7 +10265,7 @@ ], "parameters": [ { - "name": "ticketCode", + "name": "id", "in": "path", "required": true, "schema": { @@ -10370,7 +10291,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/ResendTicket" + "$ref": "#/components/schemas/CustomerOrderRelease" } }, "required": [ @@ -10429,19 +10350,50 @@ } } } + }, + "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": { + "/customer/orders/{id}": { "get": { - "operationId": "getCustomerOrders", + "operationId": "getCustomerOrdersId", "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`.", + "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": [] @@ -10452,10 +10404,9 @@ ], "parameters": [ { - "name": "eventDateId", - "in": "query", - "required": false, - "description": "Required. The event date being queried.", + "name": "id", + "in": "path", + "required": true, "schema": { "type": "string" } @@ -10479,7 +10430,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderCurrent" + "$ref": "#/components/schemas/CustomerOrderStatus" } }, "required": [ @@ -10520,7 +10471,7 @@ } }, "422": { - "description": "Operation error.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -10528,17 +10479,40 @@ } } } - } - } - }, - "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`.", + }, + "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": [] @@ -10556,15 +10530,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": { @@ -10572,12 +10537,30 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CustomerOrderCreateRequest" + "$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": { @@ -10586,7 +10569,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderCreateResult" + "$ref": "#/components/schemas/PurchaseSessionCreated" } }, "required": [ @@ -10626,16 +10609,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": { @@ -10654,6 +10627,17 @@ "$ref": "#/components/schemas/Error" } } + }, + "headers": { + "Retry-After": { + "$ref": "#/components/headers/RetryAfter" + }, + "RateLimit": { + "$ref": "#/components/headers/RateLimit" + }, + "RateLimit-Policy": { + "$ref": "#/components/headers/RateLimitPolicy" + } } }, "503": { @@ -10669,15 +10653,15 @@ } } }, - "/customer/orders/{id}/payment": { + "/customer/purchase-sessions/{id}/release": { "post": { - "operationId": "postCustomerOrdersIdPayment", + "operationId": "postCustomerPurchaseSessionsIdRelease", "tags": [ "customer", - "orders" + "purchase-sessions" ], - "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": "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": [] @@ -10703,15 +10687,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": { @@ -10723,7 +10698,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderStartPayment" + "$ref": "#/components/schemas/PurchaseSessionStatus" } }, "required": [ @@ -10763,16 +10738,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": { @@ -10791,20 +10756,30 @@ "$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", + "/content/videos": { + "get": { + "operationId": "getContentVideos", "tags": [ - "customer", - "orders" + "content" ], - "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": "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": [] @@ -10815,42 +10790,33 @@ ], "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" } } ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeRequest" - } - } - } - }, "responses": { "200": { "description": "OK", @@ -10860,11 +10826,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoChargeResult" + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentVideo" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -10900,28 +10873,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" - } - } - } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", + "description": "Request body/parameter validation failed.", "content": { "application/json": { "schema": { @@ -10933,15 +10886,14 @@ } } }, - "/customer/orders/{id}/payment/pse": { - "post": { - "operationId": "postCustomerOrdersIdPaymentPse", + "/content/posts": { + "get": { + "operationId": "getContentPosts", "tags": [ - "customer", - "orders" + "content" ], - "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": "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": [] @@ -10952,27 +10904,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" } @@ -10987,11 +10940,18 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoPse" + "type": "array", + "items": { + "$ref": "#/components/schemas/ContentPost" + } + }, + "page": { + "$ref": "#/components/schemas/Page" } }, "required": [ - "data" + "data", + "page" ] } } @@ -11027,16 +10987,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": { @@ -11046,29 +10996,16 @@ } } } - }, - "429": { - "description": "Too many requests: rate limit exceeded.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Error" - } - } - } } } - } - }, - "/customer/orders/{id}/release": { + }, "post": { - "operationId": "postCustomerOrdersIdRelease", + "operationId": "postContentPosts", "tags": [ - "customer", - "orders" + "content" ], - "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.", + "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": [] @@ -11078,14 +11015,6 @@ } ], "parameters": [ - { - "name": "id", - "in": "path", - "required": true, - "schema": { - "type": "string" - } - }, { "name": "X-Workspace-Id", "in": "header", @@ -11096,8 +11025,18 @@ } } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ContentPostCreate" + } + } + } + }, "responses": { - "200": { + "201": { "description": "OK", "content": { "application/json": { @@ -11105,7 +11044,7 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderRelease" + "$ref": "#/components/schemas/ContentPost" } }, "required": [ @@ -11115,6 +11054,16 @@ } } }, + "400": { + "description": "Bad request: malformed parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, "401": { "description": "Missing or invalid credential.", "content": { @@ -11164,9 +11113,83 @@ } } } + } + } + } + }, + "/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": [] }, - "429": { - "description": "Too many requests: rate limit exceeded.", + { + "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": { @@ -11175,8 +11198,28 @@ } } }, - "503": { - "description": "Service unavailable: an external dependency is down or initialization failed.", + "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": { @@ -11188,15 +11231,14 @@ } } }, - "/customer/orders/{id}": { + "/content/lives/{id}": { "get": { - "operationId": "getCustomerOrdersId", + "operationId": "getContentLivesId", "tags": [ - "customer", - "orders" + "content" ], - "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.", + "summary": "Live stream status", + "description": "Minimum role: `VIEWER`. Active workspace via the `X-Workspace-Id` header.", "security": [ { "apiKey": [] @@ -11233,7 +11275,106 @@ "type": "object", "properties": { "data": { - "$ref": "#/components/schemas/CustomerOrderStatus" + "$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" + } + } + } + } + } + } + }, + "/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": [ @@ -11291,10 +11432,309 @@ "$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" + } + } + } + } + } + } } }, "components": { @@ -14220,166 +14660,56 @@ ], "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-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 - } + "PurchaseSessionCreateRequest": { + "type": "object", + "properties": { + "eventDateId": { + "type": "string", + "minLength": 1, + "maxLength": 64 }, - "block_seats": { - "type": "boolean" + "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 }, - "SaleRefundResult": { + "PurchaseSessionCreated": { "type": "object", "properties": { "id": { "type": "string" }, - "reference": { + "eventDateId": { "type": "string" }, - "status": { + "state": { "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" + "const": "live" }, - "buyerName": { - "type": "string" + "seated": { + "type": "boolean", + "description": "true = the event date has a seats.io map." }, - "buyerEmail": { - "type": "string" + "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." }, - "buyerPhone": { + "seatsDeadline": { "anyOf": [ { "type": "string" @@ -14387,9 +14717,23 @@ { "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." }, - "buyerDocumentType": { + "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." + }, + "replacedSessionId": { "anyOf": [ { "type": "string" @@ -14397,9 +14741,39 @@ { "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." + } + }, + "required": [ + "id", + "eventDateId", + "state", + "seated", + "holdToken", + "seatsDeadline", + "budgetSeconds", + "replacedSessionId" + ], + "additionalProperties": false + }, + "PurchaseSessionStatus": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "buyerDocumentNumber": { + "state": { + "type": "string", + "enum": [ + "live", + "superseded", + "expired", + "converted" + ], + "description": "`live`: can create the order. `superseded`: another tab/device replaced it. `expired`: the map clock ran out or it was released. `converted`: it already created its order (`orderId`)." + }, + "seatsDeadline": { "anyOf": [ { "type": "string" @@ -14409,7 +14783,7 @@ } ] }, - "organizationId": { + "orderId": { "anyOf": [ { "type": "string" @@ -14417,9 +14791,34 @@ { "type": "null" } - ] + ], + "description": "Sale created with this session, if any." + } + }, + "required": [ + "id", + "state", + "seatsDeadline", + "orderId" + ], + "additionalProperties": false + }, + "CustomerTicketItem": { + "type": "object", + "properties": { + "ticketTypeName": { + "type": "string" }, - "paymentProvider": { + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "ticketCode": { + "type": "string", + "description": "Opaque ticket code. The QR code must encode the validator URL (`https://admin.appfreeticket.com/dashboard/tickets/validar?code=`)." + }, + "seatLabel": { "anyOf": [ { "type": "string" @@ -14427,9 +14826,101 @@ { "type": "null" } - ] + ], + "description": "Exact seat for seated events (seats.io), or null." + } + }, + "required": [ + "ticketTypeName", + "quantity", + "ticketCode", + "seatLabel" + ], + "additionalProperties": false + }, + "CustomerSale": { + "type": "object", + "properties": { + "id": { + "type": "string" }, - "paymentRef": { + "reference": { + "type": "string" + }, + "status": { + "type": "string" + }, + "event": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "slug": { + "type": "string" + } + }, + "required": [ + "name", + "slug" + ], + "additionalProperties": false + }, + "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/CustomerTicketItem" + } + }, + "total": { + "type": "number" + }, + "currency": { + "type": "string" + } + }, + "required": [ + "id", + "reference", + "status", + "event", + "eventDate", + "items", + "total", + "currency" + ], + "additionalProperties": false + }, + "CustomerOrderCreateResult": { + "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." + }, + "reference": { + "type": "string", + "description": "Sale reference (FT-…). Always identifies the purchase." + }, + "saleId": { "anyOf": [ { "type": "string" @@ -14437,22 +14928,21 @@ { "type": "null" } - ] + ], + "description": "Sale id. null when `free` is true." }, - "confirmedAt": { + "total": { "anyOf": [ { - "type": "string" + "type": "number" }, { "type": "null" } - ] - }, - "createdAt": { - "type": "string" + ], + "description": "Amount to charge. null when `free` is true." }, - "failureReason": { + "currency": { "anyOf": [ { "type": "string" @@ -14462,7 +14952,7 @@ } ] }, - "paymentStatus": { + "expiresAt": { "anyOf": [ { "type": "string" @@ -14471,690 +14961,685 @@ "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": { + "description": "Instant (ISO 8601 UTC) at which the inventory reservation expires. After that, the purchase must be started over." + } + }, + "required": [ + "free", + "reference", + "saleId", + "total", + "currency", + "expiresAt" + ], + "additionalProperties": false + }, + "CustomerOrderCurrent": { + "type": "object", + "properties": { + "order": { "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": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "seats.io numbered seat, or null if not seated." + } + }, + "required": [ + "ticketTypeId", + "ticketTypeName", + "quantity", + "seatLabel" + ], + "additionalProperties": false + } + } + }, + "required": [ + "saleId", + "reference", + "total", + "currency", + "expiresAt", + "paymentOpened", + "items" + ], + "additionalProperties": false }, { "type": "null" } - ] + ], + "description": "The purchase the buyer left unfinished for this event date, or null if there is none." + } + }, + "required": [ + "order" + ], + "additionalProperties": false + }, + "CustomerOrderRelease": { + "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`." + } + }, + "required": [ + "released" + ], + "additionalProperties": false + }, + "CustomerOrderPayment": { + "type": "object", + "properties": { + "orderId": { + "type": "string", + "description": "Merchant reference = `reference`." }, - "refund": { + "amount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Whole pesos, no decimals." + }, + "currency": { + "type": "string" + }, + "apiKey": { + "type": "string", + "description": "Bold IDENTITY key (public, sent to the browser)." + }, + "integritySignature": { + "type": "string", + "description": "SHA256 that binds the charge to the amount. Computed on the server." + }, + "renderMode": { + "type": "string", + "const": "embedded" + }, + "redirectionUrl": { + "type": "string" + }, + "description": { + "type": "string" + }, + "expirationDate": { + "type": "number", + "description": "Epoch in NANOSECONDS (what the Bold library expects)." + } + }, + "required": [ + "orderId", + "amount", + "currency", + "apiKey", + "integritySignature", + "renderMode", + "redirectionUrl", + "description", + "expirationDate" + ], + "additionalProperties": false + }, + "CustomerOrderMercadoPagoConfig": { + "type": "object", + "properties": { + "publicKey": { + "type": "string", + "description": "MercadoPago (Tickets) public key. Sent to the browser: it is what `initMercadoPago()`/`` from the `@mercadopago/sdk-react` SDK (or equivalent) receives to mount the Payment Brick. Present ONLY on the MercadoPago rail — it is the marker the landing page uses to tell it apart from the Bold rail (which carries `apiKey`+`renderMode` and NEVER `publicKey`)." + }, + "amount": { + "type": "number", + "description": "Amount to charge, in the currency's major unit (pesos, not cents) — the same `total` already returned by `POST /customer/orders`. It is re-read from the sale on every call: do not treat it as final if a long time passes between mounting the Brick and charging." + }, + "currency": { + "type": "string" + }, + "reference": { + "type": "string", + "description": "Sale reference (FT-…)." + }, + "payerEmail": { + "type": "string", + "description": "Buyer email (from the sale, not editable). Informational: the charge ALWAYS uses the sale's email, never one sent by the client." + } + }, + "required": [ + "publicKey", + "amount", + "currency", + "reference", + "payerEmail" + ], + "additionalProperties": false + }, + "CustomerOrderStartPayment": { + "anyOf": [ + { + "$ref": "#/components/schemas/CustomerOrderPayment" + }, + { + "$ref": "#/components/schemas/CustomerOrderMercadoPagoConfig" + } + ] + }, + "CustomerOrderMercadoPagoChargeRequest": { + "type": "object", + "properties": { + "token": { + "type": "string", + "minLength": 1, + "description": "Card token returned by the Payment Brick when tokenizing." + }, + "paymentMethodId": { + "type": "string", + "minLength": 1, + "description": "`payment_method_id` returned by the Brick (e.g. `visa`, `debmaster`)." + }, + "installments": { + "default": 1, + "type": "integer", + "minimum": 1, + "maximum": 9007199254740991 + }, + "issuerId": { + "description": "`issuer_id` returned by the Brick. Some BINs require it.", + "type": "string" + }, + "payer": { "type": "object", "properties": { - "amount": { - "anyOf": [ - { - "type": "number" + "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" }, - { - "type": "null" + "number": { + "type": "string" } - ] - }, - "refundedItemIds": { - "type": "array", - "items": { - "type": "string" - } - }, - "saleRefunded": { - "type": "boolean" - }, - "gatewayRefunded": { - "type": "boolean" - }, - "seats": { - "type": "string", - "enum": [ - "blocked", - "block_failed", - "released", - "release_failed", - "none" - ] + }, + "required": [ + "type", + "number" + ], + "additionalProperties": false } }, - "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" + "token", + "paymentMethodId", + "installments" ], "additionalProperties": false }, - "ReportByEventRow": { + "CustomerOrderMercadoPagoChargeResult": { "type": "object", "properties": { - "eventId": { - "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." }, - "eventName": { + "reference": { "type": "string" }, - "revenue": { - "type": "number" - }, - "ticketsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "salesCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "message": { + "description": "Human-readable message for the buyer. Only present with `rejected`.", + "type": "string" }, - "available": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "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": [ - "eventId", - "eventName", - "revenue", - "ticketsSold", - "salesCount", - "available" + "status", + "reference" ], "additionalProperties": false }, - "ReportTimeseriesRow": { + "CustomerOrderMercadoPagoPse": { "type": "object", "properties": { - "bucket": { - "type": "string" - }, - "revenue": { - "type": "number" - }, - "ticketsSold": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "salesCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "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": [ - "bucket", - "revenue", - "ticketsSold", - "salesCount" + "redirectUrl" ], "additionalProperties": false }, - "ReportFinancialsRow": { + "CustomerOrderStatus": { "type": "object", "properties": { - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" - }, - "eventDateId": { - "type": "string" - }, - "startsAt": { + "reference": { "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 + "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." }, - "gmf": { - "type": "number" + "saleStatus": { + "type": "string", + "description": "Internal sale status (PENDING, CONFIRMED, …)." }, - "net": { + "total": { "type": "number" }, "currency": { "type": "string" }, - "settlementStatus": { - "anyOf": [ - { - "type": "string", - "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" - ] - }, - { - "type": "null" - } - ] - }, - "settlementId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "settlementAmount": { + "tickets": { "anyOf": [ { - "type": "number" + "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": [ - "eventId", - "eventName", - "eventDateId", - "startsAt", - "past", - "unitsSold", - "gross", - "platformFee", - "facial", - "paymentFee", - "wompiSalesWithoutRate", - "gmf", - "net", + "reference", + "status", + "saleStatus", + "total", "currency", - "settlementStatus", - "settlementId", - "settlementAmount" + "tickets" + ], + "additionalProperties": false + }, + "CustomerOrderItem": { + "type": "object", + "properties": { + "ticketTypeId": { + "type": "string", + "minLength": 1 + }, + "quantity": { + "type": "integer", + "minimum": 1, + "maximum": 30 + }, + "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 }, - "Settlement": { + "CustomerOrderCreateRequest": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "reference": { - "type": "string" + "eventDateId": { + "type": "string", + "minLength": 1 }, - "label": { - "type": "string" + "items": { + "minItems": 1, + "maxItems": 1, + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerOrderItem" + } }, - "status": { + "holdToken": { + "description": "Hold token of the seats.io map session. Required if seats are sent.", "type": "string", - "enum": [ - "SENT", - "AWAITING_PAYMENT", - "PAID" - ] + "maxLength": 120 }, - "amount": { - "type": "number" + "discountCode": { + "type": "string", + "maxLength": 40 }, - "grossAmount": { - "anyOf": [ - { - "type": "number" + "buyer": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 2, + "maxLength": 120 }, - { - "type": "null" - } - ] - }, - "unitsSold": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "phone": { + "type": "string", + "maxLength": 40 }, - { - "type": "null" - } - ] - }, - "currency": { - "type": "string" - }, - "notes": { - "anyOf": [ - { - "type": "string" + "idType": { + "type": "string", + "enum": [ + "CC", + "CE", + "NIT", + "PP", + "TI", + "PEP" + ] }, - { - "type": "null" - } - ] - }, - "rejectionReason": { - "anyOf": [ - { - "type": "string" + "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" + ], + "additionalProperties": false }, - "event": { - "anyOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - } - }, - "required": [ - "id", - "name" - ], - "additionalProperties": false + "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": [ + "eventDateId", + "items", + "buyer", + "returnUrl" + ], + "additionalProperties": false + }, + "SaleCreate": { + "type": "object", + "properties": { + "buyer": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1 }, - { - "type": "null" - } - ] - }, - "eventDate": { - "anyOf": [ - { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "startsAt": { - "type": "string" - } - }, - "required": [ - "id", - "startsAt" - ], - "additionalProperties": false + "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,}$" }, - { - "type": "null" + "phone": { + "type": "string", + "minLength": 1 } - ] - }, - "hasDocument": { - "type": "boolean" - }, - "paymentProofs": { - "type": "array", - "items": { - "type": "object", - "properties": { - "fileName": { - "type": "string" - } - }, - "required": [ - "fileName" - ], - "additionalProperties": false - } + }, + "required": [ + "name", + "email" + ], + "additionalProperties": false }, - "allocations": { + "items": { + "minItems": 1, "type": "array", "items": { "type": "object", "properties": { - "bankAccountId": { - "type": "string" + "ticketTypeId": { + "type": "string", + "minLength": 1 }, - "percentage": { + "quantity": { "type": "integer", - "minimum": -9007199254740991, + "minimum": 1, "maximum": 9007199254740991 + }, + "seats": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + } } }, "required": [ - "bankAccountId", - "percentage" + "ticketTypeId", + "quantity" ], "additionalProperties": false } }, - "requestedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "channel": { + "default": "ADMIN", + "type": "string", + "enum": [ + "WEB", + "MOBILE", + "POS", + "ADMIN" ] }, - "paidAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "comp": { + "default": false, + "type": "boolean" }, - "createdAt": { + "notes": { "type": "string" } }, "required": [ - "id", - "reference", - "label", - "status", - "amount", - "grossAmount", - "unitsSold", - "currency", - "notes", - "rejectionReason", - "event", - "eventDate", - "hasDocument", - "paymentProofs", - "allocations", - "requestedAt", - "paidAt", - "createdAt" + "buyer", + "items", + "channel", + "comp" ], "additionalProperties": false }, - "DiscountType": { - "type": "string", - "enum": [ - "PERCENT", - "FIXED" - ] + "SaleCancelRequest": { + "type": "object", + "properties": { + "acknowledge_open_payment": { + "type": "boolean" + } + }, + "additionalProperties": false }, - "Discount": { + "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" }, - "code": { + "reference": { "type": "string" }, - "type": { - "$ref": "#/components/schemas/DiscountType" - }, - "value": { - "type": "number" - }, - "eventId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "status": { + "type": "string", + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" ] }, - "active": { - "type": "boolean" - }, - "maxUses": { - "anyOf": [ - { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - { - "type": "null" - } - ] + "channel": { + "type": "string" }, - "uses": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "subtotal": { + "type": "number" }, - "startsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "discountAmount": { + "type": "number" }, - "endsAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "serviceFee": { + "type": "number" }, - "createdAt": { - "type": "string" - } - }, - "required": [ - "id", - "code", - "type", - "value", - "eventId", - "active", - "maxUses", - "uses", - "startsAt", - "endsAt", - "createdAt" - ], - "additionalProperties": false - }, - "DiscountCreate": { - "type": "object", - "properties": { - "code": { - "type": "string", - "minLength": 1 + "iva": { + "type": "number" }, - "type": { - "$ref": "#/components/schemas/DiscountType" + "total": { + "type": "number" }, - "value": { - "type": "number", - "exclusiveMinimum": 0 + "currency": { + "type": "string" }, - "eventId": { - "anyOf": [ - { - "type": "string", - "minLength": 1 - }, - { - "type": "null" - } - ] + "buyerName": { + "type": "string" }, - "maxUses": { - "anyOf": [ - { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 - }, - { - "type": "null" - } - ] + "buyerEmail": { + "type": "string" }, - "startsAt": { + "buyerPhone": { "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": "string" }, { "type": "null" } ] }, - "endsAt": { + "buyerDocumentType": { "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": "string" }, { "type": "null" } ] - } - }, - "required": [ - "code", - "type", - "value" - ], - "additionalProperties": false - }, - "DiscountUpdate": { - "type": "object", - "properties": { - "active": { - "type": "boolean" - }, - "value": { - "type": "number", - "exclusiveMinimum": 0 }, - "maxUses": { + "buyerDocumentNumber": { "anyOf": [ { - "type": "integer", - "exclusiveMinimum": 0, - "maximum": 9007199254740991 + "type": "string" }, { "type": "null" } ] }, - "startsAt": { + "organizationId": { "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": "string" }, { "type": "null" } ] }, - "endsAt": { + "paymentProvider": { "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": "string" }, { "type": "null" } ] - } - }, - "additionalProperties": false - }, - "Webhook": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "url": { - "type": "string" - }, - "events": { - "type": "array", - "items": { - "type": "string" - } - }, - "active": { - "type": "boolean" }, - "lastDeliveryAt": { + "paymentRef": { "anyOf": [ { "type": "string" @@ -15164,86 +15649,20 @@ } ] }, - "lastDeliveryStatus": { + "confirmedAt": { "anyOf": [ { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "type": "string" }, { "type": "null" } ] }, - "failureCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, "createdAt": { "type": "string" }, - "updatedAt": { - "type": "string" - } - }, - "required": [ - "id", - "url", - "events", - "active", - "lastDeliveryAt", - "lastDeliveryStatus", - "failureCount", - "createdAt", - "updatedAt" - ], - "additionalProperties": false - }, - "WebhookUpdate": { - "type": "object", - "properties": { - "url": { - "type": "string", - "format": "uri" - }, - "events": { - "minItems": 1, - "type": "array", - "items": { - "type": "string", - "enum": [ - "sale.confirmed", - "sale.refunded" - ] - } - }, - "active": { - "type": "boolean" - } - }, - "additionalProperties": false - }, - "WebhookCreated": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "url": { - "type": "string" - }, - "events": { - "type": "array", - "items": { - "type": "string" - } - }, - "active": { - "type": "boolean" - }, - "lastDeliveryAt": { + "failureReason": { "anyOf": [ { "type": "string" @@ -15253,212 +15672,231 @@ } ] }, - "lastDeliveryStatus": { + "paymentStatus": { "anyOf": [ { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 + "type": "string" }, { "type": "null" } - ] - }, - "failureCount": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "createdAt": { - "type": "string" + ], + "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." }, - "updatedAt": { - "type": "string" + "declineCode": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] }, - "signingSecret": { - "type": "string" + "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", - "url", - "events", - "active", - "lastDeliveryAt", - "lastDeliveryStatus", - "failureCount", + "reference", + "status", + "channel", + "subtotal", + "discountAmount", + "serviceFee", + "iva", + "total", + "currency", + "buyerName", + "buyerEmail", + "buyerPhone", + "buyerDocumentType", + "buyerDocumentNumber", + "organizationId", + "paymentProvider", + "paymentRef", + "confirmedAt", "createdAt", - "updatedAt", - "signingSecret" - ], - "additionalProperties": false - }, - "WebhookCreate": { - "type": "object", - "properties": { - "url": { - "type": "string", - "format": "uri" - }, - "events": { - "minItems": 1, - "type": "array", - "items": { - "type": "string", - "enum": [ - "sale.confirmed", - "sale.refunded" - ] - }, - "description": "Subset of: sale.confirmed, sale.refunded" - }, - "secret": { - "type": "string", - "minLength": 1 - } - }, - "required": [ - "url", - "events" + "failureReason", + "paymentStatus", + "declineCode" ], "additionalProperties": false }, - "Subscriber": { + "ReportByEventRow": { "type": "object", "properties": { - "id": { + "eventId": { "type": "string" }, - "customerName": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "customerEmail": { + "eventName": { "type": "string" }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] + "revenue": { + "type": "number" + }, + "ticketsSold": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "startedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "salesCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, - "currentPeriodEnd": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "available": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 } }, "required": [ - "id", - "customerName", - "customerEmail", - "status", - "startedAt", - "currentPeriodEnd" + "eventId", + "eventName", + "revenue", + "ticketsSold", + "salesCount", + "available" ], "additionalProperties": false }, - "SubscriptionCancelResult": { + "ReportTimeseriesRow": { "type": "object", "properties": { - "id": { + "bucket": { "type": "string" }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] + "revenue": { + "type": "number" }, - "cancelledAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "ticketsSold": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "salesCount": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 } }, "required": [ - "id", - "status", - "cancelledAt" + "bucket", + "revenue", + "ticketsSold", + "salesCount" ], "additionalProperties": false }, - "SaleTicket": { + "ReportFinancialsRow": { "type": "object", "properties": { - "id": { + "eventId": { "type": "string" }, - "ticketCode": { + "eventName": { "type": "string" }, - "ticketTypeId": { + "eventDateId": { "type": "string" }, - "ticketTypeName": { + "startsAt": { "type": "string" }, - "quantity": { + "past": { + "type": "boolean" + }, + "unitsSold": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, - "seatLabel": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] + "gross": { + "type": "number" }, - "checkedInAt": { + "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" + "type": "string", + "enum": [ + "SENT", + "AWAITING_PAYMENT", + "PAID" + ] }, { "type": "null" } ] }, - "refundedAt": { + "settlementId": { "anyOf": [ { "type": "string" @@ -15468,7 +15906,7 @@ } ] }, - "refundAmount": { + "settlementAmount": { "anyOf": [ { "type": "number" @@ -15477,119 +15915,88 @@ "type": "null" } ] - }, - "seatBlocked": { - "type": "boolean" } }, "required": [ - "id", - "ticketCode", - "ticketTypeId", - "ticketTypeName", - "quantity", - "seatLabel", - "checkedInAt", - "refundedAt", - "refundAmount", - "seatBlocked" + "eventId", + "eventName", + "eventDateId", + "startsAt", + "past", + "unitsSold", + "gross", + "platformFee", + "facial", + "paymentFee", + "wompiSalesWithoutRate", + "gmf", + "net", + "currency", + "settlementStatus", + "settlementId", + "settlementAmount" ], "additionalProperties": false }, - "PaymentAttempt": { + "Settlement": { "type": "object", "properties": { "id": { "type": "string" }, - "provider": { + "reference": { + "type": "string" + }, + "label": { "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": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } + "enum": [ + "SENT", + "AWAITING_PAYMENT", + "PAID" ] }, - "declineReason": { + "amount": { + "type": "number" + }, + "grossAmount": { "anyOf": [ { - "type": "string" + "type": "number" }, { "type": "null" } ] }, - "amount": { + "unitsSold": { "anyOf": [ { - "type": "number" + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 }, { "type": "null" } ] }, - "externalRef": { + "currency": { + "type": "string" + }, + "notes": { "anyOf": [ { "type": "string" }, { - "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 - }, - "CheckinResult": { - "type": "object", - "properties": { - "ticketCode": { - "type": "string" + "type": "null" + } + ] }, - "checkedInAt": { + "rejectionReason": { "anyOf": [ { "type": "string" @@ -15599,93 +16006,112 @@ } ] }, - "checkedInBy": { + "event": { "anyOf": [ { - "type": "string" + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "id", + "name" + ], + "additionalProperties": false }, { "type": "null" } ] }, - "alreadyCheckedIn": { - "type": "boolean" - } - }, - "required": [ - "ticketCode", - "checkedInAt", - "checkedInBy", - "alreadyCheckedIn" - ], - "additionalProperties": false - }, - "CheckinRequest": { - "type": "object", - "properties": { - "source": { + "eventDate": { "anyOf": [ { - "type": "string", - "enum": [ - "pdf", - "web", - "apple", - "google" - ] + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "startsAt": { + "type": "string" + } + }, + "required": [ + "id", + "startsAt" + ], + "additionalProperties": false }, { "type": "null" } ] - } - }, - "additionalProperties": false - }, - "TicketAccess": { - "type": "object", - "properties": { - "ticketCode": { - "type": "string" }, - "valid": { + "hasDocument": { "type": "boolean" }, - "status": { - "type": "string", - "enum": [ - "VALID", - "USED", - "INVALID" - ] - }, - "saleStatus": { - "type": "string", - "enum": [ - "PENDING", - "CONFIRMED", - "ABANDONED", - "CANCELLED", - "REFUNDED" - ] - }, - "eventId": { - "type": "string" - }, - "eventName": { - "type": "string" - }, - "eventDateId": { - "type": "string" + "paymentProofs": { + "type": "array", + "items": { + "type": "object", + "properties": { + "fileName": { + "type": "string" + } + }, + "required": [ + "fileName" + ], + "additionalProperties": false + } }, - "startsAt": { - "type": "string" + "allocations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "bankAccountId": { + "type": "string" + }, + "percentage": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "amount": { + "type": "number" + }, + "mode": { + "type": "string", + "enum": [ + "PERCENT", + "AMOUNT" + ] + } + }, + "required": [ + "bankAccountId", + "percentage" + ], + "additionalProperties": false + } }, - "ticketTypeName": { - "type": "string" + "requestedAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] }, - "checkedInAt": { + "paidAt": { "anyOf": [ { "type": "string" @@ -15694,74 +16120,99 @@ "type": "null" } ] + }, + "createdAt": { + "type": "string" } }, "required": [ - "ticketCode", - "valid", + "id", + "reference", + "label", "status", - "saleStatus", - "eventId", - "eventName", - "eventDateId", - "startsAt", - "ticketTypeName", - "checkedInAt" + "amount", + "grossAmount", + "unitsSold", + "currency", + "notes", + "rejectionReason", + "event", + "eventDate", + "hasDocument", + "paymentProofs", + "allocations", + "requestedAt", + "paidAt", + "createdAt" ], "additionalProperties": false }, - "ApiKeyScope": { + "DiscountType": { "type": "string", "enum": [ - "read", - "write" + "PERCENT", + "FIXED" ] }, - "ApiKey": { + "Discount": { "type": "object", "properties": { "id": { "type": "string" }, - "name": { + "code": { "type": "string" }, - "scope": { - "$ref": "#/components/schemas/ApiKeyScope" + "type": { + "$ref": "#/components/schemas/DiscountType" }, - "keyPrefix": { - "type": "string" + "value": { + "type": "number" }, - "lastUsedAt": { + "eventId": { "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": "string" }, { "type": "null" } ] }, - "expiresAt": { + "active": { + "type": "boolean" + }, + "maxUses": { "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" } ] }, - "revokedAt": { + "uses": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "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": "string" + }, + { + "type": "null" + } + ] + }, + "endsAt": { + "anyOf": [ + { + "type": "string" }, { "type": "null" @@ -15769,51 +16220,62 @@ ] }, "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))$" + "type": "string" } }, "required": [ "id", - "name", - "scope", - "keyPrefix", - "lastUsedAt", - "expiresAt", - "revokedAt", + "code", + "type", + "value", + "eventId", + "active", + "maxUses", + "uses", + "startsAt", + "endsAt", "createdAt" ], "additionalProperties": false }, - "ApiKeyCreated": { + "DiscountCreate": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" + "code": { + "type": "string", + "minLength": 1 }, - "scope": { - "$ref": "#/components/schemas/ApiKeyScope" + "type": { + "$ref": "#/components/schemas/DiscountType" }, - "keyPrefix": { - "type": "string" + "value": { + "type": "number", + "exclusiveMinimum": 0 }, - "lastUsedAt": { + "eventId": { "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 }, { "type": "null" } ] }, - "expiresAt": { + "maxUses": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 + }, + { + "type": "null" + } + ] + }, + "startsAt": { "anyOf": [ { "type": "string", @@ -15825,7 +16287,7 @@ } ] }, - "revokedAt": { + "endsAt": { "anyOf": [ { "type": "string", @@ -15836,465 +16298,313 @@ "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 - }, - "scope": { - "default": "read", - "$ref": "#/components/schemas/ApiKeyScope" - }, - "expiresAt": { - "type": "string", - "format": "date-time", - "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" - } - }, - "required": [ - "name", - "scope" - ], - "additionalProperties": false - }, - "CustomerAuthRequest": { - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" - } - }, - "required": [ - "email" - ], - "additionalProperties": false - }, - "CustomerAuthRequestResult": { - "type": "object", - "properties": { - "status": { - "type": "string", - "const": "sent" - }, - "sent_to": { - "type": "string", - "description": "Masked email (`c***@mail.com`). Never the full address." - }, - "expires_in": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Code lifetime, in seconds." - } - }, - "required": [ - "status", - "sent_to", - "expires_in" - ], - "additionalProperties": false - }, - "CustomerAuthVerify": { - "type": "object", - "properties": { - "email": { - "type": "string", - "format": "email", - "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" - }, - "code": { - "type": "string", - "minLength": 6, - "maxLength": 6 - } - }, - "required": [ - "email", - "code" - ], - "additionalProperties": false - }, - "CustomerAuthVerifyResult": { - "type": "object", - "properties": { - "session_token": { - "type": "string", - "description": "Usable as-is as the `X-Customer-Session` header on /api/v1/customer/*." - }, - "expires_in": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991, - "description": "Session lifetime, in seconds." } }, "required": [ - "session_token", - "expires_in" + "code", + "type", + "value" ], "additionalProperties": false }, - "CustomerMe": { + "DiscountUpdate": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "email": { - "type": "string" - }, - "name": { - "type": "string" - }, - "emailVerified": { + "active": { "type": "boolean" }, - "expiresAt": { - "type": "string", - "description": "Buyer session expiry (ISO 8601)." - } - }, - "required": [ - "id", - "email", - "name", - "emailVerified", - "expiresAt" - ], - "additionalProperties": false - }, - "CustomerTicketItem": { - "type": "object", - "properties": { - "ticketTypeName": { - "type": "string" - }, - "quantity": { - "type": "integer", - "minimum": -9007199254740991, - "maximum": 9007199254740991 - }, - "ticketCode": { - "type": "string", - "description": "Opaque ticket code. The QR code must encode the validator URL (`https://admin.appfreeticket.com/dashboard/tickets/validar?code=`)." + "value": { + "type": "number", + "exclusiveMinimum": 0 }, - "seatLabel": { + "maxUses": { "anyOf": [ { - "type": "string" + "type": "integer", + "exclusiveMinimum": 0, + "maximum": 9007199254740991 }, { "type": "null" } - ], - "description": "Exact seat for seated events (seats.io), or null." - } - }, - "required": [ - "ticketTypeName", - "quantity", - "ticketCode", - "seatLabel" - ], - "additionalProperties": false - }, - "CustomerSale": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "reference": { - "type": "string" - }, - "status": { - "type": "string" + ] }, - "event": { - "type": "object", - "properties": { - "name": { - "type": "string" + "startsAt": { + "anyOf": [ + { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, - "slug": { - "type": "string" + { + "type": "null" } - }, - "required": [ - "name", - "slug" - ], - "additionalProperties": false + ] }, - "eventDate": { - "type": "object", - "properties": { - "startsAt": { + "endsAt": { + "anyOf": [ + { "type": "string", - "description": "Event start instant in ISO 8601 UTC." + "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))$" }, - "timezone": { - "type": "string", - "description": "IANA time zone of the event." + { + "type": "null" } - }, - "required": [ - "startsAt", - "timezone" - ], - "additionalProperties": false - }, - "items": { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerTicketItem" - } - }, - "total": { - "type": "number" - }, - "currency": { - "type": "string" + ] } }, - "required": [ - "id", - "reference", - "status", - "event", - "eventDate", - "items", - "total", - "currency" - ], "additionalProperties": false }, - "CustomerTicketCancelResult": { + "Webhook": { "type": "object", "properties": { "id": { "type": "string" }, - "reference": { + "url": { "type": "string" }, - "status": { + "events": { + "type": "array", + "items": { + "type": "string" + } + }, + "active": { + "type": "boolean" + }, + "lastDeliveryAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "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": [ "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" + "url", + "events", + "active", + "lastDeliveryAt", + "lastDeliveryStatus", + "failureCount", + "createdAt", + "updatedAt" ], "additionalProperties": false }, - "EnterpriseExchangeResponse": { + "WebhookUpdate": { "type": "object", "properties": { - "session_token": { + "url": { "type": "string", - "description": "Buyer session token. Send it as the `X-Customer-Session` header on /api/v1/customer/*." + "format": "uri" }, - "expires_at": { - "type": "string", - "description": "Session expiry (ISO 8601, 7-day sliding window)." + "events": { + "minItems": 1, + "type": "array", + "items": { + "type": "string", + "enum": [ + "sale.confirmed", + "sale.refunded" + ] + } }, - "customer": { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "email": { - "type": "string" - }, - "name": { - "type": "string" - }, - "email_verified": { - "type": "boolean" - } - }, - "required": [ - "id", - "email", - "name", - "email_verified" - ], - "additionalProperties": false + "active": { + "type": "boolean" } }, - "required": [ - "session_token", - "expires_at", - "customer" - ], "additionalProperties": false }, - "CustomerMembershipState": { + "WebhookCreated": { "type": "object", "properties": { + "id": { + "type": "string" + }, + "url": { + "type": "string" + }, + "events": { + "type": "array", + "items": { + "type": "string" + } + }, "active": { - "type": "boolean", - "description": "true only with an ACTIVE, unexpired membership in this workspace." + "type": "boolean" }, - "membership": { + "lastDeliveryAt": { "anyOf": [ { - "type": "object", - "properties": { - "id": { - "type": "string" - }, - "status": { - "type": "string", - "enum": [ - "PENDING", - "ACTIVE", - "EXPIRED", - "CANCELLED", - "PAUSED" - ] - }, - "plan": { - "$ref": "#/components/schemas/MembershipPlan" - }, - "startedAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ] - }, - "expiresAt": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "null = LIFETIME or a membership with no expiry." - }, - "autoRenew": { - "type": "boolean" - } - }, - "required": [ - "id", - "status", - "plan", - "startedAt", - "expiresAt", - "autoRenew" - ], - "additionalProperties": false + "type": "string" + }, + { + "type": "null" + } + ] + }, + "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": [ + "id", + "url", + "events", "active", - "membership" + "lastDeliveryAt", + "lastDeliveryStatus", + "failureCount", + "createdAt", + "updatedAt", + "signingSecret" ], "additionalProperties": false }, - "CustomerSubscribeRequest": { + "WebhookCreate": { "type": "object", "properties": { - "planId": { + "url": { "type": "string", - "minLength": 1, - "description": "Id of an active MembershipPlan in the key's workspace." + "format": "uri" + }, + "events": { + "minItems": 1, + "type": "array", + "items": { + "type": "string", + "enum": [ + "sale.confirmed", + "sale.refunded" + ] + }, + "description": "Subset of: sale.confirmed, sale.refunded" + }, + "secret": { + "type": "string", + "minLength": 1 } }, "required": [ - "planId" + "url", + "events" ], "additionalProperties": false }, - "CustomerSubscribeResult": { + "Subscriber": { "type": "object", "properties": { - "checkoutUrl": { - "type": "string", - "description": "Membership checkout URL on the canonical host. The landing page must redirect the buyer there." + "id": { + "type": "string" }, - "planId": { + "customerName": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "customerEmail": { "type": "string" + }, + "status": { + "type": "string", + "enum": [ + "PENDING", + "ACTIVE", + "EXPIRED", + "CANCELLED", + "PAUSED" + ] + }, + "startedAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "currentPeriodEnd": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] } }, "required": [ - "checkoutUrl", - "planId" + "id", + "customerName", + "customerEmail", + "status", + "startedAt", + "currentPeriodEnd" ], "additionalProperties": false }, - "CustomerSubscriptionCancelResult": { + "SubscriptionCancelResult": { "type": "object", "properties": { "id": { @@ -16324,34 +16634,212 @@ "required": [ "id", "status", - "cancelledAt" + "cancelledAt" + ], + "additionalProperties": false + }, + "SaleTicket": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "ticketCode": { + "type": "string" + }, + "ticketTypeId": { + "type": "string" + }, + "ticketTypeName": { + "type": "string" + }, + "quantity": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991 + }, + "seatLabel": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "checkedInAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "refundedAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "refundAmount": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ] + }, + "seatBlocked": { + "type": "boolean" + } + }, + "required": [ + "id", + "ticketCode", + "ticketTypeId", + "ticketTypeName", + "quantity", + "seatLabel", + "checkedInAt", + "refundedAt", + "refundAmount", + "seatBlocked" + ], + "additionalProperties": false + }, + "PaymentAttempt": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "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": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "declineReason": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "amount": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ] + }, + "externalRef": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "createdAt": { + "type": "string" + } + }, + "required": [ + "id", + "provider", + "status", + "declineCode", + "declineReason", + "amount", + "externalRef", + "createdAt" ], "additionalProperties": false }, - "CustomerSubscriptionCancelRequest": { + "TicketReassign": { "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.", + "eventDateId": { + "type": "string", + "minLength": 1 + }, + "ticketTypeId": { + "type": "string", + "minLength": 1 + }, + "seatLabel": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, - "CustomerProfile": { + "ResendTicket": { "type": "object", "properties": { - "id": { + "ticketCode": { "type": "string" }, - "email": { + "sentTo": { "type": "string" }, - "name": { + "sentAt": { + "type": "string" + } + }, + "required": [ + "ticketCode", + "sentTo", + "sentAt" + ], + "additionalProperties": false + }, + "CheckinResult": { + "type": "object", + "properties": { + "ticketCode": { "type": "string" }, - "phone": { + "checkedInAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "checkedInBy": { "anyOf": [ { "type": "string" @@ -16360,30 +16848,32 @@ "type": "null" } ] + }, + "alreadyCheckedIn": { + "type": "boolean" } }, "required": [ - "id", - "email", - "name", - "phone" + "ticketCode", + "checkedInAt", + "checkedInBy", + "alreadyCheckedIn" ], "additionalProperties": false }, - "CustomerProfileUpdate": { + "CheckinRequest": { "type": "object", "properties": { - "name": { - "type": "string", - "minLength": 1, - "maxLength": 120 - }, - "phone": { - "description": "null or an empty string clears the phone.", + "source": { "anyOf": [ { "type": "string", - "maxLength": 30 + "enum": [ + "pdf", + "web", + "apple", + "google" + ] }, { "type": "null" @@ -16393,80 +16883,49 @@ }, "additionalProperties": false }, - "PurchaseSessionCreateRequest": { + "TicketAccess": { "type": "object", "properties": { - "eventDateId": { + "ticketCode": { + "type": "string" + }, + "valid": { + "type": "boolean" + }, + "status": { "type": "string", - "minLength": 1, - "maxLength": 64 + "enum": [ + "VALID", + "USED", + "INVALID" + ] }, - "deviceKey": { + "saleStatus": { "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" + "enum": [ + "PENDING", + "CONFIRMED", + "ABANDONED", + "CANCELLED", + "REFUNDED" + ] }, - "eventDateId": { + "eventId": { "type": "string" }, - "state": { - "type": "string", - "const": "live" - }, - "seated": { - "type": "boolean", - "description": "true = the event date has a seats.io map." + "eventName": { + "type": "string" }, - "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." + "eventDateId": { + "type": "string" }, - "seatsDeadline": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Instant (ISO 8601 UTC) until which the order with seats can be created. This is the clock to display over the map. The seats.io hold expires AFTER this instant, never before. null for event dates without a map." + "startsAt": { + "type": "string" }, - "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." + "ticketTypeName": { + "type": "string" }, - "replacedSessionId": { + "checkedInAt": { "anyOf": [ { "type": "string" @@ -16474,480 +16933,600 @@ { "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." + ] } }, "required": [ - "id", + "ticketCode", + "valid", + "status", + "saleStatus", + "eventId", + "eventName", "eventDateId", - "state", - "seated", - "holdToken", - "seatsDeadline", - "budgetSeconds", - "replacedSessionId" + "startsAt", + "ticketTypeName", + "checkedInAt" ], "additionalProperties": false }, - "PurchaseSessionStatus": { + "ApiKeyScope": { + "type": "string", + "enum": [ + "read", + "write" + ] + }, + "ApiKey": { "type": "object", "properties": { "id": { "type": "string" }, - "state": { - "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`)." + "name": { + "type": "string" }, - "seatsDeadline": { + "scope": { + "$ref": "#/components/schemas/ApiKeyScope" + }, + "keyPrefix": { + "type": "string" + }, + "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" } ] }, - "orderId": { + "expiresAt": { "anyOf": [ { - "type": "string" + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } - ], - "description": "Sale created with this session, if any." + ] + }, + "revokedAt": { + "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" + } + ] + }, + "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", - "state", - "seatsDeadline", - "orderId" + "id", + "name", + "scope", + "keyPrefix", + "lastUsedAt", + "expiresAt", + "revokedAt", + "createdAt" ], "additionalProperties": false }, - "CustomerOrderCreateResult": { + "ApiKeyCreated": { "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": { - "type": "string", - "description": "Sale reference (FT-…). Always identifies the purchase." + "name": { + "type": "string" }, - "saleId": { - "anyOf": [ - { - "type": "string" - }, - { - "type": "null" - } - ], - "description": "Sale id. null when `free` is true." + "scope": { + "$ref": "#/components/schemas/ApiKeyScope" }, - "total": { + "keyPrefix": { + "type": "string" + }, + "lastUsedAt": { "anyOf": [ { - "type": "number" + "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": "Amount to charge. null when `free` is true." + ] }, - "currency": { + "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" } ] }, - "expiresAt": { + "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" } - ], - "description": "Instant (ISO 8601 UTC) at which the inventory reservation expires. After that, the purchase must be started over." + ] + }, + "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": [ - "free", - "reference", - "saleId", - "total", - "currency", - "expiresAt" + "id", + "name", + "scope", + "keyPrefix", + "lastUsedAt", + "expiresAt", + "revokedAt", + "createdAt", + "key" ], "additionalProperties": false }, - "CustomerOrderCurrent": { + "ApiKeyCreate": { "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 - } - } - }, - "required": [ - "saleId", - "reference", - "total", - "currency", - "expiresAt", - "paymentOpened", - "items" - ], - "additionalProperties": false - }, - { - "type": "null" - } - ], - "description": "The purchase the buyer left unfinished for this event date, or null if there is none." + "name": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "scope": { + "default": "read", + "$ref": "#/components/schemas/ApiKeyScope" + }, + "expiresAt": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ - "order" + "name", + "scope" ], "additionalProperties": false }, - "CustomerOrderRelease": { + "CustomerAuthRequest": { "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`." + "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": [ - "released" + "email" ], "additionalProperties": false }, - "CustomerOrderPayment": { + "CustomerAuthRequestResult": { "type": "object", "properties": { - "orderId": { + "status": { "type": "string", - "description": "Merchant reference = `reference`." + "const": "sent" }, - "amount": { + "sent_to": { + "type": "string", + "description": "Masked email (`c***@mail.com`). Never the full address." + }, + "expires_in": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, - "description": "Whole pesos, no decimals." + "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-z]{2,}$" }, - "currency": { + "code": { + "type": "string", + "minLength": 6, + "maxLength": 6 + } + }, + "required": [ + "email", + "code" + ], + "additionalProperties": false + }, + "CustomerAuthVerifyResult": { + "type": "object", + "properties": { + "session_token": { + "type": "string", + "description": "Usable as-is as the `X-Customer-Session` header on /api/v1/customer/*." + }, + "expires_in": { + "type": "integer", + "minimum": -9007199254740991, + "maximum": 9007199254740991, + "description": "Session lifetime, in seconds." + } + }, + "required": [ + "session_token", + "expires_in" + ], + "additionalProperties": false + }, + "CustomerMe": { + "type": "object", + "properties": { + "id": { "type": "string" }, - "apiKey": { - "type": "string", - "description": "Bold IDENTITY key (public, sent to the browser)." - }, - "integritySignature": { - "type": "string", - "description": "SHA256 that binds the charge to the amount. Computed on the server." - }, - "renderMode": { - "type": "string", - "const": "embedded" - }, - "redirectionUrl": { + "email": { "type": "string" }, - "description": { + "name": { "type": "string" }, - "expirationDate": { - "type": "number", - "description": "Epoch in NANOSECONDS (what the Bold library expects)." + "emailVerified": { + "type": "boolean" + }, + "expiresAt": { + "type": "string", + "description": "Buyer session expiry (ISO 8601)." } }, "required": [ - "orderId", - "amount", - "currency", - "apiKey", - "integritySignature", - "renderMode", - "redirectionUrl", - "description", - "expirationDate" + "id", + "email", + "name", + "emailVerified", + "expiresAt" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoConfig": { + "CustomerTicketCancelResult": { "type": "object", "properties": { - "publicKey": { - "type": "string", - "description": "MercadoPago (Tickets) public key. Sent to the browser: it is what `initMercadoPago()`/`` from the `@mercadopago/sdk-react` SDK (or equivalent) receives to mount the Payment Brick. Present ONLY on the MercadoPago rail — it is the marker the landing page uses to tell it apart from the Bold rail (which carries `apiKey`+`renderMode` and NEVER `publicKey`)." - }, - "amount": { - "type": "number", - "description": "Amount to charge, in the currency's major unit (pesos, not cents) — the same `total` already returned by `POST /customer/orders`. It is re-read from the sale on every call: do not treat it as final if a long time passes between mounting the Brick and charging." - }, - "currency": { + "id": { "type": "string" }, "reference": { - "type": "string", - "description": "Sale reference (FT-…)." + "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." + "status": { + "type": "string" } }, "required": [ - "publicKey", - "amount", - "currency", + "id", "reference", - "payerEmail" + "status" ], "additionalProperties": false }, - "CustomerOrderStartPayment": { - "anyOf": [ - { - "$ref": "#/components/schemas/CustomerOrderPayment" - }, - { - "$ref": "#/components/schemas/CustomerOrderMercadoPagoConfig" + "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 }, - "CustomerOrderMercadoPagoChargeRequest": { + "EnterpriseExchangeRequest": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, - "description": "Card token returned by the Payment Brick when tokenizing." - }, - "paymentMethodId": { + "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", - "minLength": 1, - "description": "`payment_method_id` returned by the Brick (e.g. `visa`, `debmaster`)." - }, - "installments": { - "default": 1, - "type": "integer", - "minimum": 1, - "maximum": 9007199254740991 + "description": "Buyer session token. Send it as the `X-Customer-Session` header on /api/v1/customer/*." }, - "issuerId": { - "description": "`issuer_id` returned by the Brick. Some BINs require it.", - "type": "string" + "expires_at": { + "type": "string", + "description": "Session expiry (ISO 8601, 7-day sliding window)." }, - "payer": { + "customer": { "type": "object", "properties": { + "id": { + "type": "string" + }, "email": { - "description": "Ignored: the charge ALWAYS uses the sale's email, never one sent by the client.", "type": "string" }, - "identification": { + "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." + }, + "membership": { + "anyOf": [ + { "type": "object", "properties": { - "type": { + "id": { "type": "string" }, - "number": { - "type": "string" + "status": { + "type": "string", + "enum": [ + "PENDING", + "ACTIVE", + "EXPIRED", + "CANCELLED", + "PAUSED" + ] + }, + "plan": { + "$ref": "#/components/schemas/MembershipPlan" + }, + "startedAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "expiresAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "null = LIFETIME or a membership with no expiry." + }, + "autoRenew": { + "type": "boolean" } }, "required": [ - "type", - "number" + "id", + "status", + "plan", + "startedAt", + "expiresAt", + "autoRenew" ], "additionalProperties": false + }, + { + "type": "null" } - }, - "additionalProperties": false + ] } }, "required": [ - "token", - "paymentMethodId", - "installments" + "active", + "membership" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoChargeResult": { + "CustomerSubscribeRequest": { "type": "object", "properties": { - "status": { + "planId": { "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." + "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." }, - "reference": { + "planId": { + "type": "string" + } + }, + "required": [ + "checkoutUrl", + "planId" + ], + "additionalProperties": false + }, + "CustomerSubscriptionCancelResult": { + "type": "object", + "properties": { + "id": { "type": "string" }, - "message": { - "description": "Human-readable message for the buyer. Only present with `rejected`.", - "type": "string" + "status": { + "type": "string", + "enum": [ + "PENDING", + "ACTIVE", + "EXPIRED", + "CANCELLED", + "PAUSED" + ] }, - "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" + "cancelledAt": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] } }, "required": [ + "id", "status", - "reference" + "cancelledAt" ], "additionalProperties": false }, - "CustomerOrderMercadoPagoPse": { + "CustomerSubscriptionCancelRequest": { "type": "object", "properties": { - "redirectUrl": { + "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", - "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." + "minLength": 1 } }, - "required": [ - "redirectUrl" - ], "additionalProperties": false }, - "CustomerOrderStatus": { + "CustomerProfile": { "type": "object", "properties": { - "reference": { + "id": { "type": "string" }, - "status": { - "type": "string", - "enum": [ - "approved", - "pending", - "rejected" - ], - "description": "`pending` is a NORMAL state: Bold may take a while to reflect the payment (PSE, Nequi and the Bancolombia button approve asynchronously) and the webhook settles it. The landing page must retry, not treat the purchase as lost." - }, - "saleStatus": { - "type": "string", - "description": "Internal sale status (PENDING, CONFIRMED, …)." - }, - "total": { - "type": "number" + "email": { + "type": "string" }, - "currency": { + "name": { "type": "string" }, - "tickets": { + "phone": { "anyOf": [ { - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerTicketItem" - } + "type": "string" }, { "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" + "id", + "email", + "name", + "phone" ], "additionalProperties": false }, + "CustomerProfileUpdate": { + "type": "object", + "properties": { + "name": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "phone": { + "description": "null or an empty string clears the phone.", + "anyOf": [ + { + "type": "string", + "maxLength": 30 + }, + { + "type": "null" + } + ] + } + }, + "additionalProperties": false + }, "ContentVideo": { "type": "object", "properties": { @@ -17448,136 +18027,128 @@ ], "additionalProperties": false }, - "ResendTicket": { + "WaitlistEntryCreate": { "type": "object", "properties": { - "ticketCode": { - "type": "string" + "city": { + "type": "string", + "minLength": 1, + "maxLength": 60 }, - "sentTo": { - "type": "string" + "name": { + "type": "string", + "minLength": 1, + "maxLength": 80 }, - "sentAt": { - "type": "string" + "contact": { + "type": "string", + "minLength": 1, + "maxLength": 120 + }, + "source": { + "type": "string", + "maxLength": 40 } }, "required": [ - "ticketCode", - "sentTo", - "sentAt" + "city", + "name", + "contact" ], "additionalProperties": false }, - "CustomerOrderItem": { + "WaitlistEntryResult": { "type": "object", "properties": { - "ticketTypeId": { - "type": "string", - "minLength": 1 + "id": { + "type": "string" }, - "quantity": { - "type": "integer", - "minimum": 1, - "maximum": 30 + "city": { + "type": "string" }, - "seats": { - "description": "seats.io labels. Only for seated events.", - "maxItems": 30, - "type": "array", - "items": { - "type": "string", - "minLength": 1, - "maxLength": 120 - } + "created": { + "type": "boolean" } }, "required": [ - "ticketTypeId", - "quantity" + "id", + "city", + "created" ], "additionalProperties": false }, - "CustomerOrderCreateRequest": { + "WaitlistEntry": { "type": "object", "properties": { - "eventDateId": { - "type": "string", - "minLength": 1 + "id": { + "type": "string" }, - "items": { - "minItems": 1, - "maxItems": 1, - "type": "array", - "items": { - "$ref": "#/components/schemas/CustomerOrderItem" - } + "city": { + "type": "string" }, - "holdToken": { - "description": "Hold token of the seats.io map session. Required if seats are sent.", - "type": "string", - "maxLength": 120 + "name": { + "type": "string" }, - "discountCode": { - "type": "string", - "maxLength": 40 + "contact": { + "type": "string" }, - "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" - ] + "customerId": { + "anyOf": [ + { + "type": "string" }, - "idNumber": { - "type": "string", - "minLength": 5, - "maxLength": 20 + { + "type": "null" + } + ] + }, + "source": { + "anyOf": [ + { + "type": "string" }, - "nitDigit": { - "description": "Check digit. Required if idType is NIT.", - "type": "string", - "maxLength": 1 + { + "type": "null" } - }, - "required": [ - "name", - "phone", - "idType", - "idNumber" - ], - "additionalProperties": false + ] }, - "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." + "createdAt": { + "type": "string" } }, "required": [ - "eventDateId", - "items", - "buyer", - "returnUrl" + "id", + "city", + "name", + "contact", + "customerId", + "source", + "createdAt" ], "additionalProperties": false } }, + "headers": { + "RateLimitPolicy": { + "description": "Quota policies applied to this request (draft-ietf-httpapi-ratelimit-headers), one list member per limiter: `\"\";q=;w=`. Example: `\"public-orders\";q=8;w=300`.", + "schema": { + "type": "string" + } + }, + "RateLimit": { + "description": "Remaining quota per policy (draft-ietf-httpapi-ratelimit-headers): `\"\";r=;t=`. Example: `\"public-orders\";r=7;t=280`.", + "schema": { + "type": "string" + } + }, + "RetryAfter": { + "description": "Seconds to wait before retrying (RFC 9110 §10.2.3). Always sent with a 429.", + "schema": { + "type": "integer", + "minimum": 1 + } + } + }, "securitySchemes": { "apiKey": { "type": "apiKey", diff --git a/src/program.test.ts b/src/program.test.ts index 74174ca..195d221 100644 --- a/src/program.test.ts +++ b/src/program.test.ts @@ -46,3 +46,12 @@ test("contract 1.19 / admin 1.5 commands are wired, destructive ones behind --ye // `plan ` (assign) must survive next to the new read. expect(longs("admin workspaces plan")).toContain("--data"); }); + +test("contract 1.24: waitlist list/create are wired, list filters by --city", () => { + const tree = new Map(walk(program)); + expect(tree.has("waitlist list")).toBe(true); + expect(tree.has("waitlist create")).toBe(true); + const longs = tree.get("waitlist list")?.options.map((o) => o.long) ?? []; + expect(longs).toContain("--city"); + expect(longs).toContain("--account"); +}); diff --git a/src/program.ts b/src/program.ts index 677a9e6..93cd02d 100644 --- a/src/program.ts +++ b/src/program.ts @@ -33,6 +33,7 @@ import { getTicketTypesId, getVenues, getVenuesId, + getWaitlist, getWebhooks, patchDiscountsId, patchEventsId, @@ -57,6 +58,7 @@ import { postSubscriptionsIdCancel, postTicketTypes, postVenues, + postWaitlist, postWebhooks, } from "./client/sdk.gen"; import { registerAccount } from "./commands/account"; @@ -409,6 +411,23 @@ registerResource(program, { }, }); +// Per-city waitlist of an enterprise landing (contract 1.24). `list` is the +// staff export (ADMIN, personal data); `create` needs an enterprise service key. +registerResource(program, { + name: "waitlist", + describe: "Per-city waitlist entries of an enterprise landing", + list: getWaitlist, + create: postWaitlist, + columns: ["id", "city", "name", "contact", "source", "createdAt"], + listFlags: [ + { + flag: "--city ", + describe: "filter by city (accents/case ignored)", + query: "city", + }, + ], +}); + registerTickets(program); registerReports(program); registerApiKeys(program);