Referência da API
A API do servidor suporta contas, faturas, checkout seguro, status e webhooks. OpenAPI descreve rotas, campos e erros. Iniciar um pagamento exige um gateway configurado, um comerciante aprovado e termos de fatura suportados.
Nesta página
URL base e 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.
Respostas da API usam Cache-Control: no-store. O /openapi.json público pode ser armazenado em cache por cinco minutos. Não coloque cookies ou segredos em uma URL.
curl 'https://kevmi.one/api/config'
curl 'https://kevmi.one/openapi.json'Autorização de solicitação#
A conta web usa um cookie de sessão HttpOnly. GET /api/auth/me retorna o usuário atual e csrfToken. Mutações exigem X-CSRF-Token e uma solicitação de mesma origem.
Chaves de comerciante Kevmi com escopo autorizam /api/v1/payments, /api/v1/payment-links e /api/v1/events. Elas não substituem o cookie de sessão para configurações de conta ou rotas 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 a presença da configuração do servidor. GET /api/checkout/{token} retorna invoice.availability para o método selecionado, incluindo aprovação do comerciante e termos salvos. Essas verificações não estabelecem conectividade do provedor nem sucesso do pagamento: o resultado vem da operação verificada do gateway.
| Grupo | Finalidade |
|---|---|
| Configuração e saúde | Prontidão do serviço público e de armazenamento |
| Autenticação | Desafios e sessões do Telegram |
| Conta | Configurações e o aplicativo privado do comerciante |
| /api/v1/payments | Criação e leitura de faturas de servidor com escopo; não inicia uma cobrança |
| /api/v1/events | Registro de eventos do servidor com events:read |
| Integrações | Administração de chaves e endpoints de webhook autenticados por sessão |
| Aplicativos e moderação | Envios de propriedade, acompanhamento de status e permissões separadas de moderador |
| Checkout | Fatura pública, solicitação de cartão criptografada, operação concreta, código bancário, status e conciliação |
| Ingresso do gateway | Notificações v3 assinadas e verificação de operação autenticada |
| Suporte e notificações | Perguntas, solicitações privadas, eventos e estado de leitura |
| Telegram | Webhook de bot verificado |
| Rotas de dinheiro não suportadas | O legado direto /api/payments e /api/payouts não cria uma cobrança nem um pagamento |
Uma solicitação de conhecimento pública#
A resposta inclui mode, answer, sources, knowledgeVersion e needsHuman. Um Origin fornecido deve corresponder à origem do aplicativo. Um agente de documentação do lado do servidor pode omitir Origin.
curl 'https://kevmi.one/api/support/ask' \
-H 'Content-Type: application/json' \
--data '{"question":"Who pays VAT?","locale":"en"}'Erros e limites#
Um erro inclui um código legível por máquina e uma mensagem. Campos de solicitação desconhecidos são rejeitados. Corpos JSON padrão permitem 16.384 bytes; /api/support/ask e o webhook do Telegram permitem 65.536.
429 indica um limite de taxa. 503 pode indicar uma integração indisponível, não um pagamento recusado. Leia error.code e não altere um status financeiro com base apenas no status HTTP.
Múltiplas lojas e um preço base em USD#
Escolha Todas as lojas para análises e operações agregadas, ou selecione uma loja para seus próprios registros. Cada loja tem um storeId separado, nome, padrão de IVA, faturas, chaves de API, endpoints de webhook, histórico de eventos e aplicativo de site. Notificações e tickets de suporte pertencem à conta. Uma conta pode criar até 100 lojas. Registros existentes permanecem na primeira loja.
As faturas do novo workspace usam pricingMode="universal" e um preço base em USD. O plano Any inclui cartão, alipay, sbp e cripto; um comerciante pode selecionar um subconjunto. Cartões e Alipay cobram em USD. O SBP cobra em RUB usando a taxa de referência USD/RUB do Banco da Rússia. Cripto cobra USDT sob a regra explícita de fatura 1 USD = 1 USDT. Esta é uma regra de conversão de fatura, não uma cotação de mercado de USDT. O gateway fornece a taxa da moeda selecionada, o valor exato da transferência e instruções antes da transferência.
A taxa de referência e ambos os valores são congelados na criação. Faturas que envolvem conversão RUB expiram dentro de 24 horas. Se a taxa de referência não puder ser obtida, a criação falha com FX_UNAVAILABLE; nenhuma taxa de fallback inventada ou desatualizada é usada. O valor do proprietário em minor e cotações usam a moeda contábil USD. quotes[method].settlement contém a cotação de cobrança nativa. O checkout público expõe a moeda de cobrança selecionada em currency, o preço original em baseAmountMinor/baseCurrency, e a taxa de referência em fx. Uma vez que um pagamento foi enviado, seu método não pode ser alterado; uma fatura tem uma operação de gateway.
Crie uma chave de API dentro da loja pretendida e envie Authorization: Bearer <key> do seu servidor. Seu vínculo de loja é imutável; X-Kevmi-Store não pode conceder acesso a outra loja. Sessões de navegador selecionam X-Kevmi-Store: <storeId>; omitir seleciona a primeira loja. O valor all é aceito apenas por GET /api/account/dashboard e GET /api/payment-links. Mutações exigem uma loja selecionada, Origin e X-CSRF-Token. IDs de conta e IDs de loja são identificadores diferentes.
Para compatibilidade, solicitações de API sem pricingMode="universal" mantêm preço nativo e as restrições originais de moeda. Faturas existentes nunca são recalculadas. Recibos confirmados nas análises refletem pagamentos verificados menos despesas de fatura salvas; eles não são um saldo sacável. Moedas de fatura legadas permanecem separadas e pagamentos são combinados com o suporte. Cumpra um pedido somente após verificar payment.fulfillmentReady=true e payment.status="succeeded" através da API do servidor, histórico de eventos ou um webhook assinado.
{
"pricingMode": "universal",
"title": "Order 1042",
"amountMinor": 1000,
"currency": "USD",
"methods": [
"card",
"alipay",
"sbp",
"crypto"
],
"vatCustomerPercent": 100,
"feeCustomerPercent": 0
}Endpoints da API #
Abra um endpoint para ver seus campos, autorização e respostas. Esses esquemas usam o mesmo documento OpenAPI disponível no URL público.
Service
Status público do serviço.
GET/api/config
Prontidão atual de integração
Nenhuma sessão de usuário necessária
Respostas
200Configuração sem segredos.
telegramobjectobrigatóriosupportobjectobrigatóriogatewayobjectobrigatóriocapabilitiesobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/health
Status da API e da tabela D1
not_configured pode ter status=ok: páginas públicas e busca podem funcionar sem banco de dados. Um banco configurado com tabelas indisponíveis retorna 503/degradado. Esta resposta não testa a conectividade de rede do Telegram ou do modelo.
Nenhuma sessão de usuário necessária
Respostas
200O armazenamento está pronto ou not_configured.
telegramobjectobrigatóriosupportobjectobrigatóriogatewayobjectobrigatóriocapabilitiesobjectobrigatóriostatusok | degradedobrigatóriostorageready | not_configured | unavailableobrigatório503D1 está indisponível ou ocorreu um erro de serviço inesperado.
Variante 1
telegramobjectobrigatóriosupportobjectobrigatóriogatewayobjectobrigatóriocapabilitiesobjectobrigatóriostatusok | degradedobrigatóriostorageready | not_configured | unavailableobrigatórioVariante 2
errorobjectobrigatórioGET/openapi.json
Contrato público legível por máquina
Somente leitura. Não contém segredos, sessões, registros de usuário nem contrato operacional com provedor de pagamento.
Nenhuma sessão de usuário necessária
Respostas
200Este documento OpenAPI 3.1.
object
POST/api/jobs/dispatch
Executar trabalhos de entrega e aplicação devidos
Ponto de entrada do agendador de servidor. Requer JOBS_SECRET, não uma sessão de navegador ou chave de comerciante. Não aceita IDs de trabalho ou URLs de saída arbitrárias.
A autorização segue as regras do endpoint
Respostas
200Concluído sem um contexto de segundo plano.
object
202Aceito em um contexto de execução em segundo plano.
acceptedtrueobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioAuth
Registro e entrada compartilham o fluxo verificado do Telegram.
GET/api/auth/me
Sessão atual e CSRF
A autorização segue as regras do endpoint
Respostas
200authenticated=false quando não existe uma sessão válida.
Variante 1
authenticatedfalseobrigatórioVariante 2
authenticatedtrueobrigatóriouserobjectobrigatóriocsrfTokenstringobrigatórioexpiresAtintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/auth/telegram/start
Iniciar entrada ou registro
Cria um desafio de 300 segundos e um cookie de prova à prova de navegador HttpOnly; no máximo seis inícios por minuto por endereço com hash. Compare o código de seis dígitos no site e no chat privado do bot.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
Corpo JSON
Respostas
201Solicitação de entrada criada; o cookie de prova a vincula ao navegador original.
challengeIdstringobrigatóriocodestringobrigatórioexpiresAtintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
telegramUrlstringobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/auth/telegram/complete
Concluir uma entrada verificada
Exige o cookie de prova do início e o mesmo navegador. Pendente retorna 202. Após a confirmação do bot, a solicitação emite uma sessão de 24 horas. Até 90 verificações por minuto por desafio. Um ID do Telegram fornecido pelo cliente não é aceito.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
Corpo JSON
challengeIdstringobrigatórioRespostas
200Conta criada ou atualizada e sessão emitida.
status"authenticated"obrigatóriouserobjectobrigatóriocsrfTokenstringobrigatórioexpiresAtintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
202Aguardando confirmação no Telegram.
status"pending"obrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório410A solicitação de entrada de cinco minutos expirou.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/auth/logout
Encerrar a sessão atual
Nenhum corpo é necessário ou lido. O comando /logout do bot encerra separadamente todas as sessões da conta.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Respostas
200Sessão removida e cookie limpo.
loggedOuttrueobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioAccount
Configurações apenas para o usuário atual.
GET/api/account/settings
Configurações do usuário atual
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Campos públicos do perfil do usuário atual.
userobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPATCH/api/account/settings
Alterar o nome da loja, o pagador de IVA ou notificações
Todos os campos são opcionais: correção parcial. Salvar vatPayer não cria uma operação financeira. Os interruptores de pagamentos e pagamentos controlam preferências, não a disponibilidade do gateway.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
storeNamestringEspaços ao redor são removidos. Comprimento após remoção: 1–80 caracteres. Caracteres de controle exceto tabs e quebras de linha são proibidos.
vatPayercustomer | merchantnotificationsobjectRespostas
200Perfil atualizado.
userobjectobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/stores
Listar todas as lojas pertencentes à conta atual
A autorização segue as regras do endpoint
Respostas
200IDs de loja são distintos de IDs de conta. Nenhum segredo é exposto.
storesarray<object>obrigatóriodefaultStoreIdstringobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/stores
Criar uma loja separada
Até 100 lojas/conta e 10 criações/hora/conta. Uma nova loja precisa de sua própria aprovação de site antes de iniciar um pagamento.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Corpo JSON
namestringobrigatórioRespostas
201Criada.
storeobjectobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPATCH/api/stores/{id}
Renomear uma loja própria ou alterar seu padrão de IVA
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Corpo JSON
namestringvatPayercustomer | merchantRespostas
200Cotações de fatura existentes permanecem inalteradas.
storeobjectobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/account/dashboard
Ler recibos verificados para uma loja ou todas as lojas próprias
Recibos líquidos não são um saldo sacável. Moedas legadas permanecem separadas. Os totais são de todos os tempos; detalhamentos diários/por método usam o período UTC solicitado.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
daysqueryRespostas
200Resumo contábil somente leitura.
storeIdstring | nullobrigatóriostoresarray<object>obrigatóriototalsarray<object>obrigatóriodailyarray<object>obrigatóriomethodsarray<object>obrigatóriodays7 | 30obrigatóriofromintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
generatedAtintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
accountingBasis"verified_receipts"obrigatóriowithdrawableBalancenullobrigatóriopayoutCreationAvailablefalseobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPayment links
Faturas de servidor para a loja atual. O preço, a moeda, o pagador de IVA, o nome do vendedor e o cálculo são imutáveis.
GET/api/payment-links
Listar links de pagamento próprios
Ordenados por createdAt DESC, id DESC. Links públicos funcionam em dispositivos; listar requer uma conta.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
limitquerycursorquerynextCursor da resposta anterior. O serviço usa JSON em base64 [createdAt,id]; passe inalterado via URLSearchParams.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Uma página de links de pagamento próprios.
linksarray<object>obrigatórionextCursorstring | nullobrigatórioCursor opaco para a próxima página. Passe como um parâmetro de consulta codificado em URL; null marca o fim.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/payment-links
Criar uma fatura com termos imutáveis
Criar uma fatura imutável e receber imediatamente checkoutUrl; isso não cobra o comprador. USD: cartão/Alipay; RUB: SBP; USDT: cripto. USD cripto permanece aceito para compatibilidade, mas não pode ser pago sem uma fatura USDT. As participações do cliente na taxa e no imposto são inteiros independentes de 0 a 100; atualmente, cartão/Alipay ao vivo suporta imposto cliente=100 e taxa cliente=0. O total do cliente nunca é alterado silenciosamente. A aplicação mais recente do site deve ser aprovada antes de uma nova cobrança ao vivo. A criação da fatura e seu evento de comerciante são confirmados atomicamente.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Idempotency-KeyheaderobrigatórioUma chave por solicitação lógica. Uma repetição com entrada canônica idêntica retorna o registro original; entrada diferente com a mesma chave retorna 409.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
Moeda USD
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"USD"obrigatóriomethodsarray<card | alipay | crypto>obrigatórioO novo checkout em USD suporta cartão e Alipay. Faturas cripto em USD são aceitas apenas por compatibilidade e retornam crypto_requires_usdt no checkout ao vivo; use USDT para cripto.
vatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Moeda RUB
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"RUB"obrigatóriomethodsarray<"sbp">obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Moeda USDT
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"USDT"obrigatóriomethodsarray<"crypto">obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Variante 4
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currencyUSD | RUB | USDTobrigatórioUnidade de entrada. RUB é convertido para USD à taxa de referência salva; USDT usa a regra explícita de fatura 1:1. A moeda base de fatura salva é USD.
methodsarray<card | alipay | sbp | crypto>obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"universal"obrigatórioRespostas
200Repetição idempotente; replayed=true.
linkobjectobrigatórioreplayedbooleanobrigatóriocheckoutUrlstringobrigatórioO link de pagamento está disponível imediatamente; nenhuma sondagem é necessária.
201Fatura criada; replayed=false.
linkobjectobrigatórioreplayedbooleanobrigatóriocheckoutUrlstringobrigatórioO link de pagamento está disponível imediatamente; nenhuma sondagem é necessária.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/payment-links/{id}
Link próprio e cálculo salvo
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioIdentificador de link próprio, não o token público.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200O ID de outro usuário e um ID ausente retornam 404.
linkobjectobrigatóriocheckoutUrlstringIncluído nas respostas de atualização de status; o link aninhado sempre contém seu checkoutUrl.
401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPATCH/api/payment-links/{id}
Pausar, retomar ou cancelar um link
Altera apenas o status. A atualização e o evento imutável de fatura updated são confirmados atomicamente. Alterações concorrentes usam uma verificação de versão; atualize e tente novamente em LINK_CHANGED. cancelled é terminal, a expiração nunca é estendida, e preço, métodos, participações de custo e descrição permanecem congelados. Repetir o status salvo retorna a fatura atual.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioIdentificador de link próprio, não o token público.
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
statusactive | paused | cancelledobrigatórioRespostas
200Estado atual do link próprio.
linkobjectobrigatóriocheckoutUrlstringIncluído nas respostas de atualização de status; o link aninhado sempre contém seu checkoutUrl.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioCheckout
Ler uma fatura sem conta. A disponibilidade de pagamento é verificada separadamente.
GET/api/checkout/{token}
Detalhes públicos da fatura para o cliente
Ler a cotação pública imutável da fatura e seu instantâneo de pagamento persistido. method deve pertencer à fatura. Nenhuma conta é necessária. Não expõe identidade do proprietário, metadados privados nem receitas do comerciante. O token concede acesso apenas a este checkout. availability reflete configuração, alocação, limites técnicos e aprovação do comerciante; confirmação de pagamento é separada.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
tokenpathobrigatórioIdentificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura.
methodqueryDeve estar presente nos métodos salvos da fatura.
Respostas
200Fatura pública e o pagamento existente, se enviado.
invoiceobjectobrigatóriopaymentoneOfobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/checkout/{token}/pay
Iniciar ou recuperar o pagamento da fatura
Operação de comprador de mesma origem; nenhuma conta ou token CSRF é necessário. O servidor reserva uma operação e uma chave de idempotência estável antes do envio ao gateway. Uma repetição recupera a mesma operação; uma resposta perdida deve ser resolvida por meio do status. O método de pagamento é bloqueado após o envio. Os dados do cartão devem ser criptografados no navegador com uma intenção de pagamento nova. SBP/cripto enviam o total salvo do cliente; cartão/Alipay usam a configuração fiscal imutável suportada. Novas cobranças exigem uma solicitação de comerciante aprovada. Pagamentos já enviados podem ser recuperados após expiração da fatura, pausa ou alterações de aprovação. Nenhuma rota /v2 ou de cartão hospedado é usada.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
tokenpathobrigatórioIdentificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura.
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
Corpo JSON
Variante 1
method"card"obrigatóriosealedobjectobrigatórioVariante 2
method"alipay"obrigatórionamestringobrigatóriocountry"CN"obrigatórioemailstringVariante 3
method"sbp"obrigatórioVariante 4
method"crypto"obrigatóriopayerCurrencystringobrigatórionetworkstringobrigatórioRespostas
200Operação existente recuperada; nenhum segundo pagamento.
paymentoneOfobrigatórioreplayedboolean202Operação enviada; a conclusão é assíncrona.
paymentoneOfobrigatórioreplayedboolean400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório410A intenção de criptografia do gateway ou o desafio do banco expirou. Obtenha uma nova intenção para a mesma operação; não crie um pagamento substituto.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório502Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/checkout/{token}/status
Ler e atualizar o mesmo pagamento
Nenhuma conta é necessária. Atualiza uma operação existente por transporte de gateway autenticado, com limitação de taxa no servidor. Nenhum novo pagamento é criado. Retorna null se nada foi enviado. Confirme um pedido somente quando fulfillmentReady for verdadeiro.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
tokenpathobrigatórioIdentificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura.
Respostas
200Estado de pagamento saneado atual.
paymentoneOfobrigatórioreplayedboolean400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório502Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/checkout/{token}/reconcile
Solicitar uma conciliação de status autoritativa
Lê a operação existente e pede ao gateway que concilie seu status de provedor. Não cria um pagamento. No máximo 3 solicitações por fatura por minuto. Disponível para pagamentos já enviados mesmo se a fatura não estiver mais ativa.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
tokenpathobrigatórioIdentificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura.
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
Corpo JSON
Respostas
200Pagamento conciliado ou null.
paymentoneOfobrigatórioreplayedboolean400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório410A intenção de criptografia do gateway ou o desafio do banco expirou. Obtenha uma nova intenção para a mesma operação; não crie um pagamento substituto.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório502Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/checkout/{token}/card-intent
Obter uma chave pública do gateway e uma intenção de criptografia vinculada
Somente o gateway possui a chave privada. Uma intenção expira em cinco minutos e vincula o pedido do comerciante, a moeda, os valores base/total, a chave de idempotência da operação e o propósito. Intenções de pagamento exigem uma fatura ativa e comerciante aprovado; intenções de código exigem um desafio bancário atual existente. Nenhum campo PAN, CVV, código bancário ou JWK privado é aceito por este endpoint. No máximo 8 intenções por fatura e 12 por cliente por minuto. O texto simples criptografado é {intent,name,country,email?,card:{number,expiration,cvv,holder}} para pagamento ou {intent,code} para código. O texto simples é montado somente dentro do navegador antes da criptografia JWE.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
tokenpathobrigatórioIdentificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura.
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
Corpo JSON
purposepayment | codeRespostas
200Intenção de curta duração e chave RSA pública apenas.
intentstringobrigatóriointentIdstringobrigatórioexpiresAtintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
keyobjectobrigatórioalgorithm"RSA-OAEP-256"obrigatórioencryption"A256GCM"obrigatórioprotocol"kevmi-card-v1"obrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório410A intenção de criptografia do gateway ou o desafio do banco expirou. Obtenha uma nova intenção para a mesma operação; não crie um pagamento substituto.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório502Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/checkout/{token}/code
Retransmitir um código criptografado para o desafio bancário atual
Obtenha uma intenção de propósito=code e criptografe {intent,code} no navegador. O gateway valida o desafio atual e consome a intenção vedada uma vez. A Kevmi nunca recebe texto simples do código. No máximo 5 envios por fatura por minuto; atualize o status após uma resposta incerta.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
tokenpathobrigatórioIdentificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura.
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
Corpo JSON
sealedobjectobrigatórioRespostas
202Código enviado; estado de pagamento atual.
paymentoneOfobrigatórioreplayedboolean400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório410A intenção de criptografia do gateway ou o desafio do banco expirou. Obtenha uma nova intenção para a mesma operação; não crie um pagamento substituto.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório502Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/checkout/{token}/crypto-services
Ler o catálogo atual de moedas e redes
Somente para uma fatura USDT que permite criptomoedas. A fatura permanece denominada em USDT; o gateway cotiza a moeda do pagador escolhida. Nunca presuma que USD equivale a USDT nem converta o valor da transferência em um número de ponto flutuante. No máximo 10 leituras de catálogo por fatura por minuto.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
tokenpathobrigatórioIdentificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura.
Respostas
200Catálogo fornecido pelo gateway, com disponibilidade atual e limites de transferência.
servicesarray<object>obrigatóriofetchedAtintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório502Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioSupport
Base de conhecimento pública e solicitações de suporte do usuário atual.
POST/api/support/ask
Resposta da base de conhecimento pública completa
Pergunta pública sem sessão ou CSRF. Uma Origin fornecida deve corresponder a APP_ORIGIN; agentes podem omiti-la. No modo IA, o servidor envia todos os artigos publicados, fatos, catálogo de páginas e prontidão de recursos. Histórico e pageContext opcionais são contexto de pergunta não confiável. O modelo não pode acessar contas, dinheiro, solicitações privadas ou ferramentas. Com D1, o limite é de 12 perguntas por minuto por endereço com hash. IA requer D1, configuração de provedor válida e cota: 60 gerações por hora em todo o serviço por padrão. A prontidão de configuração não prova disponibilidade da API externa. Erros de provedor, esgotamento de cota ou saída inválida retornam pesquisa com aiUnavailable=true e HTTP 200. Sem configuração de geração, a pesquisa regular é retornada.
Nenhuma sessão de usuário necessária
Cabeçalhos e parâmetros
OriginheaderDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
Corpo JSON
questionstringobrigatórioEspaços ao redor são removidos. Comprimento após remoção: 2–2.000 caracteres. Caracteres de controle exceto tabs e quebras de linha são proibidos.
localeru | en | es | de | fr | pt | tr | kkIdioma da resposta. Se omitido, preferências Accept-Language suportadas são usadas; caso contrário, inglês. A documentação está disponível em todos os idiomas de interface suportados.
historyarray<oneOf>Até as três últimas duplas de pergunta e resposta. Opcional. Contexto não confiável, não mensagens de papel de sistema do provedor.
pageContextstringRótulo curto de seção após remoção, 1–80 caracteres. Permite letras, dígitos, espaços e ·.,—–-:(). Quebras de linha, URLs, parâmetros de consulta e HTML são proibidos. Não inclua tokens ou segredos.
Respostas
200Uma resposta ou documentação correspondente com links de artigos validados.
Variante 1
mode"search"obrigatórioanswerstringobrigatóriosourcesarray<object>obrigatórioknowledgeVersionstring | nullobrigatórioneedsHumanbooleanobrigatórioaiUnavailabletrueVariante 2
mode"ai"obrigatórioanswerstringobrigatórioSomente texto simples; URLs e HTML são rejeitados. Links são retornados apenas em fontes.
sourcesarray<object>obrigatórioknowledgeVersionstringobrigatórioneedsHumanbooleanobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/support/tickets
As 30 solicitações de suporte próprias mais recentes
A autorização segue as regras do endpoint
Respostas
200Mais recentes primeiro por createdAt; retorna os 30 registros mais recentes.
ticketsarray<object>obrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/support/tickets
Salvar uma solicitação de suporte
Até seis solicitações por usuário por hora, compartilhadas pelo site e pelo bot. Salvar cria um registro de conta. Mantenha a referência dele para perguntar sobre o status.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Corpo JSON
subjectstringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
messagestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 5–4.000 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
Respostas
201Solicitação de suporte salva.
ticketobjectobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/support/tickets/{id}
Ler uma solicitação de suporte própria
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioIdentificador de uma solicitação de suporte própria.
Respostas
200A solicitação de outro usuário e uma solicitação ausente retornam 404.
ticketobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPATCH/api/support/tickets/{id}
Fechar uma solicitação de suporte própria
A única alteração permitida é status=closed. Esta API não reabre solicitações, edita mensagens nem envia respostas de operador.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioIdentificador de uma solicitação de suporte própria.
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Corpo JSON
status"closed"obrigatórioRespostas
200Solicitação de suporte fechada.
closedtrueobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioNotifications
Centro de eventos da conta, estado de leitura do site e status de entrega independente via Telegram.
GET/api/notifications
Uma página de notificações próprias
Até 30 registros, ordenados por createdAt DESC e depois id DESC. A listagem não altera readAt nem aciona a entrega. unreadCount é a contagem total de não lidas do usuário atual em todas as páginas. Campos do proprietário, ID do Telegram e segredos são excluídos.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
unreadquery1 seleciona apenas não lidas; 0 ou um valor omitido seleciona todos os eventos.
cursorquerynextCursor da resposta anterior. Passe inalterado via URLSearchParams; formato createdAt:id, com createdAt como um inteiro seguro em milissegundos.
Respostas
200Eventos com estados de leitura e entrega independentes.
notificationsarray<object>obrigatóriounreadCountintegerobrigatórionextCursorstring | nullobrigatórioCursor da próxima página; null se não houver mais registros.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPATCH/api/notifications/read
Marcar notificações próprias como lidas
Aceita ids ou all:true juntamente com before. before é o momento do último evento observado e não pode exceder o tempo do servidor. Eventos mais recentes permanecem não lidos. A solicitação é idempotente: valores readAt existentes não mudam. IDs de outros usuários e IDs ausentes não são modificados nem divulgados. O status do Telegram e sentAt permanecem inalterados.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Corpo JSON
Variante 1
idsarray<string>obrigatórioDuplicatas são permitidas e contadas uma vez.
Variante 2
alltrueobrigatóriobeforeintegerobrigatóriocreatedAt do último evento exibido. O servidor também exige before <= Date.now().
Respostas
200O número de eventos recém-lidos, o tempo de operação e a contagem atual de não lidas.
updatedintegerobrigatórioreadAtintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
unreadCountintegerobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/notifications/test
Enviar uma notificação de teste para o Telegram da conta
Coloca uma mensagem na fila e tenta a entrega. No máximo três por usuário por hora. O teste não é uma notificação de pagamento e não altera um saldo. HTTP 202 não confirma a entrega; verifique a lista de notificações.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Corpo JSON
Respostas
202Resultado da fila.
queuedbooleanobrigatórioidstring | null400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioTelegram
Webhook do bot; não é um webhook de pagamento.
POST/api/telegram/webhook
Receber um evento da API do Bot do Telegram
Requer apenas o cabeçalho secreto do Telegram, sem sessão, CSRF ou Origin. Campos adicionais de Update são permitidos. Trata message e callback_query; ações pessoais exigem o chat privado do remetente verificado. Outros updates são ignorados. update_id é deduplicado; um update em andamento retorna 503 para nova tentativa. Este não é um webhook de provedor de pagamento.
A autorização segue as regras do endpoint
Corpo JSON
update_idintegerobrigatóriomessageobjectMensagem do Telegram: o manipulador usa message_id, text, from e chat.
callback_queryobjectTelegram CallbackQuery: o manipulador usa id, from, data e message.chat.
Respostas
200Processado, ignorado ou já tratado.
oktrueobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório502Solicitação do Telegram falhou.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioRotas de dinheiro não suportadas
Rotas legadas de dinheiro não suportadas e execução de pagamentos. O fluxo público de checkout tem seus próprios endpoints documentados.
POST/api/payments
Operação financeira indisponível
Retorna 503 GATEWAY_NOT_CONNECTED. Operações financeiras estão indisponíveis. O corpo não é processado e nenhuma solicitação ao gateway é feita.
Nenhuma sessão de usuário necessária
Respostas
503Operações financeiras estão indisponíveis.
errorobjectobrigatórioPOST/api/payouts
Operação financeira indisponível
Retorna 503 GATEWAY_NOT_CONNECTED. Operações financeiras estão indisponíveis. O corpo não é processado e nenhuma solicitação ao gateway é feita.
Nenhuma sessão de usuário necessária
Respostas
503Operações financeiras estão indisponíveis.
errorobjectobrigatórioMerchant API
Faturas servidor-a-servidor com escopo e histórico de eventos imutável.
GET/api/v1/payments
Listar links de pagamento próprios
Ordenados por createdAt DESC, id DESC. Links públicos funcionam em dispositivos; listar requer uma conta.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
limitquerycursorquerynextCursor da resposta anterior. O serviço usa JSON em base64 [createdAt,id]; passe inalterado via URLSearchParams.
Respostas
200Uma página de links de pagamento próprios.
linksarray<object>obrigatórionextCursorstring | nullobrigatórioCursor opaco para a próxima página. Passe como um parâmetro de consulta codificado em URL; null marca o fim.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/v1/payments
Criar uma fatura com termos imutáveis
Criar uma fatura imutável e receber imediatamente checkoutUrl; isso não cobra o comprador. USD: cartão/Alipay; RUB: SBP; USDT: cripto. USD cripto permanece aceito para compatibilidade, mas não pode ser pago sem uma fatura USDT. As participações do cliente na taxa e no imposto são inteiros independentes de 0 a 100; atualmente, cartão/Alipay ao vivo suporta imposto cliente=100 e taxa cliente=0. O total do cliente nunca é alterado silenciosamente. A aplicação mais recente do site deve ser aprovada antes de uma nova cobrança ao vivo. A criação da fatura e seu evento de comerciante são confirmados atomicamente.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
Idempotency-KeyheaderobrigatórioUma chave por solicitação lógica. Uma repetição com entrada canônica idêntica retorna o registro original; entrada diferente com a mesma chave retorna 409.
Corpo JSON
Moeda USD
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"USD"obrigatóriomethodsarray<card | alipay | crypto>obrigatórioO novo checkout em USD suporta cartão e Alipay. Faturas cripto em USD são aceitas apenas por compatibilidade e retornam crypto_requires_usdt no checkout ao vivo; use USDT para cripto.
vatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Moeda RUB
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"RUB"obrigatóriomethodsarray<"sbp">obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Moeda USDT
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"USDT"obrigatóriomethodsarray<"crypto">obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Variante 4
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currencyUSD | RUB | USDTobrigatórioUnidade de entrada. RUB é convertido para USD à taxa de referência salva; USDT usa a regra explícita de fatura 1:1. A moeda base de fatura salva é USD.
methodsarray<card | alipay | sbp | crypto>obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"universal"obrigatórioRespostas
200Repetição idempotente; replayed=true.
linkobjectobrigatórioreplayedbooleanobrigatóriocheckoutUrlstringobrigatórioO link de pagamento está disponível imediatamente; nenhuma sondagem é necessária.
201Fatura criada; replayed=false.
linkobjectobrigatórioreplayedbooleanobrigatóriocheckoutUrlstringobrigatórioO link de pagamento está disponível imediatamente; nenhuma sondagem é necessária.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/v1/payments/{id}
Link próprio e cálculo salvo
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioIdentificador de link próprio, não o token público.
Respostas
200O ID de outro usuário e um ID ausente retornam 404.
linkobjectobrigatóriocheckoutUrlstringIncluído nas respostas de atualização de status; o link aninhado sempre contém seu checkoutUrl.
401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPATCH/api/v1/payments/{id}
Pausar, retomar ou cancelar um link
Altera apenas o status. A atualização e o evento imutável de fatura updated são confirmados atomicamente. Alterações concorrentes usam uma verificação de versão; atualize e tente novamente em LINK_CHANGED. cancelled é terminal, a expiração nunca é estendida, e preço, métodos, participações de custo e descrição permanecem congelados. Repetir o status salvo retorna a fatura atual.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioIdentificador de link próprio, não o token público.
Corpo JSON
statusactive | paused | cancelledobrigatórioRespostas
200Estado atual do link próprio.
linkobjectobrigatóriocheckoutUrlstringIncluído nas respostas de atualização de status; o link aninhado sempre contém seu checkoutUrl.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/v1/payment-links
Listar links de pagamento próprios
Ordenados por createdAt DESC, id DESC. Links públicos funcionam em dispositivos; listar requer uma conta.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
limitquerycursorquerynextCursor da resposta anterior. O serviço usa JSON em base64 [createdAt,id]; passe inalterado via URLSearchParams.
Respostas
200Uma página de links de pagamento próprios.
linksarray<object>obrigatórionextCursorstring | nullobrigatórioCursor opaco para a próxima página. Passe como um parâmetro de consulta codificado em URL; null marca o fim.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/v1/payment-links
Criar uma fatura com termos imutáveis
Criar uma fatura imutável e receber imediatamente checkoutUrl; isso não cobra o comprador. USD: cartão/Alipay; RUB: SBP; USDT: cripto. USD cripto permanece aceito para compatibilidade, mas não pode ser pago sem uma fatura USDT. As participações do cliente na taxa e no imposto são inteiros independentes de 0 a 100; atualmente, cartão/Alipay ao vivo suporta imposto cliente=100 e taxa cliente=0. O total do cliente nunca é alterado silenciosamente. A aplicação mais recente do site deve ser aprovada antes de uma nova cobrança ao vivo. A criação da fatura e seu evento de comerciante são confirmados atomicamente.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
Idempotency-KeyheaderobrigatórioUma chave por solicitação lógica. Uma repetição com entrada canônica idêntica retorna o registro original; entrada diferente com a mesma chave retorna 409.
Corpo JSON
Moeda USD
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"USD"obrigatóriomethodsarray<card | alipay | crypto>obrigatórioO novo checkout em USD suporta cartão e Alipay. Faturas cripto em USD são aceitas apenas por compatibilidade e retornam crypto_requires_usdt no checkout ao vivo; use USDT para cripto.
vatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Moeda RUB
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"RUB"obrigatóriomethodsarray<"sbp">obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Moeda USDT
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currency"USDT"obrigatóriomethodsarray<"crypto">obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"native"Preço legado específico por moeda. Omita para compatibilidade com integrações existentes.
Variante 4
titlestringobrigatórioEspaços ao redor são removidos. Comprimento após o corte: 1–120 caracteres. Caracteres de controle, exceto tabulações e quebras de linha, são proibidos.
descriptionstringOpcional; uma string vazia é permitida. Até 500 caracteres após o trim.
amountMinorintegerobrigatórioLimite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado.
vatPayercustomer | merchantQuando omitido, a regra atual da loja é salva.
expiresAtintegerUm horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura.
currencyUSD | RUB | USDTobrigatórioUnidade de entrada. RUB é convertido para USD à taxa de referência salva; USDT usa a regra explícita de fatura 1:1. A moeda base de fatura salva é USD.
methodsarray<card | alipay | sbp | crypto>obrigatóriovatCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo. Padrão: a preferência legada de IVA da loja.
feeCustomerPercentintegerCota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.
orderIdstringReferência do pedido visível ao comprador.
metadataobjectMetadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público.
pricingMode"universal"obrigatórioRespostas
200Repetição idempotente; replayed=true.
linkobjectobrigatórioreplayedbooleanobrigatóriocheckoutUrlstringobrigatórioO link de pagamento está disponível imediatamente; nenhuma sondagem é necessária.
201Fatura criada; replayed=false.
linkobjectobrigatórioreplayedbooleanobrigatóriocheckoutUrlstringobrigatórioO link de pagamento está disponível imediatamente; nenhuma sondagem é necessária.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/v1/payment-links/{id}
Link próprio e cálculo salvo
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioIdentificador de link próprio, não o token público.
Respostas
200O ID de outro usuário e um ID ausente retornam 404.
linkobjectobrigatóriocheckoutUrlstringIncluído nas respostas de atualização de status; o link aninhado sempre contém seu checkoutUrl.
401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPATCH/api/v1/payment-links/{id}
Pausar, retomar ou cancelar um link
Altera apenas o status. A atualização e o evento imutável de fatura updated são confirmados atomicamente. Alterações concorrentes usam uma verificação de versão; atualize e tente novamente em LINK_CHANGED. cancelled é terminal, a expiração nunca é estendida, e preço, métodos, participações de custo e descrição permanecem congelados. Repetir o status salvo retorna a fatura atual.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioIdentificador de link próprio, não o token público.
Corpo JSON
statusactive | paused | cancelledobrigatórioRespostas
200Estado atual do link próprio.
linkobjectobrigatóriocheckoutUrlstringIncluído nas respostas de atualização de status; o link aninhado sempre contém seu checkoutUrl.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/api-keys
Listar metadados das próprias chaves
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Segredos e hashes de segredos são omitidos.
keysarray<object>obrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/api-keys
Criar uma chave com escopo; revelar seu segredo uma vez
Máximo de 10 chaves ativas. No máximo 5 criações/hora/usuário. As chaves expiram, podem ser revogadas e são limitadas a 90 solicitações de API/minuto/chave.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
namestringobrigatórioscopesarray<invoices:read | invoices:write | events:read>expiresInDaysintegerRespostas
201Armazene o segredo com segurança no seu servidor.
keyobjectobrigatóriosecretstringobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioDELETE/api/api-keys/{id}
Revogar a própria chave
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Usos futuros da chave são rejeitados.
revokedtrueobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/events
Ler o histórico imutável de eventos próprios
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
beforequeryLimite de timestamp exclusivo legado. Não pode ser combinado com cursor. Use nextCursor para paginação sem perdas.
cursorquerynextCursor opaco retornado pela página anterior. Codifica [createdAt,id] e preserva eventos que compartilham o mesmo timestamp.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Mais recentes primeiro; até 50 eventos. Siga nextCursor até null.
eventsarray<object>obrigatórionextCursorstring | nullobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/v1/events
Ler o histórico imutável de eventos próprios
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
beforequeryLimite de timestamp exclusivo legado. Não pode ser combinado com cursor. Use nextCursor para paginação sem perdas.
cursorquerynextCursor opaco retornado pela página anterior. Codifica [createdAt,id] e preserva eventos que compartilham o mesmo timestamp.
Respostas
200Mais recentes primeiro; até 50 eventos. Siga nextCursor até null.
eventsarray<object>obrigatórionextCursorstring | nullobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioWebhooks
Endpoints HTTPS verificados, eventos assinados, tentativas de entrega e repetições.
GET/api/webhooks
Listar endpoints e as últimas 30 entregas
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Nenhum segredo de assinatura é retornado.
endpointsarray<object>obrigatóriodeliveriesarray<object>obrigatórioavailablebooleanobrigatórioeventTypesarray<invoice.created | invoice.updated | payment.succeeded | payment.failed | payment.refunded | payment.partially_refunded | payment.disputed | payment.review_required>obrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/webhooks
Registrar um destino HTTPS público
Até 5 endpoints e 6 criações/hora/usuário. Apenas domínios HTTPS públicos; sem credenciais, literais de IP ou portas personalizadas. Um endpoint recém-criado não recebe entregas ao vivo até que seu desafio tenha sucesso.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
urlstringobrigatóriodescriptionstringeventsarray<invoice.created | invoice.updated | payment.succeeded | payment.failed | payment.refunded | payment.partially_refunded | payment.disputed | payment.review_required>Respostas
201Salve o segredo de assinatura de uso único.
endpointobjectobrigatóriosecretstringobrigatórioExibido apenas na criação/rotação. Armazenado criptografado no lado do servidor.
400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/webhooks/{id}
Listar endpoints e as últimas 30 entregas
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioX-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Nenhum segredo de assinatura é retornado.
endpointsarray<object>obrigatóriodeliveriesarray<object>obrigatórioavailablebooleanobrigatórioeventTypesarray<invoice.created | invoice.updated | payment.succeeded | payment.failed | payment.refunded | payment.partially_refunded | payment.disputed | payment.review_required>obrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPATCH/api/webhooks/{id}
Pausar ou retomar um endpoint verificado
Endpoints verificados pausados mantêm eventos elegíveis na fila; retomar processa entregas devidas.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
statusactive | pausedobrigatórioRespostas
200Status salvo.
updatedtrueobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioDELETE/api/webhooks/{id}
Remover endpoint e cancelar trabalhos não entregues
Cancela trabalhos pendentes, com falha e alugados. Uma solicitação já enviada pela rede não pode ser recuperada.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Endpoint removido.
deletedtrueobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/webhooks/{id}/verify
Enviar um desafio de verificação de endpoint assinado
Máximo de 5 tentativas de verificação/hora/usuário. Seu servidor deve validar Kevmi-Signature e retornar JSON 2xx {"challenge":"<data.challenge>"}. Tempo limite da solicitação: 8 segundos; limite de resposta: 8192 bytes. Redirecionamentos não são seguidos. A verificação ativa o endpoint.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
Respostas
200Verificado e ativo.
verifiedtrueobrigatórioendpointobjectobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório422O destino não pôde ser verificado.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/webhooks/{id}/rotate
Substituir o segredo de assinatura e exigir verificação novamente
Máximo de 3 rotações/hora/usuário. Atualize seu servidor e verifique o endpoint novamente. Uma solicitação já em trânsito ainda pode carregar a assinatura anterior.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
Respostas
200Novo segredo exibido uma vez.
secretstringobrigatórioExibido apenas na criação/rotação. Armazenado criptografado no lado do servidor.
requiresVerificationtrueobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/webhooks/{id}/deliveries/{deliveryId}/retry
Tentar novamente uma entrega com falha para um endpoint ativo
Mantém o ID do evento e a carga útil; gera um timestamp e uma assinatura novos. Cada ciclo automático de entrega faz no máximo 6 tentativas, incluindo aluguéis expirados, com atrasos de 1m, 5m, 30m, 2h e 12h. A entrega é pelo menos uma vez; deduplique IDs de eventos no seu servidor.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatóriodeliveryIdpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
Respostas
202Nova tentativa agendada.
queuedtrueobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioApplications
Aplicativos de site autenticados e rastreamento individual.
GET/api/applications
Listar até 30 aplicações próprias
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
X-Kevmi-LocaleheaderURL de rastreamento e idioma da mensagem do sistema. Sem um valor suportado, o referenciador de mesma origem e o idioma do navegador são considerados; o padrão é inglês.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Mais recentes primeiro.
applicationsarray<object>obrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/applications
Enviar informações do site e receber uma URL de rastreamento
Requer login confirmado no Telegram. Até 5 novos envios/dia/usuário. Repetição idempotente retorna 200. O servidor avança estágios reais persistidos; resultados automáticos indisponíveis ou arriscados exigem revisão humana. A aprovação não configura o gateway de pagamento. Propriedade e estado não podem ser fornecidos pelo solicitante.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
OriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Idempotency-KeyheaderobrigatórioUma chave por solicitação lógica. Uma repetição com entrada canônica idêntica retorna o registro original; entrada diferente com a mesma chave retorna 409.
X-Kevmi-LocaleheaderURL de rastreamento e idioma da mensagem do sistema. Sem um valor suportado, o referenciador de mesma origem e o idioma do navegador são considerados; o padrão é inglês.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
websiteUrlstringobrigatórioDomínio HTTPS público sem credenciais, parâmetros de consulta, literais de IP ou portas personalizadas. Um fragmento é removido durante a normalização.
businessNamestringobrigatóriobusinessTypedigital_goods | software | services | physical_goods | education | otherobrigatóriodescriptionstringobrigatóriocontactTelegramstringobrigatórioUm nome de usuário do Telegram de 5–32 caracteres que começa com uma letra, depois letras/dígitos/sublinhados. Prefixo opcional @ ou https://t.me/; espaços em branco ao redor são removidos. Armazenado como @username.
consenttrueobrigatórioRespostas
200Envio existente.
applicationobjectobrigatóriourlstringobrigatórioreplayedbooleanobrigatório202Aceito; o processamento continua no servidor.
applicationobjectobrigatóriourlstringobrigatórioreplayedbooleanobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/applications/{id}
Ler os próprios estágios de revisão e histórico de eventos
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioX-Kevmi-LocaleheaderURL de rastreamento e idioma da mensagem do sistema. Sem um valor suportado, o referenciador de mesma origem e o idioma do navegador são considerados; o padrão é inglês.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Respostas
200Projeção privada do solicitante. Evidências e saída do modelo não são expostas.
applicationobjectobrigatórioeventsarray<object>obrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/applications/{id}/resume
Retomar um estágio de fundo elegível
Não é possível pular a revisão ou aprovar um estágio. Uma concessão de servidor impede trabalho duplicado. Aplicações que precisam de revisão e finais permanecem inalteradas. No máximo 30 solicitações de retomada de processamento/minuto/usuário.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
X-Kevmi-LocaleheaderURL de rastreamento e idioma da mensagem do sistema. Sem um valor suportado, o referenciador de mesma origem e o idioma do navegador são considerados; o padrão é inglês.
X-Kevmi-StoreheaderSelecione uma loja própria para uma sessão de navegador. Omita para usar a primeira loja. Chaves de API ignoram este cabeçalho e sempre usam seu vínculo de loja imutável. O valor all é somente leitura e suportado apenas pelos endpoints de painel e lista de faturas.
Corpo JSON
Respostas
200Nenhum processamento necessário.
applicationobjectobrigatório202Processamento agendado.
applicationobjectobrigatórioscheduledtrueobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioModeration
Moderadores do Telegram na lista de permissões; toda decisão é verificada por versão.
GET/api/moderation/applications
Listar até 100 aplicações para moderação
Requer que a identidade autenticada do Telegram esteja em MODERATOR_TELEGRAM_IDS. Inclui todos os estados, ordenando needs_review primeiro, processing segundo, depois estados finais; atualizações mais recentes primeiro dentro de um grupo.
A autorização segue as regras do endpoint
Respostas
200Fila de moderador.
applicationsarray<object>obrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGET/api/moderation/applications/{id}
Ler evidências de revisão e histórico de estágios
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioRespostas
200Evidências privadas de moderador.
applicationobjectobrigatórioeventsarray<object>obrigatórioevidenceobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioPOST/api/moderation/applications/{id}/decision
Aprovar o estágio de revisão atual ou recusar com um motivo público
Requer um moderador configurado; no máximo 30 decisões/minuto/usuário. expectedVersion é comparado atomicamente. Somente o estágio atual needs_review pode ser aprovado; aplicações finais não podem ser reabertas silenciosamente. Uma rejeição exige um motivo público editável. A decisão, o histórico de estágios e a notificação de candidato habilitada são salvos juntos.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
idpathobrigatórioOriginheaderobrigatórioDeve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.
X-CSRF-TokenheaderobrigatórioToken da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.
Corpo JSON
Variante 1
expectedVersionintegerobrigatórioaction"approve_step"obrigatórioreasonstringVariante 2
expectedVersionintegerobrigatórioaction"reject"obrigatórioreasonstringobrigatórioRespostas
200Decisão salva.
applicationobjectobrigatório400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401Nenhuma sessão válida; para um webhook, um segredo inválido.
errorobjectobrigatório403Falha na validação de Origin, CSRF ou vínculo com navegador.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.
errorobjectobrigatório429Limite de taxa excedido.
errorobjectobrigatório503Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.
errorobjectobrigatórioGateway events
Os eventos do gateway nativos da fonte são verificados e, em seguida, o pagamento autoritativo é lido por transporte de servidor autenticado. Webhooks voltados ao comerciante usam assinatura e fila de entrega separadas.
POST/api/gateway/webhook
Receber eventos de gateway nativos assinados
Nativo v3: forneça X-Gateway-Timestamp (segundos Unix), X-Gateway-Signature e X-Gateway-Event-Id correspondente. A tolerância máxima de horário é de 300 segundos. Após a verificação da assinatura, a Kevmi busca o pagamento pela API de gateway autenticada, verifica o pedido salvo, a moeda/valor exatos, o método e o estado confirmado pelo provedor, e então armazena atomicamente o recibo e o evento de caixa de saída do comerciante. Texto de webhook e observações de navegador por si só nunca confirmam um pagamento. IDs repetidos são deduplicados; um corpo alterado para um ID existente é rejeitado. Eventos atrasados usam estado autoritativo atual. Reembolsos parciais, reembolsos totais, disputas e estados de revisão são suportados. Pedidos não vinculados são reconhecidos e ignorados. Eventos normalizados legados usando Kevmi-Signature permanecem suportados separadamente; apenas suas transições succeeded/failed/full-refunded se aplicam.
A autorização segue as regras do endpoint
Cabeçalhos e parâmetros
X-Gateway-TimestampheaderObrigatório para eventos nativos v3.
X-Gateway-Event-IdheaderObrigatório para nativo v3; deve corresponder a body.id.
Corpo JSON
Variante 1
idstringobrigatórioapi_version"3"obrigatóriomode"live"obrigatóriotypestringobrigatóriodataobjectobrigatórioVariante 2
eventIdstringobrigatóriopaymentIdstringobrigatórioinvoiceIdstringobrigatóriostatussucceeded | failed | refundedobrigatórioamountMinorintegerobrigatórioValor inteiro em unidades monetárias menores.
currencyUSD | RUB | USDTobrigatórioUnidades de fatura: centavos de USD, copeques de RUB ou centésimos de USDT. Sem conversão automática de moeda.
methodcard | alipay | sbp | cryptoobrigatóriooccurredAtintegerobrigatórioCarimbo de tempo Unix em milissegundos, UTC.
Respostas
200Recebido, deduplicado ou ignorado com segurança.
receivedtrueobrigatórioreplayedbooleanignoredbooleanappliedboolean400JSON inválido, campo desconhecido ou valor inválido.
errorobjectobrigatório401A assinatura do gateway está ausente, inválida ou fora da janela de tempo aceita.
errorobjectobrigatório404O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.
errorobjectobrigatório409Um ID de evento foi reutilizado com conteúdo alterado ou um ID de pagamento conflita com o vínculo de fatura salvo.
errorobjectobrigatório413Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.
errorobjectobrigatório415Content-Type: application/json é obrigatório.
errorobjectobrigatório429O gateway está ocupado; tente novamente a entrega do webhook com o mesmo ID de evento.
errorobjectobrigatório502Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.
errorobjectobrigatório503A configuração do gateway ou o segredo de assinatura está ausente.
errorobjectobrigatório