Referencia de la API
La API del servidor admite cuentas, facturas, pago seguro, estados y webhooks. OpenAPI describe rutas, campos y errores. Iniciar un pago requiere una pasarela configurada, un comerciante aprobado y términos de factura compatibles.
En esta página
URL base y formato#
The base URL is https://kevmi.one. Request and response bodies use JSON. Money values are integer minor units. Account and support dates are Unix timestamps in milliseconds.
Las respuestas de API usan Cache-Control: no-store. El /openapi.json público puede almacenarse en caché durante cinco minutos. No coloques cookies ni secretos en una URL.
curl 'https://kevmi.one/api/config'
curl 'https://kevmi.one/openapi.json'Autorización de solicitudes#
La cuenta web usa una cookie de sesión HttpOnly. GET /api/auth/me devuelve el usuario actual y csrfToken. Las mutaciones requieren X-CSRF-Token y una solicitud de mismo origen.
Las claves de comerciante Kevmi con alcance autorizan /api/v1/payments, /api/v1/payment-links y /api/v1/events. No reemplazan la cookie de sesión para los ajustes de cuenta ni las rutas administrativas.
const me = await fetch('/api/auth/me').then(r => r.json());
if (!me.authenticated) throw new Error('Sign in required');
const response = await fetch('/api/account/settings', {
method: 'PATCH',
headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': me.csrfToken },
body: JSON.stringify({ vatPayer: 'merchant' })
});
if (!response.ok) throw new Error('Settings were not saved');
const updated = await response.json();Grupos de endpoints#
GET /api/config informa la presencia de la configuración del servidor. GET /api/checkout/{token} devuelve la disponibilidad de la factura para el método seleccionado, incluida la aprobación del comerciante y los términos guardados. Estas comprobaciones no establecen la conectividad del proveedor ni el éxito del pago: el resultado proviene de la operación verificada de la pasarela.
| Grupo | Propósito |
|---|---|
| Configuración y estado | Disponibilidad del servicio público y del almacenamiento |
| Autenticación | Desafíos y sesiones de Telegram |
| Cuenta | Ajustes y la aplicación privada del comerciante |
| /api/v1/payments | Creación y lectura de facturas de servidor con alcance; no inicia un cargo |
| /api/v1/events | Registro de eventos del servidor con events:read |
| Integraciones | Administración de claves y endpoints de webhook autenticados por sesión |
| Aplicaciones y moderación | Envíos propios, seguimiento de estado y permisos de moderador separados |
| Pago | Factura pública, solicitud de tarjeta cifrada, operación concreta, código bancario, estado y conciliación |
| Entrada de pasarela | Notificaciones v3 firmadas y verificación de operación autenticada |
| Soporte y notificaciones | Preguntas, solicitudes privadas, eventos y estado de lectura |
| Telegram | Webhook de bot verificado |
| Rutas de dinero no compatibles | Los /api/payments y /api/payouts directos heredados no crean un cargo ni un pago |
Una solicitud de conocimiento pública#
La respuesta incluye mode, answer, sources, knowledgeVersion y needsHuman. Un Origin proporcionado debe coincidir con el origen de la aplicación. Un agente de documentación del lado del servidor puede omitir Origin.
curl 'https://kevmi.one/api/support/ask' \
-H 'Content-Type: application/json' \
--data '{"question":"Who pays VAT?","locale":"en"}'Errores y límites#
Un error incluye un código legible por máquina y un mensaje. Los campos de solicitud desconocidos se rechazan. Los cuerpos JSON estándar permiten 16.384 bytes; /api/support/ask y el webhook de Telegram permiten 65.536.
429 indica un límite de velocidad. 503 puede indicar una integración no disponible, no un pago rechazado. Lee error.code y no cambies un estado financiero solo por un código de estado HTTP.
Múltiples tiendas y un precio base en USD#
Elija Todas las tiendas para análisis y operaciones agregados, o seleccione una tienda para sus propios registros. Cada tienda tiene un storeId, nombre, IVA predeterminado, facturas, claves de API, endpoints de webhook, historial de eventos y aplicación web separados. Las notificaciones y tickets de soporte pertenecen a la cuenta. Una cuenta puede crear hasta 100 tiendas. Los registros existentes permanecen en su primera tienda.
Las facturas del nuevo espacio de trabajo usan pricingMode="universal" y un precio base en USD. Any incluye tarjeta, alipay, sbp y cripto; un comerciante puede seleccionar un subconjunto. Tarjetas y Alipay cobran en USD. SBP cobra en RUB usando el tipo de referencia USD/RUB del Banco de Rusia. Cripto cobra USDT bajo la regla explícita de factura 1 USD = 1 USDT. Esta es una regla de conversión de factura, no una cotización de mercado de USDT. La pasarela proporciona la tasa de la moneda seleccionada, el monto exacto de transferencia y las instrucciones antes de la transferencia.
El tipo de referencia y ambos montos se congelan al crear. Las facturas que implican conversión de RUB vencen dentro de 24 horas. Si no se puede obtener el tipo de referencia, la creación falla con FX_UNAVAILABLE; no se usa ningún tipo de respaldo inventado o desactualizado. El monto en minor del propietario y las cotizaciones usan la moneda contable USD. quotes[method].settlement contiene la cotización de cargo nativa. El checkout público expone la moneda de cargo seleccionada en currency, el precio original en baseAmountMinor/baseCurrency y el tipo de referencia en fx. Una vez que un pago ha sido despachado, su método no se puede cambiar; una factura tiene una operación de pasarela.
Cree una clave de API dentro de la tienda prevista y envíe Authorization: Bearer <key> desde su servidor. Su vinculación a tienda es inmutable; X-Kevmi-Store no puede otorgarle acceso a otra tienda. Las sesiones del navegador seleccionan X-Kevmi-Store: <storeId>; omitirlo selecciona la primera tienda. El valor all solo es aceptado por GET /api/account/dashboard y GET /api/payment-links. Las mutaciones requieren una tienda seleccionada, Origin y X-CSRF-Token. Los IDs de cuenta y los IDs de tienda son identificadores diferentes.
Por compatibilidad, las solicitudes de API sin pricingMode="universal" conservan el precio nativo y las restricciones de moneda originales. Las facturas existentes nunca se recalculan. Los recibos confirmados en análisis reflejan pagos verificados menos gastos de factura guardados; no son un saldo retirable. Las monedas de factura heredadas permanecen separadas y los pagos se gestionan con soporte. Cumpla un pedido solo después de verificar payment.fulfillmentReady=true y payment.status="succeeded" a través de la API del servidor, el historial de eventos o un webhook firmado.
{
"pricingMode": "universal",
"title": "Order 1042",
"amountMinor": 1000,
"currency": "USD",
"methods": [
"card",
"alipay",
"sbp",
"crypto"
],
"vatCustomerPercent": 100,
"feeCustomerPercent": 0
}Endpoints de API #
Abre un endpoint para ver campos, autorización y respuestas. Los esquemas usan el mismo documento OpenAPI disponible públicamente.
Service
Estado público del servicio.
GET/api/config
Preparación de integración actual
No requiere sesión de usuario
Respuestas
200Configuración sin secretos.
telegramobjectobligatoriosupportobjectobligatoriogatewayobjectobligatoriocapabilitiesobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/health
Estado de la tabla de API y D1
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.
No requiere sesión de usuario
Respuestas
200El almacenamiento está listo o es not_configured.
telegramobjectobligatoriosupportobjectobligatoriogatewayobjectobligatoriocapabilitiesobjectobligatoriostatusok | degradedobligatoriostorageready | not_configured | unavailableobligatorio503D1 no está disponible o ocurrió un error inesperado del servicio.
Variante 1
telegramobjectobligatoriosupportobjectobligatoriogatewayobjectobligatoriocapabilitiesobjectobligatoriostatusok | degradedobligatoriostorageready | not_configured | unavailableobligatorioVariante 2
errorobjectobligatorioGET/openapi.json
Contrato público legible por máquina
Solo lectura. No contiene secretos, sesiones, registros de usuario ni contrato operativo de proveedor de pagos.
No requiere sesión de usuario
Respuestas
200Este documento OpenAPI 3.1.
object
POST/api/jobs/dispatch
Ejecutar trabajos de entrega y aplicación pendientes
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.
La autorización sigue las reglas del endpoint
Respuestas
200Completado sin un contexto de fondo.
object
202Aceptado en un contexto de ejecución en segundo plano.
acceptedtrueobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioAuth
El registro y el inicio de sesión comparten el flujo verificado de Telegram.
GET/api/auth/me
Sesión actual y CSRF
La autorización sigue las reglas del endpoint
Respuestas
200authenticated=false cuando no existe una sesión válida.
Variante 1
authenticatedfalseobligatorioVariante 2
authenticatedtrueobligatoriouserobjectobligatoriocsrfTokenstringobligatorioexpiresAtintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/auth/telegram/start
Iniciar inicio de sesión o registro
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.
No requiere sesión de usuario
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
Cuerpo JSON
Respuestas
201Solicitud de inicio de sesión creada; la cookie de prueba la vincula al navegador original.
challengeIdstringobligatoriocodestringobligatorioexpiresAtintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
telegramUrlstringobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/auth/telegram/complete
Completar un inicio de sesión verificado
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
Cuerpo JSON
challengeIdstringobligatorioRespuestas
200Cuenta creada o actualizada y sesión emitida.
status"authenticated"obligatoriouserobjectobligatoriocsrfTokenstringobligatorioexpiresAtintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
202Esperando confirmación en Telegram.
status"pending"obligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio410La solicitud de inicio de sesión de cinco minutos expiró.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/auth/logout
Terminar la sesión actual
No se requiere ni se lee ningún cuerpo. El comando /logout del bot termina por separado todas las sesiones de la cuenta.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Respuestas
200Sesión eliminada y cookie borrada.
loggedOuttrueobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioAccount
Configuración solo para el usuario actual.
GET/api/account/settings
Configuración del usuario actual
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200Campos públicos del perfil del usuario actual.
userobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPATCH/api/account/settings
Cambiar el nombre de la tienda, el pagador de IVA o las notificaciones
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
storeNamestringSe recortan los espacios circundantes. Longitud tras recorte: 1–80 caracteres. Se prohíben caracteres de control excepto tabulaciones y saltos de línea.
vatPayercustomer | merchantnotificationsobjectRespuestas
200Perfil actualizado.
userobjectobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/stores
Enumere todas las tiendas propiedad de la cuenta actual
La autorización sigue las reglas del endpoint
Respuestas
200Los IDs de tienda son distintos de los IDs de cuenta. No se exponen secretos.
storesarray<object>obligatoriodefaultStoreIdstringobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/stores
Cree una tienda separada
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Cuerpo JSON
namestringobligatorioRespuestas
201Creada.
storeobjectobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPATCH/api/stores/{id}
Cambie el nombre de una tienda propia o modifique su IVA predeterminado
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Cuerpo JSON
namestringvatPayercustomer | merchantRespuestas
200Las cotizaciones de facturas existentes no cambian.
storeobjectobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/account/dashboard
Lea recibos verificados de una tienda o de todas las tiendas propiedad
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
X-Kevmi-StoreheaderSeleccione 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.
daysqueryRespuestas
200Resumen contable de solo lectura.
storeIdstring | nullobligatoriostoresarray<object>obligatoriototalsarray<object>obligatoriodailyarray<object>obligatoriomethodsarray<object>obligatoriodays7 | 30obligatoriofromintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
generatedAtintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
accountingBasis"verified_receipts"obligatoriowithdrawableBalancenullobligatoriopayoutCreationAvailablefalseobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPayment links
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.
GET/api/payment-links
Listar enlaces de pago propios
Ordenados por createdAt DESC, id DESC. Los enlaces públicos funcionan entre dispositivos; el listado requiere una cuenta.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
limitquerycursorquerynextCursor de la respuesta anterior. El servicio usa JSON en base64 [createdAt,id]; páselo sin cambios por URLSearchParams.
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200Una página de enlaces de pago propios.
linksarray<object>obligatorionextCursorstring | nullobligatorioCursor opaco de página siguiente. Páselo como parámetro de consulta codificado en URL; null marca el final.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/payment-links
Crear una factura con términos inmutables
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Idempotency-KeyheaderobligatorioUna 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.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
Moneda USD
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"USD"obligatoriomethodsarray<card | alipay | crypto>obligatorioEl 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.
vatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Moneda RUB
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"RUB"obligatoriomethodsarray<"sbp">obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Moneda USDT
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"USDT"obligatoriomethodsarray<"crypto">obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Variante 4
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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.
currencyUSD | RUB | USDTobligatorioUnidad 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.
methodsarray<card | alipay | sbp | crypto>obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"universal"obligatorioRespuestas
200Repetición idempotente; replayed=true.
linkobjectobligatorioreplayedbooleanobligatoriocheckoutUrlstringobligatorioEl enlace de pago está disponible de inmediato; no se requiere sondeo.
201Factura creada; replayed=false.
linkobjectobligatorioreplayedbooleanobligatoriocheckoutUrlstringobligatorioEl enlace de pago está disponible de inmediato; no se requiere sondeo.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/payment-links/{id}
Enlace propio y cálculo guardado
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioIdentificador de enlace propio, no el token público.
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200El ID de otro usuario y un ID inexistente devuelven 404.
linkobjectobligatoriocheckoutUrlstringIncluido en las respuestas de actualización de estado; el enlace anidado siempre contiene su checkoutUrl.
401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPATCH/api/payment-links/{id}
Pausar, reanudar o cancelar un enlace
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioIdentificador de enlace propio, no el token público.
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
statusactive | paused | cancelledobligatorioRespuestas
200Estado actual del enlace propio.
linkobjectobligatoriocheckoutUrlstringIncluido en las respuestas de actualización de estado; el enlace anidado siempre contiene su checkoutUrl.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioCheckout
Leer una factura sin cuenta. La disponibilidad de pago se verifica por separado.
GET/api/checkout/{token}
Detalles de factura pública para el cliente
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.
No requiere sesión de usuario
Cabeceras y parámetros
tokenpathobligatorioIdentificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura.
methodqueryDebe estar presente en los métodos guardados de la factura.
Respuestas
200Factura pública y el pago existente, si fue enviado.
invoiceobjectobligatoriopaymentoneOfobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/checkout/{token}/pay
Iniciar o recuperar el pago de la factura
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.
No requiere sesión de usuario
Cabeceras y parámetros
tokenpathobligatorioIdentificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura.
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
Cuerpo JSON
Variante 1
method"card"obligatoriosealedobjectobligatorioVariante 2
method"alipay"obligatorionamestringobligatoriocountry"CN"obligatorioemailstringVariante 3
method"sbp"obligatorioVariante 4
method"crypto"obligatoriopayerCurrencystringobligatorionetworkstringobligatorioRespuestas
200Operación existente recuperada; sin segundo pago.
paymentoneOfobligatorioreplayedboolean202Operación enviada; la finalización es asíncrona.
paymentoneOfobligatorioreplayedboolean400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio410La 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.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio502Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/checkout/{token}/status
Leer y actualizar el mismo pago
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.
No requiere sesión de usuario
Cabeceras y parámetros
tokenpathobligatorioIdentificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura.
Respuestas
200Estado de pago saneado actual.
paymentoneOfobligatorioreplayedboolean400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio502Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/checkout/{token}/reconcile
Solicitar una conciliación de estado autoritativa
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.
No requiere sesión de usuario
Cabeceras y parámetros
tokenpathobligatorioIdentificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura.
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
Cuerpo JSON
Respuestas
200Pago conciliado o null.
paymentoneOfobligatorioreplayedboolean400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio410La 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.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio502Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/checkout/{token}/card-intent
Obtener una clave pública de pasarela y una intención de cifrado vinculada
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.
No requiere sesión de usuario
Cabeceras y parámetros
tokenpathobligatorioIdentificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura.
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
Cuerpo JSON
purposepayment | codeRespuestas
200Intención de corta duración y clave RSA pública solamente.
intentstringobligatoriointentIdstringobligatorioexpiresAtintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
keyobjectobligatorioalgorithm"RSA-OAEP-256"obligatorioencryption"A256GCM"obligatorioprotocol"kevmi-card-v1"obligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio410La 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.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio502Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/checkout/{token}/code
Enviar un código cifrado para el desafío bancario actual
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.
No requiere sesión de usuario
Cabeceras y parámetros
tokenpathobligatorioIdentificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura.
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
Cuerpo JSON
sealedobjectobligatorioRespuestas
202Código enviado; estado de pago actual.
paymentoneOfobligatorioreplayedboolean400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio410La 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.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio502Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/checkout/{token}/crypto-services
Leer el catálogo actual de monedas y redes
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.
No requiere sesión de usuario
Cabeceras y parámetros
tokenpathobligatorioIdentificador público aleatorio de la URL de pago. Otorga acceso de lectura solo a esta factura.
Respuestas
200Catálogo proporcionado por la pasarela, con disponibilidad y límites de transferencia actuales.
servicesarray<object>obligatoriofetchedAtintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio502Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioSupport
Base de conocimientos pública y solicitudes de soporte del usuario actual.
POST/api/support/ask
Respuesta de la base de conocimientos pública completa
Pregunta pública sin sesión ni CSRF. Un Origin proporcionado debe coincidir con APP_ORIGIN; los agentes pueden omitirlo. En modo IA, el servidor envía todos los artículos publicados, hechos, catálogo de páginas y disponibilidad de funciones. El historial opcional y pageContext son contexto de pregunta no confiable. El modelo no puede acceder a cuentas, dinero, solicitudes privadas ni herramientas. Con D1, el límite es de 12 preguntas por minuto por dirección con hash. La IA requiere D1, configuración de proveedor válida y cuota: 60 generaciones por hora en todo el servicio por defecto. La disponibilidad de configuración no demuestra disponibilidad de API externa. Errores del proveedor, cuota agotada o salida inválida devuelven búsqueda con aiUnavailable=true y HTTP 200. Sin configuración de generación, se devuelve búsqueda regular.
No requiere sesión de usuario
Cabeceras y parámetros
OriginheaderDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
Cuerpo JSON
questionstringobligatorioSe recortan los espacios circundantes. Longitud tras recorte: 2–2.000 caracteres. Se prohíben caracteres de control excepto tabulaciones y saltos de línea.
localeru | en | es | de | fr | pt | tr | kkIdioma 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.
historyarray<oneOf>Hasta los últimos tres pares de pregunta y respuesta. Opcional. Contexto no confiable, no mensajes de rol de sistema del proveedor.
pageContextstringEtiqueta 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.
Respuestas
200Una respuesta o documentación coincidente con enlaces de artículos validados.
Variante 1
mode"search"obligatorioanswerstringobligatoriosourcesarray<object>obligatorioknowledgeVersionstring | nullobligatorioneedsHumanbooleanobligatorioaiUnavailabletrueVariante 2
mode"ai"obligatorioanswerstringobligatorioSolo texto plano; las URL y el HTML se rechazan. Los enlaces se devuelven solo en las fuentes.
sourcesarray<object>obligatorioknowledgeVersionstringobligatorioneedsHumanbooleanobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/support/tickets
Las últimas 30 solicitudes de soporte propias.
La autorización sigue las reglas del endpoint
Respuestas
200Más recientes primero por createdAt; devuelve los últimos 30 registros.
ticketsarray<object>obligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/support/tickets
Guardar una solicitud de soporte
Hasta seis solicitudes por usuario por hora, compartidas entre el sitio web y el bot. Guardar crea un registro de cuenta. Conserve su referencia para preguntar sobre el estado.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Cuerpo JSON
subjectstringobligatorioLos 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.
messagestringobligatorioLos 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.
Respuestas
201Solicitud de soporte guardada.
ticketobjectobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/support/tickets/{id}
Leer una solicitud de soporte propia
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioIdentificador de una solicitud de soporte propia.
Respuestas
200La solicitud de otro usuario y una solicitud inexistente devuelven 404.
ticketobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPATCH/api/support/tickets/{id}
Cerrar una solicitud de soporte propia
El único cambio permitido es estado=cerrado. Esta API no reabre solicitudes, edita mensajes ni envía respuestas de operador.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioIdentificador de una solicitud de soporte propia.
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Cuerpo JSON
status"closed"obligatorioRespuestas
200Solicitud de soporte cerrada.
closedtrueobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioNotifications
Centro de eventos de la cuenta, estado de lectura del sitio web y estado de entrega independiente de Telegram.
GET/api/notifications
Una página de notificaciones propias
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
unreadquery1 selecciona solo no leídos; 0 o un valor omitido selecciona todos los eventos.
cursorquerynextCursor de la respuesta anterior. Páselo sin cambios por URLSearchParams; formato createdAt:id, con createdAt como entero seguro en milisegundos.
Respuestas
200Eventos con estados independientes de lectura y entrega.
notificationsarray<object>obligatoriounreadCountintegerobligatorionextCursorstring | nullobligatorioCursor de página siguiente; null si no hay más registros.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPATCH/api/notifications/read
Marcar notificaciones propias como leídas
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Cuerpo JSON
Variante 1
idsarray<string>obligatorioSe permiten duplicados y se cuentan una vez.
Variante 2
alltrueobligatoriobeforeintegerobligatoriocreatedAt del último evento mostrado. El servidor también requiere before <= Date.now().
Respuestas
200El número de eventos recién leídos, el tiempo de operación y el recuento actual de no leídos.
updatedintegerobligatorioreadAtintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
unreadCountintegerobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/notifications/test
Enviar una notificación de prueba al Telegram de la cuenta
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Cuerpo JSON
Respuestas
202Resultado de la puesta en cola.
queuedbooleanobligatorioidstring | null400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioTelegram
Webhook del bot; no es un webhook de pago.
POST/api/telegram/webhook
Recibir un evento de Telegram Bot API
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.
La autorización sigue las reglas del endpoint
Cuerpo JSON
update_idintegerobligatoriomessageobjectMensaje de Telegram: el manejador usa message_id, text, from y chat.
callback_queryobjectTelegram CallbackQuery: el handler usa id, from, data y message.chat.
Respuestas
200Procesado, omitido o ya manejado.
oktrueobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio502La solicitud de Telegram falló.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioRutas monetarias no admitidas
Rutas de dinero heredadas no compatibles y ejecución de pagos. El flujo público de pago tiene sus propios endpoints documentados.
POST/api/payments
Operación financiera no disponible
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.
No requiere sesión de usuario
Respuestas
503Las operaciones financieras no están disponibles.
errorobjectobligatorioPOST/api/payouts
Operación financiera no disponible
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.
No requiere sesión de usuario
Respuestas
503Las operaciones financieras no están disponibles.
errorobjectobligatorioMerchant API
Facturas de servidor a servidor con ámbito y historial de eventos inmutable.
GET/api/v1/payments
Listar enlaces de pago propios
Ordenados por createdAt DESC, id DESC. Los enlaces públicos funcionan entre dispositivos; el listado requiere una cuenta.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
limitquerycursorquerynextCursor de la respuesta anterior. El servicio usa JSON en base64 [createdAt,id]; páselo sin cambios por URLSearchParams.
Respuestas
200Una página de enlaces de pago propios.
linksarray<object>obligatorionextCursorstring | nullobligatorioCursor opaco de página siguiente. Páselo como parámetro de consulta codificado en URL; null marca el final.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/v1/payments
Crear una factura con términos inmutables
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
Idempotency-KeyheaderobligatorioUna 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.
Cuerpo JSON
Moneda USD
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"USD"obligatoriomethodsarray<card | alipay | crypto>obligatorioEl 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.
vatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Moneda RUB
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"RUB"obligatoriomethodsarray<"sbp">obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Moneda USDT
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"USDT"obligatoriomethodsarray<"crypto">obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Variante 4
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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.
currencyUSD | RUB | USDTobligatorioUnidad 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.
methodsarray<card | alipay | sbp | crypto>obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"universal"obligatorioRespuestas
200Repetición idempotente; replayed=true.
linkobjectobligatorioreplayedbooleanobligatoriocheckoutUrlstringobligatorioEl enlace de pago está disponible de inmediato; no se requiere sondeo.
201Factura creada; replayed=false.
linkobjectobligatorioreplayedbooleanobligatoriocheckoutUrlstringobligatorioEl enlace de pago está disponible de inmediato; no se requiere sondeo.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/v1/payments/{id}
Enlace propio y cálculo guardado
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioIdentificador de enlace propio, no el token público.
Respuestas
200El ID de otro usuario y un ID inexistente devuelven 404.
linkobjectobligatoriocheckoutUrlstringIncluido en las respuestas de actualización de estado; el enlace anidado siempre contiene su checkoutUrl.
401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPATCH/api/v1/payments/{id}
Pausar, reanudar o cancelar un enlace
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioIdentificador de enlace propio, no el token público.
Cuerpo JSON
statusactive | paused | cancelledobligatorioRespuestas
200Estado actual del enlace propio.
linkobjectobligatoriocheckoutUrlstringIncluido en las respuestas de actualización de estado; el enlace anidado siempre contiene su checkoutUrl.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/v1/payment-links
Listar enlaces de pago propios
Ordenados por createdAt DESC, id DESC. Los enlaces públicos funcionan entre dispositivos; el listado requiere una cuenta.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
limitquerycursorquerynextCursor de la respuesta anterior. El servicio usa JSON en base64 [createdAt,id]; páselo sin cambios por URLSearchParams.
Respuestas
200Una página de enlaces de pago propios.
linksarray<object>obligatorionextCursorstring | nullobligatorioCursor opaco de página siguiente. Páselo como parámetro de consulta codificado en URL; null marca el final.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/v1/payment-links
Crear una factura con términos inmutables
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
Idempotency-KeyheaderobligatorioUna 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.
Cuerpo JSON
Moneda USD
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"USD"obligatoriomethodsarray<card | alipay | crypto>obligatorioEl 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.
vatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Moneda RUB
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"RUB"obligatoriomethodsarray<"sbp">obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Moneda USDT
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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"USDT"obligatoriomethodsarray<"crypto">obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"native"Precio heredado específico por moneda. Omita para compatibilidad con integraciones existentes.
Variante 4
titlestringobligatorioLos 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.
descriptionstringOpcional; se permite una cadena vacía. Hasta 500 caracteres después de recortar.
amountMinorintegerobligatorioLímite entero técnico, no un límite comercial del proveedor. Un crédito negativo del comerciante se rechaza.
vatPayercustomer | merchantCuando se omite, se guarda la regla actual de la tienda.
expiresAtintegerUn 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.
currencyUSD | RUB | USDTobligatorioUnidad 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.
methodsarray<card | alipay | sbp | crypto>obligatoriovatCustomerPercentintegerParticipació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.
feeCustomerPercentintegerParticipación del cliente, como porcentaje entero. 0 significa que el comerciante cubre todo; 100 significa que el cliente cubre todo.
orderIdstringReferencia de pedido visible para el comprador.
metadataobjectMetadatos privados del comerciante. Como máximo 3000 bytes UTF-8 tras la serialización JSON. Nunca se exponen en el checkout público.
pricingMode"universal"obligatorioRespuestas
200Repetición idempotente; replayed=true.
linkobjectobligatorioreplayedbooleanobligatoriocheckoutUrlstringobligatorioEl enlace de pago está disponible de inmediato; no se requiere sondeo.
201Factura creada; replayed=false.
linkobjectobligatorioreplayedbooleanobligatoriocheckoutUrlstringobligatorioEl enlace de pago está disponible de inmediato; no se requiere sondeo.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/v1/payment-links/{id}
Enlace propio y cálculo guardado
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioIdentificador de enlace propio, no el token público.
Respuestas
200El ID de otro usuario y un ID inexistente devuelven 404.
linkobjectobligatoriocheckoutUrlstringIncluido en las respuestas de actualización de estado; el enlace anidado siempre contiene su checkoutUrl.
401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPATCH/api/v1/payment-links/{id}
Pausar, reanudar o cancelar un enlace
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioIdentificador de enlace propio, no el token público.
Cuerpo JSON
statusactive | paused | cancelledobligatorioRespuestas
200Estado actual del enlace propio.
linkobjectobligatoriocheckoutUrlstringIncluido en las respuestas de actualización de estado; el enlace anidado siempre contiene su checkoutUrl.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/api-keys
Listar metadatos de claves propias
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200Se omiten secretos y hashes de secretos.
keysarray<object>obligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/api-keys
Crear una clave con ámbito; revelar su secreto una vez
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
namestringobligatorioscopesarray<invoices:read | invoices:write | events:read>expiresInDaysintegerRespuestas
201Almacene el secreto de forma segura en su servidor.
keyobjectobligatoriosecretstringobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioDELETE/api/api-keys/{id}
Revocar clave propia
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200Se rechazan los usos futuros de la clave.
revokedtrueobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/events
Leer historial de eventos propio inmutable
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
beforequeryLímite de marca de tiempo exclusivo heredado. No puede combinarse con cursor. Use nextCursor para paginación sin pérdidas.
cursorquerynextCursor opaco devuelto por la página anterior. Codifica [createdAt,id] y conserva eventos que comparten una marca de tiempo.
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200Más recientes primero; hasta 50 eventos. Siga nextCursor hasta que sea null.
eventsarray<object>obligatorionextCursorstring | nullobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/v1/events
Leer historial de eventos propio inmutable
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
beforequeryLímite de marca de tiempo exclusivo heredado. No puede combinarse con cursor. Use nextCursor para paginación sin pérdidas.
cursorquerynextCursor opaco devuelto por la página anterior. Codifica [createdAt,id] y conserva eventos que comparten una marca de tiempo.
Respuestas
200Más recientes primero; hasta 50 eventos. Siga nextCursor hasta que sea null.
eventsarray<object>obligatorionextCursorstring | nullobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioWebhooks
Endpoints HTTPS verificados, eventos firmados, intentos de entrega y reintentos.
GET/api/webhooks
Listar endpoints y las últimas 30 entregas
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200No se devuelven secretos de firma.
endpointsarray<object>obligatoriodeliveriesarray<object>obligatorioavailablebooleanobligatorioeventTypesarray<invoice.created | invoice.updated | payment.succeeded | payment.failed | payment.refunded | payment.partially_refunded | payment.disputed | payment.review_required>obligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/webhooks
Registrar un destino HTTPS público
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
urlstringobligatoriodescriptionstringeventsarray<invoice.created | invoice.updated | payment.succeeded | payment.failed | payment.refunded | payment.partially_refunded | payment.disputed | payment.review_required>Respuestas
201Guarde el secreto de firma de un solo uso.
endpointobjectobligatoriosecretstringobligatorioSe muestra solo al crear/rotar. Se almacena cifrado en el servidor.
400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/webhooks/{id}
Listar endpoints y las últimas 30 entregas
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioX-Kevmi-StoreheaderSeleccione 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.
Respuestas
200No se devuelven secretos de firma.
endpointsarray<object>obligatoriodeliveriesarray<object>obligatorioavailablebooleanobligatorioeventTypesarray<invoice.created | invoice.updated | payment.succeeded | payment.failed | payment.refunded | payment.partially_refunded | payment.disputed | payment.review_required>obligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPATCH/api/webhooks/{id}
Pausar o reanudar un endpoint verificado
Los endpoints verificados pausados mantienen eventos elegibles en la cola; reanudar procesa las entregas pendientes.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
statusactive | pausedobligatorioRespuestas
200Estado guardado.
updatedtrueobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioDELETE/api/webhooks/{id}
Eliminar endpoint y cancelar trabajos no entregados
Cancela trabajos pendientes, fallidos y arrendados. Una solicitud ya enviada a través de la red no puede recuperarse.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200Endpoint eliminado.
deletedtrueobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/webhooks/{id}/verify
Enviar un desafío de verificación de endpoint firmado
Máximo de 5 intentos de verificación/hora/usuario. Su servidor debe validar Kevmi-Signature y devolver JSON 2xx {"challenge":"<data.challenge>"}. Tiempo de espera de solicitud: 8 segundos; límite de respuesta: 8192 bytes. No se siguen redirecciones. La verificación activa el endpoint.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
Respuestas
200Verificado y activo.
verifiedtrueobligatorioendpointobjectobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio422No se pudo verificar el destino.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/webhooks/{id}/rotate
Reemplazar secreto de firma y requerir verificación nuevamente
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
Respuestas
200Nuevo secreto mostrado una vez.
secretstringobligatorioSe muestra solo al crear/rotar. Se almacena cifrado en el servidor.
requiresVerificationtrueobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/webhooks/{id}/deliveries/{deliveryId}/retry
Reintentar una entrega fallida a un endpoint activo
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatoriodeliveryIdpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
Respuestas
202Reintento programado.
queuedtrueobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioApplications
Aplicaciones de sitio web autenticadas y seguimiento individual.
GET/api/applications
Listar hasta 30 aplicaciones propias
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
X-Kevmi-LocaleheaderURL 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.
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200Más recientes primero.
applicationsarray<object>obligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/applications
Enviar información del sitio web y recibir una URL de seguimiento
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
OriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Idempotency-KeyheaderobligatorioUna 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.
X-Kevmi-LocaleheaderURL 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.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
websiteUrlstringobligatorioDominio HTTPS público sin credenciales, parámetros de consulta, literales de IP ni puertos personalizados. Un fragmento se elimina durante la normalización.
businessNamestringobligatoriobusinessTypedigital_goods | software | services | physical_goods | education | otherobligatoriodescriptionstringobligatoriocontactTelegramstringobligatorioUn 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.
consenttrueobligatorioRespuestas
200Envío existente.
applicationobjectobligatoriourlstringobligatorioreplayedbooleanobligatorio202Aceptado; el procesamiento continúa en el servidor.
applicationobjectobligatoriourlstringobligatorioreplayedbooleanobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/applications/{id}
Leer etapas de revisión propias e historial de eventos
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioX-Kevmi-LocaleheaderURL 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.
X-Kevmi-StoreheaderSeleccione 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.
Respuestas
200Proyección privada del solicitante. La evidencia y la salida del modelo no se exponen.
applicationobjectobligatorioeventsarray<object>obligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/applications/{id}/resume
Reanudar una etapa de fondo elegible
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
X-Kevmi-LocaleheaderURL 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.
X-Kevmi-StoreheaderSeleccione 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.
Cuerpo JSON
Respuestas
200No se necesita procesamiento.
applicationobjectobligatorio202Procesamiento programado.
applicationobjectobligatorioscheduledtrueobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioModeration
Moderadores de Telegram en lista de permitidos; cada decisión se verifica por versión.
GET/api/moderation/applications
Listar hasta 100 aplicaciones para moderación
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.
La autorización sigue las reglas del endpoint
Respuestas
200Cola de moderador.
applicationsarray<object>obligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGET/api/moderation/applications/{id}
Leer evidencia de revisión e historial de etapas
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioRespuestas
200Evidencia privada del moderador.
applicationobjectobligatorioeventsarray<object>obligatorioevidenceobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioPOST/api/moderation/applications/{id}/decision
Aprobar la etapa de revisión actual o rechazar con una razón pública
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
idpathobligatorioOriginheaderobligatorioDebe coincidir exactamente con APP_ORIGIN. Sec-Fetch-Site: cross-site se rechaza. El servidor no proporciona acceso CORS.
X-CSRF-TokenheaderobligatorioToken de sesión actual de GET /api/auth/me o finalización exitosa del inicio de sesión.
Cuerpo JSON
Variante 1
expectedVersionintegerobligatorioaction"approve_step"obligatorioreasonstringVariante 2
expectedVersionintegerobligatorioaction"reject"obligatorioreasonstringobligatorioRespuestas
200Decisión guardada.
applicationobjectobligatorio400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401Sin sesión válida; para un webhook, un secreto inválido.
errorobjectobligatorio403Falló la validación de origen, CSRF o vinculación con el navegador.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409La solicitud de inicio de sesión se usa o se cancela, la identidad no se confirma, o una solicitud de soporte entra en conflicto.
errorobjectobligatorio429Límite de velocidad excedido.
errorobjectobligatorio503Una integración o almacenamiento no está disponible, se está procesando un evento, o el servicio no está disponible.
errorobjectobligatorioGateway events
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.
POST/api/gateway/webhook
Recibir eventos de pasarela nativos firmados
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.
La autorización sigue las reglas del endpoint
Cabeceras y parámetros
X-Gateway-TimestampheaderRequerido para eventos nativos v3.
X-Gateway-Event-IdheaderRequerido para nativo v3; debe coincidir con body.id.
Cuerpo JSON
Variante 1
idstringobligatorioapi_version"3"obligatoriomode"live"obligatoriotypestringobligatoriodataobjectobligatorioVariante 2
eventIdstringobligatoriopaymentIdstringobligatorioinvoiceIdstringobligatoriostatussucceeded | failed | refundedobligatorioamountMinorintegerobligatorioCantidad entera en unidades monetarias menores.
currencyUSD | RUB | USDTobligatorioUnidades de factura: centavos de USD, kopeks de RUB o centésimas de USDT. Sin conversión automática de moneda.
methodcard | alipay | sbp | cryptoobligatoriooccurredAtintegerobligatorioMarca de tiempo Unix en milisegundos, UTC.
Respuestas
200Recibido, deduplicado o ignorado de forma segura.
receivedtrueobligatorioreplayedbooleanignoredbooleanappliedboolean400JSON inválido, campo desconocido o valor inválido.
errorobjectobligatorio401La firma de la pasarela falta, no es válida o está fuera de la ventana de tiempo aceptada.
errorobjectobligatorio404El registro no existe, el token público no es válido o el registro solicitado pertenece a otro usuario.
errorobjectobligatorio409Se reutilizó un ID de evento con contenido cambiado o un ID de pago entra en conflicto con el vínculo de factura guardado.
errorobjectobligatorio413El cuerpo supera los 16,384 bytes; el límite es de 65,536 bytes para /api/support/ask y el webhook de Telegram.
errorobjectobligatorio415Se requiere Content-Type: application/json.
errorobjectobligatorio429La pasarela está ocupada; reintente la entrega del webhook con el mismo ID de evento.
errorobjectobligatorio502Respuesta de la pasarela no disponible, malformada o no verificable. Lea el estado del pago existente antes de intentar cualquier reintento.
errorobjectobligatorio503Falta la configuración de la pasarela o el secreto de firma.
errorobjectobligatorio