{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Kevmi — API de servidor", "version": "2026-10-23.12", "description": "API de Kevmi: inicio de sesión con Telegram, sesiones, facturas de comerciante, pago del comprador cifrado, soporte, notificaciones, aplicaciones y entrega de webhooks. Solo pagos directos únicos. Las respuestas JSON usan no-store. Las marcas de tiempo son milisegundos UTC Unix salvo que se indique lo contrario. El pago en vivo usa una pasarela externa configurada; los campos de tarjeta y código bancario se cifran en el navegador y solo la pasarela los descifra. Los nuevos cobros requieren que se apruebe la última aplicación del sitio web del comerciante. Crear una factura no cobra al comprador.", "x-updated-at": "2026-10-23" }, "servers": [ { "url": "https://kevmi.one", "description": "El origen público del proyecto; la plataforma de alojamiento puede aplicar controles de acceso adicionales." } ], "externalDocs": { "description": "Documentación pública del producto", "url": "https://kevmi.one/docs" }, "tags": [ { "name": "Service", "description": "Estado público del servicio." }, { "name": "Auth", "description": "El registro y el inicio de sesión comparten el flujo verificado de Telegram." }, { "name": "Account", "description": "Configuración solo para el usuario actual." }, { "name": "Payment links", "description": "Facturas de servidor para la tienda actual. El precio, la moneda, el pagador de IVA, el nombre del vendedor y el cálculo son inmutables." }, { "name": "Checkout", "description": "Leer una factura sin cuenta. La disponibilidad de pago se verifica por separado." }, { "name": "Support", "description": "Base de conocimientos pública y solicitudes de soporte del usuario actual." }, { "name": "Notifications", "description": "Centro de eventos de la cuenta, estado de lectura del sitio web y estado de entrega independiente de Telegram." }, { "name": "Telegram", "description": "Webhook del bot; no es un webhook de pago." }, { "name": "Disabled payments", "description": "Rutas de dinero heredadas no compatibles y ejecución de pagos. El flujo público de pago tiene sus propios endpoints documentados." }, { "name": "Merchant API", "description": "Facturas de servidor a servidor con ámbito y historial de eventos inmutable." }, { "name": "Webhooks", "description": "Endpoints HTTPS verificados, eventos firmados, intentos de entrega y reintentos." }, { "name": "Applications", "description": "Aplicaciones de sitio web autenticadas y seguimiento individual." }, { "name": "Moderation", "description": "Moderadores de Telegram en lista de permitidos; cada decisión se verifica por versión." }, { "name": "Gateway events", "description": "Los eventos de pasarela de origen nativo se verifican, luego el pago autoritativo se lee mediante transporte de servidor autenticado. Los webhooks dirigidos al comerciante usan una firma y una cola de entrega separadas." } ], "security": [], "x-disabled-route-prefixes": [ "/api/payments", "/api/payouts", "/api/gateway", "/api/linzapay" ], "x-disabled-route-behavior": "Legacy unscoped direct-money routes and payout execution remain disabled. Authenticated /api/v1/payments creates invoices; /api/checkout/{token} exposes the separate buyer checkout flow. POST /api/gateway/webhook accepts signed gateway events.", "paths": { "/api/config": { "get": { "tags": [ "Service" ], "operationId": "getConfig", "summary": "Preparación de integración actual", "responses": { "200": { "description": "Configuración sin secretos.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Config" } } } }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/health": { "get": { "tags": [ "Service" ], "operationId": "getHealth", "summary": "Estado de la tabla de API y D1", "description": "not_configured puede tener status=ok: las páginas públicas y la búsqueda pueden funcionar sin BD. Una BD configurada con tablas no disponibles devuelve 503/degraded. Esta respuesta no prueba la conectividad de red de Telegram ni del modelo.", "responses": { "200": { "description": "El almacenamiento está listo o es not_configured.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "D1 no está disponible o ocurrió un error inesperado del servicio.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Health" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/auth/me": { "get": { "tags": [ "Auth" ], "operationId": "getCurrentSession", "summary": "Sesión actual y CSRF", "security": [ {}, { "cookieSession": [] } ], "responses": { "200": { "description": "authenticated=false cuando no existe una sesión válida.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Anonymous" }, { "$ref": "#/components/schemas/CurrentSession" } ] } } } }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/telegram/start": { "post": { "tags": [ "Auth" ], "operationId": "startTelegramLogin", "summary": "Iniciar inicio de sesión o registro", "description": "Crea un desafío de 300 segundos y una cookie de prueba de navegador HttpOnly; como máximo seis inicios por minuto por dirección con hash. Compara el código de seis dígitos en el sitio web y en el chat privado del bot.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "201": { "description": "Solicitud de inicio de sesión creada; la cookie de prueba la vincula al navegador original.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Segura; HttpOnly; SameSite=Lax; Path=/. JavaScript no puede acceder al valor de la sesión. Completar el inicio de sesión también elimina la cookie de prueba del navegador." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginChallenge" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/telegram/complete": { "post": { "tags": [ "Auth" ], "operationId": "completeTelegramLogin", "summary": "Completar un inicio de sesión verificado", "description": "Requiere la cookie de prueba del inicio y el mismo navegador. Pendiente devuelve 202. Después de la confirmación del bot, la solicitud emite una sesión de 24 horas. Hasta 90 verificaciones por minuto por desafío. No se acepta un ID de Telegram proporcionado por el cliente.", "security": [ { "browserProof": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "challengeId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Cuenta creada o actualizada y sesión emitida.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Segura; HttpOnly; SameSite=Lax; Path=/. JavaScript no puede acceder al valor de la sesión. Completar el inicio de sesión también elimina la cookie de prueba del navegador." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletedLogin" } } } }, "202": { "description": "Esperando confirmación en Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "pending" } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "La solicitud de inicio de sesión de cinco minutos expiró.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_EXPIRED" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/logout": { "post": { "tags": [ "Auth" ], "operationId": "logoutCurrentSession", "summary": "Terminar la sesión actual", "description": "No se requiere ni se lee ningún cuerpo. El comando /logout del bot termina por separado todas las sesiones de la cuenta.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Sesión eliminada y cookie borrada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Segura; HttpOnly; SameSite=Lax; Path=/. JavaScript no puede acceder al valor de la sesión. Completar el inicio de sesión también elimina la cookie de prueba del navegador." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "loggedOut": { "type": "boolean", "const": true } }, "required": [ "loggedOut" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/account/settings": { "get": { "tags": [ "Account" ], "operationId": "getAccountSettings", "summary": "Configuración del usuario actual", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Campos públicos del perfil del usuario actual.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ] }, "patch": { "tags": [ "Account" ], "operationId": "updateAccountSettings", "summary": "Cambiar el nombre de la tienda, el pagador de IVA o las notificaciones", "description": "Todos los campos son opcionales: parche parcial. Guardar vatPayer no crea una operación financiera. Los interruptores de pagos y pagos salientes controlan preferencias, no la disponibilidad de la pasarela.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsPatch" } } } }, "responses": { "200": { "description": "Perfil actualizado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/ask": { "post": { "tags": [ "Support" ], "operationId": "askDocumentation", "summary": "Respuesta de la base de conocimientos pública completa", "description": "Asistencia de documentación con lecturas opcionales de cuenta autenticada. Sin includeAccount=true, no se habilitan herramientas privadas de cuenta. La herramienta acotada read_account puede leer tiendas, facturas y recibos verificados, eventos, solicitudes de aplicaciones y tickets de soporte con respuestas. Los filtros de propietario y tienda se aplican en el servidor; las herramientas no pueden mover fondos, modificar configuración ni devolver secretos de integración. Los resultados están paginados; una muestra incompleta no es el historial completo de transacciones. Las fallas del proveedor o de salida devuelven una búsqueda etiquetada en documentación. Se aplican una cuota global de generación y un límite de solicitudes por IP.", "parameters": [ { "name": "Origin", "in": "header", "required": false, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Requerido cuando includeAccount=true." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string" }, "description": "ID de tienda propiedad del usuario o todos; se ignora cuando el acceso a la cuenta está deshabilitado." } ], "requestBody": { "required": true, "description": "Objeto JSON de hasta 65,536 bytes. Los campos desconocidos se rechazan. Las longitudes de texto se verifican después de recortar.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportQuestion" } } } }, "responses": { "200": { "description": "Una respuesta o documentación coincidente con enlaces de artículos validados.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportAnswer" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/tickets": { "get": { "tags": [ "Support" ], "operationId": "listOwnTickets", "summary": "Las últimas 30 solicitudes de soporte propias.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Más recientes primero por createdAt; devuelve los últimos 30 registros.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "tickets": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Ticket" } } }, "required": [ "tickets" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Support" ], "operationId": "createOwnTicket", "summary": "Guardar una solicitud de soporte", "description": "Hasta 6 solicitudes por hora por usuario, cuota compartida para el sitio y el bot. Guardar crea una solicitud en la cuenta. Use su número para aclarar el estado. Se pone en cola una alerta administrativa duradera separada con un enlace directo al ticket; las fallas temporales de entrega se reintentan. Las respuestas del especialista siguen siendo legibles en la cuenta incluso cuando las notificaciones de Telegram están deshabilitadas.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Los espacios circundantes se recortan. Longitud después del recorte: 1–120 caracteres. Los caracteres de control excepto tabulaciones y saltos de línea están prohibidos." }, "message": { "type": "string", "minLength": 5, "x-trimmedMaxLength": 4000, "x-trimmedMinLength": 5, "description": "Los espacios circundantes se recortan. Longitud después del recorte: 5–4,000 caracteres. Los caracteres de control excepto tabulaciones y saltos de línea están prohibidos." } }, "required": [ "subject", "message" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Solicitud de soporte guardada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/tickets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tkt_[a-f0-9-]{36}$" }, "description": "Identificador de una solicitud de soporte propia." } ], "get": { "tags": [ "Support" ], "operationId": "getOwnTicket", "summary": "Leer una solicitud de soporte propia", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "La solicitud de otro usuario y una solicitud inexistente devuelven 404.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "patch": { "tags": [ "Support" ], "operationId": "closeOwnTicket", "summary": "Cerrar una solicitud de soporte propia", "description": "El único cambio permitido es estado=cerrado. Esta API no reabre solicitudes, edita mensajes ni envía respuestas de operador.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "closed" } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Solicitud de soporte cerrada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "closed": { "type": "boolean", "const": true } }, "required": [ "closed" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications": { "get": { "tags": [ "Notifications" ], "operationId": "listOwnNotifications", "summary": "Una página de notificaciones propias", "description": "Hasta 30 registros, ordenados por createdAt DESC y luego id DESC. El listado no cambia readAt ni activa la entrega. unreadCount es el total de no leídos del usuario actual en todas las páginas. Los campos de propietario, ID de Telegram y secretos se excluyen.", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "unread", "in": "query", "description": "1 selecciona solo no leídos; 0 o un valor omitido selecciona todos los eventos.", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" } }, { "name": "cursor", "in": "query", "description": "nextCursor de la respuesta anterior. Páselo sin cambios por URLSearchParams; formato createdAt:id, con createdAt como entero seguro en milisegundos.", "schema": { "type": "string", "pattern": "^\\d{1,16}:ntf_[A-Za-z0-9-]{1,80}$" } } ], "responses": { "200": { "description": "Eventos con estados independientes de lectura y entrega.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsPage" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications/read": { "patch": { "tags": [ "Notifications" ], "operationId": "markOwnNotificationsRead", "summary": "Marcar notificaciones propias como leídas", "description": "Acepta o ids, o all:true junto con before. before es el momento del último evento observado y no puede superar la hora del servidor. Los eventos más nuevos permanecen no leídos. La solicitud es idempotente: los valores readAt existentes no cambian. Los IDs de otros usuarios e inexistentes no se modifican ni revelan. El estado de Telegram y sentAt permanecen sin cambios.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadNotifications" } } } }, "responses": { "200": { "description": "El número de eventos recién leídos, el tiempo de operación y el recuento actual de no leídos.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadNotificationsResult" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications/test": { "post": { "tags": [ "Notifications" ], "operationId": "testOwnNotification", "summary": "Enviar una notificación de prueba al Telegram de la cuenta", "description": "Pone un mensaje en cola e intenta la entrega. Como máximo tres por usuario por hora. La prueba no es una notificación de pago y no cambia un saldo. HTTP 202 no confirma la entrega; revise la lista de notificaciones.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "202": { "description": "Resultado de la puesta en cola.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "id": { "type": [ "string", "null" ] } }, "required": [ "queued" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/telegram/webhook": { "post": { "tags": [ "Telegram" ], "operationId": "receiveTelegramUpdate", "summary": "Recibir un evento de Telegram Bot API", "description": "Solo requiere el encabezado secreto de Telegram, sin sesión, CSRF ni Origin. Se permiten campos adicionales de Update. Maneja message y callback_query; las acciones personales requieren el chat privado del remitente verificado. Otros updates se omiten. update_id se deduplica; un update en curso devuelve 503 para reintentar. Esto no es un webhook de proveedor de pagos.", "security": [ { "telegramWebhookSecret": [] } ], "requestBody": { "required": true, "description": "Telegram Update, máximo 65,536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramUpdate" } } } }, "responses": { "200": { "description": "Procesado, omitido o ya manejado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "La solicitud de Telegram falló.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TELEGRAM_UNAVAILABLE", "TELEGRAM_INVALID_RESPONSE", "TELEGRAM_RATE_LIMITED", "TELEGRAM_DELIVERY_FAILED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/payments": { "post": { "tags": [ "Disabled payments" ], "operationId": "paymentsUnavailable", "summary": "Operación financiera no disponible", "description": "Devuelve 503 GATEWAY_NOT_CONNECTED. Las operaciones financieras no están disponibles. El cuerpo no se procesa y no se realiza ninguna solicitud a la pasarela.", "security": [], "responses": { "503": { "description": "Las operaciones financieras no están disponibles.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "GATEWAY_NOT_CONNECTED" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/payouts": { "post": { "tags": [ "Disabled payments" ], "operationId": "payoutsUnavailable", "summary": "Operación financiera no disponible", "description": "Devuelve 503 GATEWAY_NOT_CONNECTED. Las operaciones financieras no están disponibles. El cuerpo no se procesa y no se realiza ninguna solicitud a la pasarela.", "security": [], "responses": { "503": { "description": "Las operaciones financieras no están disponibles.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "GATEWAY_NOT_CONNECTED" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/openapi.json": { "get": { "tags": [ "Service" ], "operationId": "getOpenApi", "summary": "Contrato público legible por máquina", "description": "Solo lectura. No contiene secretos, sesiones, registros de usuario ni contrato operativo de proveedor de pagos.", "responses": { "200": { "description": "Este documento OpenAPI 3.1.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "public, max-age=300" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "openapi", "info", "paths" ], "additionalProperties": true } } } } } } }, "/api/payment-links": { "get": { "tags": [ "Payment links" ], "operationId": "listOwnPaymentLinks", "summary": "Listar enlaces de pago propios", "security": [ { "cookieSession": [] } ], "description": "Ordenados por createdAt DESC, id DESC. Los enlaces públicos funcionan entre dispositivos; el listado requiere una cuenta.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor de la respuesta anterior. El servicio usa JSON en base64 [createdAt,id]; páselo sin cambios por URLSearchParams." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "responses": { "200": { "description": "Una página de enlaces de pago propios.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Payment links" ], "operationId": "createOwnPaymentLink", "summary": "Crear una factura con términos inmutables", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Una clave por solicitud lógica. Una repetición con entrada canónica idéntica devuelve el registro original; entrada diferente con la misma clave devuelve 409." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "description": "Crear una factura inmutable y recibir inmediatamente checkoutUrl; esto no cobra al comprador. USD: tarjeta/Alipay; RUB: SBP; USDT: cripto. USD cripto sigue aceptado por compatibilidad, pero no se puede pagar sin una factura USDT. Las cuotas de tarifa e IVA del cliente son enteros independientes de 0 a 100; la tarjeta/Alipay en vivo actual admite IVA cliente=100 y tarifa cliente=0. El total del cliente nunca se cambia en silencio. La aplicación más reciente debe aprobarse antes de un nuevo cargo en vivo. La creación de la factura y su evento de comerciante se confirman atómicamente.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Repetición idempotente; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Factura creada; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/payment-links/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Identificador de enlace propio, no el token público." } ], "get": { "tags": [ "Payment links" ], "operationId": "getOwnPaymentLink", "summary": "Enlace propio y cálculo guardado", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "El ID de otro usuario y un ID inexistente devuelven 404.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ] }, "patch": { "tags": [ "Payment links" ], "operationId": "changePaymentLinkStatus", "summary": "Pausar, reanudar o cancelar un enlace", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "description": "Solo cambia el estado. La actualización y el evento inmutable invoice.updated se confirman atómicamente. Los cambios concurrentes usan una verificación de versión; actualice y reintente en LINK_CHANGED. cancelled es terminal, la expiración nunca se extiende, y el precio, métodos, cuotas de costo y descripción permanecen congelados. Repetir el estado guardado devuelve la factura actual.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Estado actual del enlace propio.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura." } ], "get": { "tags": [ "Checkout" ], "operationId": "getPublicCheckout", "summary": "Detalles de factura pública para el cliente", "description": "Leer la cotización de factura pública inmutable y su instantánea de pago persistida. method debe pertenecer a la factura. No se requiere cuenta. No expone la identidad del propietario, metadatos privados ni ganancias del comerciante. El token otorga acceso solo a este pago. availability refleja configuración, asignación, límites técnicos y aprobación del comerciante; la confirmación de pago es separada.", "parameters": [ { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "description": "Debe estar presente en los métodos guardados de la factura." } ], "responses": { "200": { "description": "Factura pública y el pago existente, si fue enviado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/CheckoutInvoice" }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] } }, "required": [ "invoice", "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/pay": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura." } ], "post": { "tags": [ "Checkout" ], "operationId": "startCheckoutPayment", "summary": "Iniciar o recuperar el pago de la factura", "description": "Operación de comprador de mismo origen; no se requiere cuenta ni token CSRF. El servidor reserva una operación y una clave de idempotencia estable antes del envío a la pasarela. Una repetición recupera la misma operación; una respuesta perdida debe resolverse mediante el estado. El método de pago se bloquea después del envío. Los datos de la tarjeta deben cifrarse en el navegador con una intención de pago nueva. SBP/cripto envían el total del cliente guardado; tarjeta/Alipay usan la configuración fiscal inmutable admitida. Los nuevos cargos requieren una solicitud de comercio aprobada. Los pagos ya enviados pueden recuperarse después del vencimiento de la factura, una pausa o cambios de aprobación. No se usa ninguna ruta /v2 ni de tarjeta alojada.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCheckoutPayment" } } } }, "responses": { "200": { "description": "Operación existente recuperada; sin segundo pago.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "202": { "description": "Operación enviada; la finalización es asíncrona.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "La intención de cifrado de la pasarela o el desafío del banco expiraron. Obtenga una intención nueva para la misma operación; no cree un pago de reemplazo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/v1/payments": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnPaymentLinksViaPayments", "summary": "Listar enlaces de pago propios", "security": [ { "merchantKey": [] } ], "description": "Ordenados por createdAt DESC, id DESC. Los enlaces públicos funcionan entre dispositivos; el listado requiere una cuenta.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor de la respuesta anterior. El servicio usa JSON en base64 [createdAt,id]; páselo sin cambios por URLSearchParams." } ], "responses": { "200": { "description": "Una página de enlaces de pago propios.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:read" }, "post": { "tags": [ "Merchant API" ], "operationId": "createOwnPaymentLinkViaPayments", "summary": "Crear una factura con términos inmutables", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Una clave por solicitud lógica. Una repetición con entrada canónica idéntica devuelve el registro original; entrada diferente con la misma clave devuelve 409." } ], "description": "Crear una factura inmutable y recibir inmediatamente checkoutUrl; esto no cobra al comprador. USD: tarjeta/Alipay; RUB: SBP; USDT: cripto. USD cripto sigue aceptado por compatibilidad, pero no se puede pagar sin una factura USDT. Las cuotas de tarifa e IVA del cliente son enteros independientes de 0 a 100; la tarjeta/Alipay en vivo actual admite IVA cliente=100 y tarifa cliente=0. El total del cliente nunca se cambia en silencio. La aplicación más reciente debe aprobarse antes de un nuevo cargo en vivo. La creación de la factura y su evento de comerciante se confirman atómicamente.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Repetición idempotente; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Factura creada; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Identificador de enlace propio, no el token público." } ], "get": { "tags": [ "Merchant API" ], "operationId": "getOwnPaymentLinkViaPayments", "summary": "Enlace propio y cálculo guardado", "security": [ { "merchantKey": [] } ], "responses": { "200": { "description": "El ID de otro usuario y un ID inexistente devuelven 404.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [], "x-required-scope": "invoices:read" }, "patch": { "tags": [ "Merchant API" ], "operationId": "changePaymentLinkStatusViaPayments", "summary": "Pausar, reanudar o cancelar un enlace", "security": [ { "merchantKey": [] } ], "parameters": [], "description": "Solo cambia el estado. La actualización y el evento inmutable invoice.updated se confirman atómicamente. Los cambios concurrentes usan una verificación de versión; actualice y reintente en LINK_CHANGED. cancelled es terminal, la expiración nunca se extiende, y el precio, métodos, cuotas de costo y descripción permanecen congelados. Repetir el estado guardado devuelve la factura actual.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Estado actual del enlace propio.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payment-links": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnPaymentLinksViaLinks", "summary": "Listar enlaces de pago propios", "security": [ { "merchantKey": [] } ], "description": "Ordenados por createdAt DESC, id DESC. Los enlaces públicos funcionan entre dispositivos; el listado requiere una cuenta.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor de la respuesta anterior. El servicio usa JSON en base64 [createdAt,id]; páselo sin cambios por URLSearchParams." } ], "responses": { "200": { "description": "Una página de enlaces de pago propios.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:read" }, "post": { "tags": [ "Merchant API" ], "operationId": "createOwnPaymentLinkViaLinks", "summary": "Crear una factura con términos inmutables", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Una clave por solicitud lógica. Una repetición con entrada canónica idéntica devuelve el registro original; entrada diferente con la misma clave devuelve 409." } ], "description": "Crear una factura inmutable y recibir inmediatamente checkoutUrl; esto no cobra al comprador. USD: tarjeta/Alipay; RUB: SBP; USDT: cripto. USD cripto sigue aceptado por compatibilidad, pero no se puede pagar sin una factura USDT. Las cuotas de tarifa e IVA del cliente son enteros independientes de 0 a 100; la tarjeta/Alipay en vivo actual admite IVA cliente=100 y tarifa cliente=0. El total del cliente nunca se cambia en silencio. La aplicación más reciente debe aprobarse antes de un nuevo cargo en vivo. La creación de la factura y su evento de comerciante se confirman atómicamente.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Repetición idempotente; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Factura creada; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payment-links/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Identificador de enlace propio, no el token público." } ], "get": { "tags": [ "Merchant API" ], "operationId": "getOwnPaymentLinkViaLinks", "summary": "Enlace propio y cálculo guardado", "security": [ { "merchantKey": [] } ], "responses": { "200": { "description": "El ID de otro usuario y un ID inexistente devuelven 404.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [], "x-required-scope": "invoices:read" }, "patch": { "tags": [ "Merchant API" ], "operationId": "changePaymentLinkStatusViaLinks", "summary": "Pausar, reanudar o cancelar un enlace", "security": [ { "merchantKey": [] } ], "parameters": [], "description": "Solo cambia el estado. La actualización y el evento inmutable invoice.updated se confirman atómicamente. Los cambios concurrentes usan una verificación de versión; actualice y reintente en LINK_CHANGED. cancelled es terminal, la expiración nunca se extiende, y el precio, métodos, cuotas de costo y descripción permanecen congelados. Repetir el estado guardado devuelve la factura actual.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Estado actual del enlace propio.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/api-keys": { "get": { "tags": [ "Merchant API" ], "operationId": "listMerchantKeys", "summary": "Listar metadatos de claves propias", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Se omiten secretos y hashes de secretos.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantKey" } } }, "required": [ "keys" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ] }, "post": { "tags": [ "Merchant API" ], "operationId": "createMerchantKey", "summary": "Crear una clave con ámbito; revelar su secreto una vez", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "description": "Máximo de 10 claves activas. Como máximo 5 creaciones/hora/usuario. Las claves expiran, pueden revocarse y están limitadas a 90 solicitudes de API/minuto/clave.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoices:read", "invoices:write", "events:read" ] } }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Almacene el secreto de forma segura en su servidor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/MerchantKey" }, "secret": { "type": "string", "pattern": "^kv_live_[A-Za-z0-9_-]{43}$" } }, "required": [ "key", "secret" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/api-keys/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^key_[0-9a-f-]{36}$" } } ], "delete": { "tags": [ "Merchant API" ], "operationId": "revokeMerchantKey", "summary": "Revocar clave propia", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "responses": { "200": { "description": "Se rechazan los usos futuros de la clave.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "const": true } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/events": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnEvents", "summary": "Leer historial de eventos propio inmutable", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "description": "Límite de marca de tiempo exclusivo heredado. No puede combinarse con cursor. Use nextCursor para paginación sin pérdidas." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor opaco devuelto por la página anterior. Codifica [createdAt,id] y conserva eventos que comparten una marca de tiempo." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "responses": { "200": { "description": "Más recientes primero; hasta 50 eventos. Siga nextCursor hasta que sea null.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MerchantEvent" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "events", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/v1/events": { "get": { "tags": [ "Merchant API" ], "operationId": "listMerchantEventsWithKey", "summary": "Leer historial de eventos propio inmutable", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "description": "Límite de marca de tiempo exclusivo heredado. No puede combinarse con cursor. Use nextCursor para paginación sin pérdidas." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor opaco devuelto por la página anterior. Codifica [createdAt,id] y conserva eventos que comparten una marca de tiempo." } ], "responses": { "200": { "description": "Más recientes primero; hasta 50 eventos. Siga nextCursor hasta que sea null.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MerchantEvent" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "events", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "events:read" } }, "/api/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "Listar endpoints y las últimas 30 entregas", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "No se devuelven secretos de firma.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "available": { "type": "boolean" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "endpoints", "deliveries", "available", "eventTypes" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ] }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Registrar un destino HTTPS público", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "description": "Hasta 5 endpoints y 6 creaciones/hora/usuario. Solo dominios HTTPS públicos; sin credenciales, literales de IP ni puertos personalizados. Un endpoint recién creado no recibe entregas en vivo hasta que su desafío tenga éxito.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": "string", "maxLength": 120 }, "events": { "type": "array", "minItems": 1, "maxItems": 8, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Guarde el secreto de firma de un solo uso.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$", "description": "Se muestra solo al crear/rotar. Se almacena cifrado en el servidor." } }, "required": [ "endpoint", "secret" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Listar endpoints y las últimas 30 entregas", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "No se devuelven secretos de firma.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "available": { "type": "boolean" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "endpoints", "deliveries", "available", "eventTypes" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ] }, "patch": { "tags": [ "Webhooks" ], "operationId": "setWebhookStatus", "summary": "Pausar o reanudar un endpoint verificado", "description": "Los endpoints verificados pausados mantienen eventos elegibles en la cola; reanudar procesa las entregas pendientes.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Estado guardado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "const": true } }, "required": [ "updated" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Eliminar endpoint y cancelar trabajos no entregados", "description": "Cancela trabajos pendientes, fallidos y arrendados. Una solicitud ya enviada a través de la red no puede recuperarse.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "responses": { "200": { "description": "Endpoint eliminado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "const": true } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/verify": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "verifyWebhookEndpoint", "summary": "Enviar un desafío de verificación de endpoint firmado", "description": "Máximo de 5 intentos de verificación/hora/usuario. Su servidor debe validar Kevmi-Signature y devolver JSON 2xx {\"challenge\":\"\"}. Tiempo de espera de solicitud: 8 segundos; límite de respuesta: 8192 bytes. No se siguen redirecciones. La verificación activa el endpoint.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Verificado y activo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "const": true }, "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "verified", "endpoint" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "422": { "description": "No se pudo verificar el destino.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "WEBHOOK_UNREACHABLE", "WEBHOOK_VERIFICATION_FAILED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/rotate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Reemplazar secreto de firma y requerir verificación nuevamente", "description": "Máximo de 3 rotaciones/hora/usuario. Actualice su servidor y verifique el endpoint nuevamente. Una solicitud ya en vuelo puede aún llevar la firma anterior.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Nuevo secreto mostrado una vez.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$", "description": "Se muestra solo al crear/rotar. Se almacena cifrado en el servidor." }, "requiresVerification": { "const": true } }, "required": [ "secret", "requiresVerification" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/deliveries/{deliveryId}/retry": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^del_[a-f0-9]{40}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "retryWebhookDelivery", "summary": "Reintentar una entrega fallida a un endpoint activo", "description": "Conserva el ID del evento y la carga útil; genera una marca de tiempo y una firma nuevas. Cada ciclo de entrega automático hace como máximo 6 intentos, incluidos arrendamientos expirados, con demoras de 1m, 5m, 30m, 2h y 12h. La entrega es al menos una vez; deduplique IDs de eventos en su servidor.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "202": { "description": "Reintento programado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "const": true } }, "required": [ "queued" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications": { "get": { "tags": [ "Applications" ], "operationId": "listOwnApplications", "summary": "Listar hasta 30 aplicaciones propias", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "URL de seguimiento e idioma de mensajes del sistema. Sin un valor admitido, se consideran el referrer de mismo origen y el idioma del navegador; el respaldo es inglés." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "responses": { "200": { "description": "Más recientes primero.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Application" } } }, "required": [ "applications" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Applications" ], "operationId": "submitWebsiteApplication", "summary": "Enviar información del sitio web y recibir una URL de seguimiento", "description": "Requiere inicio de sesión de Telegram confirmado. Hasta 5 nuevos envíos/día/usuario. La repetición idempotente devuelve 200. El servidor avanza etapas reales persistidas; los resultados automáticos no disponibles o riesgosos requieren revisión humana. La aprobación no configura la pasarela de pago. La propiedad y el estado no pueden ser proporcionados por el solicitante.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Una clave por solicitud lógica. Una repetición con entrada canónica idéntica devuelve el registro original; entrada diferente con la misma clave devuelve 409." }, { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "URL de seguimiento e idioma de mensajes del sistema. Sin un valor admitido, se consideran el referrer de mismo origen y el idioma del navegador; el respaldo es inglés." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Dominio HTTPS público sin credenciales, parámetros de consulta, literales de IP ni puertos personalizados. Un fragmento se elimina durante la normalización." }, "businessName": { "type": "string", "minLength": 1, "maxLength": 100 }, "businessType": { "type": "string", "enum": [ "digital_goods", "software", "services", "physical_goods", "education", "other" ] }, "description": { "type": "string", "minLength": 40, "maxLength": 3000 }, "contactTelegram": { "type": "string", "description": "Un nombre de usuario de Telegram de 5–32 caracteres que comienza con una letra, luego letras/dígitos/guiones bajos. Prefijo opcional @ o https://t.me/; se recortan los espacios circundantes. Se almacena como @username." }, "consent": { "type": "boolean", "const": true } }, "required": [ "websiteUrl", "businessName", "businessType", "description", "contactTelegram", "consent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Envío existente.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "url": { "type": "string", "format": "uri" }, "replayed": { "type": "boolean" } }, "required": [ "application", "url", "replayed" ], "additionalProperties": false } } } }, "202": { "description": "Aceptado; el procesamiento continúa en el servidor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "url": { "type": "string", "format": "uri" }, "replayed": { "type": "boolean" } }, "required": [ "application", "url", "replayed" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "get": { "tags": [ "Applications" ], "operationId": "getOwnApplication", "summary": "Leer etapas de revisión propias e historial de eventos", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "URL de seguimiento e idioma de mensajes del sistema. Sin un valor admitido, se consideran el referrer de mismo origen y el idioma del navegador; el respaldo es inglés." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "responses": { "200": { "description": "Proyección privada del solicitante. La evidencia y la salida del modelo no se exponen.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "events": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/ApplicationEvent" } } }, "required": [ "application", "events" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications/{id}/resume": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "post": { "tags": [ "Applications" ], "operationId": "resumeApplicationJob", "summary": "Reanudar una etapa de fondo elegible", "description": "No se puede omitir la revisión ni aprobar una etapa. Un arrendamiento del servidor evita el trabajo duplicado. Las aplicaciones que requieren revisión y las finales permanecen sin cambios. Como máximo 30 solicitudes de reanudación de procesamiento/minuto/usuario.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "URL de seguimiento e idioma de mensajes del sistema. Sin un valor admitido, se consideran el referrer de mismo origen y el idioma del navegador; el respaldo es inglés." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "No se necesita procesamiento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" } }, "required": [ "application" ], "additionalProperties": false } } } }, "202": { "description": "Procesamiento programado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "scheduled": { "type": "boolean", "const": true } }, "required": [ "application", "scheduled" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications": { "get": { "tags": [ "Moderation" ], "operationId": "listModerationApplications", "summary": "Listar hasta 100 aplicaciones para moderación", "description": "Requiere que la identidad autenticada de Telegram esté en MODERATOR_TELEGRAM_IDS. Incluye todos los estados, ordenados needs_review primero, processing segundo, luego estados finales; actualizaciones más recientes primero dentro de un grupo.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Cola de moderador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Application" } } }, "required": [ "applications" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "get": { "tags": [ "Moderation" ], "operationId": "getModerationApplication", "summary": "Leer evidencia de revisión e historial de etapas", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Evidencia privada del moderador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "events": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/ApplicationEvent" } }, "evidence": { "type": "object", "additionalProperties": true } }, "required": [ "application", "events", "evidence" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications/{id}/decision": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "post": { "tags": [ "Moderation" ], "operationId": "decideApplicationStage", "summary": "Aprobar la etapa de revisión actual o rechazar con una razón pública", "description": "Requiere un moderador configurado; como máximo 30 decisiones/minuto/usuario. versionExpected se compara atómicamente. Solo la etapa actual needs_review puede ser aprobada; las solicitudes finales no pueden reabrirse en silencio. Un rechazo requiere una razón pública editable. La decisión, el historial de etapas y la notificación habilitada al solicitante se guardan juntos.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "const": "approve_step" }, "reason": { "type": "string", "maxLength": 0 } }, "required": [ "expectedVersion", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "const": "reject" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1500 } }, "required": [ "expectedVersion", "action", "reason" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Decisión guardada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" } }, "required": [ "application" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/gateway/webhook": { "post": { "tags": [ "Gateway events" ], "operationId": "receiveGatewayEvent", "summary": "Recibir eventos de pasarela nativos firmados", "description": "Nativo v3: proporcione X-Gateway-Timestamp (segundos Unix), X-Gateway-Signature y un X-Gateway-Event-Id coincidente. La desviación máxima de marca de tiempo es de 300 segundos. Tras la verificación de la firma, Kevmi obtiene el pago a través de la API de pasarela autenticada, verifica la orden guardada, la moneda/importe exactos, el método y el estado confirmado por el proveedor, y luego almacena atómicamente el recibo y el evento de bandeja de salida del comerciante. El texto del webhook y las observaciones del navegador por sí solos nunca confirman un pago. Los ID repetidos se deduplican; un cuerpo modificado para un ID existente se rechaza. Los eventos retrasados usan estado autoritativo actualizado. Se admiten reembolsos parciales, reembolsos totales, disputas y estados de revisión. Las órdenes no vinculadas se reconocen e ignoran. Los eventos normalizados heredados que usan Kevmi-Signature siguen admitidos por separado; solo aplican sus transiciones succeeded/failed/full-refunded.", "security": [ { "nativeGatewaySignature": [] }, { "gatewaySignature": [] } ], "parameters": [ { "name": "X-Gateway-Timestamp", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{10}$" }, "description": "Requerido para eventos nativos v3." }, { "name": "X-Gateway-Event-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Requerido para nativo v3; debe coincidir con body.id." } ], "requestBody": { "required": true, "description": "Cuerpo JSON firmado exacto; límite nativo v3: 524288 bytes. No analice ni vuelva a serializar antes de la verificación de la firma.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NativeGatewayEvent" }, { "$ref": "#/components/schemas/LegacyGatewayEvent" } ] } } } }, "responses": { "200": { "description": "Recibido, deduplicado o ignorado de forma segura.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" }, "ignored": { "type": "boolean" }, "applied": { "type": "boolean" } }, "required": [ "received" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "La firma de la pasarela falta, no es válida o está fuera de la ventana de tiempo aceptada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_GATEWAY_SIGNATURE", "INVALID_SIGNATURE", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Se reutilizó un ID de evento con contenido cambiado o un ID de pago entra en conflicto con el vínculo de factura guardado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_EVENT_CONFLICT", "PAYMENT_ID_CONFLICT" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "La pasarela está ocupada; reintente la entrega del webhook con el mismo ID de evento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_BUSY" ] }, "502": { "description": "Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Falta la configuración de la pasarela o el secreto de firma.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_NOT_CONNECTED", "DATABASE_NOT_CONFIGURED" ] } } } }, "/api/jobs/dispatch": { "post": { "tags": [ "Service" ], "operationId": "dispatchBackgroundJobs", "summary": "Ejecutar trabajos de entrega y aplicación pendientes", "description": "Punto de entrada del programador del servidor. Requiere JOBS_SECRET, no una sesión de navegador ni una clave de comerciante. No acepta ID de trabajos ni URL de salida arbitrarias.", "security": [ { "jobSecret": [] } ], "responses": { "200": { "description": "Completado sin un contexto de fondo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Aceptado en un contexto de ejecución en segundo plano.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "const": true } }, "required": [ "accepted" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/status": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura." } ], "get": { "tags": [ "Checkout" ], "operationId": "getCheckoutPaymentStatus", "summary": "Leer y actualizar el mismo pago", "description": "No se requiere cuenta. Actualiza una operación existente a través del transporte de pasarela autenticado, con limitación del lado del servidor. No se crea ningún pago nuevo. Devuelve null si nada fue enviado. Confirme una orden solo cuando fulfillmentReady sea true.", "responses": { "200": { "description": "Estado de pago saneado actual.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/reconcile": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura." } ], "post": { "tags": [ "Checkout" ], "operationId": "reconcileCheckoutPayment", "summary": "Solicitar una conciliación de estado autoritativa", "description": "Lee la operación existente y pide a la pasarela que concilie su estado de proveedor. No crea un pago. Como máximo 3 solicitudes por factura por minuto. Disponible para pagos ya enviados incluso si la factura ya no está activa.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Pago conciliado o null.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "La intención de cifrado de la pasarela o el desafío del banco expiraron. Obtenga una intención nueva para la misma operación; no cree un pago de reemplazo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/card-intent": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura." } ], "post": { "tags": [ "Checkout" ], "operationId": "createCardEncryptionIntent", "summary": "Obtener una clave pública de pasarela y una intención de cifrado vinculada", "description": "La pasarela es la única propietaria de la clave privada. Una intención caduca en cinco minutos y vincula la orden del comerciante, la moneda, los importes base/total, la clave de idempotencia de la operación y el propósito. Las intenciones de pago requieren una factura activa y un comerciante aprobado; las intenciones de código requieren un desafío bancario existente y actual. Este endpoint no acepta campos PAN, CVV, código bancario ni JWK privados. Como máximo 8 intenciones por factura y 12 por cliente por minuto. El texto plano cifrado es {intent,name,country,email?,card:{number,expiration,cvv,holder}} para pago o {intent,code} para código. El texto plano se ensambla solo dentro del navegador antes del cifrado JWE.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON, como máximo 2048 bytes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "payment", "code" ], "default": "payment" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Intención de corta duración y clave RSA pública solamente.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardIntent" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "La intención de cifrado de la pasarela o el desafío del banco expiraron. Obtenga una intención nueva para la misma operación; no cree un pago de reemplazo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/code": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura." } ], "post": { "tags": [ "Checkout" ], "operationId": "submitEncryptedBankCode", "summary": "Enviar un código cifrado para el desafío bancario actual", "description": "Obtenga una intención con propósito=code y cifre {intent,code} en el navegador. La pasarela valida el desafío actual y consume la intención sellada una vez. Kevmi nunca recibe el código en texto plano. Como máximo 5 envíos por factura por minuto; actualice el estado después de una respuesta incierta.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sealed": { "$ref": "#/components/schemas/SealedCardData" } }, "required": [ "sealed" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Código enviado; estado de pago actual.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "La intención de cifrado de la pasarela o el desafío del banco expiraron. Obtenga una intención nueva para la misma operación; no cree un pago de reemplazo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Se requiere Content-Type: application/json.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/crypto-services": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura." } ], "get": { "tags": [ "Checkout" ], "operationId": "getCheckoutCryptoServices", "summary": "Leer el catálogo actual de monedas y redes", "description": "Solo para una factura USDT que permita criptomonedas. La factura permanece denominada en USDT; la pasarela cotiza la moneda del pagador elegida. Nunca asuma que USD equivale a USDT ni convierta el importe de la transferencia a un número de coma flotante. Como máximo 10 lecturas de catálogo por factura por minuto.", "responses": { "200": { "description": "Catálogo proporcionado por la pasarela, con disponibilidad y límites de transferencia actuales.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "network": { "type": "string" }, "networkLabel": { "type": "string" }, "available": { "type": "boolean" }, "minAmount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Valor decimal exacto en la moneda de transferencia seleccionada." }, "maxAmount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Valor decimal exacto en la moneda de transferencia seleccionada." }, "confirmations": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "currency", "network", "networkLabel", "available", "minAmount", "maxAmount", "confirmations" ], "additionalProperties": false } }, "fetchedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "services", "fetchedAt" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/stores": { "get": { "tags": [ "Account" ], "operationId": "listStores", "summary": "Enumere todas las tiendas propiedad de la cuenta actual", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Los IDs de tienda son distintos de los IDs de cuenta. No se exponen secretos.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "stores": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Store" } }, "defaultStoreId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "stores", "defaultStoreId" ], "additionalProperties": false } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Account" ], "operationId": "createStore", "summary": "Cree una tienda separada", "description": "Hasta 100 tiendas/cuenta y 10 creaciones/hora/cuenta. Una tienda nueva necesita su propia aprobación de sitio web antes de iniciar un pago.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Creada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/Store" } }, "required": [ "store" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/stores/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } } ], "patch": { "tags": [ "Account" ], "operationId": "updateStore", "summary": "Cambie el nombre de una tienda propia o modifique su IVA predeterminado", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Las cotizaciones de facturas existentes no cambian.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/Store" } }, "required": [ "store" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/exchange-rates": { "get": { "tags": [ "Payments" ], "operationId": "getReferenceExchangeRate", "summary": "Obtenga el tipo de referencia actual USD/RUB", "description": "Almacenado en caché del servidor durante una hora. El tipo numérico usa millonésimas de RUB por USD. No se inventa ninguna cotización de respaldo. Se usa al crear la factura; una factura existente conserva su propio tipo.", "security": [], "responses": { "200": { "description": "Fuente oficial, fecha de publicación y hora de recuperación.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "rate": { "$ref": "#/components/schemas/ExchangeRate" } }, "required": [ "rate" ], "additionalProperties": false } } } }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/account/dashboard": { "get": { "tags": [ "Account" ], "operationId": "getAccountDashboard", "summary": "Lea recibos verificados de una tienda o de todas las tiendas propiedad", "description": "Los recibos netos no son un saldo retirable. Las monedas heredadas permanecen separadas. Los totales son de todos los tiempos; los desgloses diarios/por método usan el período UTC solicitado.", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Seleccione una tienda propia para una sesión de navegador. Omita para usar la primera tienda. Las claves de API ignoran este encabezado y siempre usan su vinculación a tienda inmutable. El valor all es de solo lectura y solo es compatible con los endpoints de panel y lista de facturas." }, { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30 ], "default": 7 } } ], "responses": { "200": { "description": "Resumen contable de solo lectura.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": [ "string", "null" ] }, "stores": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "name": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "invoices": { "type": "integer" }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." } }, "required": [ "id", "name", "currency", "invoices", "netMinor" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "invoices": { "type": "integer" }, "succeeded": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." } }, "required": [ "currency", "invoices", "succeeded", "grossMinor", "netMinor" ], "additionalProperties": false } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "day": { "type": "string" }, "count": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." } }, "required": [ "currency", "day", "count", "grossMinor" ], "additionalProperties": false } }, "methods": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "method": { "type": "string" }, "count": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." } }, "required": [ "currency", "method", "count", "grossMinor" ], "additionalProperties": false } }, "days": { "type": "integer", "enum": [ 7, 30 ] }, "from": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "generatedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "accountingBasis": { "type": "string", "const": "verified_receipts" }, "withdrawableBalance": { "type": "null" }, "payoutCreationAvailable": { "type": "boolean", "const": false } }, "required": [ "storeId", "stores", "totals", "daily", "methods", "days", "from", "generatedAt", "accountingBasis", "withdrawableBalance", "payoutCreationAvailable" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/admin/tickets": { "get": { "tags": [ "Support" ], "operationId": "adminListTickets", "summary": "Listar las solicitudes de soporte más recientes para moderadores", "description": "Requiere un moderador con sesión iniciada de la lista de permitidos de ID de Telegram del lado del servidor. Los identificadores nunca otorgan autorización. Los secretos, hashes de credenciales y datos de tarjeta están excluidos.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Últimas 100 solicitudes.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] } } } }, "/api/admin/tickets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tkt_[a-f0-9-]{36}$" } } ], "get": { "tags": [ "Support" ], "operationId": "adminReadTicket", "summary": "Leer una solicitud de soporte y respuestas del especialista", "description": "Requiere un moderador con sesión iniciada de la lista de permitidos de ID de Telegram del lado del servidor. Los identificadores nunca otorgan autorización. Los secretos, hashes de credenciales y datos de tarjeta están excluidos.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Solicitud y respuestas guardadas.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] } } }, "post": { "tags": [ "Support" ], "operationId": "adminReplyTicket", "summary": "Guardar una respuesta de especialista y notificar a su propietario", "description": "Requiere un moderador con sesión iniciada de la lista de permitidos de ID de Telegram del lado del servidor. Los identificadores nunca otorgan autorización. Los secretos, hashes de credenciales y datos de tarjeta están excluidos. requestId proporciona idempotencia; reutilizarlo para otro mensaje se rechaza.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "minLength": 2, "maxLength": 4000 }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "message", "requestId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Respuesta guardada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "$ref": "#/components/schemas/SupportReply" } }, "required": [ "reply" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] } } } }, "/api/admin/project": { "get": { "tags": [ "Account" ], "operationId": "adminProjectOverview", "summary": "Leer conteos de proyectos, recibos verificados, preparación de configuración y controles", "description": "Requiere un moderador con sesión iniciada de la lista de permitidos de ID de Telegram del lado del servidor. Los identificadores nunca otorgan autorización. Los secretos, hashes de credenciales y datos de tarjeta están excluidos. La preparación de configuración no es una verificación de salud del proveedor en vivo. Los recibos no son un saldo retirable.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Resumen del proyecto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] } } } }, "/api/admin/project/{section}": { "parameters": [ { "name": "section", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "users", "stores", "payments", "keys", "webhooks", "events", "audit" ] } } ], "get": { "tags": [ "Account" ], "operationId": "adminListProjectRecords", "summary": "Buscar y paginar registros de proyectos", "description": "Requiere un moderador con sesión iniciada de la lista de permitidos de ID de Telegram del lado del servidor. Los identificadores nunca otorgan autorización. Los secretos, hashes de credenciales y datos de tarjeta están excluidos.", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 120 } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 10000 } } ], "responses": { "200": { "description": "Hasta 50 registros y nextPage.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] } } } }, "/api/admin/project/action": { "post": { "tags": [ "Account" ], "operationId": "adminProjectAction", "summary": "Realizar una acción de proyecto controlada y auditada", "description": "Requiere un moderador con sesión iniciada de la lista de permitidos de ID de Telegram del servidor. Los identificadores nunca otorgan autorización. Los secretos, hashes de credenciales y detalles de tarjetas están excluidos. Requiere un motivo. Los administradores están protegidos de las restricciones del panel. El éxito de pagos, reembolsos, pagos y comandos arbitrarios del servidor no pueden fabricarse mediante este endpoint.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Debe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "block-user", "unblock-user", "revoke-sessions", "block-store", "unblock-store", "pause-payment", "cancel-payment", "revoke-key", "disable-webhook", "set-methods", "set-ai" ] }, "targetId": { "type": "string", "maxLength": 100 }, "reason": { "type": "string", "minLength": 5, "maxLength": 500 }, "methods": { "type": "array", "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "enabled": { "type": "boolean" } }, "required": [ "action", "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Acción y entrada de auditoría guardadas atómicamente.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "JSON inválido, campo desconocido o valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Sin sesión válida; para un webhook, un secreto inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falló la validación de origen, CSRF o vinculación con el navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Límite de velocidad excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "El servidor siempre devuelve 60; esto no garantiza que una cuota por hora haya expirado." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] } } } } }, "components": { "securitySchemes": { "cookieSession": { "type": "apiKey", "in": "cookie", "name": "__Host-kevmi-session", "description": "Token de sesión aleatorio, Secure/HttpOnly/SameSite=Lax, válido por 24 horas. Se almacena un hash en la base de datos. Se emite solo después de un inicio de sesión verificado de Telegram." }, "browserProof": { "type": "apiKey", "in": "cookie", "name": "__Host-kevmi-login", "description": "Cookie HttpOnly desde el inicio: challengeId.proof, válida por 300 segundos. Excluida del enlace profundo de Telegram." }, "csrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Token CSRF de sesión emitido por /api/auth/me o /api/auth/telegram/complete. Las mutaciones también requieren el Origin exacto." }, "telegramWebhookSecret": { "type": "apiKey", "in": "header", "name": "X-Telegram-Bot-Api-Secret-Token", "description": "Secreto de webhook separado configurado en el servidor. Su valor es privado. No es el token del bot." }, "merchantKey": { "type": "http", "scheme": "bearer", "bearerFormat": "kv_live_…", "description": "Clave API de comerciante con ámbito limitado. Solo se almacena su hash. Uso exclusivo de servidor a servidor; nunca la coloque en un widget o paquete de navegador." }, "gatewaySignature": { "type": "apiKey", "in": "header", "name": "Kevmi-Signature", "description": "t=,v1=. Desviación máxima de marca de tiempo: 300 segundos." }, "jobSecret": { "type": "http", "scheme": "bearer", "description": "JOBS_SECRET separado solo para servidor. No es una clave API de comerciante." }, "nativeGatewaySignature": { "type": "apiKey", "in": "header", "name": "X-Gateway-Signature", "description": "v1=; separado de la firma de comerciante Kevmi-Signature." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "EmptyObject": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "Config": { "type": "object", "properties": { "telegram": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botUsername": { "type": [ "string", "null" ] } }, "required": [ "enabled", "botUsername" ], "additionalProperties": false }, "support": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "search", "ai" ] }, "available": { "type": "boolean", "const": true } }, "required": [ "mode", "available" ], "additionalProperties": false }, "gateway": { "type": "object", "properties": { "configured": { "type": "boolean" }, "connected": { "type": "boolean", "const": false, "description": "El endpoint de configuración público no sondea la salud de la pasarela. La configuración no es una verificación exitosa de conexión en vivo." }, "status": { "type": "string", "enum": [ "configured", "not_configured" ] } }, "required": [ "configured", "connected", "status" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "server": { "type": "boolean", "const": true }, "account": { "type": "boolean" }, "notifications": { "type": "boolean" }, "tickets": { "type": "boolean" }, "directPaymentsOnly": { "type": "boolean", "const": true }, "paymentLinks": { "type": "boolean", "description": "D1 está configurado para facturas de servidor. Esto no indica preparación para el pago." }, "apiKeys": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "widgets": { "type": "boolean" }, "applications": { "type": "boolean" }, "applicationNotifications": { "type": "boolean" } }, "required": [ "server", "account", "notifications", "tickets", "directPaymentsOnly", "paymentLinks", "apiKeys", "webhooks", "widgets", "applications", "applicationNotifications" ], "additionalProperties": false } }, "required": [ "telegram", "support", "gateway", "capabilities" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "telegram": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botUsername": { "type": [ "string", "null" ] } }, "required": [ "enabled", "botUsername" ], "additionalProperties": false }, "support": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "search", "ai" ] }, "available": { "type": "boolean", "const": true } }, "required": [ "mode", "available" ], "additionalProperties": false }, "gateway": { "type": "object", "properties": { "configured": { "type": "boolean" }, "connected": { "type": "boolean", "const": false, "description": "El endpoint de configuración público no sondea la salud de la pasarela. La configuración no es una verificación exitosa de conexión en vivo." }, "status": { "type": "string", "enum": [ "configured", "not_configured" ] } }, "required": [ "configured", "connected", "status" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "server": { "type": "boolean", "const": true }, "account": { "type": "boolean" }, "notifications": { "type": "boolean" }, "tickets": { "type": "boolean" }, "directPaymentsOnly": { "type": "boolean", "const": true }, "paymentLinks": { "type": "boolean", "description": "D1 está configurado para facturas de servidor. Esto no indica preparación para el pago." }, "apiKeys": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "widgets": { "type": "boolean" }, "applications": { "type": "boolean" }, "applicationNotifications": { "type": "boolean" } }, "required": [ "server", "account", "notifications", "tickets", "directPaymentsOnly", "paymentLinks", "apiKeys", "webhooks", "widgets", "applications", "applicationNotifications" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "storage": { "type": "string", "enum": [ "ready", "not_configured", "unavailable" ] } }, "required": [ "telegram", "support", "gateway", "capabilities", "status", "storage" ], "additionalProperties": false }, "NotificationPreferences": { "type": "object", "properties": { "payments": { "type": "boolean" }, "payouts": { "type": "boolean" }, "support": { "type": "boolean" }, "security": { "type": "boolean" } }, "required": [ "payments", "payouts", "support", "security" ], "additionalProperties": false }, "SettingsPatch": { "type": "object", "properties": { "storeName": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 80, "x-trimmedMinLength": 1, "description": "Se recortan los espacios circundantes. Longitud tras recorte: 1–80 caracteres. Se prohíben caracteres de control excepto tabulaciones y saltos de línea." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "notifications": { "type": "object", "properties": { "payments": { "type": "boolean" }, "payouts": { "type": "boolean" }, "support": { "type": "boolean" }, "security": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "storeName": { "type": "string" }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "notifications": { "$ref": "#/components/schemas/NotificationPreferences" }, "isModerator": { "type": "boolean", "description": "Si esta identidad de Telegram pertenece a la lista de permitidos del moderador configurado." } }, "required": [ "id", "displayName", "username", "storeName", "vatPayer", "notifications", "isModerator" ], "additionalProperties": false }, "UserResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ], "additionalProperties": false }, "Anonymous": { "type": "object", "properties": { "authenticated": { "type": "boolean", "const": false } }, "required": [ "authenticated" ], "additionalProperties": false }, "CurrentSession": { "type": "object", "properties": { "authenticated": { "type": "boolean", "const": true }, "user": { "$ref": "#/components/schemas/User" }, "csrfToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "authenticated", "user", "csrfToken", "expiresAt" ], "additionalProperties": false }, "LoginChallenge": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "code": { "type": "string", "pattern": "^[0-9]{6}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "telegramUrl": { "type": "string", "format": "uri", "pattern": "^https://t\\.me/" } }, "required": [ "challengeId", "code", "expiresAt", "telegramUrl" ], "additionalProperties": false }, "CompletedLogin": { "type": "object", "properties": { "status": { "type": "string", "const": "authenticated" }, "user": { "$ref": "#/components/schemas/User" }, "csrfToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "status", "user", "csrfToken", "expiresAt" ], "additionalProperties": false }, "SupportQuestion": { "type": "object", "properties": { "question": { "type": "string", "minLength": 2, "x-trimmedMaxLength": 2000, "x-trimmedMinLength": 2, "description": "Se recortan los espacios circundantes. Longitud tras recorte: 2–2.000 caracteres. Se prohíben caracteres de control excepto tabulaciones y saltos de línea." }, "locale": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ], "default": "en", "description": "Idioma de respuesta. Si se omite, se usan las preferencias Accept-Language admitidas; de lo contrario inglés. La documentación está disponible en todos los idiomas de interfaz admitidos." }, "history": { "type": "array", "maxItems": 6, "description": "Hasta los últimos tres pares de pregunta y respuesta. Opcional. Contexto no confiable, no mensajes de rol de sistema del proveedor.", "items": { "oneOf": [ { "type": "object", "properties": { "role": { "type": "string", "const": "user" }, "content": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 1800, "x-trimmedMinLength": 1, "description": "Se recortan los espacios circundantes. Longitud tras recorte: 1–1.800 caracteres. Se prohíben caracteres de control excepto tabulaciones y saltos de línea." } }, "required": [ "role", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 3000, "x-trimmedMinLength": 1, "description": "Se recortan los espacios circundantes. Longitud tras recorte: 1–3.000 caracteres. Se prohíben caracteres de control excepto tabulaciones y saltos de línea." } }, "required": [ "role", "content" ], "additionalProperties": false } ] } }, "pageContext": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 80, "x-trimmedMinLength": 1, "description": "Etiqueta de sección corta tras recorte, 1–80 caracteres. Permite letras, dígitos, espacios y ·.,—–-:(). Se prohíben saltos de línea, URL, parámetros de consulta y HTML. No incluya tokens ni secretos.", "pattern": "^[\\p{L}\\p{N}\\s·.,—–\\-:()]+$", "not": { "pattern": "[\\r\\n]" } }, "includeAccount": { "type": "boolean", "default": false, "description": "Permiso explícito para usar herramientas de cuenta de solo lectura con ámbito del propietario. Requiere sesión, Origin y X-CSRF-Token cuando sea verdadero. X-Kevmi-Store selecciona una tienda propia o todas las tiendas propias. Los invitados y CSRF inválido no pueden habilitar este acceso." } }, "required": [ "question" ], "additionalProperties": false }, "SupportSource": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "pattern": "^/(?:ru/|en/)?docs/[^/]+$", "description": "Enlace relativo a un artículo de conocimiento publicado." } }, "required": [ "id", "title", "url" ], "additionalProperties": false }, "SearchSupportAnswer": { "type": "object", "properties": { "mode": { "type": "string", "const": "search" }, "answer": { "type": "string" }, "sources": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/SupportSource" } }, "knowledgeVersion": { "type": [ "string", "null" ] }, "needsHuman": { "type": "boolean" }, "aiUnavailable": { "type": "boolean", "const": true } }, "required": [ "mode", "answer", "sources", "knowledgeVersion", "needsHuman" ], "additionalProperties": false }, "AISupportAnswer": { "type": "object", "properties": { "mode": { "type": "string", "const": "ai" }, "answer": { "type": "string", "minLength": 1, "maxLength": 6000, "description": "Solo texto plano; las URL y el HTML se rechazan. Los enlaces se devuelven solo en las fuentes." }, "sources": { "type": "array", "maxItems": 25, "uniqueItems": true, "items": { "$ref": "#/components/schemas/SupportSource" } }, "knowledgeVersion": { "type": "string" }, "needsHuman": { "type": "boolean" } }, "required": [ "mode", "answer", "sources", "knowledgeVersion", "needsHuman" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "needsHuman": { "const": false } } }, "then": { "properties": { "sources": { "minItems": 1 } } } } ] }, "SupportAnswer": { "oneOf": [ { "$ref": "#/components/schemas/SearchSupportAnswer" }, { "$ref": "#/components/schemas/AISupportAnswer" } ] }, "Ticket": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tkt_[a-f0-9-]{36}$" }, "subject": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "answered", "closed" ], "description": "answered denota una solicitud respondida. La API pública permite a un usuario cerrar solo su propia solicitud." }, "source": { "type": "string", "enum": [ "web", "telegram" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/SupportReply" } } }, "required": [ "id", "subject", "message", "status", "source", "createdAt", "updatedAt" ], "additionalProperties": false }, "TicketResponse": { "type": "object", "properties": { "ticket": { "$ref": "#/components/schemas/Ticket" }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/SupportReply" } } }, "required": [ "ticket" ], "additionalProperties": false }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ntf_[A-Za-z0-9-]{1,80}$" }, "kind": { "type": "string", "enum": [ "payments", "payouts", "support", "security", "test" ] }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed" ], "description": "Estado de entrega de Telegram, independiente del estado de lectura en el sitio web." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "sentAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "readAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Hora de primera lectura en el sitio web; null significa no leído. Esto no confirma que se haya leído en Telegram." } }, "required": [ "id", "kind", "message", "status", "createdAt", "sentAt", "readAt" ], "additionalProperties": false }, "NotificationsPage": { "type": "object", "properties": { "notifications": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Notification" } }, "unreadCount": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor de página siguiente; null si no hay más registros." } }, "required": [ "notifications", "unreadCount", "nextCursor" ], "additionalProperties": false }, "ReadNotifications": { "oneOf": [ { "type": "object", "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Se permiten duplicados y se cuentan una vez.", "items": { "type": "string", "pattern": "^ntf_[A-Za-z0-9-]{1,80}$" } } }, "required": [ "ids" ], "additionalProperties": false }, { "type": "object", "properties": { "all": { "type": "boolean", "const": true }, "before": { "type": "integer", "minimum": 0, "description": "createdAt del último evento mostrado. El servidor también requiere before <= Date.now().", "maximum": 9007199254740991 } }, "required": [ "all", "before" ], "additionalProperties": false } ] }, "ReadNotificationsResult": { "type": "object", "properties": { "updated": { "type": "integer", "minimum": 0 }, "readAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "unreadCount": { "type": "integer", "minimum": 0 } }, "required": [ "updated", "readAt", "unreadCount" ], "additionalProperties": false }, "TelegramUpdate": { "type": "object", "properties": { "update_id": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "message": { "type": "object", "additionalProperties": true, "description": "Mensaje de Telegram: el manejador usa message_id, text, from y chat." }, "callback_query": { "type": "object", "additionalProperties": true, "description": "Telegram CallbackQuery: el handler usa id, from, data y message.chat." } }, "required": [ "update_id" ], "additionalProperties": true }, "IncomingQuote": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "baseMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "percentageFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "fixedFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "nominalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "feeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "merchantVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "merchantDeductionMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "totalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de factura: centavos de USD, kopeks de RUB o centésimas de USDT. Sin conversión automática de moneda." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Versión de cálculo guardada con la factura." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo. Predeterminado: la preferencia de IVA heredada de la tienda." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.", "default": 0 }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "merchantFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "settlement": { "$ref": "#/components/schemas/SettlementQuote" } }, "required": [ "amountMinor", "baseMinor", "grossMinor", "percentageFeeMinor", "fixedFeeMinor", "nominalFeeMinor", "feeMinor", "vatMinor", "customerVatMinor", "merchantVatMinor", "customerTotalMinor", "merchantDeductionMinor", "totalFeeMinor", "netMinor", "currency", "method", "vatPayer", "vatApplies", "pricingVersion" ], "additionalProperties": false }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "merchantName": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de factura: centavos de USD, kopeks de RUB o centésimas de USDT. Sin conversión automática de moneda." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "quotes": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/IncomingQuote" }, "alipay": { "$ref": "#/components/schemas/IncomingQuote" }, "sbp": { "$ref": "#/components/schemas/IncomingQuote" }, "crypto": { "$ref": "#/components/schemas/IncomingQuote" } }, "required": [], "additionalProperties": false }, "status": { "type": "string", "enum": [ "active", "paused", "expired", "cancelled" ], "description": "expired se deriva de expiresAt al leer. cancelled es definitivo." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "url": { "type": "string", "format": "uri", "description": "Página pública /pay/{token} en APP_ORIGIN." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo. Predeterminado: la preferencia de IVA heredada de la tienda." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referencia de pedido visible para el comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público." }, "checkoutUrl": { "type": "string", "format": "uri" }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/PaymentSummary" }, { "type": "null" } ], "description": "Incluido por las solicitudes GET de lista/detalle del propietario. El ciclo de vida de la factura es independiente del estado de pago verificado. No contiene tarjeta, código bancario, QR ni detalles del comprador." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "pricingMode": { "type": "string", "enum": [ "native", "universal" ] }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/ExchangeRate" }, { "type": "null" } ] }, "usdtPerUsd": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "description", "merchantName", "amountMinor", "currency", "vatPayer", "methods", "quotes", "status", "createdAt", "updatedAt", "expiresAt", "url", "vatCustomerPercent", "feeCustomerPercent", "orderId", "metadata", "checkoutUrl" ], "additionalProperties": false }, "CreatePaymentLink": { "oneOf": [ { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Los espacios circundantes se recortan. Longitud después del recorte: 1–120 caracteres. Los caracteres de control excepto tabulaciones y saltos de línea están prohibidos." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "Opcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Límite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Cuando se omite, se guarda la regla actual de la tienda." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Un momento futuro, como máximo 90 días después de la creación. Predeterminado: siete días. Se guarda en la instantánea de la factura." }, "currency": { "type": "string", "const": "USD" }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "crypto" ] }, "description": "El checkout de USD admite tarjeta y Alipay. Las facturas cripto en USD se aceptan solo por compatibilidad y devuelven crypto_requires_usdt en el checkout en vivo; use USDT para cripto." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo. Predeterminado: la preferencia de IVA heredada de la tienda." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referencia de pedido visible para el comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público." }, "pricingMode": { "type": "string", "const": "native", "description": "Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Los espacios circundantes se recortan. Longitud después del recorte: 1–120 caracteres. Los caracteres de control excepto tabulaciones y saltos de línea están prohibidos." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "Opcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Límite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Cuando se omite, se guarda la regla actual de la tienda." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Un momento futuro, como máximo 90 días después de la creación. Predeterminado: siete días. Se guarda en la instantánea de la factura." }, "currency": { "type": "string", "const": "RUB" }, "methods": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "const": "sbp" } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo. Predeterminado: la preferencia de IVA heredada de la tienda." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referencia de pedido visible para el comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público." }, "pricingMode": { "type": "string", "const": "native", "description": "Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Los espacios circundantes se recortan. Longitud después del recorte: 1–120 caracteres. Los caracteres de control excepto tabulaciones y saltos de línea están prohibidos." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "Opcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Límite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Cuando se omite, se guarda la regla actual de la tienda." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Un momento futuro, como máximo 90 días después de la creación. Predeterminado: siete días. Se guarda en la instantánea de la factura." }, "currency": { "type": "string", "const": "USDT" }, "methods": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "const": "crypto" } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo. Predeterminado: la preferencia de IVA heredada de la tienda." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referencia de pedido visible para el comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público." }, "pricingMode": { "type": "string", "const": "native", "description": "Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Los espacios circundantes se recortan. Longitud después del recorte: 1–120 caracteres. Los caracteres de control excepto tabulaciones y saltos de línea están prohibidos." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "Opcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Límite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Cuando se omite, se guarda la regla actual de la tienda." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Un momento futuro, como máximo 90 días después de la creación. Predeterminado: siete días. Se guarda en la instantánea de la factura." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidad de entrada. RUB se convierte a USD al tipo de referencia guardado; USDT usa la regla explícita de factura 1:1. La moneda base de factura guardada es USD." }, "methods": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo. Predeterminado: la preferencia de IVA heredada de la tienda." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referencia de pedido visible para el comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público." }, "pricingMode": { "type": "string", "const": "universal" } }, "required": [ "title", "amountMinor", "currency", "methods", "pricingMode" ], "additionalProperties": false } ], "description": "Los montos usan unidades menores. La tarifa y el IVA se calculan sobre el monto base del pedido. La parte del cliente se redondea hacia arriba; el comerciante cubre el resto exacto. Se rechaza una asignación heredada conflictiva de vatPayer y vatCustomerPercent. La asignación es inmutable después de la creación; emita una nueva factura para cambiarla. La tarjeta/Alipay en vivo requiere vatCustomerPercent=100 y feeCustomerPercent=0 porque la pasarela configurada no puede anular su impuesto exclusivo. Otras asignaciones guardadas devuelven unsupported_allocation; nunca se cambian silenciosamente. SBP y cripto USDT admiten asignación de tarifa. Use el objeto público de disponibilidad de factura antes de recopilar detalles de pago. El modo universal almacena un precio base en USD y cotizaciones de cargo nativas separadas: USD para tarjetas/Alipay, RUB para SBP, USDT para cripto. La conversión de RUB usa un tipo de referencia guardado del Banco de Rusia. Cripto usa la regla explícita de factura 1 USD = 1 USDT, no una cotización de mercado. Las facturas que implican conversión de RUB están limitadas a 24 horas incluso cuando expiresAt solicita una fecha posterior. La falla de la fuente FX devuelve 503 FX_UNAVAILABLE. Omita pricingMode para comportamiento nativo heredado.", "examples": [ { "pricingMode": "universal", "title": "Pedido 1042", "amountMinor": 1000, "currency": "USD", "methods": [ "card", "alipay", "sbp", "crypto" ], "vatCustomerPercent": 100, "feeCustomerPercent": 0 }, { "title": "Pedido 1042", "amountMinor": 500, "currency": "USD", "methods": [ "card", "alipay" ], "vatCustomerPercent": 100, "feeCustomerPercent": 0, "orderId": "1042" }, { "title": "Pedido 1043", "amountMinor": 1000, "currency": "USDT", "methods": [ "crypto" ], "feeCustomerPercent": 23, "orderId": "1043" } ] }, "PaymentLinkResponse": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/PaymentLink" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "Incluido en las respuestas de actualización de estado; el enlace anidado siempre contiene su checkoutUrl." } }, "required": [ "link" ], "additionalProperties": false }, "CreatePaymentLinkResponse": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/PaymentLink" }, "replayed": { "type": "boolean" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "El enlace de pago está disponible de inmediato; no se requiere sondeo." } }, "required": [ "link", "replayed", "checkoutUrl" ], "additionalProperties": false }, "PaymentLinksPage": { "type": "object", "properties": { "links": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PaymentLink" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor opaco de página siguiente. Páselo como parámetro de consulta codificado en URL; null marca el final." } }, "required": [ "links", "nextCursor" ], "additionalProperties": false }, "CheckoutQuote": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Versión de cálculo guardada con la factura." }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "merchantCoveredMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." } }, "required": [ "method", "amountMinor", "vatMinor", "customerVatMinor", "customerTotalMinor", "vatApplies", "pricingVersion", "customerFeeMinor", "merchantCoveredMinor" ], "additionalProperties": false }, "CheckoutInvoice": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "title": { "type": "string" }, "description": { "type": "string" }, "merchantName": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de factura: centavos de USD, kopeks de RUB o centésimas de USDT. Sin conversión automática de moneda." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "status": { "type": "string", "enum": [ "active", "paused", "expired", "cancelled" ], "description": "expired se deriva de expiresAt al leer. cancelled es definitivo." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "quote": { "$ref": "#/components/schemas/CheckoutQuote" }, "gatewayConnected": { "type": "boolean", "description": "Alias de compatibilidad para availability.available, no una sonda de salud de la pasarela." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo. Predeterminado: la preferencia de IVA heredada de la tienda." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referencia de pedido visible para el comprador." }, "availability": { "$ref": "#/components/schemas/CheckoutAvailability" }, "baseAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "baseCurrency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ] }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/ExchangeRate" }, { "type": "null" } ] }, "usdtPerUsd": { "type": [ "string", "null" ] } }, "required": [ "token", "title", "description", "merchantName", "amountMinor", "currency", "vatPayer", "methods", "status", "expiresAt", "createdAt", "quote", "gatewayConnected", "vatCustomerPercent", "feeCustomerPercent", "orderId", "availability" ], "additionalProperties": false }, "MerchantKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9a-f-]{36}$" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoices:read", "invoices:write", "events:read" ] } }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "revokedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "lastUsedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "name", "prefix", "scopes", "createdAt", "expiresAt" ], "additionalProperties": false }, "MerchantEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[a-f0-9]{40}$" }, "type": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] }, "apiVersion": { "type": "string", "const": "2026-10-21" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "livemode": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true, "description": "invoice.created/updated: factura persistida del comerciante, incluidos metadatos privados. Eventos de pago: hechos de pago verificados. Consulte la guía de webhooks para ejemplos." } }, "required": [ "id", "type", "apiVersion", "createdAt", "livemode", "data" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } }, "status": { "type": "string", "enum": [ "unverified", "active", "paused" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "verifiedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "url", "description", "events", "status", "createdAt", "verifiedAt" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "endpoint_id": { "type": "string" }, "type": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] }, "status": { "type": "string", "enum": [ "pending", "sending", "delivered", "failed", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 6 }, "next_attempt_at": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "last_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "delivered_at": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "id", "event_id", "endpoint_id", "type", "status", "attempts" ], "additionalProperties": false }, "Application": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "businessName": { "type": "string", "minLength": 1, "maxLength": 100 }, "businessType": { "type": "string", "enum": [ "digital_goods", "software", "services", "physical_goods", "education", "other" ] }, "description": { "type": "string", "minLength": 40, "maxLength": 3000 }, "contactTelegram": { "type": "string", "pattern": "^@[A-Za-z][A-Za-z0-9_]{4,31}$" }, "status": { "type": "string", "enum": [ "processing", "needs_review", "approved", "rejected" ] }, "currentStage": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "version": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "description": "Mensaje de etapa visible para el usuario o motivo de rechazo editado por moderador. La evidencia interna se excluye." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "stages": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "state": { "type": "string", "enum": [ "pending", "running", "complete", "review", "rejected" ] }, "message": { "type": "string" }, "updatedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "id", "state", "message", "updatedAt" ], "additionalProperties": false } }, "url": { "type": "string", "format": "uri", "description": "URL de seguimiento privada con locale explícito. Conocer la URL no otorga acceso." }, "notificationCategory": { "type": "string", "const": "support" }, "canResume": { "type": "boolean" }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "websiteUrl", "businessName", "businessType", "description", "contactTelegram", "status", "currentStage", "version", "reason", "createdAt", "updatedAt", "stages", "url", "notificationCategory", "canResume" ], "additionalProperties": false }, "ApplicationEvent": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "stage": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "state": { "type": "string", "enum": [ "pending", "running", "complete", "review", "rejected" ] }, "message": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "version", "stage", "state", "message", "createdAt" ], "additionalProperties": false }, "PaymentSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "ID de pago canónico de la pasarela cuando se conoce; de lo contrario, el ID local de operación gwp_." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "failed", "expired", "review_required", "partially_paid", "partially_refunded", "refunded", "disputed" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de factura: centavos de USD, kopeks de RUB o centésimas de USDT. Sin conversión automática de moneda." }, "fulfillmentReady": { "type": "boolean" }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "refundedAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." } }, "required": [ "id", "method", "status", "amountMinor", "currency", "fulfillmentReady", "updatedAt" ], "additionalProperties": false }, "CheckoutAvailability": { "type": "object", "properties": { "available": { "type": "boolean" }, "code": { "type": "string", "enum": [ "ready", "not_configured", "unsupported_allocation", "crypto_requires_usdt", "amount_out_of_range", "merchant_not_approved" ] }, "flow": { "type": "string", "enum": [ "encrypted_card", "qr", "crypto" ] }, "minAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "maxAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "limitsSource": { "type": "string", "const": "adapter", "description": "Límites conservadores aplicados por esta integración, no una afirmación sobre los límites comerciales del proveedor ascendente." } }, "required": [ "available", "code", "flow", "minAmountMinor", "maxAmountMinor", "limitsSource" ], "additionalProperties": false }, "CheckoutAction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redirect", "qr", "crypto" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "qrImage": { "type": [ "string", "null" ] }, "qrPayload": { "type": [ "string", "null" ] }, "address": { "type": "string" }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Monto exacto de transferencia en la moneda seleccionada; conserve la cadena decimal sin redondeo ni conversión de punto flotante." }, "currency": { "type": "string" }, "network": { "type": "string" }, "networkLabel": { "type": "string" }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "addressQrImage": { "type": [ "string", "null" ] }, "amountQrImage": { "type": [ "string", "null" ] }, "amountQrPayload": { "type": [ "string", "null" ] }, "networkFeePaidByCustomer": { "type": "boolean" } }, "required": [ "type", "expiresAt" ], "additionalProperties": false }, "CheckoutPayment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^gwp_[0-9a-f-]{36}$" }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "failed", "expired", "review_required", "partially_paid", "partially_refunded", "refunded", "disputed" ] }, "providerStatus": { "type": "string" }, "fulfillmentReady": { "type": "boolean", "description": "Solo true después de la vinculación exacta de monto/moneda/pedido y la confirmación de éxito por parte del proveedor. Una redirección del navegador nunca es confirmación de pago." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de factura: centavos de USD, kopeks de RUB o centésimas de USDT. Sin conversión automática de moneda." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "nextAction": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutAction" }, { "type": "null" } ] }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "authentication": { "type": "object", "properties": { "required": { "type": "boolean" }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "attempt": { "type": "integer", "minimum": 0 } }, "required": [ "required", "expiresAt", "attempt" ], "additionalProperties": false }, "reason": { "type": "string", "enum": [ "amount_mismatch", "confirmation_required", "refund_mismatch", "settlement_unverified" ] }, "refundedAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." } }, "required": [ "id", "method", "status", "providerStatus", "fulfillmentReady", "amountMinor", "currency", "createdAt", "updatedAt", "nextAction", "expiresAt" ], "additionalProperties": false }, "SealedCardData": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 32, "maxLength": 8192, "description": "Intención de operación firmada y de corta duración de /card-intent; reenvíela sin cambios." }, "jwe": { "type": "string", "maxLength": 14000, "pattern": "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+){4}$", "description": "JWE compacto que usa RSA-OAEP-256 y A256GCM. Encabezado protegido: kid de la clave pública, typ=kevmi-card+jwe. Solo el texto cifrado se envía a Kevmi. Nunca envíe campos de tarjeta o código bancario en texto plano." } }, "required": [ "intent", "jwe" ], "additionalProperties": false }, "CardIntent": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 32, "maxLength": 8192 }, "intentId": { "type": "string", "maxLength": 100 }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "key": { "type": "object", "properties": { "kid": { "type": "string" }, "kty": { "type": "string", "const": "RSA" }, "n": { "type": "string" }, "e": { "type": "string" }, "alg": { "type": "string", "const": "RSA-OAEP-256" }, "use": { "type": "string", "const": "enc" } }, "required": [ "kid", "kty", "n", "e", "alg", "use" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "RSA-OAEP-256" }, "encryption": { "type": "string", "const": "A256GCM" }, "protocol": { "type": "string", "const": "kevmi-card-v1" } }, "required": [ "intent", "intentId", "expiresAt", "key", "algorithm", "encryption", "protocol" ], "additionalProperties": false }, "StartCheckoutPayment": { "oneOf": [ { "type": "object", "properties": { "method": { "type": "string", "const": "card" }, "sealed": { "$ref": "#/components/schemas/SealedCardData" } }, "required": [ "method", "sealed" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "alipay" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "country": { "type": "string", "const": "CN" }, "email": { "type": "string", "format": "email", "maxLength": 254 } }, "required": [ "method", "name", "country" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "sbp" } }, "required": [ "method" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "crypto" }, "payerCurrency": { "type": "string", "pattern": "^[A-Z0-9]{2,16}$" }, "network": { "type": "string", "pattern": "^[a-z0-9_-]{2,32}$" } }, "required": [ "method", "payerCurrency", "network" ], "additionalProperties": false } ] }, "LegacyGatewayEvent": { "type": "object", "properties": { "eventId": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9_.:-]+$" }, "paymentId": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9_.:-]+$" }, "invoiceId": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "refunded" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de factura: centavos de USD, kopeks de RUB o centésimas de USDT. Sin conversión automática de moneda." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "occurredAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "eventId", "paymentId", "invoiceId", "status", "amountMinor", "currency", "method", "occurredAt" ], "additionalProperties": false }, "NativeGatewayEvent": { "type": "object", "required": [ "id", "api_version", "mode", "type", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "api_version": { "type": "string", "const": "3" }, "mode": { "type": "string", "const": "live" }, "type": { "type": "string", "pattern": "^[a-z_.]{1,80}$" }, "data": { "type": "object", "required": [ "id", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0 }, "merchant_order_id": { "type": "string" } } } } }, "Store": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "id", "name", "vatPayer", "createdAt", "updatedAt" ], "additionalProperties": false }, "ExchangeRate": { "type": "object", "properties": { "rubPerUsdMicros": { "type": "integer", "minimum": 1000000 }, "effectiveAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "fetchedAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." }, "source": { "type": "string", "const": "https://www.cbr.ru/scripts/XML_daily.asp" }, "usdtPerUsd": { "type": "string", "const": "1.00" } }, "required": [ "rubPerUsdMicros", "effectiveAt", "fetchedAt", "source", "usdtPerUsd" ], "additionalProperties": false }, "SettlementQuote": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "baseMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "percentageFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "fixedFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "nominalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "feeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "merchantVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "merchantDeductionMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "totalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de factura: centavos de USD, kopeks de RUB o centésimas de USDT. Sin conversión automática de moneda." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Versión de cálculo guardada con la factura." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo. Predeterminado: la preferencia de IVA heredada de la tienda." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Participación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.", "default": 0 }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." }, "merchantFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Cantidad entera en unidades monetarias menores." } }, "required": [ "amountMinor", "baseMinor", "grossMinor", "percentageFeeMinor", "fixedFeeMinor", "nominalFeeMinor", "feeMinor", "vatMinor", "customerVatMinor", "merchantVatMinor", "customerTotalMinor", "merchantDeductionMinor", "totalFeeMinor", "netMinor", "currency", "method", "vatPayer", "vatApplies", "pricingVersion" ], "additionalProperties": false }, "SupportReply": { "type": "object", "properties": { "id": { "type": "string" }, "message": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Marca de tiempo Unix en milisegundos, UTC." } }, "required": [ "id", "message", "createdAt" ], "additionalProperties": false } } }, "webhooks": { "merchantEvent": { "post": { "summary": "Entrega verificada al servidor del comerciante", "description": "Se entrega solo a endpoints activos y verificados por desafío. El JSON sin formato está firmado; verifique la marca de tiempo y la firma antes de analizar o cambiar el estado del pedido. Devuelva 2xx después de aceptar el evento de forma duradera. Persista los IDs de eventos para manejar duplicados. Errores de red, tiempo de espera agotado y estados que no sean 2xx activan reintentos.", "parameters": [ { "name": "Kevmi-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kevmi-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kevmi-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo 16,384 bytes. Los campos desconocidos se rechazan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantEvent" } } } }, "responses": { "2XX": { "description": "Aceptado de forma duradera por el servidor del comerciante." } } } } } }