{ "openapi": "3.1.0", "info": { "title": "xforge API", "version": "1.0.0", "description": "Tenant API. Every response is an envelope: `{ success: true, data, meta? }` or `{ success: false, error: { code, message, details? } }`. Lists are cursor-paginated: pass `meta.nextCursor` back as `cursor`." }, "paths": { "/api/v1/auth/api-keys": { "get": { "operationId": "listMyApiKeys", "summary": "List the caller's API keys", "description": "Newest first, including revoked and expired ones. The raw key is never returned again — only `prefix`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List the caller's API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "allowedIps": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "store": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "prefix", "scopes", "allowedIps", "store", "expiresAt", "lastUsedAt", "revokedAt", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createMyApiKey", "summary": "Create an API key", "description": "A long-lived credential for integrations: send it as `Authorization: Bearer ` (no `x-store` needed). It acts as the caller at ONE store (`store`, default the request's store) and has the caller's CURRENT permissions limited to `scopes` (permission codes, `.*` or `*`) — record rules still apply. `allowedIps` (IPs / CIDRs, IPv4 or IPv6, or `private`; at most 50) limits where the key may be used from: other addresses get 403 `api_key_ip_denied`; omitted / null / empty = any address (409 `api_key_ips_unsupported` until the database is upgraded). Re-authenticate like other step-ups (`password` + a second factor when MFA is on). A concrete scope must be a permission you have (403 `privilege_escalation`). Expires at `expiresAt` (default 90 days, at most 365); at most 20 active keys per user (409 `api_key_limit`). API keys cannot call `/api/v1/auth/*` except `GET /api/v1/auth/me`. Superusers cannot create keys (403 `api_key_superuser`). The raw `token` is returned only here.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Create an API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "allowedIps": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "store": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "prefix", "scopes", "allowedIps", "store", "expiresAt", "lastUsedAt", "revokedAt", "createdAt" ] }, "token": { "type": "string" } }, "required": [ "key", "token" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.api_keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "items": { "type": "string", "maxLength": 100 }, "minItems": 1, "maxItems": 100 }, "store": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" }, "expiresAt": { "type": "string", "format": "date-time" }, "allowedIps": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 }, { "type": "null" } ] } }, "required": [ "password", "name", "scopes" ] } } } } } }, "/api/v1/auth/api-keys/{id}": { "patch": { "operationId": "updateMyApiKey", "summary": "Change one of the caller's API keys", "description": "Sets `allowedIps` (IPs / CIDRs, IPv4 or IPv6, or `private`; at most 50; null or empty = any address) — omitted leaves it unchanged. Re-authenticate like other step-ups (widening the list loosens a credential). Takes effect on every server within about a second. 404 `api_key_not_found` (not yours or revoked); 409 `api_key_ips_unsupported` until the database is upgraded.", "tags": [ "auth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Change one of the caller's API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "allowedIps": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "store": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "prefix", "scopes", "allowedIps", "store", "expiresAt", "lastUsedAt", "revokedAt", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.api_keys" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] }, "allowedIps": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 }, { "type": "null" } ] } }, "required": [ "password" ] } } } } }, "delete": { "operationId": "revokeMyApiKey", "summary": "Revoke one of the caller's API keys", "description": "Takes effect on every server within about a second. 404 `api_key_not_found` (not yours or already revoked).", "tags": [ "auth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Revoke one of the caller's API keys", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/configs": { "get": { "operationId": "getPublicConfigs", "summary": "Public settings", "description": "Effective values of the settings marked public (sign-in options, customer account options) for the store of the request (`x-store` or the domain). Never contains secrets.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/api/v1/auth/email/confirm": { "post": { "operationId": "confirmEmail", "summary": "Confirm an email address with a verification token", "description": "Consumes the token from the verification email and marks the user's email as verified. The token only works while the user's email is still the address it was sent to. An invalid, used or expired token answers 401 `verify_token_invalid`; failures are throttled per IP.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Confirm an email address with a verification token", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" } }, "required": [ "token" ] } } } } } }, "/api/v1/auth/email/verify": { "post": { "operationId": "requestEmailVerification", "summary": "Send a verification link to the caller's email", "description": "Emails a one-time verification link valid for 24 hours (language from `Accept-Language`; on a domain registered to this database the link points to that domain); a newer request invalidates older links. 409 `email_missing` when the account has no email, 409 `email_already_verified` when it is already verified, 429 when requested too often, 503 when EMAIL_VERIFY_URL is not configured.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Send a verification link to the caller's email", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/login": { "post": { "operationId": "login", "summary": "Log in with login + password", "description": "Returns a token pair, or `mfaRequired: true` with a ticket when the user has MFA enabled (exchange it at POST /api/v1/auth/mfa/verify). A valid `deviceToken` (from `verifyMfa` with `rememberDevice`) of the same user skips the MFA step; an unknown, foreign, expired or revoked one is ignored (the ticket is returned as usual). Failed attempts are throttled per login and per IP. Session policy (`core.session_policy`): with `maxSessions` reached, the least recently used session is signed out, or 409 `session_limit_reached` when `onLimit` is `block`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Log in with login + password", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "anyOf": [ { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refreshToken": { "type": "string" } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store", "refreshToken" ] }, { "type": "object", "properties": { "mfaRequired": { "const": true }, "ticket": { "type": "string", "format": "uuid" }, "methods": { "type": "array", "items": { "enum": [ "totp", "recovery_code", "passkey" ], "type": "string" } }, "sms": { "type": "boolean" }, "expiresIn": { "type": "number" } }, "required": [ "mfaRequired", "ticket", "methods", "sms", "expiresIn" ] } ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "minLength": 1, "maxLength": 100 }, "password": { "type": "string" }, "deviceToken": { "type": "string", "maxLength": 200 } }, "required": [ "login", "password" ] } } } } } }, "/api/v1/auth/logout": { "post": { "operationId": "logout", "summary": "Log out", "description": "Revokes the refresh token and its whole family.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Log out", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1 } }, "required": [ "refreshToken" ] } } } } } }, "/api/v1/auth/me": { "get": { "operationId": "getMe", "summary": "Get the current user", "description": "Identity, email (and whether it is verified), current database / store, and effective roles + permissions of the caller. `passwordChangeRequired` / `mfaEnrollmentRequired` = the caller must change the password / set up a second factor first: other routes answer 403 `password_change_required` / `mfa_enrollment_required` until then (ADR-0100 / ADR-0101).", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the current user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" }, "superuser": { "type": "boolean" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "database": { "type": "string" }, "tenancy": { "enum": [ "shared", "dedicated" ], "type": "string" }, "managedByPlatform": { "type": "boolean" }, "account": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "null" } ] }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "storeName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "roles": { "type": "array", "items": { "type": "string" } }, "permissions": { "type": "array", "items": { "type": "string" } }, "conditionalPermissions": { "type": "array", "items": { "type": "string" } }, "lang": { "type": "string" }, "defaultLang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "languages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "passwordChangeRequired": { "type": "boolean" }, "mfaEnrollmentRequired": { "type": "boolean" } }, "required": [ "id", "login", "name", "superuser", "accountId", "email", "emailVerifiedAt", "database", "tenancy", "managedByPlatform", "account", "store", "storeName", "roles", "permissions", "conditionalPermissions", "lang", "defaultLang", "languages", "passwordChangeRequired", "mfaEnrollmentRequired" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/mfa": { "get": { "operationId": "getMfaStatus", "summary": "Get the caller's MFA status", "description": "`enabled` is true when the caller has TOTP or at least one passkey; `recoveryCodesLeft` counts unused recovery codes.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the caller's MFA status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "totp": { "type": "boolean" }, "passkeys": { "type": "number" }, "recoveryCodesLeft": { "type": "number" }, "smsPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "enabled", "totp", "passkeys", "recoveryCodesLeft", "smsPhone" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/mfa/recovery-codes": { "post": { "operationId": "regenerateRecoveryCodes", "summary": "Regenerate MFA recovery codes", "description": "Requires step-up (password + a second factor). Every old recovery code stops working, including unused ones, and 10 new codes are returned once (only hashes are stored). Remembered devices are forgotten too. 409 `mfa_not_enabled` when the caller has no TOTP / passkey.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Regenerate MFA recovery codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" } } }, "required": [ "recoveryCodes" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] } }, "required": [ "password" ] } } } } } }, "/api/v1/auth/mfa/sms": { "delete": { "operationId": "disableMfaSms", "summary": "Remove the backup phone number", "description": "Requires step-up. 404 `mfa_sms_not_enrolled` when there is none.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Remove the backup phone number", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] } }, "required": [ "password" ] } } } } } }, "/api/v1/auth/mfa/sms/confirm": { "post": { "operationId": "confirmMfaSms", "summary": "Confirm the backup phone number with the texted code", "description": "The number becomes (or replaces) the backup number; remembered devices are forgotten. Returns it masked. 401 `invalid_mfa_code`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirm the backup phone number with the texted code", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "phone": { "type": "string" } }, "required": [ "phone" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "code" ] } } } } } }, "/api/v1/auth/mfa/sms/send": { "post": { "operationId": "sendMfaSmsCode", "summary": "Text a sign-in code to the backup phone number", "description": "For the MFA step of a login when the authenticator app is not at hand: texts a 6-digit code (valid 5 minutes) to the user's backup number; send it as `smsCode` to `verifyMfa`. Only for users who set up a backup number (409 `mfa_sms_not_enrolled`) — the login answer has `sms: true` then. 401 `mfa_ticket_invalid`, 429 when asked too often.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Text a sign-in code to the backup phone number", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "string", "format": "uuid" } }, "required": [ "ticket" ] } } } } } }, "/api/v1/auth/mfa/sms/setup": { "post": { "operationId": "setupMfaSms", "summary": "Add a backup phone number for sign-in codes", "description": "Requires step-up and an authenticator app or passkey already on (409 `mfa_sms_needs_factor`): a texted code is only a BACKUP — it never turns MFA on and never satisfies a required-MFA policy. Texts a code to `phone`; confirm with `confirmMfaSms`. 400 `phone_invalid`, 429 when asked too often, 503 `sms_otp_unavailable` before the database upgrade.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Add a backup phone number for sign-in codes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] }, "phone": { "type": "string", "minLength": 6, "maxLength": 32 } }, "required": [ "password", "phone" ] } } } } } }, "/api/v1/auth/mfa/step-up/options": { "post": { "operationId": "getStepUpPasskeyOptions", "summary": "Start a passkey step-up", "description": "WebAuthn challenge limited to the caller's own passkeys, used as the `passkey` proof of a step-up body.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Start a passkey step-up", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "publicKey": { "type": "object", "properties": { "challenge": { "type": "string" }, "rpId": { "type": "string" }, "timeout": { "type": "number" }, "userVerification": { "const": "required" }, "allowCredentials": { "type": "array", "items": { "type": "object", "properties": { "type": { "const": "public-key" }, "id": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "id" ] } } }, "required": [ "challenge", "rpId", "timeout", "userVerification", "allowCredentials" ] } }, "required": [ "challengeId", "publicKey" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/mfa/totp": { "delete": { "operationId": "disableTotp", "summary": "Disable TOTP", "description": "Requires exactly one of `code` / `recoveryCode`. When the sign-in policy requires MFA (`core.auth_policy.requireMfa`) and this is the last factor, 409 `last_factor`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Disable TOTP", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 } }, "required": [] } } } } } }, "/api/v1/auth/mfa/totp/confirm": { "post": { "operationId": "confirmTotp", "summary": "Confirm TOTP enrollment", "description": "The first valid code enables TOTP and returns 10 new recovery codes. When this turns MFA on, all other sessions are revoked and a fresh token pair is returned in `tokens`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Confirm TOTP enrollment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "recoveryCodes": { "type": "array", "items": { "type": "string" } }, "tokens": { "anyOf": [ { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refreshToken": { "type": "string" } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store", "refreshToken" ] }, { "type": "null" } ] } }, "required": [ "recoveryCodes", "tokens" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "code" ] } } } } } }, "/api/v1/auth/mfa/totp/setup": { "post": { "operationId": "setupTotp", "summary": "Start TOTP enrollment", "description": "Requires step-up (password, plus a second factor if MFA is already on). Returns a new unconfirmed secret; 409 if TOTP is already enabled.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Start TOTP enrollment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "secret": { "type": "string" }, "otpauthUri": { "type": "string" } }, "required": [ "secret", "otpauthUri" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] } }, "required": [ "password" ] } } } } } }, "/api/v1/auth/mfa/verify": { "post": { "operationId": "verifyMfa", "summary": "Complete an MFA login", "description": "Exchanges the ticket from login plus exactly one of `code` (TOTP) / `recoveryCode` / `smsCode` (backup number, `sendMfaSmsCode`) for a token pair. With `rememberDevice: true`, `trustedDevice.token` is returned once: send it as `deviceToken` on later password logins of the same user to skip the MFA step until `trustedDevice.expiresAt` (`core.trusted_devices` days; null when the tenant turned it off). Trusted devices are forgotten when the password changes, sessions are revoked, MFA factors change or recovery codes are regenerated.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Complete an MFA login", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refreshToken": { "type": "string" }, "trustedDevice": { "anyOf": [ { "type": "object", "properties": { "token": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "token", "expiresAt" ] }, { "type": "null" } ] } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store", "refreshToken", "trustedDevice" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ticket": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "smsCode": { "type": "string", "pattern": "^\\d{6}$" }, "rememberDevice": { "type": "boolean" } }, "required": [ "ticket" ] } } } } } }, "/api/v1/auth/passkeys": { "get": { "operationId": "listPasskeys", "summary": "List the caller's passkeys", "description": "Passkeys registered by the signed-in user (never another user's).", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List the caller's passkeys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "alg": { "type": "number" }, "transports": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "name", "alg", "transports", "createdAt", "lastUsedAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/passkeys/{id}": { "delete": { "operationId": "deletePasskey", "summary": "Delete a passkey", "description": "Requires step-up (password + second factor). When the sign-in policy requires MFA (`core.auth_policy.requireMfa`) and this is the last factor, 409 `last_factor`.", "tags": [ "auth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Delete a passkey", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] } }, "required": [ "password" ] } } } } } }, "/api/v1/auth/passkeys/login/options": { "post": { "operationId": "getPasskeyLoginOptions", "summary": "Start a passkey login", "description": "Returns a WebAuthn challenge for navigator.credentials.get. With `login`, lists that user's passkeys (a stable fake id when the login is unknown); without it, uses discoverable passkeys. The body is optional.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Start a passkey login", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "publicKey": { "type": "object", "properties": { "challenge": { "type": "string" }, "rpId": { "type": "string" }, "timeout": { "type": "number" }, "userVerification": { "const": "required" }, "allowCredentials": { "type": "array", "items": { "type": "object", "properties": { "type": { "const": "public-key" }, "id": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "id" ] } } }, "required": [ "challenge", "rpId", "timeout", "userVerification", "allowCredentials" ] } }, "required": [ "challengeId", "publicKey" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [] } } } } } }, "/api/v1/auth/passkeys/login/verify": { "post": { "operationId": "verifyPasskeyLogin", "summary": "Complete a passkey login", "description": "Verifies the WebAuthn assertion against the challenge and issues a token pair.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Complete a passkey login", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refreshToken": { "type": "string" } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store", "refreshToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] } } } } } }, "/api/v1/auth/passkeys/register/options": { "post": { "operationId": "getPasskeyRegisterOptions", "summary": "Start passkey registration", "description": "Requires step-up. Returns a WebAuthn challenge for navigator.credentials.create.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Start passkey registration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "publicKey": { "type": "object", "properties": { "rp": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "displayName": { "type": "string" } }, "required": [ "id", "name", "displayName" ] }, "challenge": { "type": "string" }, "pubKeyCredParams": { "type": "array", "items": { "type": "object", "properties": { "type": { "const": "public-key" }, "alg": { "type": "number" } }, "required": [ "type", "alg" ] } }, "timeout": { "type": "number" }, "attestation": { "const": "none" }, "authenticatorSelection": { "type": "object", "properties": { "residentKey": { "const": "preferred" }, "userVerification": { "const": "required" } }, "required": [ "residentKey", "userVerification" ] }, "excludeCredentials": { "type": "array", "items": { "type": "object", "properties": { "type": { "const": "public-key" }, "id": { "type": "string" }, "transports": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "id" ] } } }, "required": [ "rp", "user", "challenge", "pubKeyCredParams", "timeout", "attestation", "authenticatorSelection", "excludeCredentials" ] } }, "required": [ "challengeId", "publicKey" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] } }, "required": [ "password" ] } } } } } }, "/api/v1/auth/passkeys/register/verify": { "post": { "operationId": "registerPasskey", "summary": "Register a passkey", "description": "Verifies the attestation and stores the passkey. When it is the first factor, recovery codes are returned and all other sessions are revoked (fresh token pair in `tokens`).", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Register a passkey", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "passkey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "createdAt" ] }, "recoveryCodes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "tokens": { "anyOf": [ { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refreshToken": { "type": "string" } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store", "refreshToken" ] }, { "type": "null" } ] } }, "required": [ "passkey", "recoveryCodes", "tokens" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "attestationObject": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "transports": { "type": "array", "items": { "type": "string", "pattern": "^[a-z-]{1,20}$" }, "maxItems": 10 } }, "required": [ "clientDataJSON", "attestationObject" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] } } } } } }, "/api/v1/auth/password": { "post": { "operationId": "changePassword", "summary": "Change the caller's password", "description": "Needs the current `password` and, when MFA is on, one second factor (`code`, `recoveryCode` or a `passkey` assertion) — the same proof as other step-ups. `newPassword` must meet the tenant's minimum length (`core.auth_policy`). Every session of the user is revoked, including the others on other devices, and this device gets a fresh token pair. Clears `passwordChangeRequired` (ADR-0100); while it is set, a `newPassword` equal to the current one is 400 `password_unchanged`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Change the caller's password", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refreshToken": { "type": "string" } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store", "refreshToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "password": { "type": "string", "maxLength": 128 }, "code": { "type": "string", "pattern": "^\\d{6}$" }, "recoveryCode": { "type": "string", "maxLength": 64 }, "passkey": { "type": "object", "properties": { "challengeId": { "type": "string", "format": "uuid" }, "credential": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "response": { "type": "object", "properties": { "clientDataJSON": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "authenticatorData": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "signature": { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, "userHandle": { "anyOf": [ { "type": "string", "maxLength": 16384, "pattern": "^[A-Za-z0-9_-]*={0,2}$" }, { "type": "null" } ] } }, "required": [ "clientDataJSON", "authenticatorData", "signature" ] } }, "required": [ "id", "response" ] } }, "required": [ "challengeId", "credential" ] }, "newPassword": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "password", "newPassword" ] } } } } } }, "/api/v1/auth/password/forgot": { "post": { "operationId": "forgotPassword", "summary": "Request a password reset email", "description": "Always answers 202, whether or not the login exists (no account enumeration). When the login (or email) belongs to an active user with an email, a one-time reset link valid for 30 minutes is emailed in the language of `Accept-Language` (en / vi); when the request comes from a domain registered to this database the link points to that domain. A newer request invalidates older links. Throttled per IP (429); extra requests for the same login are silently dropped. 503 when PASSWORD_RESET_URL is not configured.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Request a password reset email", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "null" } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "minLength": 1, "maxLength": 254 } }, "required": [ "login" ] } } } } } }, "/api/v1/auth/password/reset": { "post": { "operationId": "resetPassword", "summary": "Set a new password with a reset token", "description": "Consumes the token from the reset email and sets the new password. All existing sessions are revoked (access tokens fail with `token_revoked`, refresh tokens are rejected) and the failed-login lock is cleared. MFA stays enabled: the next login still asks for the second factor. An invalid, used or expired token answers 401 `reset_token_invalid`; failures are throttled per IP.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Set a new password with a reset token", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[A-Za-z0-9_-]+$" }, "password": { "type": "string", "minLength": 8, "maxLength": 128 } }, "required": [ "token", "password" ] } } } } } }, "/api/v1/auth/refresh": { "post": { "operationId": "refreshToken", "summary": "Rotate a refresh token", "description": "Exchanges a refresh token for a new token pair; the old refresh token is revoked. Replaying a rotated token revokes its whole family. A session unused for longer than `idleTimeoutMinutes` (`core.session_policy`) is ended: 401 `refresh_token_expired`.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rotate a refresh token", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refreshToken": { "type": "string" } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store", "refreshToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "minLength": 1 } }, "required": [ "refreshToken" ] } } } } } }, "/api/v1/auth/sessions": { "get": { "operationId": "listSessions", "summary": "List the caller's sessions", "description": "One entry per sign-in that can still refresh (newest activity first). `current` marks the session of the access token in use (tokens issued before sessions were tracked are never `current`).", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List the caller's sessions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastActiveAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "current": { "type": "boolean" } }, "required": [ "id", "startedAt", "lastActiveAt", "expiresAt", "store", "current" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/sessions/{id}": { "delete": { "operationId": "revokeSession", "summary": "Sign out one session", "description": "Revokes the session's refresh token so it cannot refresh again. An access token already issued to it keeps working until it expires (at most `expiresIn` seconds); use `revokeAllSessions` to cut every session at once. 404 `session_not_found`.", "tags": [ "auth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Sign out one session", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/sessions/revoke-all": { "post": { "operationId": "revokeAllSessions", "summary": "Sign out everywhere", "description": "Revokes every session of the caller immediately (access tokens included) and returns a fresh token pair for this device.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sign out everywhere", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refreshToken": { "type": "string" } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store", "refreshToken" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/stores": { "get": { "operationId": "listMyStores", "summary": "List stores the caller can enter", "description": "Active stores the user is a member of (all active stores for a superuser), for the store picker after login.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List stores the caller can enter", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "defaultLang": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "name", "timezone", "currency", "defaultLang", "languages" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/switch-store": { "post": { "operationId": "switchStore", "summary": "Switch to another store", "description": "Issues a new access token for the target store using the current token (send it without `x-store`). The refresh token is not rotated.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Switch to another store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "accessToken": { "type": "string" }, "tokenType": { "const": "Bearer" }, "expiresIn": { "type": "number" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId", "accessToken", "tokenType", "expiresIn", "store" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, "required": [ "store" ] } } } } } }, "/api/v1/auth/trusted-devices": { "get": { "operationId": "listTrustedDevices", "summary": "List the caller's remembered devices", "description": "Devices that currently skip the MFA step at password login (newest first). Empty when the tenant turned the feature off.", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List the caller's remembered devices", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "label", "ip", "createdAt", "lastUsedAt", "expiresAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/trusted-devices/{id}": { "delete": { "operationId": "revokeTrustedDevice", "summary": "Forget one remembered device", "description": "That device has to pass the MFA step again. 404 `trusted_device_not_found`.", "tags": [ "auth" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Forget one remembered device", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/auth/trusted-devices/revoke-all": { "post": { "operationId": "revokeAllTrustedDevices", "summary": "Forget every remembered device", "description": "Every device of the caller has to pass the MFA step again at the next login. Sessions are not signed out (see `revokeAllSessions`).", "tags": [ "auth" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Forget every remembered device", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/brands": { "get": { "operationId": "listBrands", "summary": "List brands", "description": "Brands of the current store. `lang` + every translatable field are picked for the request language (x-lang / Accept-Language, falling back to the store's default language); `translations` holds every translation. `q` searches the code and every translated name. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "brands" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "sort_order", "-sort_order", "code", "-code", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: brands.code, brand_translations.name" }, "description": "Case-insensitive substring search in: brands.code, brand_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List brands", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "logoFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "websiteUrl", "logoFileId", "logoFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.read" ] }, "post": { "operationId": "createBrand", "summary": "Create a brand", "description": "Created in the current store. `code` is unique per store among brands not in the trash (409 `brand_code_exists`). Optional initial `translations`: each `lang` must be enabled for the store (400 `unsupported_language`); an empty `slug` is generated from `name`; a slug already used in the same language → 409 `brand_slug_exists`. `logoFileId` must be a file of the current store (400 `file_not_attachable`).", "tags": [ "brands" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a brand", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "logoFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "websiteUrl", "logoFileId", "logoFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "websiteUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 500 }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "active": { "type": "boolean", "default": true }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "lang", "name" ] }, "maxItems": 20, "default": [] } }, "required": [ "code" ] } } } } } }, "/api/v1/brands/{id}": { "get": { "operationId": "getBrand", "summary": "Get a brand", "description": "`name` / `slug` in the request language, `translations` with every language. 404 `brand_not_found` when the brand does not exist in the current store or is in the trash.", "tags": [ "brands" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a brand", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "logoFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "websiteUrl", "logoFileId", "logoFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.read" ] }, "put": { "operationId": "replaceBrand", "summary": "Replace a brand (full update)", "description": "Replaces every brand field (fields not sent take their defaults); translations stay unchanged.", "tags": [ "brands" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a brand (full update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "logoFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "websiteUrl", "logoFileId", "logoFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "websiteUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 500 }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "active": { "type": "boolean", "default": true } }, "required": [ "code" ] } } } } }, "patch": { "operationId": "updateBrand", "summary": "Update a brand (partial)", "description": "Fields not sent stay unchanged. `translations`, when sent, replaces the whole set in the same transaction (languages left out are deleted; each `lang` must be enabled for the store → 400 `unsupported_language`; an empty `slug` is generated from `name`; a slug taken in that language → 409 `brand_slug_exists`). Single translations can also be edited through /brands/{id}/translations.", "tags": [ "brands" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a brand (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "logoFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "websiteUrl", "logoFileId", "logoFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "websiteUrl": { "anyOf": [ { "type": "string", "format": "uri", "maxLength": 500 }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0 }, "active": { "type": "boolean" }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "lang", "name" ] }, "maxItems": 20 } }, "required": [] } } } } }, "delete": { "operationId": "deleteBrand", "summary": "Delete a brand", "description": "Moves the brand to the trash (restore with POST /brands/{id}/restore). `?force=true` deletes it permanently, also from the trash, and additionally requires `brand.hard_delete`.", "tags": [ "brands" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a brand", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.delete" ] } }, "/api/v1/brands/{id}/restore": { "post": { "operationId": "restoreBrand", "summary": "Restore a brand from the trash", "description": "404 when the brand is not in the trash; 409 `brand_code_exists` when another brand took its code meanwhile.", "tags": [ "brands" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a brand from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "websiteUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logoFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "logoFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "websiteUrl", "logoFileId", "logoFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.restore" ] } }, "/api/v1/brands/{id}/translations": { "post": { "operationId": "addBrandTranslation", "summary": "Add a brand translation", "description": "Adds the translation of one language: 400 `unsupported_language` when the language is not enabled for the store, 409 `brand_translation_lang_exists` when it already exists, 409 `brand_slug_exists` when the slug is taken in that language. An empty `slug` is generated from `name`.", "tags": [ "brands" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Add a brand translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "lang", "name" ] } } } } } }, "/api/v1/brands/{id}/translations/{lang}": { "patch": { "operationId": "updateBrandTranslation", "summary": "Update a brand translation", "description": "Partial update of the translation in `lang`; fields not sent stay unchanged. 404 `brand_translation_not_found` when the brand has no translation in that language.", "tags": [ "brands" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lang", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a brand translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "slug": { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, "metaTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [] } } } } }, "delete": { "operationId": "deleteBrandTranslation", "summary": "Delete a brand translation", "description": "Deletes the translation in `lang`; the brand and its other translations stay. 404 `brand_translation_not_found` when the brand has no translation in that language.", "tags": [ "brands" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "lang", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a brand translation", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.update" ] } }, "/api/v1/brands/options": { "get": { "operationId": "listBrandOptions", "summary": "List brand options", "description": "Same query as GET /brands, trimmed to `{ id, code }` + the translation picked for the request language (`lang` + every translatable field, null when the brand has no translation) for pickers.", "tags": [ "brands" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "sort_order", "-sort_order", "code", "-code", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: brands.code, brand_translations.name" }, "description": "Case-insensitive substring search in: brands.code, brand_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List brand options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] } }, "required": [ "id", "code", "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.read" ] } }, "/api/v1/brands/trash": { "get": { "operationId": "listBrandTrash", "summary": "List brands in the trash", "description": "Brands of the current store that were moved to the trash, most recently deleted first, with who deleted them. `q` searches the code and every translated name. Restore with POST /brands/{id}/restore, delete permanently with DELETE /brands/{id}?force=true. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "brands" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: brands.code, brand_translations.name" }, "description": "Case-insensitive substring search in: brands.code, brand_translations.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List brands in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "lang", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "brand.restore" ] } }, "/api/v1/core/accounts": { "get": { "operationId": "listAccounts", "summary": "List accounts", "description": "Superuser only.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List accounts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "limits": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } } }, "required": [ "id", "name", "createdAt", "limits" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] }, "post": { "operationId": "createAccount", "summary": "Create an account", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). A dedicated database holds exactly one account.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create an account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "name" ] } } } } } }, "/api/v1/core/accounts/{id}/limits": { "put": { "operationId": "setAccountLimits", "summary": "Set an account's limits", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Replaces the account's limits: quota → ceiling across ALL its stores (e.g. `files.storage_mb`), on top of each store's plan. Only quotas that declare a customer-level limit are accepted (400 `quota_not_account_level`; unknown quota → 400 `unknown_plan_item`). `{}` removes every limit.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Set an account's limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "limits": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } } }, "required": [ "id", "limits" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "limits": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0 } } }, "required": [ "limits" ] } } } } } }, "/api/v1/core/api-keys": { "get": { "operationId": "listApiKeys", "summary": "List API keys", "description": "API keys of the users you manage, newest first (revoked / expired included). An account admin sees every key of the account; a store admin sees keys bound to its store.", "tags": [ "core" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "50", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "allowedIps": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "store": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "login": { "type": "string" } }, "required": [ "id", "login" ] } }, "required": [ "id", "name", "prefix", "scopes", "allowedIps", "store", "expiresAt", "lastUsedAt", "revokedAt", "createdAt", "user" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ] } }, "/api/v1/core/api-keys/{id}": { "delete": { "operationId": "revokeApiKey", "summary": "Revoke an API key", "description": "Takes effect on every server within about a second. 404 `api_key_not_found` (outside your scope or already revoked).", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Revoke an API key", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ] } }, "/api/v1/core/audit": { "get": { "operationId": "listAuditLog", "summary": "List audit log entries", "description": "Newest first. Inside a store only that store's entries are returned; a superuser outside any store sees all. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "core" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "50", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$" } }, { "name": "actor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "action", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "until", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List audit log entries", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "actorId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "actorLogin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "action": { "type": "string" }, "target": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "status": { "type": "number" }, "ip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userAgent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "storeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "id", "at", "actorId", "actorLogin", "action", "target", "status", "ip", "userAgent", "details", "storeId" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.view_audit" ] } }, "/api/v1/core/audit/records/{resource}/{id}": { "get": { "operationId": "listRecordChanges", "summary": "List the change history of a business record", "description": "Who changed which field of the record, with the value before / after, newest first. `resource` is the table a module declares as auditable (e.g. `brands`); 404 `audit_resource_not_found` when no installed module declares it. Also requires the resource's read permission (403 `forbidden`). Only the current store's changes. Fields a module does not record values for come with `redacted: true` and null `from` / `to`. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "core" ], "parameters": [ { "name": "resource", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z_][a-z0-9_]{0,62}$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "50", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "id", "-id" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-id`" }, "description": "Sort field; prefix `-` for descending. Default `-id`" }, { "name": "at.gte", "in": "query", "required": false, "schema": { "type": "string", "description": "gte: timestamp" }, "description": "gte: timestamp" }, { "name": "at.lt", "in": "query", "required": false, "schema": { "type": "string", "description": "lt: timestamp" }, "description": "lt: timestamp" }, { "name": "actor_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List the change history of a business record", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "at": { "type": "string", "format": "date-time", "pattern": "Z$" }, "module": { "type": "string" }, "resource": { "type": "string" }, "resourceId": { "type": "string" }, "action": { "type": "string" }, "actorId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "actorLogin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "impersonatedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "request": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "from": {}, "to": {}, "redacted": { "type": "boolean" } }, "required": [ "field", "from", "to", "redacted" ] } }, "meta": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id", "at", "module", "resource", "resourceId", "action", "actorId", "actorLogin", "impersonatedBy", "request", "changes", "meta" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.view_record_history" ] } }, "/api/v1/core/configs": { "get": { "operationId": "listConfigs", "summary": "List the tenant's settings", "description": "Every setting of core and the installed modules, with the effective value for the current store (`source` = the level it came from), and the value stored at each level. Secret fields are masked.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List the tenant's settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "module": { "type": "string" }, "summary": { "type": "string" }, "scopes": { "type": "array", "items": { "enum": [ "database", "account", "store" ], "type": "string" } }, "public": { "type": "boolean" }, "secretFields": { "type": "array", "items": { "type": "string" } }, "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "source": { "enum": [ "database", "account", "store", "default" ], "type": "string" }, "layers": { "type": "object", "properties": { "database": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "version": { "type": "number" }, "changedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "value", "version", "changedAt" ] }, { "type": "null" } ] }, "account": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "version": { "type": "number" }, "changedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "value", "version", "changedAt" ] }, { "type": "null" } ] }, "store": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "version": { "type": "number" }, "changedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "value", "version", "changedAt" ] }, { "type": "null" } ] } }, "required": [ "database", "account", "store" ] } }, "required": [ "code", "module", "summary", "scopes", "public", "secretFields", "value", "source", "layers" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_settings" ] } }, "/api/v1/core/configs/{code}": { "put": { "operationId": "setConfig", "summary": "Set a setting at one level", "description": "Stores the whole value at `scope`: `store` (current store), `account` (account-level administrator) or `database` (superuser; in a dedicated database also an account-level administrator). Stores inherit account, which inherits database. Send the mask `••••••••` in a secret field to keep the stored secret. 400 `config_scope_not_allowed`, 409 `version_conflict`, 503 `secrets_not_configured`.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Set a setting at one level", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "module": { "type": "string" }, "summary": { "type": "string" }, "scopes": { "type": "array", "items": { "enum": [ "database", "account", "store" ], "type": "string" } }, "public": { "type": "boolean" }, "secretFields": { "type": "array", "items": { "type": "string" } }, "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "source": { "enum": [ "database", "account", "store", "default" ], "type": "string" }, "layers": { "type": "object", "properties": { "database": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "version": { "type": "number" }, "changedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "value", "version", "changedAt" ] }, { "type": "null" } ] }, "account": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "version": { "type": "number" }, "changedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "value", "version", "changedAt" ] }, { "type": "null" } ] }, "store": { "anyOf": [ { "type": "object", "properties": { "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "version": { "type": "number" }, "changedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "value", "version", "changedAt" ] }, { "type": "null" } ] } }, "required": [ "database", "account", "store" ] } }, "required": [ "code", "module", "summary", "scopes", "public", "secretFields", "value", "source", "layers" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_settings" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "enum": [ "database", "account", "store" ], "type": "string" }, "value": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "version": { "type": "integer", "minimum": 1 } }, "required": [ "scope", "value" ] } } } } }, "delete": { "operationId": "resetConfig", "summary": "Remove a setting at one level", "description": "Deletes the value stored at `scope`; the level falls back to the one above it.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "scope", "in": "query", "required": true, "schema": { "enum": [ "database", "account", "store" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Remove a setting at one level", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_settings" ] } }, "/api/v1/core/customers": { "get": { "operationId": "listCustomers", "summary": "List storefront customers", "description": "Customers who signed up or shopped at a store you manage, ordered by email (erased accounts are left out). A customer account is shared by every store of the database: `stores` lists only the stores within your scope. An account admin sees customers of every store of the account, a store admin those of its store. `store` keeps only customers of that store code (a store outside your scope or unknown gives an empty list). `q` searches name, email and phone, ignoring case and Vietnamese accents (`nguyen` finds `Nguyễn`, `0912` finds `84912…`); short terms (under 3 characters) can be slow on a large database. `erasable` / `editable` tell whether you may erase / change the customer, judged by store links: the action can still be refused when a store outside your scope holds the customer's data. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "core" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "50", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 254 } }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 254, "format": "email" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 } }, { "name": "store", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 64 } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List storefront customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "phoneVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deletionRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "purgeAfter": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "stores": { "type": "array", "items": { "type": "string" } }, "erasable": { "type": "boolean" }, "editable": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "email", "name", "phone", "active", "emailVerifiedAt", "phoneVerifiedAt", "deletionRequestedAt", "purgeAfter", "stores", "erasable", "editable", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.view_customers" ] }, "post": { "operationId": "createCustomer", "summary": "Create a storefront customer without a password", "description": "Creates the account and links it to the current store (400 `store_required` without a store). No password and nothing is emailed: the customer takes over the account with the existing flows — `storefrontForgotPassword` (the link proves the mailbox and sets a password) or social sign-in with a verified email; `storefrontRegister` answers 409 `email_taken` for this email, as for any existing account. Email and phone are unverified. 409 `email_taken` when the email has an account anywhere in this database: the same answer whoever the customer belongs to, and that account is not linked or changed. Try `listCustomers?email=` to open it (only customers within your scope show); otherwise ask the customer to sign in at your store, which links them. 429 `too_many_attempts` after repeated `email_taken` answers. 400 `phone_invalid`.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a storefront customer without a password", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "phoneVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deletionRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "purgeAfter": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "stores": { "type": "array", "items": { "type": "string" } }, "erasable": { "type": "boolean" }, "editable": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "email", "name", "phone", "active", "emailVerifiedAt", "phoneVerifiedAt", "deletionRequestedAt", "purgeAfter", "stores", "erasable", "editable", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 254, "format": "email" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "anyOf": [ { "type": "string", "minLength": 6, "maxLength": 32 }, { "type": "null" } ] } }, "required": [ "email", "name" ] } } } } } }, "/api/v1/core/customers/{id}": { "get": { "operationId": "getCustomer", "summary": "Get a storefront customer", "description": "`stores` lists only the stores within your scope. 404 `customer_not_found` when the customer does not exist, was erased, or has no store within your scope — the same answer for all three. The order history is `listOrders?customer_id=` of the order module.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a storefront customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "phoneVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deletionRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "purgeAfter": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "stores": { "type": "array", "items": { "type": "string" } }, "erasable": { "type": "boolean" }, "editable": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "email", "name", "phone", "active", "emailVerifiedAt", "phoneVerifiedAt", "deletionRequestedAt", "purgeAfter", "stores", "erasable", "editable", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.view_customers" ] }, "patch": { "operationId": "updateCustomer", "summary": "Change a storefront customer's name or phone", "description": "The profile is shared by every store of the database, so every store the customer uses must be within your scope, as for `eraseCustomer`: another store of the same account → 403 `account_scope_required`; a store of another account → 409 `customer_shared`; 404 `customer_not_found` outside your scope. A new `phone` (or null) drops the phone verification: the customer verifies again before signing in with it; sending the same number changes nothing. Needs both view and manage permissions: the response is the profile as `getCustomer` shows it, and a customer outside your view scope is 404 even within your manage scope. The email and `active` cannot be changed here (`active` applies to every store of the database, so a store cannot set it). 400 `phone_invalid`.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Change a storefront customer's name or phone", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "phoneVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deletionRequestedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "purgeAfter": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "stores": { "type": "array", "items": { "type": "string" } }, "erasable": { "type": "boolean" }, "editable": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "email", "name", "phone", "active", "emailVerifiedAt", "phoneVerifiedAt", "deletionRequestedAt", "purgeAfter", "stores", "erasable", "editable", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_customers", "core.view_customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "phone": { "anyOf": [ { "type": "string", "minLength": 6, "maxLength": 32 }, { "type": "null" } ] } }, "required": [] } } } } } }, "/api/v1/core/customers/{id}/erase": { "post": { "operationId": "eraseCustomer", "summary": "Erase a storefront customer's account", "description": "For a deletion request the customer sent to the shop. Immediate and final, like the customer deleting the account themselves (no grace period): personal details are erased (the record stays anonymised for business data), sign-in methods, sessions and store links are removed, Apple sign-in authorizations are revoked in the background. Installed modules anonymise their own copies (e.g. order contact snapshots: name `Deleted customer`, email / phone / note null, address keeps only province + country; carts are deleted). `confirm` must be the customer's current email (400 `erase_confirm_mismatch`). The account is erased for EVERY store of the database, so every store the customer uses — linked, or still holding the customer's data (orders, carts) after an unlink — must be within your scope: another store of the same account → 403 `account_scope_required` (ask an account admin); a store of another account → 409 `customer_shared` (only the platform operator can erase it). 404 `customer_not_found` outside your scope.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Erase a storefront customer's account", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.erase_customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "string", "maxLength": 254 } }, "required": [ "confirm" ] } } } } } }, "/api/v1/core/customers/{id}/unlink": { "post": { "operationId": "unlinkCustomer", "summary": "Remove a storefront customer from your stores", "description": "For a customer who also shops at stores you do not manage (where `eraseCustomer` answers 403 / 409): removes the customer from the stores within your scope only — the account itself stays, other stores are untouched. Sessions the customer opened at those stores are revoked (an access token lives until its short TTL). If the customer signs in at that store again, the link is created again. Modules drop their non-document data of the customer at those stores (cart, wishlist…); documents (orders, returns…) are kept. 404 `customer_not_found` when the customer has no store within your scope.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Remove a storefront customer from your stores", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "unlinkedStores": { "type": "array", "items": { "type": "string" } } }, "required": [ "unlinkedStores" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.erase_customers" ] } }, "/api/v1/core/jobs": { "get": { "operationId": "listJobs", "summary": "List background jobs", "description": "Jobs of this database, newest first, filtered by `status` / `type`. Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). The payload is never returned.", "tags": [ "core" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "50", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "id", "-id" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-id`" }, "description": "Sort field; prefix `-` for descending. Default `-id`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: pending, running, done, dead" }, "description": "eq: one of: pending, running, done, dead" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List background jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Job id (bigint as string)" }, "type": { "type": "string", "description": "`.`" }, "status": { "enum": [ "pending", "running", "done", "dead" ], "type": "string" }, "attempts": { "type": "number" }, "maxAttempts": { "type": "number" }, "runAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "When the job is (or was last) due to run" }, "lockedUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ], "description": "Lease of the worker running it; null when not running" }, "stuck": { "type": "boolean", "description": "Running, but its lease expired more than 300 s ago and no worker picked it up again: the worker died and none is serving this database (or all are full)." }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error of the last failed attempt, cut to 500 characters. The payload is never returned." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "type", "status", "attempts", "maxAttempts", "runAt", "lockedUntil", "stuck", "lastError", "createdAt", "finishedAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/jobs/{id}": { "get": { "operationId": "getJob", "summary": "Get a background job", "description": "404 `job_not_found` when there is no such job.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,17}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a background job", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Job id (bigint as string)" }, "type": { "type": "string", "description": "`.`" }, "status": { "enum": [ "pending", "running", "done", "dead" ], "type": "string" }, "attempts": { "type": "number" }, "maxAttempts": { "type": "number" }, "runAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "When the job is (or was last) due to run" }, "lockedUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ], "description": "Lease of the worker running it; null when not running" }, "stuck": { "type": "boolean", "description": "Running, but its lease expired more than 300 s ago and no worker picked it up again: the worker died and none is serving this database (or all are full)." }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error of the last failed attempt, cut to 500 characters. The payload is never returned." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "type", "status", "attempts", "maxAttempts", "runAt", "lockedUntil", "stuck", "lastError", "createdAt", "finishedAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] }, "delete": { "operationId": "deleteJob", "summary": "Delete a dead job", "description": "Drops a `dead` job once it has been looked into (otherwise kept 30 days). Any other status is 409 `job_not_deletable`.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,17}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a dead job", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/jobs/{id}/retry": { "post": { "operationId": "retryJob", "summary": "Run a job again now", "description": "A `dead` or `pending` job runs again immediately with its attempts reset to 0. Any other status is 409 `job_not_retryable`.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,17}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Run a job again now", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "Job id (bigint as string)" }, "type": { "type": "string", "description": "`.`" }, "status": { "enum": [ "pending", "running", "done", "dead" ], "type": "string" }, "attempts": { "type": "number" }, "maxAttempts": { "type": "number" }, "runAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "When the job is (or was last) due to run" }, "lockedUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ], "description": "Lease of the worker running it; null when not running" }, "stuck": { "type": "boolean", "description": "Running, but its lease expired more than 300 s ago and no worker picked it up again: the worker died and none is serving this database (or all are full)." }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error of the last failed attempt, cut to 500 characters. The payload is never returned." }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "type", "status", "attempts", "maxAttempts", "runAt", "lockedUntil", "stuck", "lastError", "createdAt", "finishedAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/modules": { "get": { "operationId": "listDatabaseModules", "summary": "List modules", "description": "Superuser only. Every module known to the code with its installed version in this database.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List modules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "summary": { "type": "string" }, "version": { "type": "string" }, "installedVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "needsUpgrade": { "type": "boolean" }, "depends": { "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean" }, "autoInstall": { "type": "boolean" } }, "required": [ "name", "summary", "version", "installedVersion", "needsUpgrade", "depends", "required", "autoInstall" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/modules/{name}": { "delete": { "operationId": "uninstallModule", "summary": "Uninstall a module", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Returns the modules removed (auto-installed glue modules go with it).", "tags": [ "core" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Uninstall a module", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "uninstalled": { "type": "array", "items": { "type": "string" } } }, "required": [ "uninstalled" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/modules/install": { "post": { "operationId": "installModules", "summary": "Install modules", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Installs the modules plus missing dependencies; returns the modules newly installed, in order.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Install modules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "installed": { "type": "array", "items": { "type": "string" } } }, "required": [ "installed" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "maxItems": 200, "minItems": 1 } }, "required": [ "modules" ] } } } } } }, "/api/v1/core/modules/upgrade": { "post": { "operationId": "upgradeModules", "summary": "Upgrade modules", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Runs pending migrations of the given modules (default: all installed).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Upgrade modules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "module": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to": { "type": "string" }, "migrations": { "type": "array", "items": { "type": "string" } } }, "required": [ "module", "from", "to", "migrations" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "maxItems": 200 } }, "required": [] } } } } } }, "/api/v1/core/permissions": { "get": { "operationId": "listPermissions", "summary": "List permissions", "description": "All permission codes known to this database (core + installed modules).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "module": { "type": "string" }, "description": { "type": "string" } }, "required": [ "code", "module", "description" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_roles" ] } }, "/api/v1/core/record-rules": { "get": { "operationId": "listRecordRules", "summary": "List record rules", "description": "A non-platform admin only sees rules attached to their account's roles.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List record rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "table": { "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "template": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "appliesTo": { "enum": [ "all", "read", "write" ], "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "table", "role", "template", "params", "appliesTo", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_record_rules" ] }, "post": { "operationId": "createRecordRule", "summary": "Create a record rule", "description": "Row-level rule built from a named template; `role` null applies it to every role.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a record rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "table": { "type": "string" }, "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "template": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "appliesTo": { "enum": [ "all", "read", "write" ], "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "table", "role", "template", "params", "appliesTo", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_record_rules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "table": { "type": "string" }, "role": { "anyOf": [ { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, { "type": "null" } ], "default": null }, "template": { "enum": [ "owner", "equals", "in", "all", "expr", "attr", "via", "subtree", "recentDays" ], "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "default": {} }, "appliesTo": { "enum": [ "all", "read", "write" ], "type": "string" } }, "required": [ "table", "template" ] } } } } } }, "/api/v1/core/record-rules/{id}": { "delete": { "operationId": "deleteRecordRule", "summary": "Delete a record rule", "description": "Needs an account-level admin (403 `account_scope_required`). 404 `rule_not_found` for a rule outside the caller's account; global rules (no role) can only be deleted by a superuser (403 `superuser_required`).", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a record rule", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_record_rules" ] } }, "/api/v1/core/roles": { "get": { "operationId": "listRoles", "summary": "List roles", "description": "Platform-wide roles plus roles of the caller's account.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List roles", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "code", "name", "accountId", "permissions", "conditions" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_roles" ] }, "post": { "operationId": "createRole", "summary": "Create a role", "description": "Permissions granted must be within the caller's own permissions. `conditions` maps a permission to a condition (ADR-0021): conditions on record attributes only for permissions a module declares conditional (400 `permission_not_conditional`); conditions made only of environment checks (`{ env: \"time\" | \"weekday\" | \"ip\" }`, ADR-0046) are accepted for any permission and decide the grant per request.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a role", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "code", "name", "accountId", "permissions", "conditions" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_roles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "permissions": { "type": "array", "items": { "type": "string" }, "maxItems": 500, "default": [] }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "conditions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "code", "name" ] } } } } } }, "/api/v1/core/roles/{code}": { "patch": { "operationId": "updateRole", "summary": "Update a role", "description": "Only the sent fields change; `permissions` replaces the whole list.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a role", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "permissions": { "type": "array", "items": { "type": "string" } }, "conditions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "code", "name", "accountId", "permissions", "conditions" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_roles" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "permissions": { "type": "array", "items": { "type": "string" }, "maxItems": 500 }, "conditions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [] } } } } }, "delete": { "operationId": "deleteRole", "summary": "Delete a role", "description": "Needs an account-level admin (403 `account_scope_required` for a store-level role). Users lose the role and its record rules are deleted with it. Shared roles can only be deleted by a superuser (403 `role_read_only`).", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a role", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_roles" ] } }, "/api/v1/core/schedules": { "get": { "operationId": "listSchedules", "summary": "List scheduled tasks", "description": "Scheduled tasks of core and the installed modules: timing, latest run (runs are kept 7 days), next slot, a due slot nobody claimed yet (`dueAt`) and the latest missed slot (`missedAt`). Per-store schedules are folded into one row with store counts; `lastRun.error` is the handler's error text, cut short. Not paginated: the whole list in one page (`meta.nextCursor` is always null). Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List scheduled tasks", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "`.` / `core.`" }, "module": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Declaring module; null = core" }, "everySeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "cron": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timeZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "IANA time zone of `cron` (default `UTC`), or `store` = each store's own time zone; null with `everySeconds`" }, "catchUp": { "type": "boolean" }, "lastRun": { "anyOf": [ { "type": "object", "properties": { "slotAt": { "type": "string", "format": "date-time", "pattern": "Z$", "description": "The due moment this run was for (start of the `everySeconds` window / the cron fire time)" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ], "description": "null while running — or the process died mid-run" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Error of the run, cut to 500 characters" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Store code, for a per-store schedule" } }, "required": [ "slotAt", "startedAt", "finishedAt", "error", "store" ] }, { "type": "null" } ], "description": "Latest claimed run (per-store: the latest of any store). Runs are kept 7 days." }, "nextRunAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ], "description": "When the next slot opens (per-store: the earliest store)" }, "dueAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ], "description": "The current slot is due and no worker has claimed it yet (still inside its run window)" }, "missedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ], "description": "The latest slot whose run window passed with no worker claiming it (it will not be run late). Only judged once the task has run before." }, "stores": { "anyOf": [ { "type": "object", "properties": { "eligible": { "type": "number" }, "due": { "type": "number" }, "missed": { "type": "number" }, "failed": { "type": "number" } }, "required": [ "eligible", "due", "missed", "failed" ] }, { "type": "null" } ], "description": "Per-store schedule: eligible stores (active, customer not suspended, module enabled) and how many are due / missed / failed their latest run. null otherwise." } }, "required": [ "name", "module", "everySeconds", "cron", "timeZone", "catchUp", "lastRun", "nextRunAt", "dueAt", "missedAt", "stores" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/store-modules": { "get": { "operationId": "listCurrentStoreModules", "summary": "Modules of the current store", "description": "Every module installed in this database with its state in the current store. Acts on the current store only, within what the platform allows (installed, in the plan, assigned on a shared database). `reason`: `plan` / `platform` = the provider decides (not toggleable here), `disabled` = turned off here, `dependency_disabled` = a module it depends on is turned off here; `locked` = always on. Turning a module off keeps its data. Other server processes see the change within 5 s; the menu follows (`core.menu_changed`). 400 `store_required` without a current store; 409 `store_modules_unsupported` on turning on / off while this database is not upgraded yet (the list still works).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Modules of the current store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "depends": { "type": "array", "items": { "type": "string" } }, "locked": { "type": "boolean" }, "usable": { "type": "boolean" }, "reason": { "anyOf": [ { "enum": [ "plan", "platform", "disabled", "dependency_disabled" ], "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "group", "summary", "depends", "locked", "usable", "reason" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_store_modules" ] } }, "/api/v1/core/store-modules/disable": { "post": { "operationId": "disableCurrentStoreModules", "summary": "Turn modules off in the current store", "description": "Turns the modules off together, in one transaction; returns every module's state. 400 `module_required` for an always-on module; 409 `store_module_in_use` (`details.dependents`) when other usable modules depend on them — send them in the same request; glue modules follow automatically. A module may refuse while it has unfinished work (its own error code). Modules not installed / not allowed are ignored. 400 `unknown_modules` (`details.modules`) for names the server does not know. Acts on the current store only, within what the platform allows (installed, in the plan, assigned on a shared database). `reason`: `plan` / `platform` = the provider decides (not toggleable here), `disabled` = turned off here, `dependency_disabled` = a module it depends on is turned off here; `locked` = always on. Turning a module off keeps its data. Other server processes see the change within 5 s; the menu follows (`core.menu_changed`). 400 `store_required` without a current store; 409 `store_modules_unsupported` on turning on / off while this database is not upgraded yet (the list still works).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Turn modules off in the current store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "depends": { "type": "array", "items": { "type": "string" } }, "locked": { "type": "boolean" }, "usable": { "type": "boolean" }, "reason": { "anyOf": [ { "enum": [ "plan", "platform", "disabled", "dependency_disabled" ], "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "group", "summary", "depends", "locked", "usable", "reason" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_store_modules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "maxItems": 200, "minItems": 1 } }, "required": [ "modules" ] } } } } } }, "/api/v1/core/store-modules/enable": { "post": { "operationId": "enableCurrentStoreModules", "summary": "Turn modules back on in the current store", "description": "Turns the modules back on with the dependencies turned off here; returns every module's state. 409 `store_module_unavailable` (`details.reason`: `not_installed` / `plan` / `platform`) when the platform does not allow one of them; 400 `unknown_modules` for names the server does not know. Acts on the current store only, within what the platform allows (installed, in the plan, assigned on a shared database). `reason`: `plan` / `platform` = the provider decides (not toggleable here), `disabled` = turned off here, `dependency_disabled` = a module it depends on is turned off here; `locked` = always on. Turning a module off keeps its data. Other server processes see the change within 5 s; the menu follows (`core.menu_changed`). 400 `store_required` without a current store; 409 `store_modules_unsupported` on turning on / off while this database is not upgraded yet (the list still works).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Turn modules back on in the current store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "type": "string" }, "depends": { "type": "array", "items": { "type": "string" } }, "locked": { "type": "boolean" }, "usable": { "type": "boolean" }, "reason": { "anyOf": [ { "enum": [ "plan", "platform", "disabled", "dependency_disabled" ], "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "group", "summary", "depends", "locked", "usable", "reason" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_store_modules" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "maxItems": 200, "minItems": 1 } }, "required": [ "modules" ] } } } } } }, "/api/v1/core/store-relations": { "get": { "operationId": "listStoreRelations", "summary": "List store relations (chains / marketplaces)", "description": "Superuser only. Every `branch` (chain) and `hub_member` (marketplace) relation of the database, by store code.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List store relations (chains / marketplaces)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "parent": { "type": "string" }, "child": { "type": "string" }, "type": { "enum": [ "branch", "hub_member" ], "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "parent", "child", "type", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] }, "post": { "operationId": "addStoreRelation", "summary": "Relate two stores", "description": "`branch`: the child store inherits (reads) the parent's rows of tables its modules share with branches; same account, one parent, no cycles. `hub_member`: the hub store reads the member's rows of tables shared with hubs; may cross accounts. Writes always stay in the store's own rows.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Relate two stores", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "parent": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" }, "child": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" }, "type": { "enum": [ "branch", "hub_member" ], "type": "string" } }, "required": [ "parent", "child", "type" ] } } } } }, "delete": { "operationId": "removeStoreRelation", "summary": "Remove a store relation", "description": "Superuser only. Identified by `parent`, `child` and `type` in the query; the child / member stops reading the shared rows right away. 404 `store_relation_not_found` when no such relation exists.", "tags": [ "core" ], "parameters": [ { "name": "parent", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "child", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "type", "in": "query", "required": true, "schema": { "enum": [ "branch", "hub_member" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Remove a store relation", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/stores": { "get": { "operationId": "listStoreModules", "summary": "List stores with their modules", "description": "Superuser only. `modules` are the modules enabled per store; `alwaysOn` are required modules enabled everywhere.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List stores with their modules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" }, "accountId": { "type": "string", "format": "uuid" }, "active": { "type": "boolean" }, "defaultLang": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } }, "modules": { "type": "array", "items": { "type": "string" } }, "alwaysOn": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "name", "accountId", "active", "defaultLang", "languages", "modules", "alwaysOn" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] }, "post": { "operationId": "createStore", "summary": "Create a store", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). `languages` are the content languages of the store (default `[defaultLang]`); `defaultLang` must be one of them (default: the first language, else `en`).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "defaultLang": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "accountId", "code", "name", "active", "timezone", "currency", "defaultLang", "languages" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "format": "uuid" }, "code": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "defaultLang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "languages": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "minItems": 1, "maxItems": 20 } }, "required": [ "accountId", "code", "name" ] } } } } } }, "/api/v1/core/stores/{code}": { "patch": { "operationId": "updateStore", "summary": "Update a store", "description": "Superuser only. Rename, or change the time zone (IANA, e.g. `Asia/Ho_Chi_Minh`) that defines the store's business day, its default currency, or its content languages (`defaultLang` must be one of `languages`; removing a language keeps stored translations, they reappear when it is added back). Omitted fields keep their value. 409 `database_upgrade_required` / `store_languages_unsupported` on a database not yet upgraded.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "accountId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "timezone": { "type": "string" }, "currency": { "type": "string" }, "defaultLang": { "type": "string" }, "languages": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "accountId", "code", "name", "active", "timezone", "currency", "defaultLang", "languages" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "timezone": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "defaultLang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "languages": { "type": "array", "items": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "minItems": 1, "maxItems": 20 } }, "required": [] } } } } } }, "/api/v1/core/stores/{code}/modules": { "post": { "operationId": "enableStoreModules", "summary": "Enable modules for a store", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Adds modules (with dependencies); returns the effective set.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Enable modules for a store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "maxItems": 200, "minItems": 1 } }, "required": [ "modules" ] } } } } }, "put": { "operationId": "setStoreModules", "summary": "Set the modules of a store", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Replaces the enabled set (dependencies added); returns the effective set.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Set the modules of a store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "modules": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" }, "maxItems": 200 } }, "required": [ "modules" ] } } } } } }, "/api/v1/core/stores/{code}/modules/{name}": { "delete": { "operationId": "disableStoreModule", "summary": "Disable a module for a store", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Fails if an enabled non-glue module depends on it; returns the effective set.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Disable a module for a store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "string" } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/stores/{code}/plan": { "put": { "operationId": "setStorePlan", "summary": "Set a store's plan", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Replaces the store's plan snapshot: enabled features, quota limits (period comes from the module declaring the quota), `modules` the plan allows (their dependencies and auto-installed glue come along; `[]` = only always-on modules; null / omitted = no module limit — store enablement still applies on a shared database; a module outside them answers 404 `module_not_enabled`), expiry and grace end. 400 `unknown_plan_item` for a feature / quota / module the code does not declare; 409 `plan_modules_unsupported` when `modules` is set and the database is not upgraded to core 0047 yet. A store without a plan is unlimited.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Set a store's plan", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "store": { "type": "string" }, "plan": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "modules": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "quotas": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "limit": { "type": "number" }, "period": { "enum": [ "none", "day", "month", "year" ], "type": "string" } }, "required": [ "limit", "period" ] } } }, "required": [ "store", "plan", "features", "modules", "quotas" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,62}$" }, "features": { "type": "array", "items": { "type": "string" }, "maxItems": 500 }, "quotas": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "integer", "minimum": 0 } }, "modules": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 500 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "graceUntil": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "code", "features", "quotas" ] } } } } }, "delete": { "operationId": "removeStorePlan", "summary": "Remove a store's plan (unlimited)", "description": "Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane). Deletes the store's plan snapshot: every feature is enabled and no quota applies. 404 `store_not_found` for an unknown store code.", "tags": [ "core" ], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Remove a store's plan (unlimited)", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/core/users": { "get": { "operationId": "listUsers", "summary": "List users", "description": "Users ordered by login; a non-platform admin only sees users of their own account. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "core" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "50", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List users", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "superuser": { "type": "boolean" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "passwordChangeRequired": { "type": "boolean" }, "stores": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } }, "storeRoles": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "permissionOverrides": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "granted": { "type": "boolean" } }, "required": [ "permission", "store", "granted" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "login", "name", "active", "superuser", "accountId", "email", "emailVerifiedAt", "passwordChangeRequired", "stores", "roles", "storeRoles", "attributes", "permissionOverrides", "createdAt", "updatedAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ] }, "post": { "operationId": "createUser", "summary": "Create a user", "description": "Roles granted must be within the caller's own permissions. `email` must be unique in the database (case-insensitive, 409 `email_taken`); it starts unverified. `passwordChangeRequired: true` makes the user change the password before doing anything else: their tokens only reach their own account routes (`/auth/me`, `/auth/password`, sessions…; anything else → 403 `password_change_required`, including adding MFA factors, passkeys or API keys) until they change it with `POST /api/v1/auth/password` or a reset link.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "superuser": { "type": "boolean" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "passwordChangeRequired": { "type": "boolean" }, "stores": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } }, "storeRoles": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "permissionOverrides": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "granted": { "type": "boolean" } }, "required": [ "permission", "store", "granted" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "login", "name", "active", "superuser", "accountId", "email", "emailVerifiedAt", "passwordChangeRequired", "stores", "roles", "storeRoles", "attributes", "permissionOverrides", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "login": { "type": "string", "minLength": 1, "maxLength": 100 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "email": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email" }, { "type": "null" } ] }, "superuser": { "type": "boolean" }, "accountId": { "type": "string", "format": "uuid" }, "stores": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" }, "maxItems": 500 }, "roles": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, "maxItems": 100 }, "storeRoles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, "maxItems": 100 } }, "attributes": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z_][a-z0-9_]{0,62}$" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" } ] }, "maxItems": 100 } ] } }, "passwordChangeRequired": { "type": "boolean" } }, "required": [ "login", "name", "password" ] } } } } } }, "/api/v1/core/users/{id}": { "get": { "operationId": "getUser", "summary": "Get a user", "description": "A store-level admin only sees members of their own store; any other user is 404 `user_not_found`, like a user that does not exist.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "superuser": { "type": "boolean" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "passwordChangeRequired": { "type": "boolean" }, "stores": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } }, "storeRoles": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "permissionOverrides": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "granted": { "type": "boolean" } }, "required": [ "permission", "store", "granted" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "login", "name", "active", "superuser", "accountId", "email", "emailVerifiedAt", "passwordChangeRequired", "stores", "roles", "storeRoles", "attributes", "permissionOverrides", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ] }, "patch": { "operationId": "updateUser", "summary": "Update a user", "description": "Only the sent fields change. Setting a new password also clears the failed-login lock. Changing `email` to another address clears `emailVerifiedAt`; `null` removes it. Changing `passwordChangeRequired` signs the user out everywhere, so the next sign-in carries the new state. Setting a new `password` does not set the flag by itself: send `passwordChangeRequired: true` with it for a temporary password.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "superuser": { "type": "boolean" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "passwordChangeRequired": { "type": "boolean" }, "stores": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } }, "storeRoles": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "permissionOverrides": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "granted": { "type": "boolean" } }, "required": [ "permission", "store", "granted" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "login", "name", "active", "superuser", "accountId", "email", "emailVerifiedAt", "passwordChangeRequired", "stores", "roles", "storeRoles", "attributes", "permissionOverrides", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email" }, { "type": "null" } ] }, "password": { "type": "string", "minLength": 8, "maxLength": 128 }, "active": { "type": "boolean" }, "superuser": { "type": "boolean" }, "stores": { "type": "array", "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" }, "maxItems": 500 }, "roles": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, "maxItems": 100 }, "storeRoles": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" }, "additionalProperties": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,49}$" }, "maxItems": 100 } }, "attributes": { "type": "object", "propertyNames": { "type": "string", "pattern": "^[a-z_][a-z0-9_]{0,62}$" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "array", "items": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "number" }, { "type": "boolean" } ] }, "maxItems": 100 } ] } }, "passwordChangeRequired": { "type": "boolean" } }, "required": [] } } } } } }, "/api/v1/core/users/{id}/effective-permissions": { "get": { "operationId": "getUserEffectivePermissions", "summary": "Explain a user's effective permissions", "description": "Every permission the user has (or is denied) at `store` and where it comes from: roles (common or of that store, with conditions) and overrides. `ignored` marks a source with no effect (an override wins over roles; an unconditional grant makes conditions irrelevant; a store override replaces a common one; a broken condition is dropped). Without `store`: only common roles / overrides. A store admin sees users of its store, at its store only (403 `outside_store_scope`).", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "store", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,49}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Explain a user's effective permissions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "superuser": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "role", "store" ] } }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "effect": { "enum": [ "granted", "conditional", "denied" ], "type": "string" }, "accountWide": { "type": "boolean" }, "sources": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "role" }, "role": { "type": "string" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "condition": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "ignored": { "type": "boolean" } }, "required": [ "kind", "role", "store", "condition", "ignored" ] }, { "type": "object", "properties": { "kind": { "const": "override" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "granted": { "type": "boolean" }, "ignored": { "type": "boolean" } }, "required": [ "kind", "store", "granted", "ignored" ] } ] } } }, "required": [ "code", "effect", "accountWide", "sources" ] } } }, "required": [ "userId", "store", "superuser", "roles", "permissions" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ] } }, "/api/v1/core/users/{id}/mfa/reset": { "post": { "operationId": "resetUserMfa", "summary": "Reset a user's MFA", "description": "Removes TOTP, recovery codes and passkeys of the user and revokes all their sessions. Only a superuser can reset MFA of a superuser.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Reset a user's MFA", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ] } }, "/api/v1/core/users/{id}/permission-overrides": { "put": { "operationId": "setUserPermissionOverrides", "summary": "Replace a user's permission overrides", "description": "Grants or DENIES single permissions to one user on top of their roles. A deny wins over every grant (roles and conditions); an override for a store wins over one for all stores (`store: null`). A store admin sets only overrides of its own store (others stay); an account admin replaces them all. Granting needs the permission yourself (403 `privilege_escalation`); denying does not. Superusers ignore overrides.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a user's permission overrides", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "superuser": { "type": "boolean" }, "accountId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "emailVerifiedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "passwordChangeRequired": { "type": "boolean" }, "stores": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string" } }, "storeRoles": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "attributes": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ] } }, "permissionOverrides": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string" }, "store": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "granted": { "type": "boolean" } }, "required": [ "permission", "store", "granted" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "login", "name", "active", "superuser", "accountId", "email", "emailVerifiedAt", "passwordChangeRequired", "stores", "roles", "storeRoles", "attributes", "permissionOverrides", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "overrides": { "type": "array", "items": { "type": "object", "properties": { "permission": { "type": "string", "maxLength": 200 }, "store": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ], "default": null }, "granted": { "type": "boolean" } }, "required": [ "permission", "granted" ] }, "maxItems": 200 } }, "required": [ "overrides" ] } } } } } }, "/api/v1/core/users/{id}/unlock": { "post": { "operationId": "unlockUser", "summary": "Unlock a user's login", "description": "Clears the failed-login lock of the user.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Unlock a user's login", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_users" ] } }, "/api/v1/core/webhooks": { "get": { "operationId": "listWebhooks", "summary": "Outbound webhooks of this store", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Outbound webhooks of this store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failures": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "url", "description", "events", "active", "disabledReason", "failures", "createdAt", "updatedAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ] }, "post": { "operationId": "createWebhook", "summary": "Register an outbound webhook", "description": "`secret` signs every delivery (`X-Xforge-Signature: t=,v1=.\")>`) and is shown only now. At most 20 per store. 400 `unknown_webhook_event`; 503 `secrets_not_configured` without SECRET_ENCRYPTION_KEY.", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Register an outbound webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failures": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "secret": { "type": "string" } }, "required": [ "id", "url", "description", "events", "active", "disabledReason", "failures", "createdAt", "updatedAt", "secret" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000 }, "events": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" }, "minItems": 1, "maxItems": 100 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "url", "events" ] } } } } } }, "/api/v1/core/webhooks/{id}": { "patch": { "operationId": "updateWebhook", "summary": "Change an outbound webhook", "description": "Turning it back on (`active: true`) clears `failures` and `disabledReason`. 404 `webhook_not_found`; 400 `unknown_webhook_event`.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Change an outbound webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "disabledReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failures": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "url", "description", "events", "active", "disabledReason", "failures", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000 }, "events": { "type": "array", "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" }, "minItems": 1, "maxItems": 100 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [] } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Remove an outbound webhook (and its delivery log)", "description": "404 `webhook_not_found`.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Remove an outbound webhook (and its delivery log)", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ] } }, "/api/v1/core/webhooks/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "Latest 50 deliveries of a webhook", "description": "Kept 30 days. 404 `webhook_not_found`.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest 50 deliveries of a webhook", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event": { "type": "string" }, "status": { "enum": [ "pending", "done", "failed", "skipped" ], "type": "string" }, "attempts": { "type": "number" }, "lastStatus": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lastError": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "event", "status", "attempts", "lastStatus", "lastError", "createdAt", "deliveredAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ] } }, "/api/v1/core/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "summary": "Replace the signing secret", "description": "The old secret stops working at once; the new one is shown only now. 404 `webhook_not_found`; 503 `secrets_not_configured`.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Replace the signing secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "secret": { "type": "string" } }, "required": [ "secret" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ] } }, "/api/v1/core/webhooks/{id}/test": { "post": { "operationId": "testWebhook", "summary": "Send a test event (core.ping)", "description": "Queued like a real delivery (see `listWebhookDeliveries`); `data` = `{ message: \"ping\" }`. 404 `webhook_not_found`; 409 `webhook_inactive` when it is turned off.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "202": { "description": "Send a test event (core.ping)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "queued": { "type": "number" } }, "required": [ "queued" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ] } }, "/api/v1/core/webhooks/deliveries/{id}/redeliver": { "post": { "operationId": "redeliverWebhook", "summary": "Send a past delivery again", "description": "A new delivery with the same `data` (new `id`). 404 `webhook_delivery_not_found`; 409 `webhook_inactive`.", "tags": [ "core" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "202": { "description": "Send a past delivery again", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ] } }, "/api/v1/core/webhooks/events": { "get": { "operationId": "listWebhookEvents", "summary": "Webhook events available in this store", "description": "Events of modules installed and enabled in the current store that the caller may read (each event has its module's read permission).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook events available in this store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "module": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "module", "description" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "core.manage_webhooks" ] } }, "/api/v1/core/workers": { "get": { "operationId": "listWorkers", "summary": "List background job worker processes", "description": "Job worker processes that serve this database (heartbeat at most every 30 s, or every `JOBS_POLL_SECONDS` when longer): host, build, database filter, running jobs, last full pass. `state`: `alive`, `silent` (no heartbeat for 3 intervals, at least 90 s — died or hangs) or `stopped` (shut down cleanly). No `alive` row = no worker runs this database's jobs and schedules. Rows not updated for 24 hours are dropped. Newest start first, at most 500 rows; not paginated (`meta.nextCursor` is always null). Superuser of a standalone deployment only (403 `managed_by_platform` under a control plane).", "tags": [ "core" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List background job worker processes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Process id, random at start-up" }, "host": { "type": "string", "description": "`HOSTNAME` of the process (or the OS host name)" }, "pid": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "version": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "`FORGE_BUILD` of the process; null = not set" }, "databaseFilter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Databases the worker serves: `DB_FILTER` as an anchored regular expression `^(?:…)$`; null = every database. Always null on the tenant route (`/api/v1/core/workers`): the filter names other databases" }, "databases": { "type": "number", "description": "Databases served at the last heartbeat" }, "running": { "type": "number", "description": "Jobs running in the process" }, "concurrency": { "type": "number", "description": "Most jobs the process runs at once (`JOBS_CONCURRENCY`)" }, "beatSeconds": { "type": "number", "description": "Heartbeat interval of the process (seconds)" }, "state": { "enum": [ "alive", "silent", "stopped" ], "type": "string", "description": "`alive`; `silent` = no heartbeat for 3 intervals (at least 90 s) — the process died or hangs; `stopped` = shut down cleanly" }, "seenSecondsAgo": { "type": "number", "description": "Seconds since the last heartbeat (database clock)" }, "startedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "seenAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastScanAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ], "description": "End of the last full pass over every served database" }, "stoppedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "host", "pid", "version", "databaseFilter", "databases", "running", "concurrency", "beatSeconds", "state", "seenSecondsAgo", "startedAt", "seenAt", "lastScanAt", "stoppedAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "superuser" ] } }, "/api/v1/coupons": { "get": { "operationId": "listCoupons", "summary": "List coupons", "description": "Coupons of the current store, newest first. `q` searches the code and name; filter `active`, `customer_id`. `redeemedCount` = uses on orders not cancelled. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "coupons" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: coupons.code, coupons.name" }, "description": "Case-insensitive substring search in: coupons.code, coupons.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "customer_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List coupons", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string" }, "maxDiscount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "productInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, { "type": "null" } ] } }, "required": [ "productId", "productInfo" ] } }, "redeemedCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "discountType", "discountValue", "maxDiscount", "minSubtotal", "currency", "startsAt", "endsAt", "usageLimit", "perCustomerLimit", "customerId", "customerInfo", "products", "redeemedCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.read" ] }, "post": { "operationId": "createCoupon", "summary": "Create a coupon", "description": "Created in the current store, in the store's currency. `code` is stored upper-case and unique per store among rows not in the trash (409 `coupon_code_exists`). `discountType: percent` → `discountValue` is a percentage (0, 100] with an optional `maxDiscount` cap; `fixed` → an amount. `productIds` empty = the whole order; a product not in the store → 409 `coupon_product_not_found`. `customerId` must be a customer of the store. Buyers type the code into the cart (`setMyCartCodes`); one coupon per order.", "tags": [ "coupons" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a coupon", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string" }, "maxDiscount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "productInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, { "type": "null" } ] } }, "required": [ "productId", "productInfo" ] } }, "redeemedCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "discountType", "discountValue", "maxDiscount", "minSubtotal", "currency", "startsAt", "endsAt", "usageLimit", "perCustomerLimit", "customerId", "customerInfo", "products", "redeemedCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "maxDiscount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200, "default": [] } }, "required": [ "code", "name", "discountType", "discountValue" ] } } } } } }, "/api/v1/coupons/{id}": { "get": { "operationId": "getCoupon", "summary": "Get a coupon", "description": "404 `coupon_not_found` when it does not exist in the current store or is in the trash.", "tags": [ "coupons" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a coupon", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string" }, "maxDiscount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "productInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, { "type": "null" } ] } }, "required": [ "productId", "productInfo" ] } }, "redeemedCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "discountType", "discountValue", "maxDiscount", "minSubtotal", "currency", "startsAt", "endsAt", "usageLimit", "perCustomerLimit", "customerId", "customerInfo", "products", "redeemedCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.read" ] }, "put": { "operationId": "replaceCoupon", "summary": "Replace a coupon (full update)", "description": "Replaces every field (fields not sent take their defaults). 409 `coupon_code_exists`.", "tags": [ "coupons" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a coupon (full update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string" }, "maxDiscount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "productInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, { "type": "null" } ] } }, "required": [ "productId", "productInfo" ] } }, "redeemedCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "discountType", "discountValue", "maxDiscount", "minSubtotal", "currency", "startsAt", "endsAt", "usageLimit", "perCustomerLimit", "customerId", "customerInfo", "products", "redeemedCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "maxDiscount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200, "default": [] } }, "required": [ "code", "name", "discountType", "discountValue" ] } } } } }, "patch": { "operationId": "updateCoupon", "summary": "Update a coupon (partial)", "description": "Fields not sent stay unchanged; `null` clears an optional field. 409 `coupon_code_exists`.", "tags": [ "coupons" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a coupon (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string" }, "maxDiscount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "productInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, { "type": "null" } ] } }, "required": [ "productId", "productInfo" ] } }, "redeemedCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "discountType", "discountValue", "maxDiscount", "minSubtotal", "currency", "startsAt", "endsAt", "usageLimit", "perCustomerLimit", "customerId", "customerInfo", "products", "redeemedCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "maxDiscount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "integer", "minimum": 1 }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "productIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 200 } }, "required": [] } } } } }, "delete": { "operationId": "deleteCoupon", "summary": "Delete a coupon", "description": "Moves it to the trash (restore with POST /coupons/{id}/restore). `?force=true` deletes it permanently and additionally requires `coupon.hard_delete`. Modules depending on it may refuse.", "tags": [ "coupons" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a coupon", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.delete" ] } }, "/api/v1/coupons/{id}/restore": { "post": { "operationId": "restoreCoupon", "summary": "Restore a coupon from the trash", "description": "404 when it is not in the trash; 409 `coupon_code_exists` when another row took its code meanwhile.", "tags": [ "coupons" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a coupon from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "discountType": { "enum": [ "percent", "fixed" ], "type": "string" }, "discountValue": { "type": "string" }, "maxDiscount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minSubtotal": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "usageLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "perCustomerLimit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "productInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, { "type": "null" } ] } }, "required": [ "productId", "productInfo" ] } }, "redeemedCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "discountType", "discountValue", "maxDiscount", "minSubtotal", "currency", "startsAt", "endsAt", "usageLimit", "perCustomerLimit", "customerId", "customerInfo", "products", "redeemedCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.restore" ] } }, "/api/v1/coupons/options": { "get": { "operationId": "listCouponOptions", "summary": "List coupon options", "description": "Same query as GET /coupons, trimmed to `{ id, code, name, active }` for pickers.", "tags": [ "coupons" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: coupons.code, coupons.name" }, "description": "Case-insensitive substring search in: coupons.code, coupons.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "customer_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List coupon options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.read" ] } }, "/api/v1/coupons/trash": { "get": { "operationId": "listCouponTrash", "summary": "List coupons in the trash", "description": "Coupons moved to the trash, most recently deleted first, with who deleted them. Restore with POST /coupons/{id}/restore, delete permanently with DELETE /coupons/{id}?force=true. Cursor-paginated.", "tags": [ "coupons" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: coupons.code, coupons.name" }, "description": "Case-insensitive substring search in: coupons.code, coupons.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List coupons in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "coupon.restore" ] } }, "/api/v1/customer-type-price-rules": { "get": { "operationId": "listCustomerTypePriceRules", "summary": "List customer type price rules", "description": "Price rules of customer types, newest first. Filter by `customer_type_id`, `price_list_id`, `active`. Cursor-paginated.", "tags": [ "customer-type-price-rules" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "customer_type_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "price_list_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List customer type price rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "customerTypeId": { "type": "string", "format": "uuid" }, "customerTypeInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "priceListId": { "type": "string", "format": "uuid" }, "priceListInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "discountPct": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "customerTypeId", "customerTypeInfo", "priceListId", "priceListInfo", "discountPct", "startsAt", "endsAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type_price_rule.read" ] }, "post": { "operationId": "createCustomerTypePriceRule", "summary": "Create a customer type price rule", "description": "One rule per customer type × price list (409 `customer_type_price_rule_exists`); both must be of the current store (404 `customer_type_price_rule_ref_not_found`). `discountPct`: (0, 100], 2 decimals; `endsAt` after `startsAt`. Customers of the type get the prices of the price list in quotes (its `audience` is ignored — the rule says who; its currency, channel and period still apply), minus `discountPct` % when set; the lowest of catalog / price lists / rules wins. Rules of an inactive or trashed type do nothing.", "tags": [ "customer-type-price-rules" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a customer type price rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "customerTypeId": { "type": "string", "format": "uuid" }, "customerTypeInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "priceListId": { "type": "string", "format": "uuid" }, "priceListInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "discountPct": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "customerTypeId", "customerTypeInfo", "priceListId", "priceListInfo", "discountPct", "startsAt", "endsAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type_price_rule.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerTypeId": { "type": "string", "format": "uuid" }, "priceListId": { "type": "string", "format": "uuid" }, "discountPct": { "anyOf": [ { "type": "string", "pattern": "^(100(\\.0{1,2})?|[0-9]{1,2}(\\.[0-9]{1,2})?)$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "customerTypeId", "priceListId" ] } } } } } }, "/api/v1/customer-type-price-rules/{id}": { "get": { "operationId": "getCustomerTypePriceRule", "summary": "Get a customer type price rule", "description": "404 `customer_type_price_rule_not_found`.", "tags": [ "customer-type-price-rules" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a customer type price rule", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "customerTypeId": { "type": "string", "format": "uuid" }, "customerTypeInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "priceListId": { "type": "string", "format": "uuid" }, "priceListInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "discountPct": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "customerTypeId", "customerTypeInfo", "priceListId", "priceListInfo", "discountPct", "startsAt", "endsAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type_price_rule.read" ] }, "patch": { "operationId": "updateCustomerTypePriceRule", "summary": "Update a customer type price rule (partial)", "description": "Fields not sent stay unchanged; `null` clears. The customer type and price list are fixed — delete and create another rule to change them. Customers of the type get the prices of the price list in quotes (its `audience` is ignored — the rule says who; its currency, channel and period still apply), minus `discountPct` % when set; the lowest of catalog / price lists / rules wins. Rules of an inactive or trashed type do nothing.", "tags": [ "customer-type-price-rules" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a customer type price rule (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "customerTypeId": { "type": "string", "format": "uuid" }, "customerTypeInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "priceListId": { "type": "string", "format": "uuid" }, "priceListInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "discountPct": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "customerTypeId", "customerTypeInfo", "priceListId", "priceListInfo", "discountPct", "startsAt", "endsAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type_price_rule.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "discountPct": { "anyOf": [ { "type": "string", "pattern": "^(100(\\.0{1,2})?|[0-9]{1,2}(\\.[0-9]{1,2})?)$" }, { "type": "null" } ] }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [] } } } } }, "delete": { "operationId": "deleteCustomerTypePriceRule", "summary": "Delete a customer type price rule", "description": "Deletes the rule.", "tags": [ "customer-type-price-rules" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a customer type price rule", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type_price_rule.delete" ] } }, "/api/v1/customer-type-price-rules/options": { "get": { "operationId": "listCustomerTypePriceRuleOptions", "summary": "List customer type price rule options", "description": "Same query as GET /customer-type-price-rules, trimmed for pickers.", "tags": [ "customer-type-price-rules" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "customer_type_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "price_list_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List customer type price rule options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customerTypeId": { "type": "string", "format": "uuid" }, "customerTypeInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "priceListId": { "type": "string", "format": "uuid" }, "priceListInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "id", "customerTypeId", "customerTypeInfo", "priceListId", "priceListInfo", "active" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type_price_rule.read" ] } }, "/api/v1/customer-types": { "get": { "operationId": "listCustomerTypes", "summary": "List customer types", "description": "Customer types of the current store, default sort by `name`. `q` searches the code and name. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "customer-types" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `name`" }, "description": "Sort field; prefix `-` for descending. Default `name`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: customer_types.code, customer_types.name" }, "description": "Case-insensitive substring search in: customer_types.code, customer_types.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List customer types", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.read" ] }, "post": { "operationId": "createCustomerType", "summary": "Create a customer type", "description": "Created in the current store. `code` is unique per store among rows not in the trash (409 `customer_type_code_exists`).", "tags": [ "customer-types" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a customer type", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "code", "name" ] } } } } } }, "/api/v1/customer-types/{id}": { "get": { "operationId": "getCustomerType", "summary": "Get a customer type", "description": "404 `customer_type_not_found` when it does not exist in the current store or is in the trash.", "tags": [ "customer-types" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a customer type", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.read" ] }, "put": { "operationId": "replaceCustomerType", "summary": "Replace a customer type (full update)", "description": "Replaces every field (fields not sent take their defaults). 409 `customer_type_code_exists`.", "tags": [ "customer-types" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a customer type (full update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "code", "name" ] } } } } }, "patch": { "operationId": "updateCustomerType", "summary": "Update a customer type (partial)", "description": "Fields not sent stay unchanged; `null` clears an optional field. 409 `customer_type_code_exists`.", "tags": [ "customer-types" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a customer type (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [] } } } } }, "delete": { "operationId": "deleteCustomerType", "summary": "Delete a customer type", "description": "Moves it to the trash (restore with POST /customer-types/{id}/restore). `?force=true` deletes it permanently and additionally requires `customer_type.hard_delete`. Modules depending on it may refuse.", "tags": [ "customer-types" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a customer type", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.delete" ] } }, "/api/v1/customer-types/{id}/restore": { "post": { "operationId": "restoreCustomerType", "summary": "Restore a customer type from the trash", "description": "404 when it is not in the trash; 409 `customer_type_code_exists` when another row took its code meanwhile.", "tags": [ "customer-types" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a customer type from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.restore" ] } }, "/api/v1/customer-types/members": { "get": { "operationId": "listCustomerTypeMembers", "summary": "Customers and their customer type", "description": "One row per customer that has a type in the current store (customers removed from the store are left out), newest assignment first. `customerTypeInfo` is null when the type is in the trash (the customer keeps it until set again). Filter by `customer_type_id` (customers of a type) or `customer_id` (the type of a customer). Cursor-paginated.", "tags": [ "customer-types" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "assigned_at", "-assigned_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-assigned_at`" }, "description": "Sort field; prefix `-` for descending. Default `-assigned_at`" }, { "name": "customer_type_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customers and their customer type", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerTypeId": { "type": "string", "format": "uuid" }, "customerTypeInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "assignedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "assignedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "assignedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "customerId", "customerInfo", "customerTypeId", "customerTypeInfo", "assignedAt", "assignedBy", "assignedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.read" ] } }, "/api/v1/customer-types/members/{customerId}": { "put": { "operationId": "setCustomerType", "summary": "Set the customer type of a customer", "description": "`customerTypeId: null` removes the type. A customer has at most one type per store; setting another moves it (new `assignedAt` / `assignedBy`), setting the same one changes nothing. 404 `customer_type_customer_not_found` when the customer is not a customer of the store; 404 `customer_type_not_found`; 409 `customer_type_inactive`. Returns the assignment, `data: null` after removing.", "tags": [ "customer-types" ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Set the customer type of a customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerTypeId": { "type": "string", "format": "uuid" }, "customerTypeInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "assignedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "assignedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "assignedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "customerId", "customerInfo", "customerTypeId", "customerTypeInfo", "assignedAt", "assignedBy", "assignedByInfo" ] }, { "type": "null" } ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.assign" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerTypeId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "customerTypeId" ] } } } } } }, "/api/v1/customer-types/options": { "get": { "operationId": "listCustomerTypeOptions", "summary": "List customer type options", "description": "Same query as GET /customer-types, trimmed to `{ id, code, name, active }` for pickers.", "tags": [ "customer-types" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `name`" }, "description": "Sort field; prefix `-` for descending. Default `name`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: customer_types.code, customer_types.name" }, "description": "Case-insensitive substring search in: customer_types.code, customer_types.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List customer type options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.read" ] } }, "/api/v1/customer-types/trash": { "get": { "operationId": "listCustomerTypeTrash", "summary": "List customer types in the trash", "description": "Customer types moved to the trash, most recently deleted first, with who deleted them. Restore with POST /customer-types/{id}/restore, delete permanently with DELETE /customer-types/{id}?force=true. Cursor-paginated.", "tags": [ "customer-types" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: customer_types.code, customer_types.name" }, "description": "Case-insensitive substring search in: customer_types.code, customer_types.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List customer types in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "customer_type.restore" ] } }, "/api/v1/data/datasets": { "get": { "operationId": "listDatasets", "summary": "Datasets the user can export or import", "description": "Modules installed and enabled in the current store; only datasets the user may export or import (each dataset has its own export / import permission). Labels and column headers follow `x-lang` / `Accept-Language`.", "tags": [ "data" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Datasets the user can export or import", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "module": { "type": "string" }, "label": { "type": "string" }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "header": { "type": "string" }, "required": { "type": "boolean" }, "exportOnly": { "type": "boolean" } }, "required": [ "key", "header", "required", "exportOnly" ] } }, "canExport": { "type": "boolean" }, "canImport": { "type": "boolean" } }, "required": [ "name", "module", "label", "columns", "canExport", "canImport" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "type": "null" } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/data/datasets/{name}/export": { "get": { "operationId": "exportDataset", "summary": "Export a dataset as CSV or Excel", "description": "`format=csv` (UTF-8 with BOM) or `xlsx`. At most 100000 rows — more: 400 `export_too_large`. 403 `forbidden` without the dataset's export permission (`canExport`); 404 `dataset_not_found`; 503 `data_transfer_busy` when too many exports / imports run.", "tags": [ "data" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "csv", "xlsx" ], "type": "string", "default": "csv" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Export a dataset as CSV or Excel", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Content-Disposition": { "description": "attachment; filename=…", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/data/datasets/{name}/exports": { "post": { "operationId": "startDatasetExport", "summary": "Export a dataset in the background", "description": "For large exports: runs as the caller (same permissions / record rules as `exportDataset`), up to 500000 rows (CSV) / 100000 (Excel). Realtime event `core.data_export` (`{ exportId, status }`) when finished; then `downloadDataExport` (24 h). 403 `forbidden` without the export permission, `api_key_forbidden` / `impersonation_forbidden` (API key / signed in as another user); 404 `dataset_not_found`; 409 `data_exports_unsupported` (database not upgraded yet).", "tags": [ "data" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "csv", "xlsx" ], "type": "string", "default": "csv" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "202": { "description": "Export a dataset in the background", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dataset": { "type": "string" }, "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "status": { "enum": [ "pending", "running", "done", "failed" ], "type": "string" }, "rows": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "dataset", "format", "status", "rows", "error", "createdAt", "finishedAt", "expiresAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/data/datasets/{name}/import": { "post": { "operationId": "importDataset", "summary": "Import a CSV or Excel file", "description": "Body = the file (`format=csv`, UTF-8, separator `,` `;` or tab; or `xlsx`, first sheet). First row = headers (column key, English or translated header; `*` ignored). At most 5000 rows / 10 MB. Every row is checked first; with errors (or `dryRun=true`) nothing is written and `errors` lists them by line. Otherwise the whole file is written in one transaction — the first failing row cancels it (reported with its line). Errors: `rule` = cell rule (`required`, `type`…), `unknown_column` or `error` (while writing — see `code`). 403 `forbidden` without the import permission (`canImport`); 400 `import_file_invalid` / `import_too_many_rows`, 413 `import_too_large`, 503 `data_transfer_busy`.", "tags": [ "data" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "csv", "xlsx" ], "type": "string", "default": "csv" } }, { "name": "dryRun", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string", "default": "false" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Import a CSV or Excel file", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "applied": { "type": "boolean" }, "dryRun": { "type": "boolean" }, "rows": { "type": "number" }, "created": { "type": "number" }, "updated": { "type": "number" }, "skipped": { "type": "number" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "number" }, "column": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rule": { "type": "string" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "type": "string" } }, "required": [ "line", "column", "rule", "code", "message" ] } } }, "required": [ "applied", "dryRun", "rows", "created", "updated", "skipped", "errors" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/v1/data/datasets/{name}/imports": { "post": { "operationId": "startDatasetImport", "summary": "Import a large CSV or Excel file in the background", "description": "Body = the file (as `importDataset`), up to 20000 rows / 50 MB. Runs as the caller (same checks and rules as `importDataset`); `dryRun=true` only checks. Realtime event `core.data_import` (`{ importId, status }`) when finished; result + errors by line: `getDataImport` (kept 7 days). 403 `forbidden` without the import permission; 429 `too_many_imports`; 409 `data_imports_unsupported`; 413 `import_too_large`; 408 `import_upload_timeout`; 404 `dataset_not_found`; 403 `api_key_forbidden` / `impersonation_forbidden`. `error` of a failed import: `forbidden`, `dataset_not_found`, `import_file_invalid`, `import_too_many_rows`, `import_too_large`, `import_file_missing`, `import_abandoned` (never ran), `internal_error`.", "tags": [ "data" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "csv", "xlsx" ], "type": "string", "default": "csv" } }, { "name": "dryRun", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string", "default": "false" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "202": { "description": "Import a large CSV or Excel file in the background", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dataset": { "type": "string" }, "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "dryRun": { "type": "boolean" }, "status": { "enum": [ "pending", "running", "done", "failed" ], "type": "string" }, "applied": { "type": "boolean" }, "rows": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "skipped": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "dataset", "format", "dryRun", "status", "applied", "rows", "created", "updated", "skipped", "error", "errorCount", "createdAt", "finishedAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/v1/data/datasets/{name}/template": { "get": { "operationId": "datasetImportTemplate", "summary": "Empty import file (header row only)", "description": "Columns accepted by the import, in the request language; required ones end with `*`.", "tags": [ "data" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "csv", "xlsx" ], "type": "string", "default": "csv" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Empty import file (header row only)", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Content-Disposition": { "description": "attachment; filename=…", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/data/exports": { "get": { "operationId": "listDataExports", "summary": "My background exports in this store", "description": "Newest first, at most 50 (files live 24 h).", "tags": [ "data" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "My background exports in this store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dataset": { "type": "string" }, "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "status": { "enum": [ "pending", "running", "done", "failed" ], "type": "string" }, "rows": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "dataset", "format", "status", "rows", "error", "createdAt", "finishedAt", "expiresAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "type": "null" } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/data/exports/{id}/file": { "get": { "operationId": "downloadDataExport", "summary": "Download a finished background export", "description": "Only the caller's own export in the current store, while it lives. 404 `export_not_found`, 409 `export_not_ready` (pending / running / failed). The export permission is checked again.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Download a finished background export", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Content-Disposition": { "description": "attachment; filename=…", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/data/imports": { "get": { "operationId": "listDataImports", "summary": "My background imports in this store", "description": "Newest first, at most 50 (kept 7 days).", "tags": [ "data" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "My background imports in this store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dataset": { "type": "string" }, "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "dryRun": { "type": "boolean" }, "status": { "enum": [ "pending", "running", "done", "failed" ], "type": "string" }, "applied": { "type": "boolean" }, "rows": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "skipped": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "dataset", "format", "dryRun", "status", "applied", "rows", "created", "updated", "skipped", "error", "errorCount", "createdAt", "finishedAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "type": "null" } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/data/imports/{id}": { "get": { "operationId": "getDataImport", "summary": "A background import with its errors by line", "description": "Only the caller's own import in the current store. 404 `import_not_found`.", "tags": [ "data" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A background import with its errors by line", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "dataset": { "type": "string" }, "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "dryRun": { "type": "boolean" }, "status": { "enum": [ "pending", "running", "done", "failed" ], "type": "string" }, "applied": { "type": "boolean" }, "rows": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "created": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "updated": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "skipped": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "errorCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "errors": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "number" }, "column": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rule": { "type": "string" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "message": { "type": "string" } }, "required": [ "line", "column", "rule", "code", "message" ] } } }, "required": [ "id", "dataset", "format", "dryRun", "status", "applied", "rows", "created", "updated", "skipped", "error", "errorCount", "createdAt", "finishedAt", "errors" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/files": { "get": { "operationId": "listFiles", "summary": "List files", "description": "Files of the current store, newest first by default (`sort`: `created_at`, `size`, `name`). `q` searches the file name (accent-insensitive); `content_type` / `content_type.in` filter by exact MIME type, `kind` by group (`image`, `video`, `audio`, `other`); `owner_id` = files uploaded by that user. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "files" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "50", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "size", "-size", "name", "-name" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: files.name" }, "description": "Case-insensitive substring search in: files.name" }, { "name": "content_type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "content_type.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated text values (max 100)" }, "description": "in: comma-separated text values (max 100)" }, { "name": "owner_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "kind", "in": "query", "required": false, "schema": { "enum": [ "image", "video", "audio", "other" ], "type": "string", "description": "Content group by MIME type: `image/*`, `video/*`, `audio/*`, or `other` (none of these)" }, "description": "Content group by MIME type: `image/*`, `video/*`, `audio/*`, or `other` (none of these)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List files", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" }, "storeId": { "type": "string", "format": "uuid" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ownerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "contentType", "size", "sha256", "storeId", "ownerId", "ownerInfo", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.read" ] }, "post": { "operationId": "uploadFile", "summary": "Upload a file", "description": "Send multipart/form-data with field `file`, or the raw bytes as the body with `?name=` and the file's Content-Type. Limited to the server's max upload size (413 above it); use the chunked upload endpoints for larger files. Stored in the current store, owned by the caller.", "tags": [ "files" ], "parameters": [ { "name": "name", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "201": { "description": "Upload a file", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" }, "storeId": { "type": "string", "format": "uuid" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ownerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "contentType", "size", "sha256", "storeId", "ownerId", "ownerInfo", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.write" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" } }, "required": [ "file" ] } } } } } }, "/api/v1/files/{id}": { "get": { "operationId": "getFile", "summary": "Get file metadata", "description": "Metadata only (name, type, size, SHA-256); the bytes come from GET /files/{id}/content. 404 `file_not_found` when the file does not exist in the current store.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get file metadata", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" }, "storeId": { "type": "string", "format": "uuid" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ownerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "contentType", "size", "sha256", "storeId", "ownerId", "ownerInfo", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.read" ] }, "delete": { "operationId": "deleteFile", "summary": "Delete a file", "description": "Removes the metadata row and the stored object.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a file", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.write" ] } }, "/api/v1/files/{id}/content": { "get": { "operationId": "downloadFile", "summary": "Download file content", "description": "Streams the stored bytes with the file's own Content-Type, always as an attachment (Content-Disposition) with nosniff.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Download file content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "content-disposition": { "description": "`attachment` with the stored file name (RFC 6266)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.read" ] } }, "/api/v1/files/uploads": { "post": { "operationId": "startUpload", "summary": "Start a chunked upload", "description": "Creates an upload session for a large file. The server fixes the part size (`partSize`, default 16 MiB, enlarged when needed to stay within the part-count limit); parts 1..n-1 must be exactly `partSize` bytes and the last part the remainder. Sessions expire after 24 hours.", "tags": [ "files" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Start a chunked upload", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "partSize": { "type": "number" }, "parts": { "type": "number" }, "received": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "number" }, "size": { "type": "number" }, "etag": { "type": "string" }, "sha256": { "type": "string" } }, "required": [ "n", "size", "etag", "sha256" ] } }, "status": { "enum": [ "uploading", "completing", "completed", "aborted" ], "type": "string" }, "storeId": { "type": "string", "format": "uuid" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ownerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "contentType", "size", "partSize", "parts", "received", "status", "storeId", "ownerId", "ownerInfo", "createdAt", "expiresAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "size": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "partSize": { "anyOf": [ { "type": "integer", "minimum": 5242880, "maximum": 104857600 }, { "type": "null" } ] } }, "required": [ "name", "size" ] } } } } } }, "/api/v1/files/uploads/{id}": { "get": { "operationId": "getUpload", "summary": "Get a chunked upload session", "description": "Status and the parts received so far, so a client can resume by sending only the missing parts. Only the session owner (or a superuser) can see it.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a chunked upload session", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "partSize": { "type": "number" }, "parts": { "type": "number" }, "received": { "type": "array", "items": { "type": "object", "properties": { "n": { "type": "number" }, "size": { "type": "number" }, "etag": { "type": "string" }, "sha256": { "type": "string" } }, "required": [ "n", "size", "etag", "sha256" ] } }, "status": { "enum": [ "uploading", "completing", "completed", "aborted" ], "type": "string" }, "storeId": { "type": "string", "format": "uuid" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ownerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "contentType", "size", "partSize", "parts", "received", "status", "storeId", "ownerId", "ownerInfo", "createdAt", "expiresAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.write" ] }, "delete": { "operationId": "abortUpload", "summary": "Abort a chunked upload", "description": "Discards the session and any parts already sent.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Abort a chunked upload", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.write" ] } }, "/api/v1/files/uploads/{id}/complete": { "post": { "operationId": "completeUpload", "summary": "Complete a chunked upload", "description": "Assembles all parts into a file whose id equals the upload id. 409 `upload_incomplete` lists missing parts. Idempotent: calling again after success returns the same file.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Complete a chunked upload", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" }, "storeId": { "type": "string", "format": "uuid" }, "ownerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ownerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "name", "contentType", "size", "sha256", "storeId", "ownerId", "ownerInfo", "createdAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.write" ] } }, "/api/v1/files/uploads/{id}/parts/{n}": { "put": { "operationId": "uploadPart", "summary": "Upload one part", "description": "The raw body is exactly part `n` (1-based). Its size must match the size the server expects for that part. Re-sending a part overwrites it.", "tags": [ "files" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "n", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,4}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Upload one part", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "n": { "type": "number" }, "size": { "type": "number" }, "etag": { "type": "string" }, "sha256": { "type": "string" } }, "required": [ "n", "size", "etag", "sha256" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.write" ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/v1/files/usage": { "get": { "operationId": "getFileUsage", "summary": "Storage used and its limits", "description": "Bytes used by the current store and by all stores of its customer, with the limits in MB: `limitMb` of `store` comes from the store's plan, of `account` from the customer's limits (null = unlimited). Uploads beyond either limit get 403 `quota_exceeded` (`details.scope` = `store` | `account`). `maxUploadBytes` / `maxFileBytes` = the largest file accepted in one request / in parts right now (server ceiling, lowered by the plan and the customer's limits); larger gets 413 `file_too_large`.", "tags": [ "files" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Storage used and its limits", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "store": { "type": "object", "properties": { "usedBytes": { "type": "number" }, "limitMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "usedBytes", "limitMb" ] }, "account": { "type": "object", "properties": { "usedBytes": { "type": "number" }, "limitMb": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "usedBytes", "limitMb" ] }, "maxUploadBytes": { "type": "number" }, "maxFileBytes": { "type": "number" } }, "required": [ "store", "account", "maxUploadBytes", "maxFileBytes" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "files.read" ] } }, "/api/v1/gift-cards": { "get": { "operationId": "listGiftCards", "summary": "List gift cards", "description": "Gift cards of the current store, newest first. Filter `code` matches the WHOLE code only (case, spaces and dashes ignored) — no partial search. `code` is masked (`****ABCD`, `codeMasked: true`) unless the user has `gift_card.view_code`. Cursor-paginated.", "tags": [ "gift-cards" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List gift cards", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "codeMasked": { "type": "boolean" }, "currency": { "type": "string" }, "initialAmount": { "type": "string" }, "balance": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "codeMasked", "currency", "initialAmount", "balance", "expiresAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.read" ] }, "post": { "operationId": "createGiftCard", "summary": "Create a gift card", "description": "Issues a card in the store's currency with `amount` as its balance (rounded to the currency's minor unit). `code` absent = a random 16-character code; a custom code is stored upper-case without spaces / dashes (409 `gift_card_code_exists`). The response carries the FULL code once — hand it to the buyer; it is not replayed for a repeated `Idempotency-Key` (409 `idempotency_response_withheld`). Buyers type the code into the cart (`setMyCartCodes`); it pays the rest of the order after discounts, taxes and shipping.", "tags": [ "gift-cards" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a gift card", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "codeMasked": { "type": "boolean" }, "currency": { "type": "string" }, "initialAmount": { "type": "string" }, "balance": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "codeMasked", "currency", "initialAmount", "balance", "expiresAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9 -]{12,64}$" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "amount" ] } } } } } }, "/api/v1/gift-cards/{id}": { "get": { "operationId": "getGiftCard", "summary": "Get a gift card", "description": "404 `gift_card_not_found`. `code` is masked (`****ABCD`, `codeMasked: true`) unless the user has `gift_card.view_code`.", "tags": [ "gift-cards" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a gift card", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "codeMasked": { "type": "boolean" }, "currency": { "type": "string" }, "initialAmount": { "type": "string" }, "balance": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "codeMasked", "currency", "initialAmount", "balance", "expiresAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.read" ] }, "patch": { "operationId": "updateGiftCard", "summary": "Update a gift card (partial)", "description": "Fields not sent stay unchanged; `null` clears `expiresAt` / `notes`. The code, currency and amount are fixed — change the balance with POST /gift-cards/{id}/adjust.", "tags": [ "gift-cards" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a gift card (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "codeMasked": { "type": "boolean" }, "currency": { "type": "string" }, "initialAmount": { "type": "string" }, "balance": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "codeMasked", "currency", "initialAmount", "balance", "expiresAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [] } } } } }, "delete": { "operationId": "deleteGiftCard", "summary": "Delete a gift card", "description": "Deletes a card that was never used; 409 `gift_card_in_use` once it has any redemption / adjustment — deactivate it (`active: false`) instead.", "tags": [ "gift-cards" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a gift card", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.delete" ] } }, "/api/v1/gift-cards/{id}/adjust": { "post": { "operationId": "adjustGiftCard", "summary": "Top up or deduct a gift card balance", "description": "Signed `amount` (positive = top up, negative = deduct), rounded to the currency's minor unit, with a required `note`; recorded in the card's ledger. The balance never goes below zero (409 `gift_card_insufficient_balance`, `details.balance`). 404 `gift_card_not_found`. `code` is masked (`****ABCD`, `codeMasked: true`) unless the user has `gift_card.view_code`.", "tags": [ "gift-cards" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Top up or deduct a gift card balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "codeMasked": { "type": "boolean" }, "currency": { "type": "string" }, "initialAmount": { "type": "string" }, "balance": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "codeMasked", "currency", "initialAmount", "balance", "expiresAt", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.adjust" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "note": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "amount", "note" ] } } } } } }, "/api/v1/gift-cards/{id}/transactions": { "get": { "operationId": "listGiftCardTransactions", "summary": "Ledger of a gift card", "description": "Every balance change, newest first: `issue`, `redeem` (paid an order, negative), `release` (money back: order cancelled, or POST /gift-cards/order-refunds), `adjust` (by staff). `balance` = balance after the change. 404 `gift_card_not_found`. Cursor-paginated.", "tags": [ "gift-cards" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ledger of a gift card", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "issue", "redeem", "release", "adjust" ], "type": "string" }, "amount": { "type": "string" }, "balance": { "type": "string" }, "orderId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "type", "amount", "balance", "orderId", "orderInfo", "note", "createdAt", "createdBy", "createdByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.read" ] } }, "/api/v1/gift-cards/options": { "get": { "operationId": "listGiftCardOptions", "summary": "List gift card options", "description": "Same query as GET /gift-cards, trimmed to `{ id, code, balance, active }`. `code` is masked (`****ABCD`, `codeMasked: true`) unless the user has `gift_card.view_code`.", "tags": [ "gift-cards" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "code", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List gift card options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "balance": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "balance", "active" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.read" ] } }, "/api/v1/gift-cards/order-refunds": { "get": { "operationId": "listGiftCardOrderRefundables", "summary": "What can still go back to gift cards for an order", "description": "One row per gift card used for the order `order_id`: `redeemed`, `released`, `refundable` (`0` when the order is not paid yet or was cancelled). Codes are always masked. Empty when no card paid for the order. 404 `gift_card_order_not_found`.", "tags": [ "gift-cards" ], "parameters": [ { "name": "order_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "What can still go back to gift cards for an order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "giftCardId": { "type": "string", "format": "uuid" }, "giftCardInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "currency": { "type": "string" }, "balance": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "currency", "balance", "active" ] }, "redeemed": { "type": "string" }, "released": { "type": "string" }, "refundable": { "type": "string" } }, "required": [ "giftCardId", "giftCardInfo", "redeemed", "released", "refundable" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.read" ] }, "post": { "operationId": "refundOrderToGiftCard", "summary": "Give the gift card part of an order back to the card", "description": "Staff decide the amount: nothing splits a refund between cash and cards automatically (POST /refunds pays back cash / bank transfer only, capped by `grandTotal`). Adds a `release` to the ledger of the card that paid for the order, with `reason` as its `note`. `amount` (rounded to the currency's minor unit) cannot exceed what the order still owes that card — cancelling the order later only returns the rest, and nothing can be refunded after a cancel (409 `gift_card_refund_exceeds`, `details.available`; also when the card did not pay for this order). The order's status and payment status do not change. 404 `gift_card_order_not_found`, `gift_card_not_found`; 409 `gift_card_refund_order_not_paid` (cancel the order instead).", "tags": [ "gift-cards" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Give the gift card part of an order back to the card", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "giftCardId": { "type": "string", "format": "uuid" }, "giftCardInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "currency": { "type": "string" }, "balance": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "currency", "balance", "active" ] }, "redeemed": { "type": "string" }, "released": { "type": "string" }, "refundable": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "amount": { "type": "string" } }, "required": [ "giftCardId", "giftCardInfo", "redeemed", "released", "refundable", "orderId", "orderInfo", "amount" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "gift_card.adjust" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "giftCardId": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reason": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "orderId", "giftCardId", "amount" ] } } } } } }, "/api/v1/me/events": { "get": { "operationId": "streamMyEvents", "summary": "Realtime events (Server-Sent Events)", "description": "Long-lived `text/event-stream` for the signed-in user in the current store. Each event: `id` (pass back as `Last-Event-ID` header or `lastEventId` query when reconnecting), `event` = topic (`core.notification`, `core.menu_changed`, `.`), `data` = JSON `{ topic, data, createdAt }` with references only — re-read through the API. First event is `ready` (no `id`, `data` = `{ storeId }`). `core.menu_changed` (no `id`, not replayed) = the user's `GET /api/v1/menu` changed (module enabled / disabled, plan, permissions) — re-read it; the server checks every 5 s, so also re-read the menu on every `ready`. `: ping` comments every 25 s. The stream ends when the access token expires (refresh, then reconnect). Events are hints: after a long disconnect re-read state. 503 `realtime_unavailable` when disabled or this server / database is full; 429 `too_many_streams` above 5 streams per user. Not available to API keys.", "tags": [ "me" ], "parameters": [ { "name": "lastEventId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 64 } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Realtime events (Server-Sent Events)", "content": { "text/event-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/me/notifications": { "get": { "operationId": "listMyNotifications", "summary": "List my notifications", "description": "Notifications for the signed-in user in the current store, newest first. `unread=true` keeps unread only. `title` follows `x-lang` / `Accept-Language`. Not available to API keys (403 `api_key_forbidden`). Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "me" ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d+$" } }, { "name": "unread", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List my notifications", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "title": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "null" } ] } }, "link": { "anyOf": [ { "type": "object", "properties": { "key": { "type": "string" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "key", "id" ] }, { "type": "null" } ] }, "readAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "kind", "title", "params", "link", "readAt", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/me/notifications/{id}/read": { "post": { "operationId": "markMyNotificationRead", "summary": "Mark one of my notifications as read", "description": "404 `notification_not_found` when it is not the caller's in the current store. Marking twice is fine.", "tags": [ "me" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Mark one of my notifications as read", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/me/notifications/read-all": { "post": { "operationId": "markAllMyNotificationsRead", "summary": "Mark all my notifications as read", "description": "In the current store. Returns how many changed. Not while signed in as another user (403 `impersonation_forbidden`).", "tags": [ "me" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Mark all my notifications as read", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "updated": { "type": "number" } }, "required": [ "updated" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/me/notifications/unread-count": { "get": { "operationId": "countMyUnreadNotifications", "summary": "Count my unread notifications", "description": "Unread notifications for the signed-in user in the current store, for the badge. Counts up to 999; `capped: true` = there are more.", "tags": [ "me" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Count my unread notifications", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "count": { "type": "number" }, "capped": { "type": "boolean" } }, "required": [ "count", "capped" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/me/push": { "get": { "operationId": "getMyPushConfig", "summary": "Web Push configuration", "description": "`publicKey` is the VAPID key for `PushManager.subscribe({ applicationServerKey })`; `enabled: false` when the server has no Web Push keys.", "tags": [ "me" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Web Push configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "publicKey": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "enabled", "publicKey" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/me/push/subscriptions": { "get": { "operationId": "listMyPushSubscriptions", "summary": "My browsers with Web Push in this store", "tags": [ "me" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "My browsers with Web Push in this store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastSuccessAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "label", "lastSuccessAt", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createMyPushSubscription", "summary": "Turn on Web Push for this browser", "description": "Body = `PushSubscription.toJSON()` (+ optional `label`). The endpoint must be a known browser push service. Subscribing the same endpoint again replaces it. At most 10 browsers per user per store (the oldest is dropped). 409 `push_disabled` when the server has no Web Push keys.", "tags": [ "me" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Turn on Web Push for this browser", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "type": "string", "maxLength": 1000 }, "keys": { "type": "object", "properties": { "p256dh": { "type": "string", "pattern": "^[A-Za-z0-9_-]+={0,2}$", "maxLength": 100 }, "auth": { "type": "string", "pattern": "^[A-Za-z0-9_-]+={0,2}$", "maxLength": 40 } }, "required": [ "p256dh", "auth" ] }, "label": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "expirationTime": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "endpoint", "keys" ] } } } } } }, "/api/v1/me/push/subscriptions/{id}": { "delete": { "operationId": "deleteMyPushSubscription", "summary": "Turn off Web Push for a browser", "description": "404 `push_subscription_not_found` when it is not the caller's in the current store.", "tags": [ "me" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Turn off Web Push for a browser", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/menu": { "get": { "operationId": "listMenu", "summary": "Admin menu entries the current user can use", "description": "Menu entries declared by modules, filtered to the current user and store: the module is installed and enabled in the store, the user holds `permission` (with or without conditions) and the store's plan has the entry's feature. `key` is stable (`.`) — map it to your own screen. Labels follow `x-lang` / `Accept-Language` like error messages. Sorted by `group`, then `order`, then `key`.", "tags": [ "menu" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Admin menu entries the current user can use", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "module": { "type": "string" }, "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "type": "string" }, "permission": { "type": "string" }, "icon": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "order": { "type": "number" }, "screen": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "revision": { "type": "string" } }, "required": [ "type", "revision" ] }, { "type": "null" } ] } }, "required": [ "key", "module", "group", "label", "permission", "icon", "order", "screen" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/menu/{key}/screen": { "get": { "operationId": "getMenuScreen", "summary": "Data description of a menu entry's admin screen", "description": "Lets a generic CMS screen draw the entry without code for it: `type` (`crud`, `custom`; new types will be added — show \"not supported\" for an unknown `type` or a `schemaVersion` above the one you know), `layout` (per type: columns, filters, form fields with the field's JSON Schema, enums), and `operations` — method, path, permissions, plan features and JSON Schemas of every operation the screen uses, so it can be called by method + path (`call()` of the SDK runtime). Gated exactly like `listMenu`: 404 `menu_entry_not_found` when the entry is not in the caller's menu in this store (unknown key, module not installed / enabled, missing permission, feature not in plan); 404 `menu_screen_not_declared` when the module declares no screen for it. The description does not depend on the caller: show buttons like elsewhere (permissions ∪ conditionalPermissions; `conditional` operations may answer 403 `condition_not_met`). Labels follow `x-lang` / `Accept-Language`. Cache by (`key`, `revision`, language) — `listMenu` carries the current `revision`.", "tags": [ "menu" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Data description of a menu entry's admin screen", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "schemaVersion": { "type": "number" }, "key": { "type": "string" }, "module": { "type": "string" }, "type": { "type": "string" }, "revision": { "type": "string" }, "title": { "type": "string" }, "layout": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "operations": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } }, "conditional": { "type": "boolean" }, "features": { "type": "array", "items": { "type": "string" } }, "idempotent": { "type": "boolean" }, "status": { "type": "number" }, "bodyContentType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rawResponse": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "params": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "query": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "body": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "response": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "meta": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "method", "path", "permissions", "conditional", "features", "idempotent", "status", "bodyContentType", "rawResponse", "params", "query", "body", "response", "meta" ] } } }, "required": [ "schemaVersion", "key", "module", "type", "revision", "title", "layout", "operations" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/modules": { "get": { "operationId": "listModules", "summary": "Modules for building the menu", "description": "Every module known to the code: whether it is installed in this database and usable in the current store. `group` is the module's area (`catalog`, `inventory`…) for grouping a menu; null = no area.", "tags": [ "modules" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Modules for building the menu", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "summary": { "type": "string" }, "depends": { "type": "array", "items": { "type": "string" } }, "group": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "installed": { "type": "boolean" }, "enabled": { "type": "boolean" } }, "required": [ "name", "version", "summary", "depends", "group", "installed", "enabled" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/orders": { "get": { "operationId": "listOrders", "summary": "List orders", "description": "Orders of the current store, newest first. Filter by `status`, `payment_status`, `payment_method`, `channel`, `customer_id`; `q` searches the number. Cursor-paginated.", "tags": [ "orders" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: orders.number" }, "description": "Case-insensitive substring search in: orders.number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: placed, confirmed, fulfilled, completed, cancelled" }, "description": "eq: one of: placed, confirmed, fulfilled, completed, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "payment_status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: unpaid, paid, partially_refunded, refunded" }, "description": "eq: one of: unpaid, paid, partially_refunded, refunded" }, { "name": "payment_status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: web, pos, admin, marketplace, b2b" }, "description": "eq: one of: web, pos, admin, marketplace, b2b" }, { "name": "channel.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "payment_method", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: prepaid, cod" }, "description": "eq: one of: prepaid, cod" }, { "name": "payment_method.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "customer_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerName": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "actions", "sourceType", "customerId", "customerInfo", "customerName", "warehouseId", "warehouseInfo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.read" ] }, "post": { "operationId": "createOrder", "summary": "Create an order", "description": "Staff places an order (channel `admin`) in ONE transaction: re-prices the lines, reserves stock in the store's default warehouse, creates the payment intent. `customerId` must be a customer of this store (otherwise 404 `order_customer_not_found`, same answer for an unknown id); without it `contact.name` is required (400 `order_contact_required`). Errors of one line carry `error.at = lines.` (short stock: 409 `stock_insufficient_available`). `paymentMethod`: `prepaid` (default) or `cod` (409 `order_cod_unavailable` before the database is upgraded). A zero-total order is always `prepaid` and already paid. `paymentCode` is the transfer content of the payment intent.", "tags": [ "orders" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create an order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerName": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "actions", "sourceType", "customerId", "customerInfo", "customerName", "warehouseId", "warehouseInfo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] }, "paymentCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "order", "paymentCode" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "variantId", "qty" ] }, "minItems": 1, "maxItems": 200 }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 }, "shippingFee": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] } }, "required": [] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "phone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1, "maxLength": 255 }, "line2": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "name", "line1", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" } }, "required": [ "lines" ] } } } } } }, "/api/v1/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get an order with its lines", "tags": [ "orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get an order with its lines", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerName": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "actions", "sourceType", "customerId", "customerInfo", "customerName", "warehouseId", "warehouseInfo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.read" ] } }, "/api/v1/orders/{id}/cancel": { "post": { "operationId": "cancelOrder", "summary": "Cancel an order", "description": "placed / confirmed → cancelled: releases the reserved stock and cancels the pending payment intent; extension modules undo what they committed (`order.cancelling`). A paid order needs a full refund first (`paymentStatus: refunded` — module `refund`; otherwise 409 `order_paid_cancel`); a fulfilled order cannot be cancelled; extension modules may block (e.g. 409 `shipment_on_the_way`).", "tags": [ "orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Cancel an order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerName": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "actions", "sourceType", "customerId", "customerInfo", "customerName", "warehouseId", "warehouseInfo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.cancel" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [] } } } } } }, "/api/v1/orders/{id}/complete": { "post": { "operationId": "completeOrder", "summary": "Complete an order", "description": "fulfilled → completed.", "tags": [ "orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Complete an order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerName": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "actions", "sourceType", "customerId", "customerInfo", "customerName", "warehouseId", "warehouseInfo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.manage" ] } }, "/api/v1/orders/{id}/confirm": { "post": { "operationId": "confirmOrder", "summary": "Confirm an order", "description": "placed → confirmed (an order confirms itself when its payment arrives). 409 `order_invalid_transition`.", "tags": [ "orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Confirm an order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerName": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "actions", "sourceType", "customerId", "customerInfo", "customerName", "warehouseId", "warehouseInfo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.manage" ] } }, "/api/v1/orders/{id}/fulfill": { "post": { "operationId": "fulfillOrder", "summary": "Fulfil an order (ship the goods)", "description": "confirmed → fulfilled: the reserved goods leave the order's warehouse (one `PX-…` voucher, purpose `sale`); the shipped lots / serials are kept on each line (`detail`). Payment is not required (cash on delivery). Errors of one line carry `error.at = items.`.", "tags": [ "orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Fulfil an order (ship the goods)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerName": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "actions", "sourceType", "customerId", "customerInfo", "customerName", "warehouseId", "warehouseInfo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.manage" ] } }, "/api/v1/orders/{id}/record-payment": { "post": { "operationId": "recordOrderPayment", "summary": "Record money received outside the gateways", "description": "For a `prepaid`, unpaid, open order: staff received the money in cash, by transfer or card. `amount` must equal `grandTotal` (409 `order_payment_amount_mismatch`). The money goes on the order's payment intent; the order turns `paid` (and confirms itself) when the resulting job runs, usually within seconds — wait for the realtime `order.changed` or read the order again. 409 `order_payment_not_recordable`, `payment_intent_not_payable`.", "tags": [ "orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Record money received outside the gateways", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "channel": { "enum": [ "web", "pos", "admin", "marketplace", "b2b" ], "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" }, "currency": { "type": "string" }, "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" }, "itemCount": { "type": "number" }, "placedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "confirmedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "fulfilledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "paymentIntentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "paymentIntentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "sourceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "customerName": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "customerEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "customerPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "line1": { "type": "string" }, "line2": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "country": { "type": "string" } }, "required": [ "name", "phone", "line1", "line2", "ward", "district", "province", "postalCode", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cancelReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total", "detail" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } } }, "required": [ "id", "storeId", "number", "channel", "status", "paymentStatus", "paymentMethod", "currency", "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal", "itemCount", "placedAt", "confirmedAt", "fulfilledAt", "completedAt", "cancelledAt", "paidAt", "paymentIntentId", "paymentIntentInfo", "actions", "sourceType", "customerId", "customerInfo", "customerName", "warehouseId", "warehouseInfo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "customerEmail", "customerPhone", "shippingAddress", "note", "cancelReason", "items", "adjustments" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.record_payment" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "enum": [ "cash", "bank_transfer", "card", "other" ], "type": "string" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reference": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "method", "amount" ] } } } } } }, "/api/v1/orders/quote": { "post": { "operationId": "quoteOrder", "summary": "Preview the totals of an order to create", "description": "Takes the body of `createOrder` and prices the lines for channel `admin` (taxes, extension modules, `codes`, `shippingFee`; `contact`, `shippingAddress`, `note`, `paymentMethod` do not change the result, but are still validated: send only the fields that price, not a half-filled form). Nothing is held and stock is not checked. Errors of one line carry `error.at = lines.`. 404 `order_customer_not_found` when `customerId` is not a customer of this store; 400 `price_code_not_recognized`; 429 when too many codes were wrong.", "tags": [ "orders" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Preview the totals of an order to create", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "currency": { "type": "string" }, "day": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] } }, "required": [ "currency", "day", "lines", "adjustments", "totals" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "order.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "variantId", "qty" ] }, "minItems": 1, "maxItems": 200 }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 }, "shippingFee": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "contact": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] } }, "required": [] }, "shippingAddress": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "phone": { "anyOf": [ { "type": "string", "maxLength": 50 }, { "type": "null" } ] }, "line1": { "type": "string", "minLength": 1, "maxLength": 255 }, "line2": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "ward": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "district": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "province": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "postalCode": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "name", "line1", "country" ] }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "paymentMethod": { "enum": [ "prepaid", "cod" ], "type": "string" } }, "required": [ "lines" ] } } } } } }, "/api/v1/payments/intents": { "get": { "operationId": "listPaymentIntents", "summary": "List payment intents", "description": "Payment intents of the current store, newest first. Filters: `status` (`status.in=pending,paid`), `reference_type`, `reference_id`. Cursor-paginated.", "tags": [ "payments" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "expires_at", "-expires_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: pending, paid, expired, cancelled" }, "description": "eq: one of: pending, paid, expired, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "reference_type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "reference_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List payment intents", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "transfer": { "anyOf": [ { "type": "object", "properties": { "bankBin": { "type": "string" }, "account": { "type": "string" }, "holder": { "type": "string" }, "content": { "type": "string" }, "amount": { "type": "string" }, "qrUrl": { "type": "string" } }, "required": [ "bankBin", "account", "holder", "content", "amount", "qrUrl" ] }, { "type": "null" } ] }, "momo": { "type": "boolean" }, "einvoiceBuyer": { "anyOf": [ { "type": "object", "properties": { "buyerType": { "enum": [ "personal", "company" ], "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nationalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "buyerType", "name", "legalName", "taxCode", "address", "email", "phone", "nationalId" ] }, { "type": "null" } ] }, "einvoice": { "anyOf": [ { "type": "object", "properties": { "status": { "enum": [ "pending", "submitted", "issued", "failed", "unconfirmed", "skipped" ], "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceSeries": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxAuthorityCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "invoiceNumber", "invoiceSeries", "taxAuthorityCode", "pdfUrl", "issuedAt", "error" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "code", "status", "amount", "currency", "paidAmount", "paidAt", "description", "referenceType", "referenceId", "expiresAt", "transfer", "momo", "einvoiceBuyer", "einvoice", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.read" ] }, "post": { "operationId": "createPaymentIntent", "summary": "Create a payment intent", "description": "An amount to collect from a buyer. Returns the payment `code` (the transfer content), bank transfer details + VietQR image when SePay is set up (`transfer`), and whether MoMo is available (`momo`). VND only for now. 400 `payment_amount_invalid`.", "tags": [ "payments" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a payment intent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "transfer": { "anyOf": [ { "type": "object", "properties": { "bankBin": { "type": "string" }, "account": { "type": "string" }, "holder": { "type": "string" }, "content": { "type": "string" }, "amount": { "type": "string" }, "qrUrl": { "type": "string" } }, "required": [ "bankBin", "account", "holder", "content", "amount", "qrUrl" ] }, { "type": "null" } ] }, "momo": { "type": "boolean" }, "einvoiceBuyer": { "anyOf": [ { "type": "object", "properties": { "buyerType": { "enum": [ "personal", "company" ], "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nationalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "buyerType", "name", "legalName", "taxCode", "address", "email", "phone", "nationalId" ] }, { "type": "null" } ] }, "einvoice": { "anyOf": [ { "type": "object", "properties": { "status": { "enum": [ "pending", "submitted", "issued", "failed", "unconfirmed", "skipped" ], "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceSeries": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxAuthorityCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "invoiceNumber", "invoiceSeries", "taxAuthorityCode", "pdfUrl", "issuedAt", "error" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "code", "status", "amount", "currency", "paidAmount", "paidAt", "description", "referenceType", "referenceId", "expiresAt", "transfer", "momo", "einvoiceBuyer", "einvoice", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.write" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "currency": { "enum": [ "VND" ], "type": "string", "default": "VND" }, "description": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string", "pattern": "^[a-z][a-z0-9_.]{0,49}$" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "expiresInMinutes": { "type": "integer", "minimum": 5, "maximum": 43200, "default": 1440 }, "einvoiceBuyer": { "anyOf": [ { "type": "object", "properties": { "buyerType": { "enum": [ "personal", "company" ], "type": "string" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "legalName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}(-\\d{3})?$|^\\d{13}$" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "pattern": "^\\+?\\d{8,15}$" }, { "type": "null" } ] }, "nationalId": { "anyOf": [ { "type": "string", "pattern": "^\\d{9}$|^\\d{12}$" }, { "type": "null" } ] } }, "required": [ "buyerType" ] }, { "type": "null" } ] } }, "required": [ "amount" ] } } } } } }, "/api/v1/payments/intents/{id}": { "get": { "operationId": "getPaymentIntent", "summary": "Get a payment intent", "description": "Status, amount and how the buyer can pay: `transfer` (bank account, transfer content, VietQR) when bank transfer is configured, `momo` when MoMo is available. 404 `payment_intent_not_found` when the intent does not exist in the current store.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a payment intent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "transfer": { "anyOf": [ { "type": "object", "properties": { "bankBin": { "type": "string" }, "account": { "type": "string" }, "holder": { "type": "string" }, "content": { "type": "string" }, "amount": { "type": "string" }, "qrUrl": { "type": "string" } }, "required": [ "bankBin", "account", "holder", "content", "amount", "qrUrl" ] }, { "type": "null" } ] }, "momo": { "type": "boolean" }, "einvoiceBuyer": { "anyOf": [ { "type": "object", "properties": { "buyerType": { "enum": [ "personal", "company" ], "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nationalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "buyerType", "name", "legalName", "taxCode", "address", "email", "phone", "nationalId" ] }, { "type": "null" } ] }, "einvoice": { "anyOf": [ { "type": "object", "properties": { "status": { "enum": [ "pending", "submitted", "issued", "failed", "unconfirmed", "skipped" ], "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceSeries": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxAuthorityCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "invoiceNumber", "invoiceSeries", "taxAuthorityCode", "pdfUrl", "issuedAt", "error" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "code", "status", "amount", "currency", "paidAmount", "paidAt", "description", "referenceType", "referenceId", "expiresAt", "transfer", "momo", "einvoiceBuyer", "einvoice", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.read" ] } }, "/api/v1/payments/intents/{id}/cancel": { "post": { "operationId": "cancelPaymentIntent", "summary": "Cancel a pending payment intent", "description": "Money that arrives later for a cancelled intent goes to the unmatched queue. 409 `payment_intent_not_payable` when it is not pending.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Cancel a pending payment intent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "transfer": { "anyOf": [ { "type": "object", "properties": { "bankBin": { "type": "string" }, "account": { "type": "string" }, "holder": { "type": "string" }, "content": { "type": "string" }, "amount": { "type": "string" }, "qrUrl": { "type": "string" } }, "required": [ "bankBin", "account", "holder", "content", "amount", "qrUrl" ] }, { "type": "null" } ] }, "momo": { "type": "boolean" }, "einvoiceBuyer": { "anyOf": [ { "type": "object", "properties": { "buyerType": { "enum": [ "personal", "company" ], "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nationalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "buyerType", "name", "legalName", "taxCode", "address", "email", "phone", "nationalId" ] }, { "type": "null" } ] }, "einvoice": { "anyOf": [ { "type": "object", "properties": { "status": { "enum": [ "pending", "submitted", "issued", "failed", "unconfirmed", "skipped" ], "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceSeries": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxAuthorityCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "invoiceNumber", "invoiceSeries", "taxAuthorityCode", "pdfUrl", "issuedAt", "error" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "code", "status", "amount", "currency", "paidAmount", "paidAt", "description", "referenceType", "referenceId", "expiresAt", "transfer", "momo", "einvoiceBuyer", "einvoice", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.write" ] } }, "/api/v1/payments/intents/{id}/einvoice/retry": { "post": { "operationId": "retryPaymentIntentEinvoice", "summary": "Retry the VAT e-invoice of a paid intent", "description": "Re-queues a `failed`, `unconfirmed` or `skipped` e-invoice (409 `payment_einvoice_not_retryable` otherwise) — fix the cause first (store e-invoice settings, buyer tax code…). The next attempt still looks the invoice up at SePay before sending, so nothing is issued twice.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Retry the VAT e-invoice of a paid intent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "transfer": { "anyOf": [ { "type": "object", "properties": { "bankBin": { "type": "string" }, "account": { "type": "string" }, "holder": { "type": "string" }, "content": { "type": "string" }, "amount": { "type": "string" }, "qrUrl": { "type": "string" } }, "required": [ "bankBin", "account", "holder", "content", "amount", "qrUrl" ] }, { "type": "null" } ] }, "momo": { "type": "boolean" }, "einvoiceBuyer": { "anyOf": [ { "type": "object", "properties": { "buyerType": { "enum": [ "personal", "company" ], "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nationalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "buyerType", "name", "legalName", "taxCode", "address", "email", "phone", "nationalId" ] }, { "type": "null" } ] }, "einvoice": { "anyOf": [ { "type": "object", "properties": { "status": { "enum": [ "pending", "submitted", "issued", "failed", "unconfirmed", "skipped" ], "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceSeries": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxAuthorityCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "invoiceNumber", "invoiceSeries", "taxAuthorityCode", "pdfUrl", "issuedAt", "error" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "code", "status", "amount", "currency", "paidAmount", "paidAt", "description", "referenceType", "referenceId", "expiresAt", "transfer", "momo", "einvoiceBuyer", "einvoice", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.reconcile" ] } }, "/api/v1/payments/intents/{id}/momo": { "post": { "operationId": "createPaymentIntentMomoCheckout", "summary": "Start a MoMo payment for an intent", "description": "Creates a MoMo order with the store's own merchant keys and returns where to pay (`payUrl`, `deeplink`, `qrCodeUrl`). Each call makes a new MoMo order. 409 `payment_provider_not_configured` / `payment_intent_not_payable`, 400 `momo_amount_out_of_range`, 502 `momo_rejected`, 503 `momo_unavailable` / `payment_callback_url_missing`.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Start a MoMo payment for an intent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "intentId": { "type": "string", "format": "uuid" }, "orderId": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "payUrl": { "type": "string" }, "deeplink": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qrCodeUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "intentId", "orderId", "amount", "currency", "payUrl", "deeplink", "qrCodeUrl", "expiresAt" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.write" ] } }, "/api/v1/payments/intents/{id}/momo/query": { "post": { "operationId": "queryPaymentIntentMomo", "summary": "Ask MoMo about the intent's latest MoMo order", "description": "Reconciles when MoMo's IPN was lost: a paid order is recorded exactly like the IPN (same MoMo transaction id, so a late IPN adds nothing). Only MoMo's final failure codes count as `failed`; errors of the query itself are `unknown`. 409 `payment_momo_order_missing`.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Ask MoMo about the intent's latest MoMo order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "orderId": { "type": "string" }, "status": { "enum": [ "paid", "pending", "failed", "unknown" ], "type": "string" }, "resultCode": { "type": "number" }, "message": { "type": "string" }, "transId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "amount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "intent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "transfer": { "anyOf": [ { "type": "object", "properties": { "bankBin": { "type": "string" }, "account": { "type": "string" }, "holder": { "type": "string" }, "content": { "type": "string" }, "amount": { "type": "string" }, "qrUrl": { "type": "string" } }, "required": [ "bankBin", "account", "holder", "content", "amount", "qrUrl" ] }, { "type": "null" } ] }, "momo": { "type": "boolean" }, "einvoiceBuyer": { "anyOf": [ { "type": "object", "properties": { "buyerType": { "enum": [ "personal", "company" ], "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nationalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "buyerType", "name", "legalName", "taxCode", "address", "email", "phone", "nationalId" ] }, { "type": "null" } ] }, "einvoice": { "anyOf": [ { "type": "object", "properties": { "status": { "enum": [ "pending", "submitted", "issued", "failed", "unconfirmed", "skipped" ], "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceSeries": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxAuthorityCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "invoiceNumber", "invoiceSeries", "taxAuthorityCode", "pdfUrl", "issuedAt", "error" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "code", "status", "amount", "currency", "paidAmount", "paidAt", "description", "referenceType", "referenceId", "expiresAt", "transfer", "momo", "einvoiceBuyer", "einvoice", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "orderId", "status", "resultCode", "message", "transId", "amount", "intent" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.reconcile" ] } }, "/api/v1/payments/transactions": { "get": { "operationId": "listPaymentTransactions", "summary": "List incoming transactions", "description": "Money received from the gateways, newest first. `status=unmatched` is the reconciliation queue (`unmatchedReason`: no_code, intent_not_found, not_payable, currency_mismatch, underpaid). Filters: `status`, `provider`, `intent_id`.", "tags": [ "payments" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "received_at", "-received_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-received_at`" }, "description": "Sort field; prefix `-` for descending. Default `-received_at`" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: matched, unmatched, ignored" }, "description": "eq: one of: matched, unmatched, ignored" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "intent_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "intent_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List incoming transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "externalId": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "intentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "intentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "status": { "enum": [ "matched", "unmatched", "ignored" ], "type": "string" }, "unmatchedReason": { "anyOf": [ { "enum": [ "no_code", "intent_not_found", "not_payable", "currency_mismatch", "underpaid" ], "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "provider", "externalId", "amount", "currency", "content", "intentId", "intentInfo", "status", "unmatchedReason", "note", "receivedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.read" ] } }, "/api/v1/payments/transactions/{id}/ignore": { "post": { "operationId": "ignorePaymentTransaction", "summary": "Ignore an unmatched transaction", "description": "Takes it out of the reconciliation queue (refunded, not a sale…). 409 `payment_transaction_not_unmatched`.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Ignore an unmatched transaction", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "externalId": { "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "intentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "intentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "id", "number", "status", "amount", "currency", "paidAmount", "paidAt" ] }, { "type": "null" } ] }, "status": { "enum": [ "matched", "unmatched", "ignored" ], "type": "string" }, "unmatchedReason": { "anyOf": [ { "enum": [ "no_code", "intent_not_found", "not_payable", "currency_mismatch", "underpaid" ], "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "provider", "externalId", "amount", "currency", "content", "intentId", "intentInfo", "status", "unmatchedReason", "note", "receivedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.reconcile" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "required": [] } } } } } }, "/api/v1/payments/transactions/{id}/match": { "post": { "operationId": "matchPaymentTransaction", "summary": "Match an unmatched transaction to an intent", "description": "Marks the intent paid with the transaction's amount (also when it is less than due, or the intent already expired). 404 `payment_transaction_not_found` / `payment_intent_not_found`, 409 `payment_transaction_not_unmatched` / `payment_intent_not_payable` / `payment_currency_mismatch`.", "tags": [ "payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Match an unmatched transaction to an intent", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "code": { "type": "string" }, "status": { "enum": [ "pending", "paid", "expired", "cancelled" ], "type": "string" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "paidAmount": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "transfer": { "anyOf": [ { "type": "object", "properties": { "bankBin": { "type": "string" }, "account": { "type": "string" }, "holder": { "type": "string" }, "content": { "type": "string" }, "amount": { "type": "string" }, "qrUrl": { "type": "string" } }, "required": [ "bankBin", "account", "holder", "content", "amount", "qrUrl" ] }, { "type": "null" } ] }, "momo": { "type": "boolean" }, "einvoiceBuyer": { "anyOf": [ { "type": "object", "properties": { "buyerType": { "enum": [ "personal", "company" ], "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "legalName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nationalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "buyerType", "name", "legalName", "taxCode", "address", "email", "phone", "nationalId" ] }, { "type": "null" } ] }, "einvoice": { "anyOf": [ { "type": "object", "properties": { "status": { "enum": [ "pending", "submitted", "issued", "failed", "unconfirmed", "skipped" ], "type": "string" }, "invoiceNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "invoiceSeries": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxAuthorityCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pdfUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "issuedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "invoiceNumber", "invoiceSeries", "taxAuthorityCode", "pdfUrl", "issuedAt", "error" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "code", "status", "amount", "currency", "paidAmount", "paidAt", "description", "referenceType", "referenceId", "expiresAt", "transfer", "momo", "einvoiceBuyer", "einvoice", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.reconcile" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "intentId": { "type": "string", "format": "uuid" } }, "required": [ "intentId" ] } } } } } }, "/api/v1/payments/webhooks": { "get": { "operationId": "getPaymentWebhookUrls", "summary": "Webhook URLs to paste into the payment gateways", "description": "URLs of this store's SePay webhook (paste into SePay with authentication `API Key` = the store's `payments.sepay` webhookKey) and MoMo IPN (sent to MoMo automatically on every checkout). null when the server has no public URL (PUBLIC_API_URL).", "tags": [ "payments" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Webhook URLs to paste into the payment gateways", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "sepay": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "momo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "sepay", "momo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "payments.read" ] } }, "/api/v1/plan": { "get": { "operationId": "getStorePlan", "summary": "The current store's plan, limits and usage", "description": "`plan` is null and `features` null when the store has no plan (unlimited). `modules` lists the modules the plan allows (their dependencies and auto-installed glue are usable too; `[]` = only always-on modules); null = no module limit. Counter quotas report usage in the current period, computed in the store's time zone; `accountLimits` are the customer-wide caps across all stores.", "tags": [ "plan" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The current store's plan, limits and usage", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "plan": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "active", "grace", "expired" ], "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "graceUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "features": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "modules": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "quotas": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "limit": { "type": "number" }, "period": { "enum": [ "none", "day", "month", "year" ], "type": "string" }, "used": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "key", "limit", "period", "used" ] } }, "accountLimits": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } } }, "required": [ "plan", "state", "expiresAt", "graceUntil", "features", "modules", "quotas", "accountLimits" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/pre-order-settings": { "get": { "operationId": "listPreOrderSettings", "summary": "List pre-order settings", "description": "Pre-order (backorder) settings of the current store, newest first. Filter by `variant_id` / `allow_backorder`. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "pre-order-settings" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "variant_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "allow_backorder", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List pre-order settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "allowBackorder": { "type": "boolean" }, "maxBackorderQty": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedRestockAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "variantId", "variantInfo", "allowBackorder", "maxBackorderQty", "expectedRestockAt", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "pre_order_setting.read" ] }, "post": { "operationId": "createPreOrderSetting", "summary": "Create a pre-order setting", "description": "One setting per variant (409 `pre_order_setting_variant_exists`); 404 `pre_order_setting_variant_not_found` when the variant is not in the current store. While `allowBackorder` is on, orders may reserve this variant beyond the available quantity of a warehouse by up to `maxBackorderQty` (base unit, per warehouse; null = no limit). Only variants without batch / serial tracking can be sold beyond stock.", "tags": [ "pre-order-settings" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a pre-order setting", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "allowBackorder": { "type": "boolean" }, "maxBackorderQty": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedRestockAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "variantId", "variantInfo", "allowBackorder", "maxBackorderQty", "expectedRestockAt", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "pre_order_setting.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "allowBackorder": { "type": "boolean", "default": true }, "maxBackorderQty": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "expectedRestockAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "variantId" ] } } } } } }, "/api/v1/pre-order-settings/{id}": { "get": { "operationId": "getPreOrderSetting", "summary": "Get a pre-order setting", "description": "404 `pre_order_setting_not_found` when it does not exist in the current store or is in the trash.", "tags": [ "pre-order-settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a pre-order setting", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "allowBackorder": { "type": "boolean" }, "maxBackorderQty": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedRestockAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "variantId", "variantInfo", "allowBackorder", "maxBackorderQty", "expectedRestockAt", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "pre_order_setting.read" ] }, "patch": { "operationId": "updatePreOrderSetting", "summary": "Update a pre-order setting (partial)", "description": "Fields not sent stay unchanged; `null` clears an optional field. The variant cannot change. While `allowBackorder` is on, orders may reserve this variant beyond the available quantity of a warehouse by up to `maxBackorderQty` (base unit, per warehouse; null = no limit). Only variants without batch / serial tracking can be sold beyond stock.", "tags": [ "pre-order-settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a pre-order setting (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "allowBackorder": { "type": "boolean" }, "maxBackorderQty": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedRestockAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "variantId", "variantInfo", "allowBackorder", "maxBackorderQty", "expectedRestockAt", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "pre_order_setting.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowBackorder": { "type": "boolean" }, "maxBackorderQty": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "expectedRestockAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [] } } } } }, "delete": { "operationId": "deletePreOrderSetting", "summary": "Delete a pre-order setting", "description": "Moves it to the trash (backorders stop at once; restore with POST /pre-order-settings/{id}/restore). `?force=true` deletes it permanently and additionally requires `pre_order_setting.hard_delete`.", "tags": [ "pre-order-settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a pre-order setting", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "pre_order_setting.delete" ] } }, "/api/v1/pre-order-settings/{id}/restore": { "post": { "operationId": "restorePreOrderSetting", "summary": "Restore a pre-order setting from the trash", "description": "404 when it is not in the trash; 409 `pre_order_setting_variant_exists` when the variant got another setting meanwhile.", "tags": [ "pre-order-settings" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a pre-order setting from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "allowBackorder": { "type": "boolean" }, "maxBackorderQty": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedRestockAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "variantId", "variantInfo", "allowBackorder", "maxBackorderQty", "expectedRestockAt", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "pre_order_setting.restore" ] } }, "/api/v1/pre-order-settings/options": { "get": { "operationId": "listPreOrderSettingOptions", "summary": "List pre-order setting options", "description": "Same query as GET /pre-order-settings, trimmed to `{ id, variantId, variantInfo, allowBackorder }`.", "tags": [ "pre-order-settings" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "variant_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "allow_backorder", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List pre-order setting options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "allowBackorder": { "type": "boolean" } }, "required": [ "id", "variantId", "variantInfo", "allowBackorder" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "pre_order_setting.read" ] } }, "/api/v1/pre-order-settings/trash": { "get": { "operationId": "listPreOrderSettingTrash", "summary": "List pre-order settings in the trash", "description": "Pre-order settings moved to the trash, most recently deleted first, with who deleted them. Restore with POST /pre-order-settings/{id}/restore, delete permanently with DELETE /pre-order-settings/{id}?force=true. Cursor-paginated.", "tags": [ "pre-order-settings" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List pre-order settings in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "pre_order_setting.restore" ] } }, "/api/v1/price-lists": { "get": { "operationId": "listPriceLists", "summary": "List price lists", "description": "Price lists of the current store, default sort by `name`. `itemCount` / `customerCount` = its prices / customers. `q` searches the code and name. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "price-lists" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `name`" }, "description": "Sort field; prefix `-` for descending. Default `name`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: price_lists.code, price_lists.name" }, "description": "Case-insensitive substring search in: price_lists.code, price_lists.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List price lists", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string" }, "audience": { "enum": [ "all", "customers" ], "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "customerCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "currency", "channel", "audience", "startsAt", "endsAt", "itemCount", "customerCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.read" ] }, "post": { "operationId": "createPriceList", "summary": "Create a price list", "description": "Created in the current store, in the store's currency. `code` is unique per store among rows not in the trash (409 `price_list_code_exists`). The list offers unit prices to quotes (cart, checkout) on its `channel` (`all` = every channel) within `startsAt`..`endsAt`, to every buyer (`audience: all`) or only to its customers (`audience: customers`, PUT /price-lists/{id}/customers); the LOWEST offer among applicable lists and the catalog price wins. Prices: PUT /price-lists/{id}/items.", "tags": [ "price-lists" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a price list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string" }, "audience": { "enum": [ "all", "customers" ], "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "customerCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "currency", "channel", "audience", "startsAt", "endsAt", "itemCount", "customerCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string", "default": "all" }, "audience": { "enum": [ "all", "customers" ], "type": "string", "default": "all" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "code", "name" ] } } } } } }, "/api/v1/price-lists/{id}": { "get": { "operationId": "getPriceList", "summary": "Get a price list", "description": "404 `price_list_not_found` when it does not exist in the current store or is in the trash.", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a price list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string" }, "audience": { "enum": [ "all", "customers" ], "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "customerCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "currency", "channel", "audience", "startsAt", "endsAt", "itemCount", "customerCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.read" ] }, "put": { "operationId": "replacePriceList", "summary": "Replace a price list (full update)", "description": "Replaces every field (fields not sent take their defaults). 409 `price_list_code_exists`.", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a price list (full update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string" }, "audience": { "enum": [ "all", "customers" ], "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "customerCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "currency", "channel", "audience", "startsAt", "endsAt", "itemCount", "customerCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string", "default": "all" }, "audience": { "enum": [ "all", "customers" ], "type": "string", "default": "all" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "code", "name" ] } } } } }, "patch": { "operationId": "updatePriceList", "summary": "Update a price list (partial)", "description": "Fields not sent stay unchanged; `null` clears an optional field. 409 `price_list_code_exists`.", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a price list (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string" }, "audience": { "enum": [ "all", "customers" ], "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "customerCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "currency", "channel", "audience", "startsAt", "endsAt", "itemCount", "customerCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string" }, "audience": { "enum": [ "all", "customers" ], "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [] } } } } }, "delete": { "operationId": "deletePriceList", "summary": "Delete a price list", "description": "Moves it to the trash (restore with POST /price-lists/{id}/restore). `?force=true` deletes it permanently and additionally requires `price_list.hard_delete`. Modules depending on it may refuse.", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a price list", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.delete" ] } }, "/api/v1/price-lists/{id}/customers": { "get": { "operationId": "listPriceListCustomers", "summary": "Customers of a price list", "description": "Customers the list applies to when `audience: customers`. 404 `price_list_not_found`.", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customers of a price list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] } }, "required": [ "customerId", "customerInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.read" ] }, "put": { "operationId": "setPriceListCustomers", "summary": "Replace the customers of a price list", "description": "Replaces ALL customers (≤ 2000); used when `audience: customers`. Each must be a customer of the store (409 `price_list_customer_not_found` with `error.at = customerIds.`).", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace the customers of a price list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "customerId": { "type": "string", "format": "uuid" }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] } }, "required": [ "customerId", "customerInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 2000 } }, "required": [ "customerIds" ] } } } } } }, "/api/v1/price-lists/{id}/items": { "get": { "operationId": "listPriceListItems", "summary": "Prices of a price list", "description": "Every price of the list (variant × selling unit × minimum quantity), by variant. 404 `price_list_not_found`.", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Prices of a price list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "minQty": { "type": "string" }, "price": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "minQty", "price" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.read" ] }, "put": { "operationId": "setPriceListItems", "summary": "Replace the prices of a price list", "description": "Replaces ALL prices (≤ 2000). Each price applies to a variant in a selling unit (`uomId`: null or the product's base unit = base unit, stored as null; otherwise a unit the product sells in, else 409 `price_list_uom_not_found`) from `minQty` (in that unit) up; several rows of one variant + unit = quantity tiers — the lowest qualifying price is offered. Prices follow the catalog's tax convention. 409 `price_list_variant_not_found` / `price_list_uom_not_found` with `error.at = items.`; 409 `price_list_item_duplicate`.", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace the prices of a price list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "minQty": { "type": "string" }, "price": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "minQty", "price" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "minQty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$", "default": "1" }, "price": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "variantId", "price" ] }, "maxItems": 2000 } }, "required": [ "items" ] } } } } } }, "/api/v1/price-lists/{id}/restore": { "post": { "operationId": "restorePriceList", "summary": "Restore a price list from the trash", "description": "404 when it is not in the trash; 409 `price_list_code_exists` when another row took its code meanwhile.", "tags": [ "price-lists" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a price list from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "channel": { "enum": [ "all", "web", "pos", "admin" ], "type": "string" }, "audience": { "enum": [ "all", "customers" ], "type": "string" }, "startsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "customerCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "notes", "currency", "channel", "audience", "startsAt", "endsAt", "itemCount", "customerCount", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.restore" ] } }, "/api/v1/price-lists/options": { "get": { "operationId": "listPriceListOptions", "summary": "List price list options", "description": "Same query as GET /price-lists, trimmed to `{ id, code, name, active }` for pickers.", "tags": [ "price-lists" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `name`" }, "description": "Sort field; prefix `-` for descending. Default `name`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: price_lists.code, price_lists.name" }, "description": "Case-insensitive substring search in: price_lists.code, price_lists.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List price list options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.read" ] } }, "/api/v1/price-lists/trash": { "get": { "operationId": "listPriceListTrash", "summary": "List price lists in the trash", "description": "Price lists moved to the trash, most recently deleted first, with who deleted them. Restore with POST /price-lists/{id}/restore, delete permanently with DELETE /price-lists/{id}?force=true. Cursor-paginated.", "tags": [ "price-lists" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: price_lists.code, price_lists.name" }, "description": "Case-insensitive substring search in: price_lists.code, price_lists.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List price lists in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price_list.restore" ] } }, "/api/v1/price/quote": { "post": { "operationId": "quotePrices", "summary": "Quote lines (staff)", "description": "Prices lines the way carts, checkout and orders do: catalog price per unit (`uomId`, null = base unit) → offers of extension modules (lowest wins) → tax of the product on the store's current day (inclusive / exclusive) → discounts and offsets of extension modules in phases (`unit_promo`, `order_promo`, `code`, `shipping`, `offset`) → per-line rounding to the currency. A code no module accepts → 400 `price_code_not_recognized`. Each distinct code is a guess: too many failed codes (per staff member and per IP, in the store), or fewer guesses left than distinct codes → 429 `too_many_attempts` with `details.retryAfter` (header `retry-after`), before quoting — retry with fewer codes or wait. Read-only. Errors of one line carry `error.at = lines.`.", "tags": [ "price" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Quote lines (staff)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "currency": { "type": "string" }, "day": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "listPrice": { "type": "string" }, "unitPrice": { "type": "string" }, "priceSource": { "type": "string" }, "taxRate": { "type": "string" }, "taxInclusive": { "type": "boolean" }, "gross": { "type": "string" }, "discount": { "type": "string" }, "net": { "type": "string" }, "tax": { "type": "string" }, "total": { "type": "string" } }, "required": [ "variantId", "variantInfo", "uomId", "uomInfo", "factor", "qty", "baseQty", "listPrice", "unitPrice", "priceSource", "taxRate", "taxInclusive", "gross", "discount", "net", "tax", "total" ] } }, "adjustments": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "phase": { "enum": [ "unit_promo", "order_promo", "code", "shipping", "offset" ], "type": "string" }, "scope": { "enum": [ "line", "order", "shipping", "offset" ], "type": "string" }, "amount": { "type": "string" }, "lineIndex": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "phase", "scope", "amount", "lineIndex", "code", "referenceId", "label" ] } }, "totals": { "type": "object", "properties": { "subtotal": { "type": "string" }, "discountTotal": { "type": "string" }, "taxTotal": { "type": "string" }, "shippingTotal": { "type": "string" }, "offsetTotal": { "type": "string" }, "grandTotal": { "type": "string" } }, "required": [ "subtotal", "discountTotal", "taxTotal", "shippingTotal", "offsetTotal", "grandTotal" ] } }, "required": [ "currency", "day", "lines", "adjustments", "totals" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "price.quote" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "variantId", "qty" ] }, "minItems": 1, "maxItems": 200 }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "codes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 64 }, "maxItems": 10 }, "shipping": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "lines" ] } } } } } }, "/api/v1/prints": { "get": { "operationId": "listPrintables", "summary": "Printable document templates I can use in this store", "description": "Templates of installed + enabled modules whose view permission the caller holds; labels follow `x-lang` / `Accept-Language`.", "tags": [ "prints" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Printable document templates I can use in this store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "module": { "type": "string" }, "label": { "type": "string" }, "canEmail": { "type": "boolean" } }, "required": [ "name", "module", "label", "canEmail" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "type": "null" } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/prints/{name}/{id}": { "get": { "operationId": "printDocument", "summary": "Render a document for printing (HTML) or as PDF", "description": "`format=html` (default): self-contained A4 HTML (sandboxed by CSP) — show it in a sandboxed iframe and print / save as PDF in the browser. `format=pdf`: server-side PDF, only when the deployment has a PDF renderer (409 `pdf_unavailable`; 502 `pdf_render_failed`). 404 `printable_not_found` / `print_record_not_found` (also for records of another store); 413 `print_too_large`; 503 `data_transfer_busy` (too many PDFs rendering). Language: `x-lang` / `Accept-Language`.", "tags": [ "prints" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._-]+$" } }, { "name": "format", "in": "query", "required": false, "schema": { "enum": [ "html", "pdf" ], "type": "string", "default": "html" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Render a document for printing (HTML) or as PDF", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Content-Disposition": { "description": "inline / attachment; filename=…; filename*=UTF-8''…", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/prints/{name}/{id}/email": { "post": { "operationId": "emailDocument", "summary": "Email a document to the recipient the module defines", "description": "The recipient comes from the record (e.g. the order's customer) — never from the request. Needs the template's email permission. Attachment: PDF when the deployment has a PDF renderer, otherwise the HTML file. Sent in the background (202). The same recipient gets at most one document per 10 minutes from a store (429 `print_email_repeat`). 409 `print_email_unavailable` (template cannot email) / `print_recipient_missing` (record has no valid email); 404 as `printDocument`; 403 `api_key_forbidden` / `impersonation_forbidden`.", "tags": [ "prints" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[A-Za-z0-9._-]+$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "202": { "description": "Email a document to the recipient the module defines", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "to": { "type": "string" } }, "required": [ "to" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/product-categories": { "get": { "operationId": "listProductCategories", "summary": "List product categories", "description": "Categories of the current store as a flat list; build the tree from `parentId` (or `path`). The default `sort=tree` is the tree order: parents before their children, siblings by `sortOrder`, then code. `sort=path` also returns parents before their children, siblings in creation order. Filters: `parent_id` (`parent_id.null=true` = roots), `depth`, `active`. `q` searches the code and every translated name. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "product-categories" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "tree", "-tree", "sort_order", "-sort_order", "code", "-code", "path", "-path", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `tree`" }, "description": "Sort field; prefix `-` for descending. Default `tree`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: product_categories.code, product_category_translations.name" }, "description": "Case-insensitive substring search in: product_categories.code, product_category_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "parent_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "parent_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: int" }, "description": "eq: int" }, { "name": "depth.lte", "in": "query", "required": false, "schema": { "type": "string", "description": "lte: int" }, "description": "lte: int" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List product categories", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "path": { "type": "string" }, "depth": { "type": "number" }, "code": { "type": "string" }, "imageFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "imageFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "parentId", "parentInfo", "path", "depth", "code", "imageFileId", "imageFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product_category.read" ] }, "post": { "operationId": "createProductCategory", "summary": "Create a product category", "description": "Created in the current store, under `parentId` (a root when omitted; 400 `product_category_parent_not_found` when the parent is not a category of this store; at most 8 levels → 409 `product_category_too_deep`). `code` is unique per store (409 `product_category_code_exists`). `translations` languages must be enabled for the store (400 `unsupported_language`); an empty `slug` is generated from `name`; a slug used by another category in the same language → 409 `product_category_slug_exists`. `imageFileId` must be a file of the current store (400 `file_not_attachable`).", "tags": [ "product-categories" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a product category", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "path": { "type": "string" }, "depth": { "type": "number" }, "code": { "type": "string" }, "imageFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "imageFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "parentId", "parentInfo", "path", "depth", "code", "imageFileId", "imageFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product_category.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "imageFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "active": { "type": "boolean", "default": true }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "lang", "name" ] }, "maxItems": 20, "default": [] } }, "required": [ "code" ] } } } } } }, "/api/v1/product-categories/{id}": { "get": { "operationId": "getProductCategory", "summary": "Get a product category", "description": "404 `product_category_not_found` when the category does not exist in the current store.", "tags": [ "product-categories" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a product category", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "path": { "type": "string" }, "depth": { "type": "number" }, "code": { "type": "string" }, "imageFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "imageFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "parentId", "parentInfo", "path", "depth", "code", "imageFileId", "imageFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product_category.read" ] }, "patch": { "operationId": "updateProductCategory", "summary": "Update a product category (partial)", "description": "Fields not sent stay unchanged. A new `parentId` moves the category WITH its whole subtree (`null` = make it a root); moving it under itself or one of its descendants → 409 `product_category_cycle`, deeper than 8 levels → 409 `product_category_too_deep`. `translations`, when sent, replaces the whole set (languages left out are deleted).", "tags": [ "product-categories" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a product category (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "path": { "type": "string" }, "depth": { "type": "number" }, "code": { "type": "string" }, "imageFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "imageFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "parentId", "parentInfo", "path", "depth", "code", "imageFileId", "imageFileInfo", "sortOrder", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product_category.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "imageFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0 }, "active": { "type": "boolean" }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "lang", "name" ] }, "maxItems": 20 } }, "required": [] } } } } }, "delete": { "operationId": "deleteProductCategory", "summary": "Delete a product category", "description": "Deletes the category permanently (categories have no trash). 409 `product_category_has_children` while it still has sub-categories; modules depending on categories (e.g. products) may refuse while they still use it.", "tags": [ "product-categories" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a product category", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product_category.delete" ] } }, "/api/v1/product-categories/options": { "get": { "operationId": "listProductCategoryOptions", "summary": "List product category options", "description": "Same query as GET /product-categories (default `sort=tree`), trimmed for tree pickers: `{ id, parentId, path, depth, code, active }` + the translation picked for the request language. Pages of up to 1000 rows (the default) so a whole tree usually comes back in one call; follow meta.nextCursor until null for larger trees.", "tags": [ "product-categories" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "1000", "minimum": 1, "maximum": 1000 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "tree", "-tree", "sort_order", "-sort_order", "code", "-code", "path", "-path", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `tree`" }, "description": "Sort field; prefix `-` for descending. Default `tree`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: product_categories.code, product_category_translations.name" }, "description": "Case-insensitive substring search in: product_categories.code, product_category_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "parent_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "parent_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "depth", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: int" }, "description": "eq: int" }, { "name": "depth.lte", "in": "query", "required": false, "schema": { "type": "string", "description": "lte: int" }, "description": "lte: int" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List product category options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "path": { "type": "string" }, "depth": { "type": "number" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] } }, "required": [ "id", "parentId", "parentInfo", "path", "depth", "code", "active", "lang", "name", "description", "slug", "metaTitle", "metaDescription" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product_category.read" ] } }, "/api/v1/products": { "get": { "operationId": "listProducts", "summary": "List products", "description": "Products of the current store (without variants: `variantCount` + the price range of active variants; `minPrice` / `maxPrice` / `currency` are null when the active variants use different currencies). `lang` + every translatable field are picked for the request language; `translations` holds every translation. `q` searches the code and every translated name. `in_category` = a category and all of its sub-categories. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "products" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "sort_order", "-sort_order", "code", "-code", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: products.code, product_translations.name" }, "description": "Case-insensitive substring search in: products.code, product_translations.name" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: draft, active, archived" }, "description": "eq: one of: draft, active, archived" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "featured", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "brand_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "brand_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "brand_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "category_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "category_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "base_uom_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "base_uom_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "in_category", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Category id: products in that category OR any of its sub-categories (AND-ed with the other filters, e.g. `category_id`)" }, "description": "Category id: products in that category OR any of its sub-categories (AND-ed with the other filters, e.g. `category_id`)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List products", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "active", "name" ] }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "number" }, "version": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "shortDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "imageFileId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "imageFileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "variantCount": { "type": "number" }, "minPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "maxPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "brandId", "brandInfo", "categoryId", "categoryInfo", "baseUomId", "baseUomInfo", "status", "featured", "sortOrder", "version", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "translations", "imageFileId", "imageFileInfo", "variantCount", "minPrice", "maxPrice", "currency", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.read" ] }, "post": { "operationId": "createProduct", "summary": "Create a product", "description": "Created in the current store with at least one variant (a product without options has one variant with `options: []`). `code` and every variant `sku` / `barcode` are unique per store (409 `product_code_exists` / `product_sku_exists` / `product_barcode_exists`). `brandId` / `categoryId` / `baseUomId` / `uoms[].uomId` must belong to the store (400 `product_brand_invalid` / `product_category_invalid` / `product_uom_invalid`); extra units must differ from the base unit (400 `product_extra_uoms_invalid`). Variant options pick one value per attribute (400 `product_variant_options_invalid`), every variant uses the same attributes (409 `product_variant_attributes_mismatch`) with distinct combinations (409 `product_variant_combination_exists`). A variant `currency` defaults to the store currency; `unitPrices` only for the product's extra units (400 `product_variant_price_uom_invalid`). `status: active` needs a translation and an active variant (409 `product_not_publishable`). `imageFileIds` must be files of the current store (400 `file_not_attachable`).", "tags": [ "products" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a product", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "active", "name" ] }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "number" }, "version": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "shortDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileId", "fileInfo", "sortOrder" ] } }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uomId", "uomInfo", "factor", "barcode" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "weightGrams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "price", "compareAtPrice", "currency", "weightGrams", "sortOrder", "active", "options", "unitPrices", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "brandId", "brandInfo", "categoryId", "categoryInfo", "baseUomId", "baseUomInfo", "status", "featured", "sortOrder", "version", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "translations", "images", "uoms", "variants", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string", "default": "draft" }, "featured": { "type": "boolean", "default": false }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "shortDescription": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 100000 }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "lang", "name" ] }, "maxItems": 20, "default": [] }, "imageFileIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "default": [] }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "factor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,12})(\\.[0-9]{1,6})?$" }, "barcode": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" }, { "type": "null" } ] } }, "required": [ "uomId", "factor" ] }, "maxItems": 20, "default": [] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "barcode": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" }, { "type": "null" } ] }, "price": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "compareAtPrice": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "weightGrams": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "active": { "type": "boolean", "default": true }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "valueId": { "type": "string", "format": "uuid" } }, "required": [ "attributeId", "valueId" ] }, "maxItems": 10, "default": [] }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "price": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "uomId", "price" ] }, "maxItems": 20, "default": [] } }, "required": [ "sku", "price" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "code", "baseUomId", "variants" ] } } } } } }, "/api/v1/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get a product", "description": "The product with its images, extra units and every variant (options + price per unit). 404 `product_not_found` when it does not exist in the current store or is in the trash.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a product", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "active", "name" ] }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "number" }, "version": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "shortDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileId", "fileInfo", "sortOrder" ] } }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uomId", "uomInfo", "factor", "barcode" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "weightGrams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "price", "compareAtPrice", "currency", "weightGrams", "sortOrder", "active", "options", "unitPrices", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "brandId", "brandInfo", "categoryId", "categoryInfo", "baseUomId", "baseUomInfo", "status", "featured", "sortOrder", "version", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "translations", "images", "uoms", "variants", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.read" ] }, "patch": { "operationId": "updateProduct", "summary": "Update a product (partial)", "description": "Send the `version` you read: 409 `version_conflict` (with `currentVersion`) when someone saved in between. Fields not sent stay unchanged; `translations`, `imageFileIds` and `uoms`, when sent, replace the whole set (dropping an extra unit also drops the variants' prices in that unit). Switching to `status: active` needs a translation and an active variant (409 `product_not_publishable`). Variants are edited through /products/{id}/variants.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a product (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "active", "name" ] }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "number" }, "version": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "shortDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileId", "fileInfo", "sortOrder" ] } }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uomId", "uomInfo", "factor", "barcode" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "weightGrams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "price", "compareAtPrice", "currency", "weightGrams", "sortOrder", "active", "options", "unitPrices", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "brandId", "brandInfo", "categoryId", "categoryInfo", "baseUomId", "baseUomInfo", "status", "featured", "sortOrder", "version", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "translations", "images", "uoms", "variants", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "integer", "minimum": 0 }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "shortDescription": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string", "maxLength": 100000 }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string", "maxLength": 250, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "lang", "name" ] }, "maxItems": 20 }, "imageFileIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50 }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "factor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,12})(\\.[0-9]{1,6})?$" }, "barcode": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" }, { "type": "null" } ] } }, "required": [ "uomId", "factor" ] }, "maxItems": 20 } }, "required": [ "version" ] } } } } }, "delete": { "operationId": "deleteProduct", "summary": "Delete a product", "description": "Moves the product to the trash (restore with POST /products/{id}/restore); its SKUs and slugs stay reserved. `?force=true` deletes it permanently, also from the trash, and additionally requires `product.hard_delete`. Modules depending on products may refuse.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a product", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.delete" ] } }, "/api/v1/products/{id}/restore": { "post": { "operationId": "restoreProduct", "summary": "Restore a product from the trash", "description": "404 when the product is not in the trash; 409 `product_code_exists` / `product_slug_exists` when another product took its code or slug meanwhile.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a product from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "active", "name" ] }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "number" }, "version": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "shortDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileId", "fileInfo", "sortOrder" ] } }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uomId", "uomInfo", "factor", "barcode" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "weightGrams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "price", "compareAtPrice", "currency", "weightGrams", "sortOrder", "active", "options", "unitPrices", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "brandId", "brandInfo", "categoryId", "categoryInfo", "baseUomId", "baseUomInfo", "status", "featured", "sortOrder", "version", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "translations", "images", "uoms", "variants", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.restore" ] } }, "/api/v1/products/{id}/variants": { "post": { "operationId": "addProductVariant", "summary": "Add a product variant", "description": "Adds one variant (same rules as the variants of POST /products) and returns the whole product — its `version` changes. Send the product `version` you read: 409 `version_conflict` (with `currentVersion`) when someone saved the product or one of its variants in between.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Add a product variant", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "active", "name" ] }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "number" }, "version": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "shortDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileId", "fileInfo", "sortOrder" ] } }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uomId", "uomInfo", "factor", "barcode" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "weightGrams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "price", "compareAtPrice", "currency", "weightGrams", "sortOrder", "active", "options", "unitPrices", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "brandId", "brandInfo", "categoryId", "categoryInfo", "baseUomId", "baseUomInfo", "status", "featured", "sortOrder", "version", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "translations", "images", "uoms", "variants", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "sku": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "barcode": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" }, { "type": "null" } ] }, "price": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "compareAtPrice": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "weightGrams": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "active": { "type": "boolean", "default": true }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "valueId": { "type": "string", "format": "uuid" } }, "required": [ "attributeId", "valueId" ] }, "maxItems": 10, "default": [] }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "price": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "uomId", "price" ] }, "maxItems": 20, "default": [] } }, "required": [ "version", "sku", "price" ] } } } } } }, "/api/v1/products/{id}/variants/{variantId}": { "patch": { "operationId": "updateProductVariant", "summary": "Update a product variant (partial)", "description": "Send the product `version` you read: 409 `version_conflict` (with `currentVersion`) when someone saved the product or one of its variants in between. Fields not sent stay unchanged; `options` / `unitPrices`, when sent, replace the whole set. Changing `currency` without sending `unitPrices` drops the variant's set unit prices (they fall back to conversion). Returns the whole product. 404 `product_variant_not_found` when the variant is not one of this product's.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "variantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a product variant (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "active", "name" ] }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "number" }, "version": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "shortDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileId", "fileInfo", "sortOrder" ] } }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uomId", "uomInfo", "factor", "barcode" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "weightGrams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "price", "compareAtPrice", "currency", "weightGrams", "sortOrder", "active", "options", "unitPrices", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "brandId", "brandInfo", "categoryId", "categoryInfo", "baseUomId", "baseUomInfo", "status", "featured", "sortOrder", "version", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "translations", "images", "uoms", "variants", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "sku": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "barcode": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,64}$" }, { "type": "null" } ] }, "price": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "compareAtPrice": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "weightGrams": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] }, "sortOrder": { "type": "integer", "minimum": 0 }, "active": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "valueId": { "type": "string", "format": "uuid" } }, "required": [ "attributeId", "valueId" ] }, "maxItems": 10 }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "price": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "uomId", "price" ] }, "maxItems": 20 } }, "required": [ "version" ] } } } } }, "delete": { "operationId": "deleteProductVariant", "summary": "Delete a product variant", "description": "Deletes the variant permanently and returns the whole product. `?version=` = the product `version` you read (409 `version_conflict` with `currentVersion` when it changed). 409 `product_last_variant` for the only variant; modules depending on products may refuse (e.g. while stock or orders use it).", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "variantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "version", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,9}$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Delete a product variant", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "brandId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "brandInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "active", "name" ] }, { "type": "null" } ] }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "categoryInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "path": { "type": "string" }, "active": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "path", "active", "name" ] }, { "type": "null" } ] }, "baseUomId": { "type": "string", "format": "uuid" }, "baseUomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "featured": { "type": "boolean" }, "sortOrder": { "type": "number" }, "version": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" }, "shortDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string" }, "metaTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "images": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "fileInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "contentType": { "type": "string" }, "size": { "type": "number" }, "sha256": { "type": "string" } }, "required": [ "id", "name", "contentType", "size", "sha256" ] }, { "type": "null" } ] }, "sortOrder": { "type": "number" } }, "required": [ "fileId", "fileInfo", "sortOrder" ] } }, "uoms": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "uomId", "uomInfo", "factor", "barcode" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "string" }, "compareAtPrice": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "type": "string" }, "weightGrams": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sortOrder": { "type": "number" }, "active": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid" }, "attributeInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "valueId": { "type": "string", "format": "uuid" }, "valueInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "swatchHex", "name" ] } }, "required": [ "attributeId", "attributeInfo", "valueId", "valueInfo" ] } }, "unitPrices": { "type": "array", "items": { "type": "object", "properties": { "uomId": { "type": "string", "format": "uuid" }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "price": { "type": "string" }, "source": { "enum": [ "base", "explicit", "converted" ], "type": "string", "description": "`base` = the variant price (base unit), `explicit` = set for this unit, `converted` = price × factor rounded to the currency" } }, "required": [ "uomId", "uomInfo", "factor", "price", "source" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "price", "compareAtPrice", "currency", "weightGrams", "sortOrder", "active", "options", "unitPrices", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "brandId", "brandInfo", "categoryId", "categoryInfo", "baseUomId", "baseUomInfo", "status", "featured", "sortOrder", "version", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription", "translations", "images", "uoms", "variants", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.update" ] } }, "/api/v1/products/attributes": { "get": { "operationId": "listProductAttributes", "summary": "List product attributes", "description": "Option attributes of the current store (Color, Size…) with all their values. `q` searches the code and every translated name. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "products" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "sort_order", "-sort_order", "code", "-code", "created_at", "-created_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: product_attributes.code, product_attribute_translations.name" }, "description": "Case-insensitive substring search in: product_attributes.code, product_attribute_translations.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List product attributes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } } }, "required": [ "id", "code", "sortOrder", "swatchHex", "lang", "name", "translations" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "sortOrder", "lang", "name", "translations", "values", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.read" ] }, "post": { "operationId": "createProductAttribute", "summary": "Create a product attribute", "description": "`code` is unique per store (409 `product_attribute_code_exists`); value codes are unique per attribute (409 `product_attribute_value_code_exists`). Translation languages must be enabled for the store (400 `unsupported_language`).", "tags": [ "products" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a product attribute", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } } }, "required": [ "id", "code", "sortOrder", "swatchHex", "lang", "name", "translations" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "sortOrder", "lang", "name", "translations", "values", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.manage_attributes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "lang", "name" ] }, "maxItems": 20, "default": [] }, "values": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "swatchHex": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "lang", "name" ] }, "maxItems": 20, "default": [] } }, "required": [ "code" ] }, "maxItems": 200, "default": [] } }, "required": [ "code" ] } } } } } }, "/api/v1/products/attributes/{id}": { "get": { "operationId": "getProductAttribute", "summary": "Get a product attribute", "description": "404 `product_attribute_not_found` when the attribute does not exist in the current store.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a product attribute", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } } }, "required": [ "id", "code", "sortOrder", "swatchHex", "lang", "name", "translations" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "sortOrder", "lang", "name", "translations", "values", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.read" ] }, "patch": { "operationId": "updateProductAttribute", "summary": "Update a product attribute (partial)", "description": "Fields not sent stay unchanged; `translations`, when sent, replaces the whole set. Values are edited through /products/attributes/{id}/values.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a product attribute (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } } }, "required": [ "id", "code", "sortOrder", "swatchHex", "lang", "name", "translations" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "sortOrder", "lang", "name", "translations", "values", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.manage_attributes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "sortOrder": { "type": "integer", "minimum": 0 }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "lang", "name" ] }, "maxItems": 20 } }, "required": [] } } } } }, "delete": { "operationId": "deleteProductAttribute", "summary": "Delete a product attribute", "description": "Deletes the attribute and its values permanently; 409 `resource_in_use` while a variant uses it.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a product attribute", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.manage_attributes" ] } }, "/api/v1/products/attributes/{id}/values": { "post": { "operationId": "addProductAttributeValue", "summary": "Add a value to a product attribute", "description": "Returns the whole attribute. 409 `product_attribute_value_code_exists` when the attribute already has that code.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Add a value to a product attribute", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } } }, "required": [ "id", "code", "sortOrder", "swatchHex", "lang", "name", "translations" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "sortOrder", "lang", "name", "translations", "values", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.manage_attributes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "sortOrder": { "type": "integer", "minimum": 0, "default": 0 }, "swatchHex": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "lang", "name" ] }, "maxItems": 20, "default": [] } }, "required": [ "code" ] } } } } } }, "/api/v1/products/attributes/{id}/values/{valueId}": { "patch": { "operationId": "updateProductAttributeValue", "summary": "Update a product attribute value (partial)", "description": "Fields not sent stay unchanged; `translations`, when sent, replaces the whole set. Returns the whole attribute; 404 `product_attribute_value_not_found` when the value is not one of this attribute's.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "valueId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a product attribute value (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } } }, "required": [ "id", "code", "sortOrder", "swatchHex", "lang", "name", "translations" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "sortOrder", "lang", "name", "translations", "values", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.manage_attributes" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$" }, "sortOrder": { "type": "integer", "minimum": 0 }, "swatchHex": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "lang", "name" ] }, "maxItems": 20 } }, "required": [] } } } } }, "delete": { "operationId": "deleteProductAttributeValue", "summary": "Delete a product attribute value", "description": "Deletes the value permanently and returns the whole attribute; 409 `resource_in_use` while a variant uses it.", "tags": [ "products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "valueId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Delete a product attribute value", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "sortOrder": { "type": "number" }, "swatchHex": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } } }, "required": [ "id", "code", "sortOrder", "swatchHex", "lang", "name", "translations" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "sortOrder", "lang", "name", "translations", "values", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.manage_attributes" ] } }, "/api/v1/products/options": { "get": { "operationId": "listProductOptions", "summary": "List product options", "description": "Same query as GET /products, trimmed to `{ id, code, status }` + the translation picked for the request language, for pickers.", "tags": [ "products" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "sort_order", "-sort_order", "code", "-code", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, "description": "Sort field; prefix `-` for descending. Default `sort_order`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: products.code, product_translations.name" }, "description": "Case-insensitive substring search in: products.code, product_translations.name" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: draft, active, archived" }, "description": "eq: one of: draft, active, archived" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "featured", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "brand_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "brand_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "brand_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "category_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "category_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "category_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "base_uom_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "base_uom_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "in_category", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "description": "Category id: products in that category OR any of its sub-categories (AND-ed with the other filters, e.g. `category_id`)" }, "description": "Category id: products in that category OR any of its sub-categories (AND-ed with the other filters, e.g. `category_id`)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List product options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shortDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "description": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metaTitle": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] }, "metaDescription": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, { "type": "null" } ] } }, "required": [ "id", "code", "status", "lang", "name", "shortDescription", "description", "slug", "metaTitle", "metaDescription" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.read" ] } }, "/api/v1/products/trash": { "get": { "operationId": "listProductTrash", "summary": "List products in the trash", "description": "Products of the current store that were moved to the trash, most recently deleted first, with who deleted them. `q` searches the code and every translated name. Restore with POST /products/{id}/restore, delete permanently with DELETE /products/{id}?force=true. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "products" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: products.code, product_translations.name" }, "description": "Case-insensitive substring search in: products.code, product_translations.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List products in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "status": { "enum": [ "draft", "active", "archived" ], "type": "string" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "status", "lang", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.restore" ] } }, "/api/v1/products/variants/options": { "get": { "operationId": "listProductVariantOptions", "summary": "List product variant options", "description": "Variants (SKUs) for pickers in business forms (stock receipts, orders…): SKU, barcode, product name + option combination in the request language (`optionsLabel`, e.g. `Red / M`), price. `q` searches the SKU, barcode, product code and every translated product name (not option names). No status filter by default — pass `status=active&active=true` for sellable variants only. Variants of products in the trash are left out. Cursor-paginated (up to 200 per page).", "tags": [ "products" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "sku", "-sku" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `sku`" }, "description": "Sort field; prefix `-` for descending. Default `sku`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: product_variants.sku, product_variants.barcode, products.code, product_translations.name" }, "description": "Case-insensitive substring search in: product_variants.sku, product_variants.barcode, products.code, product_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "product_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "product_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: draft, active, archived" }, "description": "eq: one of: draft, active, archived" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List product variant options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "string" }, "currency": { "type": "string" } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel", "price", "currency" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "product.read" ] } }, "/api/v1/purchase-orders": { "get": { "operationId": "listPurchaseOrders", "summary": "List purchase orders", "description": "Purchase orders of the current store, newest first. Filter by `status`, `supplier_id`, `warehouse_id`; `q` searches the number. Cursor-paginated.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: purchase_orders.number" }, "description": "Case-insensitive substring search in: purchase_orders.number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: draft, ordered, partial, received, closed, cancelled" }, "description": "eq: one of: draft, ordered, partial, received, closed, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "supplier_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "supplier_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List purchase orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.read" ] }, "post": { "operationId": "createPurchaseOrder", "summary": "Create a purchase order (draft)", "description": "Creates a draft with a generated number (`PO-YYYYMMDD-0001`, store day). Lines are fixed from now on (cancel and recreate to change them). Each line is in a purchase unit (`uomId`: the product's base unit or one of its extra units, with the factor snapshotted; `uomId: null` in responses = the base unit); `qty × factor` must be exact at 4 decimals in the base unit (400 `purchase_order_qty_not_exact`). `unitCost` is per purchase unit. Errors of one line carry `error.at = lines.`.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a purchase order (draft)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qtyOrdered": { "type": "string" }, "qtyReceived": { "type": "string" }, "baseQtyOrdered": { "type": "string" }, "factor": { "type": "string" }, "unitCost": { "type": "string" }, "lineTotal": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qtyOrdered", "qtyReceived", "baseQtyOrdered", "factor", "unitCost", "lineTotal" ] } } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "supplierId": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "expectedDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "unitCost": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "variantId", "qty", "unitCost" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "supplierId", "warehouseId", "lines" ] } } } } } }, "/api/v1/purchase-orders/{id}": { "get": { "operationId": "getPurchaseOrder", "summary": "Get a purchase order with its lines", "tags": [ "purchase-orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a purchase order with its lines", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qtyOrdered": { "type": "string" }, "qtyReceived": { "type": "string" }, "baseQtyOrdered": { "type": "string" }, "factor": { "type": "string" }, "unitCost": { "type": "string" }, "lineTotal": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qtyOrdered", "qtyReceived", "baseQtyOrdered", "factor", "unitCost", "lineTotal" ] } } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.read" ] }, "delete": { "operationId": "deletePurchaseOrder", "summary": "Delete a draft purchase order", "description": "Only drafts (nothing in stock yet) — placed orders are cancelled or closed instead.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a draft purchase order", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.delete" ] } }, "/api/v1/purchase-orders/{id}/cancel": { "post": { "operationId": "cancelPurchaseOrder", "summary": "Cancel a purchase order", "description": "Draft / ordered (nothing received yet) → cancelled.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Cancel a purchase order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qtyOrdered": { "type": "string" }, "qtyReceived": { "type": "string" }, "baseQtyOrdered": { "type": "string" }, "factor": { "type": "string" }, "unitCost": { "type": "string" }, "lineTotal": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qtyOrdered", "qtyReceived", "baseQtyOrdered", "factor", "unitCost", "lineTotal" ] } } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.update" ] } }, "/api/v1/purchase-orders/{id}/close": { "post": { "operationId": "closePurchaseOrder", "summary": "Close a fully received purchase order", "description": "Received → closed.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Close a fully received purchase order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qtyOrdered": { "type": "string" }, "qtyReceived": { "type": "string" }, "baseQtyOrdered": { "type": "string" }, "factor": { "type": "string" }, "unitCost": { "type": "string" }, "lineTotal": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qtyOrdered", "qtyReceived", "baseQtyOrdered", "factor", "unitCost", "lineTotal" ] } } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.update" ] } }, "/api/v1/purchase-orders/{id}/place": { "post": { "operationId": "placePurchaseOrder", "summary": "Place a draft purchase order", "description": "Draft → ordered (sent to the supplier). 409 `purchase_order_invalid_status` otherwise.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Place a draft purchase order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qtyOrdered": { "type": "string" }, "qtyReceived": { "type": "string" }, "baseQtyOrdered": { "type": "string" }, "factor": { "type": "string" }, "unitCost": { "type": "string" }, "lineTotal": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qtyOrdered", "qtyReceived", "baseQtyOrdered", "factor", "unitCost", "lineTotal" ] } } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.update" ] } }, "/api/v1/purchase-orders/{id}/receive": { "post": { "operationId": "receivePurchaseOrder", "summary": "Receive goods of a purchase order", "description": "Adds the received quantities to stock (one `PN-…` voucher, purpose `purchase_receipt`, unit cost = line cost / factor) in the same transaction as the received quantities and status (ordered / partial → partial / received). Quantities are in each line's purchase unit; batch-tracked variants need `lotNumber`, serial-tracked ones one serial per BASE unit. Needs `stock.view_cost` too (the cost goes into the stock ledger). A line over its remaining quantity → 409 `purchase_order_receive_exceeds_ordered`; errors of one line carry `error.at = lines.`.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Receive goods of a purchase order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qtyOrdered": { "type": "string" }, "qtyReceived": { "type": "string" }, "baseQtyOrdered": { "type": "string" }, "factor": { "type": "string" }, "unitCost": { "type": "string" }, "lineTotal": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qtyOrdered", "qtyReceived", "baseQtyOrdered", "factor", "unitCost", "lineTotal" ] } } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.receive", "stock.view_cost" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid" }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "lotNumber": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "manufactureDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "serialNumbers": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 }, "maxItems": 1000 }, { "type": "null" } ] } }, "required": [ "itemId", "qty" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "lines" ] } } } } } }, "/api/v1/purchase-orders/{id}/returns": { "post": { "operationId": "returnPurchaseOrderItems", "summary": "Return received goods to the supplier", "description": "Takes received goods back out of stock (one `PX-…` voucher, purpose `purchase_return`) and lowers the received quantity — the order goes back to partial (a replacement is expected) or ordered. Lots / serials as for the stock supplier return.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Return received goods to the supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qtyOrdered": { "type": "string" }, "qtyReceived": { "type": "string" }, "baseQtyOrdered": { "type": "string" }, "factor": { "type": "string" }, "unitCost": { "type": "string" }, "lineTotal": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qtyOrdered", "qtyReceived", "baseQtyOrdered", "factor", "unitCost", "lineTotal" ] } } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.receive" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "format": "uuid" }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "lotNumber": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "serialNumbers": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 }, "maxItems": 1000 }, { "type": "null" } ] } }, "required": [ "itemId", "qty" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "lines" ] } } } } } }, "/api/v1/purchase-orders/{id}/short-close": { "post": { "operationId": "shortClosePurchaseOrder", "summary": "Close a partially received purchase order", "description": "Partial → closed: the rest will not arrive; received stock stays.", "tags": [ "purchase-orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Close a partially received purchase order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "supplierId": { "type": "string", "format": "uuid" }, "supplierInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "ordered", "partial", "received", "closed", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "itemsTotal": { "type": "string" }, "expectedDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "orderedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qtyOrdered": { "type": "string" }, "qtyReceived": { "type": "string" }, "baseQtyOrdered": { "type": "string" }, "factor": { "type": "string" }, "unitCost": { "type": "string" }, "lineTotal": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qtyOrdered", "qtyReceived", "baseQtyOrdered", "factor", "unitCost", "lineTotal" ] } } }, "required": [ "id", "storeId", "number", "supplierId", "supplierInfo", "warehouseId", "warehouseInfo", "status", "currency", "itemsTotal", "expectedDate", "note", "orderedAt", "receivedAt", "closedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "purchase_order.update" ] } }, "/api/v1/refunds": { "get": { "operationId": "listRefunds", "summary": "List refunds", "description": "Refunds of the current store, newest first. Filter by `status`, `order_id`; `q` searches the number. `actions` lists what the caller can do now (`send`, `complete`, `fail`). Cursor-paginated.", "tags": [ "refunds" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: refunds.number" }, "description": "Case-insensitive substring search in: refunds.number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: pending, processing, completed, failed" }, "description": "eq: one of: pending, processing, completed, failed" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "order_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List refunds", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "status": { "enum": [ "pending", "processing", "completed", "failed" ], "type": "string" }, "method": { "enum": [ "bank_transfer", "cash", "manual", "momo" ], "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "shippingAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "status", "method", "currency", "amount", "shippingAmount", "reason", "reference", "failReason", "completedAt", "failedAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "refund.read" ] }, "post": { "operationId": "createRefund", "summary": "Create a refund for an order (pending)", "description": "Records money to give back for a paid order (`paymentStatus` `paid` / `partially_refunded`, else 409 `refund_order_not_paid`), in the order's currency, with a generated number (`RF-YYYYMMDD-0001`). `shippingAmount` is the part of `amount` that is shipping (400 `refund_shipping_over_amount` when larger). Pending and completed refunds together cannot exceed the order total (409 `refund_amount_exceeds`) nor its shipping (409 `refund_shipping_exceeds`). Nothing is paid out by the system for `bank_transfer` / `cash` / `manual`: staff pay the customer, then complete the refund. `momo` needs the order paid through the store's MoMo (409 `refund_momo_unavailable`) and is sent with POST /refunds/{id}/send.", "tags": [ "refunds" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a refund for an order (pending)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "status": { "enum": [ "pending", "processing", "completed", "failed" ], "type": "string" }, "method": { "enum": [ "bank_transfer", "cash", "manual", "momo" ], "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "shippingAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "status", "method", "currency", "amount", "shippingAmount", "reason", "reference", "failReason", "completedAt", "failedAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "refund.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "shippingAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "method": { "enum": [ "bank_transfer", "cash", "manual", "momo" ], "type": "string" }, "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "orderId", "amount", "method" ] } } } } } }, "/api/v1/refunds/{id}": { "get": { "operationId": "getRefund", "summary": "Get a refund", "tags": [ "refunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a refund", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "status": { "enum": [ "pending", "processing", "completed", "failed" ], "type": "string" }, "method": { "enum": [ "bank_transfer", "cash", "manual", "momo" ], "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "shippingAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "status", "method", "currency", "amount", "shippingAmount", "reason", "reference", "failReason", "completedAt", "failedAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "refund.read" ] } }, "/api/v1/refunds/{id}/complete": { "post": { "operationId": "completeRefund", "summary": "Complete a refund (money paid back)", "description": "pending / processing → completed, with the transfer reference (for a `processing` MoMo refund: after checking MoMo's portal). The order becomes `partially_refunded`, or `refunded` when everything is paid back (`refund.complete` is enough to change the order's payment status — on purpose) — a fully refunded order that is not fulfilled yet can then be cancelled. Extension modules reverse their part in the same transaction (`refund.completing`). 409 `refund_not_pending`.", "tags": [ "refunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Complete a refund (money paid back)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "status": { "enum": [ "pending", "processing", "completed", "failed" ], "type": "string" }, "method": { "enum": [ "bank_transfer", "cash", "manual", "momo" ], "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "shippingAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "status", "method", "currency", "amount", "shippingAmount", "reason", "reference", "failReason", "completedAt", "failedAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "refund.complete" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [] } } } } } }, "/api/v1/refunds/{id}/fail": { "post": { "operationId": "failRefund", "summary": "Mark a refund failed", "description": "pending / processing → failed (the payout did not go through); its amount is free to refund again. A `processing` MoMo refund needs `gatewayChecked: true` (you checked MoMo's portal: not paid back — 409 `refund_gateway_check_required`) and can never be failed once MoMo confirmed it (409 `refund_gateway_paid`). 409 `refund_not_pending`.", "tags": [ "refunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Mark a refund failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "status": { "enum": [ "pending", "processing", "completed", "failed" ], "type": "string" }, "method": { "enum": [ "bank_transfer", "cash", "manual", "momo" ], "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "shippingAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "status", "method", "currency", "amount", "shippingAmount", "reason", "reference", "failReason", "completedAt", "failedAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "refund.complete" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500, "minLength": 1 }, "gatewayChecked": { "type": "boolean" } }, "required": [ "reason" ] } } } } } }, "/api/v1/refunds/{id}/send": { "post": { "operationId": "sendRefund", "summary": "Send a MoMo refund through the store's MoMo account", "description": "pending → processing, then MoMo is called (outside any transaction) to pay back the order's MoMo payment: accepted → completed (`reference` = MoMo's refund transaction), rejected → failed (`failReason`). No clear answer (timeout, MoMo still processing, MoMo rejecting the call itself) → stays `processing`: check MoMo's portal, then complete it, or fail it with `gatewayChecked: true`; once MoMo confirmed the refund it can only be completed. 409 `refund_not_gateway` (not a `momo` refund), `refund_momo_unavailable` (order not paid with MoMo, or MoMo not configured for the store), `refund_not_pending`; 400 `momo_amount_out_of_range` / `momo_currency_unsupported`.", "tags": [ "refunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Send a MoMo refund through the store's MoMo account", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "status": { "enum": [ "pending", "processing", "completed", "failed" ], "type": "string" }, "method": { "enum": [ "bank_transfer", "cash", "manual", "momo" ], "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "shippingAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "status", "method", "currency", "amount", "shippingAmount", "reason", "reference", "failReason", "completedAt", "failedAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "refund.send" ] } }, "/api/v1/reports": { "get": { "operationId": "listReports", "summary": "Reports the user can run", "description": "Reports of modules installed and enabled in the current store that the caller may view (each report has its module's permission). Labels follow `x-lang` / `Accept-Language`.", "tags": [ "reports" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Reports the user can run", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "module": { "type": "string" }, "label": { "type": "string" }, "params": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "enum": [ "date", "text", "number", "select" ], "type": "string" }, "required": { "type": "boolean" }, "options": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "key", "label", "type", "required", "options" ] } }, "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "header": { "type": "string" }, "numeric": { "type": "boolean" }, "money": { "type": "boolean" } }, "required": [ "key", "header", "numeric", "money" ] } } }, "required": [ "name", "module", "label", "params", "columns" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/reports/{name}/export": { "post": { "operationId": "exportReport", "summary": "Run a report and download it as CSV or Excel", "description": "Same parameters and limits as `runReport`; the summary row (if any) is the last row.", "tags": [ "reports" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run a report and download it as CSV or Excel", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Content-Disposition": { "description": "attachment; filename=…", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "enum": [ "csv", "xlsx" ], "type": "string", "default": "csv" }, "params": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] }, { "type": "null" } ] } } }, "required": [] } } } } } }, "/api/v1/reports/{name}/exports": { "post": { "operationId": "startReportExport", "summary": "Run a report in the background", "description": "Runs as the caller (same permission / record rules). Realtime event `core.data_export` (`{ exportId, status }`) when finished; download with `downloadDataExport` (24 h); listed by `listDataExports`. 429 `too_many_exports`; 409 `data_exports_unsupported`; not available to API keys.", "tags": [ "reports" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "202": { "description": "Run a report in the background", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "enum": [ "csv", "xlsx" ], "type": "string", "default": "csv" }, "params": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] }, { "type": "null" } ] } } }, "required": [] } } } } } }, "/api/v1/reports/{name}/run": { "post": { "operationId": "runReport", "summary": "Run a report", "description": "Reads only (POST to carry typed parameters; nothing is written, no Idempotency-Key). `params` = the report's declared parameters (`date` = `YYYY-MM-DD` in the store's time zone). Read-only transaction, 30 s per query / 60 s in total, at most 10 000 rows (400 `report_too_large`). 404 `report_not_found` (also for a malformed name → 400 `validation_failed`); 503 `data_transfer_busy`. New parameter types may be added to `listReports` over time — show unknown ones as text.", "tags": [ "reports" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Run a report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "columns": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "header": { "type": "string" }, "numeric": { "type": "boolean" }, "money": { "type": "boolean" } }, "required": [ "key", "header", "numeric", "money" ] } }, "rows": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "null" } ] } } }, "summary": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, { "type": "null" } ] } }, { "type": "null" } ] } }, "required": [ "columns", "rows", "summary" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "params": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] }, { "type": "null" } ] } } }, "required": [] } } } } } }, "/api/v1/reports/schedules": { "get": { "operationId": "listReportSchedules", "summary": "My scheduled report emails in this store", "tags": [ "reports" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "My scheduled report emails in this store", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "report": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "frequency": { "enum": [ "daily", "weekly", "monthly" ], "type": "string" }, "hour": { "type": "number" }, "weekday": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "nextRunAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastRunAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "report", "params", "format", "frequency", "hour", "weekday", "monthDay", "active", "nextRunAt", "lastRunAt", "lastStatus", "lang" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createReportSchedule", "summary": "Email me a report on a schedule", "description": "Sent to the caller's own VERIFIED email only; runs as the caller with their permission at send time (no permission → not sent, `lastStatus: forbidden`). Times are in the store's time zone. At most 10 per user per store (409 `too_many_report_schedules`). 404 `report_not_found` (no view permission); 409 `report_email_required` without a verified email; 409 `report_schedules_unsupported` before the core upgrade; 403 `superuser_job_forbidden` for superusers, `api_key_forbidden`, `impersonation_forbidden`. `lastStatus`: `generated`, `sent`, `skipped` (store inactive / account suspended), `forbidden` (no view permission at send time), `params_invalid`, `no_verified_email`, `failed` — more values may be added.", "tags": [ "reports" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Email me a report on a schedule", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "report": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "frequency": { "enum": [ "daily", "weekly", "monthly" ], "type": "string" }, "hour": { "type": "number" }, "weekday": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "nextRunAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastRunAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "report", "params", "format", "frequency", "hour", "weekday", "monthDay", "active", "nextRunAt", "lastRunAt", "lastStatus", "lang" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "report": { "type": "string", "pattern": "^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$" }, "format": { "enum": [ "csv", "xlsx" ], "type": "string", "default": "xlsx" }, "params": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] }, { "type": "null" } ] } }, "frequency": { "enum": [ "daily", "weekly", "monthly" ], "type": "string" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "weekday": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "null" } ] }, "monthDay": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 28 }, { "type": "null" } ] } }, "required": [ "report", "frequency", "hour" ] } } } } } }, "/api/v1/reports/schedules/{id}": { "patch": { "operationId": "updateReportSchedule", "summary": "Change or pause a scheduled report", "description": "404 `report_schedule_not_found`; 404 `report_not_found` when changing `params` without view permission. `weekday` / `monthDay` are kept only for weekly / monthly.", "tags": [ "reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Change or pause a scheduled report", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "report": { "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "frequency": { "enum": [ "daily", "weekly", "monthly" ], "type": "string" }, "hour": { "type": "number" }, "weekday": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "monthDay": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "nextRunAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "lastRunAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "report", "params", "format", "frequency", "hour", "weekday", "monthDay", "active", "nextRunAt", "lastRunAt", "lastStatus", "lang" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "enum": [ "csv", "xlsx" ], "type": "string" }, "params": { "type": "object", "propertyNames": { "type": "string", "maxLength": 64 }, "additionalProperties": { "anyOf": [ { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "number" } ] }, { "type": "null" } ] } }, "frequency": { "enum": [ "daily", "weekly", "monthly" ], "type": "string" }, "hour": { "type": "integer", "minimum": 0, "maximum": 23 }, "weekday": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 7 }, { "type": "null" } ] }, "monthDay": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 28 }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [] } } } } }, "delete": { "operationId": "deleteReportSchedule", "summary": "Stop a scheduled report", "description": "404 `report_schedule_not_found`.", "tags": [ "reports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Stop a scheduled report", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } } } }, "/api/v1/return-requests": { "get": { "operationId": "listReturnRequests", "summary": "List return requests", "description": "Return requests of the current store, newest first. Filter by `status` / `order_id`; `q` searches the number. Cursor-paginated.", "tags": [ "return-requests" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: return_requests.number" }, "description": "Case-insensitive substring search in: return_requests.number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: requested, approved, received, refunded, closed, rejected, cancelled" }, "description": "eq: one of: requested, approved, received, refunded, closed, rejected, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List return requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.read" ] }, "post": { "operationId": "createReturnRequest", "summary": "Create a return request for an order", "description": "For a delivered order (`fulfilled` / `completed`, else 409 `return_request_order_not_returnable`). Each line: an order line and a quantity in that line's selling unit, at most what was bought minus what open return requests already hold (409 `return_request_qty_exceeded`, `details.available` in the base unit; errors carry `error.at = items.`). `total` = suggested refund (line total × returned / bought). Starts `requested`.", "tags": [ "return-requests" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a return request for an order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "items": { "type": "array", "items": { "type": "object", "properties": { "orderItemId": { "type": "string", "format": "uuid" }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "orderItemId", "qty" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "orderId", "reason", "items" ] } } } } } }, "/api/v1/return-requests/{id}": { "get": { "operationId": "getReturnRequest", "summary": "Get a return request", "description": "With its lines. 404 `return_request_not_found`.", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a return request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.read" ] } }, "/api/v1/return-requests/{id}/approve": { "post": { "operationId": "approveReturnRequest", "summary": "Approve a return request", "description": "`requested` → `approved` (the buyer may send the goods).", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Approve a return request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.manage" ] } }, "/api/v1/return-requests/{id}/cancel": { "post": { "operationId": "cancelReturnRequest", "summary": "Cancel a return request", "description": "`requested` / `approved` → `cancelled`; its quantities are released.", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Cancel a return request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.manage" ] } }, "/api/v1/return-requests/{id}/close": { "post": { "operationId": "closeReturnRequest", "summary": "Close a received return without a refund", "description": "`received` → `closed` (exchange, refund outside the system).", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Close a received return without a refund", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.manage" ] } }, "/api/v1/return-requests/{id}/receive": { "post": { "operationId": "receiveReturnRequest", "summary": "Receive the returned goods", "description": "`approved` → `received`. `resellable` lines go back to the order's warehouse, to the SAME batches / serials that were shipped: pick them with `batches` / `serialIds` among those of the order line not returned yet, or leave them out to take them in shipping order (409 `return_request_detail_invalid`, `details.reason`). `damaged` lines are recorded, not restocked. `items` lists only lines that differ from the default (`resellable`, shipping order); errors carry `error.at = items.`.", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Receive the returned goods", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.receive" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "condition": { "enum": [ "resellable", "damaged" ], "type": "string", "default": "resellable" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "qty" ] }, "minItems": 1, "maxItems": 100 }, "serialIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "id" ] }, "maxItems": 200, "default": [] } }, "required": [] } } } } } }, "/api/v1/return-requests/{id}/refund": { "post": { "operationId": "refundReturnRequest", "summary": "Refund a received return", "description": "`received` → `refunded`: creates a `pending` refund of the order (module `refund`, same transaction) for `amount` (default: the request's `total`) — the refund's own limits apply (`refund_amount_exceeded`…). Complete or fail it with the refund routes; `refundInfo` shows its state.", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Refund a received return", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.refund" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "enum": [ "bank_transfer", "cash", "manual", "momo" ], "type": "string" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "shippingAmount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "reason": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "method" ] } } } } } }, "/api/v1/return-requests/{id}/reject": { "post": { "operationId": "rejectReturnRequest", "summary": "Reject a return request", "description": "`requested` → `rejected` with a `reason` shown to the buyer; its quantities are released.", "tags": [ "return-requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Reject a return request", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "customerId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "currency": { "type": "string" }, "total": { "type": "string" }, "reason": { "type": "string" }, "rejectionReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "refundId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "refundInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "type": "string" }, "amount": { "type": "string" } }, "required": [ "id", "number", "status", "amount" ] }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderItemId": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "orderItemInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "qty": { "type": "string" }, "unitPrice": { "type": "string" }, "total": { "type": "string" } }, "required": [ "id", "qty", "unitPrice", "total" ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "amount": { "type": "string" }, "condition": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "restocked": { "type": "boolean" } }, "required": [ "id", "orderItemId", "variantId", "variantInfo", "orderItemInfo", "qty", "baseQty", "amount", "condition", "detail", "restocked" ] } } }, "required": [ "id", "storeId", "number", "status", "orderId", "orderInfo", "customerId", "customerInfo", "currency", "total", "reason", "rejectionReason", "refundId", "refundInfo", "itemCount", "approvedAt", "receivedAt", "finishedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "return_request.manage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "reason" ] } } } } } }, "/api/v1/shipments": { "get": { "operationId": "listShipments", "summary": "List shipments", "description": "Shipments of the current store, newest first. Filter by `status`, `order_id`, `cod_status`, `carrier`; `q` searches the number and the tracking number. `actions` lists what the caller can do now: `update`, the target statuses of POST /shipments/{id}/status (`in_transit` still needs the order `fulfilled`), `cod_remit`. Cursor-paginated.", "tags": [ "shipments" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: shipments.number, shipments.tracking_number" }, "description": "Case-insensitive substring search in: shipments.number, shipments.tracking_number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: pending, in_transit, out_for_delivery, delivered, failed, returned, cancelled" }, "description": "eq: one of: pending, in_transit, out_for_delivery, delivered, failed, returned, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "order_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "order_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "cod_status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: none, pending, collected, remitted" }, "description": "eq: one of: none, pending, collected, remitted" }, { "name": "cod_status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "carrier", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "carrier.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated text values (max 100)" }, "description": "in: comma-separated text values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List shipments", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "carrier": { "type": "string" }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "in_transit", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codStatus": { "enum": [ "none", "pending", "collected", "remitted" ], "type": "string" }, "codCollectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codRemittedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "returnedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "carrier", "trackingNumber", "status", "currency", "codAmount", "note", "failReason", "codStatus", "codCollectedAt", "codRemittedAt", "codReference", "shippedAt", "deliveredAt", "failedAt", "returnedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "shipment.read" ] }, "post": { "operationId": "createShipment", "summary": "Create a shipment for an order (pending)", "description": "For a `confirmed` or `fulfilled` order (409 `shipment_order_not_shippable`), with a generated number (`SH-YYYYMMDD-0001`). `carrier` is a free code (`ghn`, `ghtk`, `self`…); `codAmount` = cash the carrier collects, in the order's currency. An order may have up to 50 shipments (409 `shipment_limit_reached`). A shipment's last status (delivered) can complete the order: `shipment.manage` is enough for that on purpose — delivery staff close orders.", "tags": [ "shipments" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a shipment for an order (pending)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "carrier": { "type": "string" }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "in_transit", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codStatus": { "enum": [ "none", "pending", "collected", "remitted" ], "type": "string" }, "codCollectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codRemittedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "returnedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "carrier", "trackingNumber", "status", "currency", "codAmount", "note", "failReason", "codStatus", "codCollectedAt", "codRemittedAt", "codReference", "shippedAt", "deliveredAt", "failedAt", "returnedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "shipment.manage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "carrier": { "type": "string", "maxLength": 60, "minLength": 1 }, "trackingNumber": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "orderId", "carrier" ] } } } } } }, "/api/v1/shipments/{id}": { "get": { "operationId": "getShipment", "summary": "Get a shipment", "tags": [ "shipments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "carrier": { "type": "string" }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "in_transit", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codStatus": { "enum": [ "none", "pending", "collected", "remitted" ], "type": "string" }, "codCollectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codRemittedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "returnedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "carrier", "trackingNumber", "status", "currency", "codAmount", "note", "failReason", "codStatus", "codCollectedAt", "codRemittedAt", "codReference", "shippedAt", "deliveredAt", "failedAt", "returnedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "shipment.read" ] }, "patch": { "operationId": "updateShipment", "summary": "Update carrier details of a shipment", "description": "Changes only the keys sent. Not after delivered / returned / cancelled (409 `shipment_closed`).", "tags": [ "shipments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update carrier details of a shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "carrier": { "type": "string" }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "in_transit", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codStatus": { "enum": [ "none", "pending", "collected", "remitted" ], "type": "string" }, "codCollectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codRemittedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "returnedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "carrier", "trackingNumber", "status", "currency", "codAmount", "note", "failReason", "codStatus", "codCollectedAt", "codRemittedAt", "codReference", "shippedAt", "deliveredAt", "failedAt", "returnedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "shipment.manage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "carrier": { "type": "string", "maxLength": 60, "minLength": 1 }, "trackingNumber": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [] } } } } } }, "/api/v1/shipments/{id}/cod-remit": { "post": { "operationId": "remitShipmentCod", "summary": "Record that the carrier remitted the cash on delivery", "description": "`codStatus` collected → remitted, with the transfer reference. When the order is still unpaid and the cash remitted for ALL its shipments reaches the order total, that total is recorded as a payment of the order's payment intent (provider `cod`, once per order) — the order becomes paid like any payment; a partial remittance only marks the shipment. 404 `payment_intent_not_found` when the order's payment intent is gone. 409 `shipment_cod_not_collected`, `payment_intent_not_payable`, `payment_currency_mismatch`.", "tags": [ "shipments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Record that the carrier remitted the cash on delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "carrier": { "type": "string" }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "in_transit", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codStatus": { "enum": [ "none", "pending", "collected", "remitted" ], "type": "string" }, "codCollectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codRemittedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "returnedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "carrier", "trackingNumber", "status", "currency", "codAmount", "note", "failReason", "codStatus", "codCollectedAt", "codRemittedAt", "codReference", "shippedAt", "deliveredAt", "failedAt", "returnedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "shipment.reconcile" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "maxLength": 120, "minLength": 1 } }, "required": [ "reference" ] } } } } } }, "/api/v1/shipments/{id}/status": { "post": { "operationId": "setShipmentStatus", "summary": "Move a shipment to its next status", "description": "pending → in_transit (needs the order `fulfilled`: goods issued — 409 `shipment_order_not_fulfilled`) | cancelled; in_transit → out_for_delivery | delivered | failed | returned; out_for_delivery → delivered | failed | returned; failed → in_transit | returned. `reason` is used only when moving to `failed` and is kept as `failReason` (the last failure) afterwards. When a fulfilled order has no open shipment left and at least one delivered, it becomes `completed` (same transaction). 409 `shipment_invalid_transition`.", "tags": [ "shipments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Move a shipment to its next status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "status": { "enum": [ "placed", "confirmed", "fulfilled", "completed", "cancelled" ], "type": "string" }, "paymentStatus": { "enum": [ "unpaid", "paid", "partially_refunded", "refunded" ], "type": "string" }, "currency": { "type": "string" }, "grandTotal": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "id", "number", "status", "paymentStatus", "currency", "grandTotal" ] }, { "type": "null" } ] }, "carrier": { "type": "string" }, "trackingNumber": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "in_transit", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ], "type": "string" }, "currency": { "type": "string" }, "codAmount": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "codStatus": { "enum": [ "none", "pending", "collected", "remitted" ], "type": "string" }, "codCollectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codRemittedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "codReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "returnedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "orderId", "orderInfo", "carrier", "trackingNumber", "status", "currency", "codAmount", "note", "failReason", "codStatus", "codCollectedAt", "codRemittedAt", "codReference", "shippedAt", "deliveredAt", "failedAt", "returnedAt", "cancelledAt", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "shipment.manage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "enum": [ "in_transit", "out_for_delivery", "delivered", "failed", "returned", "cancelled" ], "type": "string" }, "reason": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "required": [ "status" ] } } } } } }, "/api/v1/shipments/cod-summary": { "get": { "operationId": "getShipmentCodSummary", "summary": "Cash on delivery the carriers still hold", "description": "Delivered shipments whose cash on delivery has not been remitted yet (`codStatus: collected`), totalled per carrier and currency, with the oldest collection time. Filter `carrier`. List the shipments with GET /shipments?cod_status=collected&carrier=….", "tags": [ "shipments" ], "parameters": [ { "name": "carrier", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 60 } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cash on delivery the carriers still hold", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "carrier": { "type": "string" }, "currency": { "type": "string" }, "shipments": { "type": "number" }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "oldestCollectedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] } }, "required": [ "carrier", "currency", "shipments", "amount", "oldestCollectedAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "shipment.read" ] } }, "/api/v1/stock-counts": { "get": { "operationId": "listStockCounts", "summary": "List stock counts", "description": "Stock counts of the current store, newest first. Filter by `status`, `warehouse_id`; `q` searches the number. Cursor-paginated.", "tags": [ "stock-counts" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: stock_counts.number" }, "description": "Case-insensitive substring search in: stock_counts.number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: open, reconciled, cancelled" }, "description": "eq: one of: open, reconciled, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List stock counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "open", "reconciled", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "number", "warehouseId", "warehouseInfo", "status", "note", "reconciledAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_count.read" ] }, "post": { "operationId": "createStockCount", "summary": "Open a stock count", "description": "Records counted quantities of one warehouse and snapshots the book quantity of each line (`systemQty`, base unit) at this moment; `difference` = counted − book. Untracked variants are counted per variant; batch-tracked ones per batch (`batchId` required); serial-tracked ones per serial (`serialId`, counted 0 or 1, base unit). A line in an extra unit (`uomId`) is converted with the product's factor. A line already counted by another OPEN count of the warehouse → 409 `stock_count_already_open`. Nothing changes in stock until reconciled. Errors of one line carry `error.at = lines.`.", "tags": [ "stock-counts" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Open a stock count", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "open", "reconciled", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "countedQty": { "type": "string" }, "baseCountedQty": { "type": "string" }, "systemQty": { "type": "string" }, "difference": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "batchId", "batchInfo", "serialId", "serialInfo", "uomId", "uomInfo", "factor", "countedQty", "baseCountedQty", "systemQty", "difference" ] } } }, "required": [ "id", "storeId", "number", "warehouseId", "warehouseInfo", "status", "note", "reconciledAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_count.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "uuid" }, "note": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "countedQty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "variantId", "countedQty" ] }, "minItems": 1, "maxItems": 500 } }, "required": [ "warehouseId", "lines" ] } } } } } }, "/api/v1/stock-counts/{id}": { "get": { "operationId": "getStockCount", "summary": "Get a stock count with its lines", "tags": [ "stock-counts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a stock count with its lines", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "open", "reconciled", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "countedQty": { "type": "string" }, "baseCountedQty": { "type": "string" }, "systemQty": { "type": "string" }, "difference": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "batchId", "batchInfo", "serialId", "serialInfo", "uomId", "uomInfo", "factor", "countedQty", "baseCountedQty", "systemQty", "difference" ] } } }, "required": [ "id", "storeId", "number", "warehouseId", "warehouseInfo", "status", "note", "reconciledAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_count.read" ] }, "delete": { "operationId": "deleteStockCount", "summary": "Delete an unreconciled stock count", "description": "Open or cancelled counts only (nothing moved in stock).", "tags": [ "stock-counts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete an unreconciled stock count", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_count.delete" ] } }, "/api/v1/stock-counts/{id}/cancel": { "post": { "operationId": "cancelStockCount", "summary": "Cancel an open stock count", "tags": [ "stock-counts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Cancel an open stock count", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "open", "reconciled", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "countedQty": { "type": "string" }, "baseCountedQty": { "type": "string" }, "systemQty": { "type": "string" }, "difference": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "batchId", "batchInfo", "serialId", "serialInfo", "uomId", "uomInfo", "factor", "countedQty", "baseCountedQty", "systemQty", "difference" ] } } }, "required": [ "id", "storeId", "number", "warehouseId", "warehouseInfo", "status", "note", "reconciledAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_count.create" ] } }, "/api/v1/stock-counts/{id}/reconcile": { "post": { "operationId": "reconcileStockCount", "summary": "Reconcile a stock count", "description": "Open → reconciled: every line with a difference becomes a stock adjustment of that difference (one voucher per direction, purpose `stock_count`) on the exact batch / serial, in one transaction. The count is the truth: it may push stock below reserved quantities (no `stock_insufficient_*`). Serial lines: missing (0) → `damaged`, found (1) → `in_stock`. Errors of one line carry `error.at = items.` (line order of the count).", "tags": [ "stock-counts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Reconcile a stock count", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "open", "reconciled", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "factor": { "type": "string" }, "countedQty": { "type": "string" }, "baseCountedQty": { "type": "string" }, "systemQty": { "type": "string" }, "difference": { "type": "string" } }, "required": [ "id", "variantId", "variantInfo", "batchId", "batchInfo", "serialId", "serialInfo", "uomId", "uomInfo", "factor", "countedQty", "baseCountedQty", "systemQty", "difference" ] } } }, "required": [ "id", "storeId", "number", "warehouseId", "warehouseInfo", "status", "note", "reconciledAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_count.reconcile" ] } }, "/api/v1/stock-transfers": { "get": { "operationId": "listStockTransfers", "summary": "List stock transfers", "description": "Transfers of the current store, newest first. Filter by `status`, `from_warehouse_id`, `to_warehouse_id`; `q` searches the number. Cursor-paginated.", "tags": [ "stock-transfers" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "updated_at", "-updated_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: stock_transfers.number" }, "description": "Case-insensitive substring search in: stock_transfers.number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: draft, in_transit, completed, cancelled" }, "description": "eq: one of: draft, in_transit, completed, cancelled" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "from_warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "from_warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "to_warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "to_warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List stock transfers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "fromWarehouseId": { "type": "string", "format": "uuid" }, "fromWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "toWarehouseId": { "type": "string", "format": "uuid" }, "toWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "in_transit", "completed", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "number", "fromWarehouseId", "fromWarehouseInfo", "toWarehouseId", "toWarehouseInfo", "status", "note", "shippedAt", "receivedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_transfer.read" ] }, "post": { "operationId": "createStockTransfer", "summary": "Create a stock transfer (draft)", "description": "Creates a draft between two warehouses of the store with a generated number (`TR-YYYYMMDD-0001`, store day). Lines are fixed from now on. A line may be in an extra unit of the product (`uomId`, factor snapshotted; `uomId: null` = base unit); `qty × factor` must be exact at 4 decimals (400 `stock_transfer_qty_not_exact`). Nothing moves until shipped. Errors of one line carry `error.at = lines.`.", "tags": [ "stock-transfers" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a stock transfer (draft)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "fromWarehouseId": { "type": "string", "format": "uuid" }, "fromWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "toWarehouseId": { "type": "string", "format": "uuid" }, "toWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "in_transit", "completed", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "factor": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "baseQty", "factor", "detail" ] } } }, "required": [ "id", "storeId", "number", "fromWarehouseId", "fromWarehouseInfo", "toWarehouseId", "toWarehouseInfo", "status", "note", "shippedAt", "receivedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_transfer.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromWarehouseId": { "type": "string", "format": "uuid" }, "toWarehouseId": { "type": "string", "format": "uuid" }, "note": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, "required": [ "variantId", "qty" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "fromWarehouseId", "toWarehouseId", "lines" ] } } } } } }, "/api/v1/stock-transfers/{id}": { "get": { "operationId": "getStockTransfer", "summary": "Get a stock transfer with its lines", "tags": [ "stock-transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a stock transfer with its lines", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "fromWarehouseId": { "type": "string", "format": "uuid" }, "fromWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "toWarehouseId": { "type": "string", "format": "uuid" }, "toWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "in_transit", "completed", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "factor": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "baseQty", "factor", "detail" ] } } }, "required": [ "id", "storeId", "number", "fromWarehouseId", "fromWarehouseInfo", "toWarehouseId", "toWarehouseInfo", "status", "note", "shippedAt", "receivedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_transfer.read" ] }, "delete": { "operationId": "deleteStockTransfer", "summary": "Delete a draft stock transfer", "description": "Only drafts (nothing moved yet).", "tags": [ "stock-transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a draft stock transfer", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_transfer.delete" ] } }, "/api/v1/stock-transfers/{id}/cancel": { "post": { "operationId": "cancelStockTransfer", "summary": "Cancel a stock transfer", "description": "Draft → cancelled; in_transit → cancelled with the shipped lots / serials returned to the source warehouse (one `PN-…` voucher, purpose `transfer_cancel`). Completed transfers cannot be cancelled (make a reverse transfer).", "tags": [ "stock-transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Cancel a stock transfer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "fromWarehouseId": { "type": "string", "format": "uuid" }, "fromWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "toWarehouseId": { "type": "string", "format": "uuid" }, "toWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "in_transit", "completed", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "factor": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "baseQty", "factor", "detail" ] } } }, "required": [ "id", "storeId", "number", "fromWarehouseId", "fromWarehouseInfo", "toWarehouseId", "toWarehouseInfo", "status", "note", "shippedAt", "receivedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_transfer.ship" ] } }, "/api/v1/stock-transfers/{id}/receive": { "post": { "operationId": "receiveStockTransfer", "summary": "Receive a stock transfer", "description": "In_transit → completed: the shipped lots / serials enter the destination warehouse (one `PN-…` voucher, purpose `transfer_in`).", "tags": [ "stock-transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Receive a stock transfer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "fromWarehouseId": { "type": "string", "format": "uuid" }, "fromWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "toWarehouseId": { "type": "string", "format": "uuid" }, "toWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "in_transit", "completed", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "factor": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "baseQty", "factor", "detail" ] } } }, "required": [ "id", "storeId", "number", "fromWarehouseId", "fromWarehouseInfo", "toWarehouseId", "toWarehouseInfo", "status", "note", "shippedAt", "receivedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_transfer.receive" ] } }, "/api/v1/stock-transfers/{id}/ship": { "post": { "operationId": "shipStockTransfer", "summary": "Ship a stock transfer", "description": "Draft → in_transit: takes the goods out of the source warehouse (one `PX-…` voucher, purpose `transfer_out`; batches FEFO / any available serials) and records on each line which lots / serials left (`detail`) so receiving or cancelling puts back exactly those. Short stock → 409 `stock_insufficient_available` with `error.at = items.` (line order of the transfer, as in `items`).", "tags": [ "stock-transfers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Ship a stock transfer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "fromWarehouseId": { "type": "string", "format": "uuid" }, "fromWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "toWarehouseId": { "type": "string", "format": "uuid" }, "toWarehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "status": { "enum": [ "draft", "in_transit", "completed", "cancelled" ], "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "receivedAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "Z$" }, { "type": "null" } ] }, "itemCount": { "type": "number" }, "actions": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "uomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "uomInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "allowFraction", "name" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "baseQty": { "type": "string" }, "factor": { "type": "string" }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "uomId", "uomInfo", "qty", "baseQty", "factor", "detail" ] } } }, "required": [ "id", "storeId", "number", "fromWarehouseId", "fromWarehouseInfo", "toWarehouseId", "toWarehouseInfo", "status", "note", "shippedAt", "receivedAt", "cancelledAt", "itemCount", "actions", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "items" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock_transfer.ship" ] } }, "/api/v1/stock/adjustments": { "post": { "operationId": "createStockAdjustment", "summary": "Adjust stock quantities", "description": "Records the physical truth (count, damage, loss…): each line changes on-hand stock by `qtyDelta` (signed), all lines in one transaction; increases land on a `PN-…` voucher, decreases on a `PX-…` voucher. A decrease below zero or below the reserved quantity is refused (409 `stock_insufficient_on_hand` / `stock_exceeds_reserved`) unless `allowDeficit: true` is sent on purpose. Tracked variants name the lot (`batchId`) or the serial (`serialId`, ±1: in stock ↔ damaged).", "tags": [ "stock" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Adjust stock quantities", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "vouchers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "direction": { "enum": [ "in", "out" ], "type": "string" }, "purpose": { "enum": [ "sale", "pos_sale", "marketplace_sale", "exchange_issue", "purchase_return", "transfer_out", "adjustment_decrease", "purchase_receipt", "manual_receipt", "trade_in", "transfer_in", "transfer_cancel", "order_cancel", "order_edit", "customer_return", "pos_refund", "marketplace_cancel", "adjustment_increase", "stock_count" ], "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "externalReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lineCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "unitCost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "qty", "unitCost", "currency", "batchId", "batchInfo", "serialId", "serialInfo" ] } } }, "required": [ "id", "number", "direction", "purpose", "warehouseId", "warehouseInfo", "referenceType", "referenceId", "externalReference", "reason", "note", "lineCount", "createdAt", "createdBy", "createdByInfo", "lines" ] } } }, "required": [ "vouchers" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.adjust" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "maxLength": 255, "minLength": 1 }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "allowDeficit": { "type": "boolean", "default": false }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "qtyDelta": { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "unitCost": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] } }, "required": [ "variantId", "qtyDelta" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "warehouseId", "reason", "lines" ] } } } } } }, "/api/v1/stock/allocation": { "get": { "operationId": "previewStockAllocation", "summary": "Preview which warehouses would fulfil a quantity", "description": "Read-only: takes available stock from active warehouses in `priority` order (unexpired lots / serials only for tracked variants). Nothing is reserved; `shortfall` is what no warehouse can cover.", "tags": [ "stock" ], "parameters": [ { "name": "variantId", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "qty", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Preview which warehouses would fulfil a quantity", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "requested": { "type": "string" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "available": { "type": "string" } }, "required": [ "warehouseId", "warehouseInfo", "qty", "available" ] } }, "shortfall": { "type": "string" } }, "required": [ "variantId", "variantInfo", "requested", "allocations", "shortfall" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] } }, "/api/v1/stock/batches": { "get": { "operationId": "listStockBatches", "summary": "List stock batches (lots)", "description": "Lots of batch-tracked variants, most recently received first. `on_hand.gt=0` hides empty lots; `q` searches the lot number. Cursor-paginated.", "tags": [ "stock" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "received_at", "-received_at", "lot_number", "-lot_number", "created_at", "-created_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-received_at`" }, "description": "Sort field; prefix `-` for descending. Default `-received_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: stock_batches.lot_number" }, "description": "Case-insensitive substring search in: stock_batches.lot_number" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "variant_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "variant_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "on_hand.gt", "in": "query", "required": false, "schema": { "type": "string", "description": "gt: decimal" }, "description": "gt: decimal" }, { "name": "on_hand", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: decimal" }, "description": "eq: decimal" }, { "name": "expiry_date.lte", "in": "query", "required": false, "schema": { "type": "string", "description": "lte: date" }, "description": "lte: date" }, { "name": "expiry_date.gte", "in": "query", "required": false, "schema": { "type": "string", "description": "gte: date" }, "description": "gte: date" }, { "name": "expiry_date.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List stock batches (lots)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "manufactureDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "onHand": { "type": "string" }, "reserved": { "type": "string" }, "unitCost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "variantId", "variantInfo", "lotNumber", "expiryDate", "manufactureDate", "receivedAt", "onHand", "reserved", "unitCost", "currency", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] } }, "/api/v1/stock/batches/expiring": { "get": { "operationId": "listExpiringStockBatches", "summary": "List batches expiring soon", "description": "Lots still in stock whose expiry date is within `days` (default 30) from today in store time, soonest first, expired lots included. `expiryStatus`: `expired`, `critical` (≤ 7 days) or `warning`. Expired lots stay on hand but are never reserved or issued.", "tags": [ "stock" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "expiry_date", "-expiry_date" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `expiry_date`" }, "description": "Sort field; prefix `-` for descending. Default `expiry_date`" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "variant_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "variant_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "days", "in": "query", "required": false, "schema": { "type": "string", "description": "Batches expiring within this many days from today (store time), expired ones included; default 30" }, "description": "Batches expiring within this many days from today (store time), expired ones included; default 30" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List batches expiring soon", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "manufactureDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "receivedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "onHand": { "type": "string" }, "reserved": { "type": "string" }, "unitCost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "daysUntilExpiry": { "type": "number" }, "expiryStatus": { "enum": [ "expired", "critical", "warning" ], "type": "string" } }, "required": [ "id", "warehouseId", "warehouseInfo", "variantId", "variantInfo", "lotNumber", "expiryDate", "manufactureDate", "receivedAt", "onHand", "reserved", "unitCost", "currency", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo", "daysUntilExpiry", "expiryStatus" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] } }, "/api/v1/stock/levels": { "get": { "operationId": "listStockLevels", "summary": "List stock levels", "description": "Stock per (warehouse, variant) in base units of the product, least available first. `is_low=true` lists rows at or under their low-stock threshold. Cursor-paginated.", "tags": [ "stock" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "available", "-available", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `available`" }, "description": "Sort field; prefix `-` for descending. Default `available`" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "variant_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "variant_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "location_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "location_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "is_low", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "available.lte", "in": "query", "required": false, "schema": { "type": "string", "description": "lte: decimal" }, "description": "lte: decimal" }, { "name": "available.gt", "in": "query", "required": false, "schema": { "type": "string", "description": "gt: decimal" }, "description": "gt: decimal" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List stock levels", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "locationInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" } }, "required": [ "id", "code", "name", "type" ] }, { "type": "null" } ] }, "trackingMode": { "enum": [ "none", "batch", "serial" ], "type": "string" }, "onHand": { "type": "string" }, "reserved": { "type": "string" }, "available": { "type": "string" }, "lowStockThreshold": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isLow": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "variantId", "variantInfo", "locationId", "locationInfo", "trackingMode", "onHand", "reserved", "available", "lowStockThreshold", "isLow", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] } }, "/api/v1/stock/levels/{id}": { "get": { "operationId": "getStockLevel", "summary": "Get a stock level", "tags": [ "stock" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a stock level", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "locationInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" } }, "required": [ "id", "code", "name", "type" ] }, { "type": "null" } ] }, "trackingMode": { "enum": [ "none", "batch", "serial" ], "type": "string" }, "onHand": { "type": "string" }, "reserved": { "type": "string" }, "available": { "type": "string" }, "lowStockThreshold": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isLow": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "variantId", "variantInfo", "locationId", "locationInfo", "trackingMode", "onHand", "reserved", "available", "lowStockThreshold", "isLow", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] }, "patch": { "operationId": "updateStockLevel", "summary": "Set the low-stock threshold or pick location", "description": "`lowStockThreshold`: the row is flagged `isLow` when available ≤ threshold (`null` turns it off). `locationId`: main pick location, a location of the same warehouse (404 `stock_location_not_found`). Quantities are changed through receipts and adjustments, not here.", "tags": [ "stock" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Set the low-stock threshold or pick location", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "locationInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" } }, "required": [ "id", "code", "name", "type" ] }, { "type": "null" } ] }, "trackingMode": { "enum": [ "none", "batch", "serial" ], "type": "string" }, "onHand": { "type": "string" }, "reserved": { "type": "string" }, "available": { "type": "string" }, "lowStockThreshold": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isLow": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "variantId", "variantInfo", "locationId", "locationInfo", "trackingMode", "onHand", "reserved", "available", "lowStockThreshold", "isLow", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.adjust" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lowStockThreshold": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [] } } } } } }, "/api/v1/stock/movements": { "get": { "operationId": "listStockMovements", "summary": "List stock movements (ledger)", "description": "The append-only stock ledger, newest first: every change of on-hand or reserved quantity with the quantities after it. `unitCost` is null without `stock.view_cost`. Filter by `warehouse_id`, `variant_id`, `type`, `reference_type` + `reference_id`, `batch_id`, `serial_id`, `created_at.gte` / `.lt`. Cursor-paginated.", "tags": [ "stock" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "variant_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "variant_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: receipt, supplier_return, adjustment, reservation, release, commit, issue, restock, transfer_out, transfer_in" }, "description": "eq: one of: receipt, supplier_return, adjustment, reservation, release, commit, issue, restock, transfer_out, transfer_in" }, { "name": "type.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "reference_type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "reference_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "batch_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "serial_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "created_at.gte", "in": "query", "required": false, "schema": { "type": "string", "description": "gte: timestamp" }, "description": "gte: timestamp" }, { "name": "created_at.lt", "in": "query", "required": false, "schema": { "type": "string", "description": "lt: timestamp" }, "description": "lt: timestamp" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List stock movements (ledger)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "type": { "enum": [ "receipt", "supplier_return", "adjustment", "reservation", "release", "commit", "issue", "restock", "transfer_out", "transfer_in" ], "type": "string" }, "qtyDelta": { "type": "string" }, "balanceOnHand": { "type": "string" }, "balanceReserved": { "type": "string" }, "unitCost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "externalReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] }, "detail": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "const": "batches" }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qty": { "type": "string" } }, "required": [ "id", "lotNumber", "expiryDate", "qty" ] } } }, "required": [ "kind", "batches" ] }, { "type": "object", "properties": { "kind": { "const": "serials" }, "serials": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" } }, "required": [ "id", "serialNo" ] } } }, "required": [ "kind", "serials" ] } ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "variantId", "variantInfo", "type", "qtyDelta", "balanceOnHand", "balanceReserved", "unitCost", "currency", "reason", "referenceType", "referenceId", "externalReference", "note", "batchId", "batchInfo", "serialId", "serialInfo", "detail", "createdAt", "createdBy", "createdByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] } }, "/api/v1/stock/receipts": { "post": { "operationId": "createStockReceipt", "summary": "Receive goods into a warehouse", "description": "Manual goods receipt: every line adds stock in base units, all lines in one transaction and one `PN-…` voucher. Batch-tracked variants need `lotNumber` (receiving an existing lot adds to it, the lot cost becomes the weighted average); serial-tracked variants need one `serialNumbers` entry per unit (409 `stock_serial_exists`). `unitCost` requires `stock.view_cost` (403 otherwise); `currency` defaults to the store currency. `locationId` sets the main pick location of the stock row.", "tags": [ "stock" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Receive goods into a warehouse", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "direction": { "enum": [ "in", "out" ], "type": "string" }, "purpose": { "enum": [ "sale", "pos_sale", "marketplace_sale", "exchange_issue", "purchase_return", "transfer_out", "adjustment_decrease", "purchase_receipt", "manual_receipt", "trade_in", "transfer_in", "transfer_cancel", "order_cancel", "order_edit", "customer_return", "pos_refund", "marketplace_cancel", "adjustment_increase", "stock_count" ], "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "externalReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lineCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "unitCost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "qty", "unitCost", "currency", "batchId", "batchInfo", "serialId", "serialInfo" ] } } }, "required": [ "id", "number", "direction", "purpose", "warehouseId", "warehouseInfo", "referenceType", "referenceId", "externalReference", "reason", "note", "lineCount", "createdAt", "createdBy", "createdByInfo", "lines" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.receive" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "uuid" }, "reason": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "unitCost": { "anyOf": [ { "type": "string", "pattern": "^-?(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] }, "lotNumber": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "manufactureDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "serialNumbers": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 }, "minItems": 1, "maxItems": 1000 }, { "type": "null" } ] }, "locationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "lowStockThreshold": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, { "type": "null" } ] } }, "required": [ "variantId", "qty" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "warehouseId", "lines" ] } } } } } }, "/api/v1/stock/serials": { "get": { "operationId": "listStockSerials", "summary": "List serial numbers", "description": "Units of serial-tracked variants with their status (`in_stock`, `reserved`, `in_transit`, `sold`, `returned`, `damaged`). `q` searches the serial number. Cursor-paginated.", "tags": [ "stock" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "serial_no", "-serial_no", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `serial_no`" }, "description": "Sort field; prefix `-` for descending. Default `serial_no`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: stock_serials.serial_no" }, "description": "Case-insensitive substring search in: stock_serials.serial_no" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "variant_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "variant_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "batch_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: in_stock, reserved, in_transit, sold, returned, damaged" }, "description": "eq: one of: in_stock, reserved, in_transit, sold, returned, damaged" }, { "name": "status.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List serial numbers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "variantId", "variantInfo", "batchId", "batchInfo", "serialNo", "status", "expiryDate", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] } }, "/api/v1/stock/supplier-returns": { "post": { "operationId": "createStockSupplierReturn", "summary": "Return goods to a supplier", "description": "Takes stock out of a warehouse back to the supplier, all lines in one transaction and one `PX-…` voucher. Cannot go below zero or below the reserved quantity. Batch-tracked variants name the `lotNumber`; serial-tracked ones list the `serialNumbers` (they become `returned`).", "tags": [ "stock" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Return goods to a supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "direction": { "enum": [ "in", "out" ], "type": "string" }, "purpose": { "enum": [ "sale", "pos_sale", "marketplace_sale", "exchange_issue", "purchase_return", "transfer_out", "adjustment_decrease", "purchase_receipt", "manual_receipt", "trade_in", "transfer_in", "transfer_cancel", "order_cancel", "order_edit", "customer_return", "pos_refund", "marketplace_cancel", "adjustment_increase", "stock_count" ], "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "externalReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lineCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "unitCost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "qty", "unitCost", "currency", "batchId", "batchInfo", "serialId", "serialInfo" ] } } }, "required": [ "id", "number", "direction", "purpose", "warehouseId", "warehouseInfo", "referenceType", "referenceId", "externalReference", "reason", "note", "lineCount", "createdAt", "createdBy", "createdByInfo", "lines" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.receive" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warehouseId": { "type": "string", "format": "uuid" }, "reason": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "qty": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,14})(\\.[0-9]{1,4})?$" }, "lotNumber": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "serialNumbers": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 }, "minItems": 1, "maxItems": 1000 }, { "type": "null" } ] } }, "required": [ "variantId", "qty" ] }, "minItems": 1, "maxItems": 200 } }, "required": [ "warehouseId", "lines" ] } } } } } }, "/api/v1/stock/tracking/{variantId}": { "get": { "operationId": "getStockTracking", "summary": "Get the tracking mode of a variant", "description": "`none` (quantity only), `batch` (lots with expiry dates, issued soonest-expiry first) or `serial` (one serial number per unit).", "tags": [ "stock" ], "parameters": [ { "name": "variantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the tracking mode of a variant", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "mode": { "enum": [ "none", "batch", "serial" ], "type": "string" } }, "required": [ "variantId", "variantInfo", "mode" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] }, "put": { "operationId": "setStockTracking", "summary": "Set the tracking mode of a variant", "description": "Only while the variant has no stock, reservations or units in transit in any warehouse (409 `stock_tracking_locked`).", "tags": [ "stock" ], "parameters": [ { "name": "variantId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Set the tracking mode of a variant", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "mode": { "enum": [ "none", "batch", "serial" ], "type": "string" } }, "required": [ "variantId", "variantInfo", "mode" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.manage_tracking" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "enum": [ "none", "batch", "serial" ], "type": "string" } }, "required": [ "mode" ] } } } } } }, "/api/v1/stock/vouchers": { "get": { "operationId": "listStockVouchers", "summary": "List stock vouchers", "description": "Goods receipt (`PN-…`, direction `in`) and goods issue (`PX-…`, direction `out`) vouchers, generated for every change of on-hand quantity. `q` searches the number. Cursor-paginated.", "tags": [ "stock" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at", "number", "-number" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: stock_vouchers.number" }, "description": "Case-insensitive substring search in: stock_vouchers.number" }, { "name": "direction", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: in, out" }, "description": "eq: one of: in, out" }, { "name": "direction.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "purpose", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: sale, pos_sale, marketplace_sale, exchange_issue, purchase_return, transfer_out, adjustment_decrease, purchase_receipt, manual_receipt, trade_in, transfer_in, transfer_cancel, order_cancel, order_edit, customer_return, pos_refund, marketplace_cancel, adjustment_increase, stock_count" }, "description": "eq: one of: sale, pos_sale, marketplace_sale, exchange_issue, purchase_return, transfer_out, adjustment_decrease, purchase_receipt, manual_receipt, trade_in, transfer_in, transfer_cancel, order_cancel, order_edit, customer_return, pos_refund, marketplace_cancel, adjustment_increase, stock_count" }, { "name": "purpose.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "warehouse_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "warehouse_id.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated uuid values (max 100)" }, "description": "in: comma-separated uuid values (max 100)" }, { "name": "reference_type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "reference_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "created_at.gte", "in": "query", "required": false, "schema": { "type": "string", "description": "gte: timestamp" }, "description": "gte: timestamp" }, { "name": "created_at.lt", "in": "query", "required": false, "schema": { "type": "string", "description": "lt: timestamp" }, "description": "lt: timestamp" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List stock vouchers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "direction": { "enum": [ "in", "out" ], "type": "string" }, "purpose": { "enum": [ "sale", "pos_sale", "marketplace_sale", "exchange_issue", "purchase_return", "transfer_out", "adjustment_decrease", "purchase_receipt", "manual_receipt", "trade_in", "transfer_in", "transfer_cancel", "order_cancel", "order_edit", "customer_return", "pos_refund", "marketplace_cancel", "adjustment_increase", "stock_count" ], "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "externalReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lineCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "number", "direction", "purpose", "warehouseId", "warehouseInfo", "referenceType", "referenceId", "externalReference", "reason", "note", "lineCount", "createdAt", "createdBy", "createdByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] } }, "/api/v1/stock/vouchers/{id}": { "get": { "operationId": "getStockVoucher", "summary": "Get a stock voucher with its lines", "tags": [ "stock" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a stock voucher with its lines", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": "string" }, "direction": { "enum": [ "in", "out" ], "type": "string" }, "purpose": { "enum": [ "sale", "pos_sale", "marketplace_sale", "exchange_issue", "purchase_return", "transfer_out", "adjustment_decrease", "purchase_receipt", "manual_receipt", "trade_in", "transfer_in", "transfer_cancel", "order_cancel", "order_edit", "customer_return", "pos_refund", "marketplace_cancel", "adjustment_increase", "stock_count" ], "type": "string" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "referenceType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "referenceId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "externalReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lineCount": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "qty": { "type": "string" }, "unitCost": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "batchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "batchInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "lotNumber": { "type": "string" }, "expiryDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "lotNumber", "expiryDate" ] }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "serialInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "serialNo": { "type": "string" }, "status": { "enum": [ "in_stock", "reserved", "in_transit", "sold", "returned", "damaged" ], "type": "string" } }, "required": [ "id", "serialNo", "status" ] }, { "type": "null" } ] } }, "required": [ "id", "variantId", "variantInfo", "qty", "unitCost", "currency", "batchId", "batchInfo", "serialId", "serialInfo" ] } } }, "required": [ "id", "number", "direction", "purpose", "warehouseId", "warehouseInfo", "referenceType", "referenceId", "externalReference", "reason", "note", "lineCount", "createdAt", "createdBy", "createdByInfo", "lines" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "stock.read" ] } }, "/api/v1/suppliers": { "get": { "operationId": "listSuppliers", "summary": "List suppliers", "description": "Suppliers of the current store, default sort by `name`. `q` searches the code, name, contact name and tax code. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "suppliers" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `name`" }, "description": "Sort field; prefix `-` for descending. Default `name`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: suppliers.code, suppliers.name, suppliers.contact_name, suppliers.tax_code" }, "description": "Case-insensitive substring search in: suppliers.code, suppliers.name, suppliers.contact_name, suppliers.tax_code" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List suppliers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "contactName", "contactEmail", "contactPhone", "address", "taxCode", "paymentTermsDays", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.read" ] }, "post": { "operationId": "createSupplier", "summary": "Create a supplier", "description": "Created in the current store. `code` is unique per store among suppliers not in the trash (409 `supplier_code_exists`). `taxCode`: 10 or 13 digits (`0101234567-001` for a branch).", "tags": [ "suppliers" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "contactName", "contactEmail", "contactPhone", "address", "taxCode", "paymentTermsDays", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "contactName": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string", "pattern": "^\\+?[0-9 .-]{8,20}$" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}(-\\d{3})?$|^\\d{13}$" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 365 }, { "type": "null" } ] }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "code", "name" ] } } } } } }, "/api/v1/suppliers/{id}": { "get": { "operationId": "getSupplier", "summary": "Get a supplier", "description": "404 `supplier_not_found` when the supplier does not exist in the current store or is in the trash.", "tags": [ "suppliers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a supplier", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "contactName", "contactEmail", "contactPhone", "address", "taxCode", "paymentTermsDays", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.read" ] }, "put": { "operationId": "replaceSupplier", "summary": "Replace a supplier (full update)", "description": "Replaces every field (fields not sent take their defaults). 409 `supplier_code_exists`.", "tags": [ "suppliers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a supplier (full update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "contactName", "contactEmail", "contactPhone", "address", "taxCode", "paymentTermsDays", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "contactName": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string", "pattern": "^\\+?[0-9 .-]{8,20}$" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}(-\\d{3})?$|^\\d{13}$" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 365 }, { "type": "null" } ] }, "active": { "type": "boolean", "default": true }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "code", "name" ] } } } } }, "patch": { "operationId": "updateSupplier", "summary": "Update a supplier (partial)", "description": "Fields not sent stay unchanged; `null` clears an optional field. 409 `supplier_code_exists`.", "tags": [ "suppliers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a supplier (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "contactName", "contactEmail", "contactPhone", "address", "taxCode", "paymentTermsDays", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "contactName": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string", "pattern": "^\\+?[0-9 .-]{8,20}$" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string", "pattern": "^\\d{10}(-\\d{3})?$|^\\d{13}$" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 365 }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [] } } } } }, "delete": { "operationId": "deleteSupplier", "summary": "Delete a supplier", "description": "Moves the supplier to the trash (restore with POST /suppliers/{id}/restore). `?force=true` deletes it permanently, also from the trash, and additionally requires `supplier.hard_delete`. Modules depending on suppliers may refuse (e.g. 409 while purchase orders are open).", "tags": [ "suppliers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a supplier", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.delete" ] } }, "/api/v1/suppliers/{id}/restore": { "post": { "operationId": "restoreSupplier", "summary": "Restore a supplier from the trash", "description": "404 `supplier_not_found` when it is not in the trash; 409 `supplier_code_exists` when another supplier took its code meanwhile.", "tags": [ "suppliers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a supplier from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taxCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paymentTermsDays": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "contactName", "contactEmail", "contactPhone", "address", "taxCode", "paymentTermsDays", "active", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.restore" ] } }, "/api/v1/suppliers/options": { "get": { "operationId": "listSupplierOptions", "summary": "List supplier options", "description": "Same query as GET /suppliers, trimmed to `{ id, code, name, active }` for pickers.", "tags": [ "suppliers" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `name`" }, "description": "Sort field; prefix `-` for descending. Default `name`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: suppliers.code, suppliers.name, suppliers.contact_name, suppliers.tax_code" }, "description": "Case-insensitive substring search in: suppliers.code, suppliers.name, suppliers.contact_name, suppliers.tax_code" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List supplier options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.read" ] } }, "/api/v1/suppliers/trash": { "get": { "operationId": "listSupplierTrash", "summary": "List suppliers in the trash", "description": "Suppliers of the current store that were moved to the trash, most recently deleted first, with who deleted them. `q` searches the code and name. Restore with POST /suppliers/{id}/restore, delete permanently with DELETE /suppliers/{id}?force=true. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "suppliers" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: suppliers.code, suppliers.name" }, "description": "Case-insensitive substring search in: suppliers.code, suppliers.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List suppliers in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "supplier.restore" ] } }, "/api/v1/tax-classes": { "get": { "operationId": "listTaxClasses", "summary": "List tax classes", "description": "Tax classes of the current store, default sort by `name`. `q` searches the code and name. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "tax-classes" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `name`" }, "description": "Sort field; prefix `-` for descending. Default `name`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: tax_classes.code, tax_classes.name" }, "description": "Case-insensitive substring search in: tax_classes.code, tax_classes.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List tax classes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "isDefault", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.read" ] }, "post": { "operationId": "createTaxClass", "summary": "Create a tax class", "description": "Created in the current store. `code` is unique per store among rows not in the trash (409 `tax_code_exists`); at most one class is the default (`isDefault`, 409 `tax_default_exists`) — products without a class use it.", "tags": [ "tax-classes" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a tax class", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "isDefault", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "isDefault": { "type": "boolean", "default": false }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "code", "name" ] } } } } } }, "/api/v1/tax-classes/{id}": { "get": { "operationId": "getTaxClass", "summary": "Get a tax class", "description": "404 `tax_not_found` when it does not exist in the current store or is in the trash.", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a tax class", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "isDefault", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.read" ] }, "put": { "operationId": "replaceTaxClass", "summary": "Replace a tax class (full update)", "description": "Replaces every field (fields not sent take their defaults). 409 `tax_code_exists`.", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a tax class (full update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "isDefault", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean", "default": true }, "isDefault": { "type": "boolean", "default": false }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [ "code", "name" ] } } } } }, "patch": { "operationId": "updateTaxClass", "summary": "Update a tax class (partial)", "description": "Fields not sent stay unchanged; `null` clears an optional field. 409 `tax_code_exists`.", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a tax class (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "isDefault", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "active": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 5000 }, { "type": "null" } ] } }, "required": [] } } } } }, "delete": { "operationId": "deleteTaxClass", "summary": "Delete a tax class", "description": "Moves it to the trash (restore with POST /tax-classes/{id}/restore). `?force=true` deletes it permanently and additionally requires `tax.hard_delete`. Modules depending on it may refuse.", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a tax class", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.delete" ] } }, "/api/v1/tax-classes/{id}/rates": { "get": { "operationId": "listTaxRates", "summary": "List the rates of a tax class", "description": "Every rate of the class (periods never overlap), latest period first. Not paginated (a class has few rates).", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List the rates of a tax class", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "taxClassId": { "type": "string", "format": "uuid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rate": { "type": "string" }, "inclusive": { "type": "boolean" }, "effectiveFrom": { "type": "string" }, "effectiveTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "taxClassId", "name", "rate", "inclusive", "effectiveFrom", "effectiveTo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.read" ] }, "post": { "operationId": "createTaxRate", "summary": "Add a rate to a tax class", "description": "A percentage valid from `effectiveFrom` (inclusive) to `effectiveTo` (exclusive, null = open-ended), store dates. `inclusive` = selling prices of products in the class already include the tax. Periods of one class never overlap (409 `tax_rate_overlaps`).", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Add a rate to a tax class", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "taxClassId": { "type": "string", "format": "uuid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rate": { "type": "string" }, "inclusive": { "type": "boolean" }, "effectiveFrom": { "type": "string" }, "effectiveTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "taxClassId", "name", "rate", "inclusive", "effectiveFrom", "effectiveTo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "rate": { "type": "string", "pattern": "^(100(\\.0{1,4})?|[1-9]?[0-9](\\.[0-9]{1,4})?)$" }, "inclusive": { "type": "boolean", "default": false }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "rate", "effectiveFrom" ] } } } } } }, "/api/v1/tax-classes/{id}/rates/{rateId}": { "put": { "operationId": "replaceTaxRate", "summary": "Replace a tax rate", "description": "Replaces every field. Changing a rate does not touch orders already placed (they keep their snapshot). 409 `tax_rate_overlaps`.", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "rateId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a tax rate", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "taxClassId": { "type": "string", "format": "uuid" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rate": { "type": "string" }, "inclusive": { "type": "boolean" }, "effectiveFrom": { "type": "string" }, "effectiveTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "taxClassId", "name", "rate", "inclusive", "effectiveFrom", "effectiveTo", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "rate": { "type": "string", "pattern": "^(100(\\.0{1,4})?|[1-9]?[0-9](\\.[0-9]{1,4})?)$" }, "inclusive": { "type": "boolean", "default": false }, "effectiveFrom": { "type": "string", "format": "date" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "rate", "effectiveFrom" ] } } } } }, "delete": { "operationId": "deleteTaxRate", "summary": "Delete a tax rate", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "rateId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a tax rate", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.update" ] } }, "/api/v1/tax-classes/{id}/restore": { "post": { "operationId": "restoreTaxClass", "summary": "Restore a tax class from the trash", "description": "404 when it is not in the trash; 409 `tax_code_exists` when another row took its code meanwhile.", "tags": [ "tax-classes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a tax class from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "active", "isDefault", "notes", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.restore" ] } }, "/api/v1/tax-classes/options": { "get": { "operationId": "listTaxClassOptions", "summary": "List tax class options", "description": "Same query as GET /tax-classes, trimmed to `{ id, code, name, active }` for pickers.", "tags": [ "tax-classes" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `name`" }, "description": "Sort field; prefix `-` for descending. Default `name`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: tax_classes.code, tax_classes.name" }, "description": "Case-insensitive substring search in: tax_classes.code, tax_classes.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List tax class options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.read" ] } }, "/api/v1/tax-classes/products/{productId}": { "get": { "operationId": "getProductTaxClass", "summary": "Get the tax class of a product", "description": "`taxClassId` = the class assigned to the product (null = none: the store's default class applies). `effectiveTaxClassId` = the class that really applies (null = no tax).", "tags": [ "tax-classes" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get the tax class of a product", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "taxClassId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "taxClassInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "effectiveTaxClassId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "effectiveTaxClassInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] } }, "required": [ "productId", "taxClassId", "taxClassInfo", "effectiveTaxClassId", "effectiveTaxClassInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.read" ] }, "put": { "operationId": "setProductTaxClass", "summary": "Set the tax class of a product", "description": "`taxClassId: null` removes the assignment (the default class applies). 400 `tax_product_invalid`, 404 `tax_not_found` (class missing or in the trash).", "tags": [ "tax-classes" ], "parameters": [ { "name": "productId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Set the tax class of a product", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "productId": { "type": "string", "format": "uuid" }, "taxClassId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "taxClassInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "effectiveTaxClassId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "effectiveTaxClassInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] } }, "required": [ "productId", "taxClassId", "taxClassInfo", "effectiveTaxClassId", "effectiveTaxClassInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taxClassId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "taxClassId" ] } } } } } }, "/api/v1/tax-classes/trash": { "get": { "operationId": "listTaxClassTrash", "summary": "List tax classes in the trash", "description": "Tax classes moved to the trash, most recently deleted first, with who deleted them. Restore with POST /tax-classes/{id}/restore, delete permanently with DELETE /tax-classes/{id}?force=true. Cursor-paginated.", "tags": [ "tax-classes" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: tax_classes.code, tax_classes.name" }, "description": "Case-insensitive substring search in: tax_classes.code, tax_classes.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List tax classes in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "tax.restore" ] } }, "/api/v1/uoms": { "get": { "operationId": "listUoms", "summary": "List units of measure", "description": "Units of the current store, default sort by `code`. Filters `category`, `active`; `q` searches the code and every translated name. `lang` + `name` are picked for the request language. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "uoms" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "category", "-category", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `code`" }, "description": "Sort field; prefix `-` for descending. Default `code`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: uoms.code, uom_translations.name" }, "description": "Case-insensitive substring search in: uoms.code, uom_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List units of measure", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "category", "symbol", "allowFraction", "active", "lang", "name", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.read" ] }, "post": { "operationId": "createUom", "summary": "Create a unit of measure", "description": "`code` is unique per store among units not in the trash (409 `uom_code_exists`). Optional `translations` (`[{ lang, name }]`): each `lang` must be enabled for the store (400 `unsupported_language`).", "tags": [ "uoms" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a unit of measure", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "category", "symbol", "allowFraction", "active", "lang", "name", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,29}$" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10 }, { "type": "null" } ] }, "allowFraction": { "type": "boolean", "default": false }, "active": { "type": "boolean", "default": true }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "lang", "name" ] }, "maxItems": 20, "default": [] } }, "required": [ "code", "category" ] } } } } } }, "/api/v1/uoms/{id}": { "get": { "operationId": "getUom", "summary": "Get a unit of measure", "description": "404 `uom_not_found` when it does not exist in the current store or is in the trash.", "tags": [ "uoms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a unit of measure", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "category", "symbol", "allowFraction", "active", "lang", "name", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.read" ] }, "put": { "operationId": "replaceUom", "summary": "Replace a unit of measure (full update)", "description": "Replaces every field (fields not sent take their defaults); names stay unchanged.", "tags": [ "uoms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a unit of measure (full update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "category", "symbol", "allowFraction", "active", "lang", "name", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,29}$" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10 }, { "type": "null" } ] }, "allowFraction": { "type": "boolean", "default": false }, "active": { "type": "boolean", "default": true } }, "required": [ "code", "category" ] } } } } }, "patch": { "operationId": "updateUom", "summary": "Update a unit of measure (partial)", "description": "Fields not sent stay unchanged; names are edited with PUT /uoms/{id}/translations.", "tags": [ "uoms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a unit of measure (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "category", "symbol", "allowFraction", "active", "lang", "name", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,29}$" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 10 }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "active": { "type": "boolean" } }, "required": [] } } } } }, "delete": { "operationId": "deleteUom", "summary": "Delete a unit of measure", "description": "Moves it to the trash (restore with POST /uoms/{id}/restore). `?force=true` deletes it permanently and additionally requires `uom.hard_delete`. Modules using units (products) may refuse with 409.", "tags": [ "uoms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a unit of measure", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.delete" ] } }, "/api/v1/uoms/{id}/restore": { "post": { "operationId": "restoreUom", "summary": "Restore a unit of measure from the trash", "description": "404 `uom_not_found` when it is not in the trash; 409 `uom_code_exists` when the code was taken meanwhile.", "tags": [ "uoms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a unit of measure from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "category", "symbol", "allowFraction", "active", "lang", "name", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.restore" ] } }, "/api/v1/uoms/{id}/translations": { "put": { "operationId": "setUomTranslations", "summary": "Replace the names of a unit of measure", "description": "The full set `[{ lang, name }]`: languages left out are removed. Each `lang` must be enabled for the store (400 `unsupported_language`).", "tags": [ "uoms" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace the names of a unit of measure", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "active": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string" }, "name": { "type": "string" } }, "required": [ "lang", "name" ] } }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "category", "symbol", "allowFraction", "active", "lang", "name", "translations", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "translations": { "type": "array", "items": { "type": "object", "properties": { "lang": { "type": "string", "pattern": "^[a-z]{2,3}(-([A-Z][a-z]{3}|[A-Z]{2}|\\d{3}))?$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "lang", "name" ] }, "maxItems": 20 } }, "required": [ "translations" ] } } } } } }, "/api/v1/uoms/baseline": { "post": { "operationId": "installBaselineUoms", "summary": "Install the baseline units of measure", "description": "Adds the standard units (pcs, box, pack, carton, kg, g, l, ml, m, m2, min, hour, day, session) to the current store, named in the store's languages. Codes the store already has (also in the trash) are left untouched — safe to call again.", "tags": [ "uoms" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Install the baseline units of measure", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "string" } }, "skipped": { "type": "array", "items": { "type": "string" } } }, "required": [ "created", "skipped" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.create" ] } }, "/api/v1/uoms/options": { "get": { "operationId": "listUomOptions", "summary": "List unit of measure options", "description": "Same query as GET /uoms, trimmed for pickers (`allowFraction` tells whether quantities may have decimals).", "tags": [ "uoms" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "category", "-category", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `code`" }, "description": "Sort field; prefix `-` for descending. Default `code`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: uoms.code, uom_translations.name" }, "description": "Case-insensitive substring search in: uoms.code, uom_translations.name" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: text" }, "description": "eq: text" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List unit of measure options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "category": { "enum": [ "count", "weight", "volume", "length", "area", "time", "service", "digital", "energy" ], "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "allowFraction": { "type": "boolean" }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "category", "symbol", "allowFraction", "lang", "name" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.read" ] } }, "/api/v1/uoms/trash": { "get": { "operationId": "listUomTrash", "summary": "List units of measure in the trash", "description": "Units of the current store that were moved to the trash, most recently deleted first, with who deleted them. `q` searches the code and every translated name. Restore with POST /uoms/{id}/restore, delete permanently with DELETE /uoms/{id}?force=true. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "uoms" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: uoms.code, uom_translations.name" }, "description": "Case-insensitive substring search in: uoms.code, uom_translations.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List units of measure in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "symbol", "lang", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "uom.restore" ] } }, "/api/v1/warehouses": { "get": { "operationId": "listWarehouses", "summary": "List warehouses", "description": "Warehouses of the current store, default sort by `priority` (the order used to pick a warehouse for fulfilment). `q` searches the code, name and city. Cursor-paginated: pass meta.nextCursor as `cursor`.", "tags": [ "warehouses" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "priority", "-priority", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `priority`" }, "description": "Sort field; prefix `-` for descending. Default `priority`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: warehouses.code, warehouses.name, warehouses.city" }, "description": "Case-insensitive substring search in: warehouses.code, warehouses.name, warehouses.city" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "is_default", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: physical, virtual, dropship" }, "description": "eq: one of: physical, virtual, dropship" }, { "name": "type.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List warehouses", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string" }, "addressLine": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" }, "priority": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "type", "addressLine", "city", "phone", "email", "isDefault", "active", "priority", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.read" ] }, "post": { "operationId": "createWarehouse", "summary": "Create a warehouse", "description": "Created in the current store. `code` is unique per store among warehouses not in the trash (409 `warehouse_code_exists`). `isDefault: true` takes the default flag from the current default warehouse; the first warehouse of a store becomes the default automatically.", "tags": [ "warehouses" ], "parameters": [ { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a warehouse", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string" }, "addressLine": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" }, "priority": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "type", "addressLine", "city", "phone", "email", "isDefault", "active", "priority", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.create" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string", "default": "physical" }, "addressLine": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "pattern": "^\\+?[0-9 .-]{8,20}$" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "null" } ] }, "isDefault": { "type": "boolean", "default": false }, "active": { "type": "boolean", "default": true }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } }, "required": [ "code", "name" ] } } } } } }, "/api/v1/warehouses/{id}": { "get": { "operationId": "getWarehouse", "summary": "Get a warehouse", "description": "404 `warehouse_not_found` when the warehouse does not exist in the current store or is in the trash.", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a warehouse", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string" }, "addressLine": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" }, "priority": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "type", "addressLine", "city", "phone", "email", "isDefault", "active", "priority", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.read" ] }, "put": { "operationId": "replaceWarehouse", "summary": "Replace a warehouse (full update)", "description": "Replaces every field (fields not sent take their defaults). 409 `warehouse_code_exists`.", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Replace a warehouse (full update)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string" }, "addressLine": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" }, "priority": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "type", "addressLine", "city", "phone", "email", "isDefault", "active", "priority", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string", "default": "physical" }, "addressLine": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "pattern": "^\\+?[0-9 .-]{8,20}$" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean", "default": true }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } }, "required": [ "code", "name" ] } } } } }, "patch": { "operationId": "updateWarehouse", "summary": "Update a warehouse (partial)", "description": "Fields not sent stay unchanged; `null` clears an optional field. `isDefault: true` moves the default flag here. 409 `warehouse_code_exists`.", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a warehouse (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string" }, "addressLine": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" }, "priority": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "type", "addressLine", "city", "phone", "email", "isDefault", "active", "priority", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.update" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string" }, "addressLine": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "pattern": "^\\+?[0-9 .-]{8,20}$" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "format": "email", "maxLength": 255 }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" }, "priority": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, "required": [] } } } } }, "delete": { "operationId": "deleteWarehouse", "summary": "Delete a warehouse", "description": "Moves the warehouse to the trash (restore with POST /warehouses/{id}/restore); a default warehouse stops being the default. `?force=true` deletes it permanently with its locations and additionally requires `warehouse.hard_delete`. Modules depending on warehouses may refuse (e.g. 409 while it still holds stock).", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "force", "in": "query", "required": false, "schema": { "enum": [ "true", "false" ], "type": "string" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a warehouse", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.delete" ] } }, "/api/v1/warehouses/{id}/locations": { "get": { "operationId": "listWarehouseLocations", "summary": "List locations of a warehouse", "description": "Zones, shelves and bins of the warehouse, default sort by `code`. `parent_id.null=true` lists the top level. Cursor-paginated.", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "created_at", "-created_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `code`" }, "description": "Sort field; prefix `-` for descending. Default `code`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: warehouse_locations.code, warehouse_locations.name" }, "description": "Case-insensitive substring search in: warehouse_locations.code, warehouse_locations.name" }, { "name": "parent_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "parent_id.null", "in": "query", "required": false, "schema": { "type": "string", "description": "null: `true` = is null, `false` = is not null" }, "description": "null: `true` = is null, `false` = is not null" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: zone, shelf, bin" }, "description": "eq: one of: zone, shelf, bin" }, { "name": "type.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List locations of a warehouse", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" } }, "required": [ "id", "code", "name", "type" ] }, { "type": "null" } ] }, "depth": { "type": "number" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "parentId", "parentInfo", "depth", "code", "name", "type", "active", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.read" ] }, "post": { "operationId": "createWarehouseLocation", "summary": "Create a warehouse location", "description": "`parentId` must be a location of the same warehouse; locations nest at most 3 levels (422 `warehouse_location_too_deep`). `code` is unique per warehouse (409 `warehouse_location_code_exists`).", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "201": { "description": "Create a warehouse location", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" } }, "required": [ "id", "code", "name", "type" ] }, { "type": "null" } ] }, "depth": { "type": "number" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "parentId", "parentInfo", "depth", "code", "name", "type", "active", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.manage_locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,49}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "active": { "type": "boolean", "default": true } }, "required": [ "code", "type" ] } } } } } }, "/api/v1/warehouses/{id}/locations/{locationId}": { "get": { "operationId": "getWarehouseLocation", "summary": "Get a warehouse location", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get a warehouse location", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" } }, "required": [ "id", "code", "name", "type" ] }, { "type": "null" } ] }, "depth": { "type": "number" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "parentId", "parentInfo", "depth", "code", "name", "type", "active", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.read" ] }, "patch": { "operationId": "updateWarehouseLocation", "summary": "Update a warehouse location (partial)", "description": "Changing `parentId` is only allowed while the location has no children (409 `warehouse_location_has_children`).", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Update a warehouse location (partial)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "warehouseId": { "type": "string", "format": "uuid" }, "warehouseInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "active" ] }, { "type": "null" } ] }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "parentInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" } }, "required": [ "id", "code", "name", "type" ] }, { "type": "null" } ] }, "depth": { "type": "number" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "warehouseId", "warehouseInfo", "parentId", "parentInfo", "depth", "code", "name", "type", "active", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.manage_locations" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,49}$" }, "name": { "anyOf": [ { "type": "string", "maxLength": 150 }, { "type": "null" } ] }, "type": { "enum": [ "zone", "shelf", "bin" ], "type": "string" }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [] } } } } }, "delete": { "operationId": "deleteWarehouseLocation", "summary": "Delete a warehouse location", "description": "Deletes permanently; 409 `warehouse_location_has_children` while it has child locations. Stock rows that used it as their pick location lose it.", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "204": { "description": "Delete a warehouse location", "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.manage_locations" ] } }, "/api/v1/warehouses/{id}/restore": { "post": { "operationId": "restoreWarehouse", "summary": "Restore a warehouse from the trash", "description": "404 `warehouse_not_found` when it is not in the trash; 409 `warehouse_code_exists` when another warehouse took its code meanwhile. The restored warehouse is not the default.", "tags": [ "warehouses" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional unique key (1-255 printable ASCII, e.g. a UUID) for safely retrying this write: the same key + same request within 24 h returns the stored result with `Idempotent-Replayed: true` instead of running it again. Same key with a different request → 422 `idempotency_key_reused`; while the first one is still running → 409 `idempotency_in_progress`.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Restore a warehouse from the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "storeId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "physical", "virtual", "dropship" ], "type": "string" }, "addressLine": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" }, "priority": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "createdBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "createdByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "updatedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "updatedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "storeId", "code", "name", "type", "addressLine", "city", "phone", "email", "isDefault", "active", "priority", "createdAt", "createdBy", "createdByInfo", "updatedAt", "updatedBy", "updatedByInfo" ] } }, "required": [ "success", "data" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` when this is the stored result of an earlier request with the same Idempotency-Key", "schema": { "type": "string", "const": "true" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.restore" ] } }, "/api/v1/warehouses/options": { "get": { "operationId": "listWarehouseOptions", "summary": "List warehouse options", "description": "Same query as GET /warehouses, trimmed to `{ id, code, name, isDefault, active }` for pickers.", "tags": [ "warehouses" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "code", "-code", "name", "-name", "priority", "-priority", "created_at", "-created_at", "updated_at", "-updated_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `priority`" }, "description": "Sort field; prefix `-` for descending. Default `priority`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: warehouses.code, warehouses.name, warehouses.city" }, "description": "Case-insensitive substring search in: warehouses.code, warehouses.name, warehouses.city" }, { "name": "active", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "is_default", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: bool" }, "description": "eq: bool" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: one of: physical, virtual, dropship" }, "description": "eq: one of: physical, virtual, dropship" }, { "name": "type.in", "in": "query", "required": false, "schema": { "type": "string", "description": "in: comma-separated enum values (max 100)" }, "description": "in: comma-separated enum values (max 100)" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List warehouse options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" } }, "required": [ "id", "code", "name", "isDefault", "active" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.read" ] } }, "/api/v1/warehouses/trash": { "get": { "operationId": "listWarehouseTrash", "summary": "List warehouses in the trash", "description": "Warehouses of the current store that were moved to the trash, most recently deleted first. Restore with POST /warehouses/{id}/restore, delete permanently with DELETE /warehouses/{id}?force=true. Cursor-paginated.", "tags": [ "warehouses" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "deleted_at", "-deleted_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, "description": "Sort field; prefix `-` for descending. Default `-deleted_at`" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "description": "Case-insensitive substring search in: warehouses.code, warehouses.name" }, "description": "Case-insensitive substring search in: warehouses.code, warehouses.name" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List warehouses in the trash", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "type": "string" }, "deletedAt": { "type": "string", "format": "date-time", "pattern": "Z$" }, "deletedBy": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "deletedByInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "login": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "login", "name" ] }, { "type": "null" } ] } }, "required": [ "id", "code", "name", "deletedAt", "deletedBy", "deletedByInfo" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "warehouse.restore" ] } }, "/api/v1/wishlist": { "get": { "operationId": "listWishlistItems", "summary": "Wishlist items of the store's customers", "description": "Every saved variant of every customer, newest first. Filter by `customer_id` / `variant_id`. Cursor-paginated.", "tags": [ "wishlist" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": "20", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "description": "`meta.nextCursor` of the previous page" }, "description": "`meta.nextCursor` of the previous page" }, { "name": "sort", "in": "query", "required": false, "schema": { "enum": [ "created_at", "-created_at" ], "type": "string", "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, "description": "Sort field; prefix `-` for descending. Default `-created_at`" }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "variant_id", "in": "query", "required": false, "schema": { "type": "string", "description": "eq: uuid" }, "description": "eq: uuid" }, { "name": "x-database", "in": "header", "required": false, "description": "Business database; optional when the host name is mapped to one", "schema": { "type": "string" } }, { "name": "x-store", "in": "header", "required": false, "description": "Store code; must match the store the token was issued for (switch with /api/v1/auth/switch-store)", "schema": { "type": "string" } }, { "name": "x-lang", "in": "header", "required": false, "description": "Content language (BCP-47, e.g. vi, en); overrides Accept-Language. Unsupported values fall back to the store's default language", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Wishlist items of the store's customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customerId": { "type": "string", "format": "uuid" }, "customerInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "email" ] }, { "type": "null" } ] }, "variantId": { "type": "string", "format": "uuid" }, "variantInfo": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sku": { "type": "string" }, "barcode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" }, "productName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "productId": { "type": "string", "format": "uuid" }, "productInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "code", "name" ] }, "optionsLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "sku", "barcode", "active", "productName", "productId", "productInfo", "optionsLabel" ] }, { "type": "null" } ] }, "onSale": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "pattern": "Z$" } }, "required": [ "id", "customerId", "customerInfo", "variantId", "variantInfo", "onSale", "createdAt" ] } }, "meta": { "type": "object", "properties": { "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "nextCursor" ] } }, "required": [ "success", "data", "meta" ] } } }, "headers": { "Api-Version": { "description": "Contract version that answered this request", "schema": { "type": "string" } }, "x-request-id": { "description": "Request id to quote when reporting a problem (log lookup)", "schema": { "type": "string" } } } }, "default": { "$ref": "#/components/responses/Error" } }, "x-permissions": [ "wishlist.read" ] } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "responses": { "Error": { "description": "Error envelope", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "const": false }, "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {}, "at": { "type": "string", "description": "Element of the request body that caused the error, e.g. `lines.3` (multi-line operations)" } }, "required": [ "code", "message" ] } }, "required": [ "success", "error" ] } } } } } }, "security": [ { "bearer": [] } ] }