{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Kevmi — API de servidor", "version": "2026-10-23.12", "description": "API Kevmi: entrada via Telegram, sessões, faturas de comerciante, checkout de comprador criptografado, suporte, notificações, aplicativos e entrega de webhook. Somente pagamentos diretos únicos. As respostas JSON usam no-store. Os registros de data/hora são em Unix milliseconds UTC, salvo indicação contrária. O checkout ao vivo usa um gateway externo configurado; os campos de cartão e código bancário são criptografados no navegador e descriptografados apenas pelo gateway. Novas cobranças exigem que o aplicativo de site do comerciante mais recente seja aprovado. Criar uma fatura não cobra o comprador.", "x-updated-at": "2026-10-23" }, "servers": [ { "url": "https://kevmi.one", "description": "A origem pública do projeto; a plataforma de hospedagem pode aplicar controles de acesso adicionais." } ], "externalDocs": { "description": "Documentação pública do produto", "url": "https://kevmi.one/docs" }, "tags": [ { "name": "Service", "description": "Status público do serviço." }, { "name": "Auth", "description": "Registro e entrada compartilham o fluxo verificado do Telegram." }, { "name": "Account", "description": "Configurações apenas para o usuário atual." }, { "name": "Payment links", "description": "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." }, { "name": "Checkout", "description": "Ler uma fatura sem conta. A disponibilidade de pagamento é verificada separadamente." }, { "name": "Support", "description": "Base de conhecimento pública e solicitações de suporte do usuário atual." }, { "name": "Notifications", "description": "Centro de eventos da conta, estado de leitura do site e status de entrega independente via Telegram." }, { "name": "Telegram", "description": "Webhook do bot; não é um webhook de pagamento." }, { "name": "Disabled payments", "description": "Rotas legadas de dinheiro não suportadas e execução de pagamentos. O fluxo público de checkout tem seus próprios endpoints documentados." }, { "name": "Merchant API", "description": "Faturas servidor-a-servidor com escopo e histórico de eventos imutável." }, { "name": "Webhooks", "description": "Endpoints HTTPS verificados, eventos assinados, tentativas de entrega e repetições." }, { "name": "Applications", "description": "Aplicativos de site autenticados e rastreamento individual." }, { "name": "Moderation", "description": "Moderadores do Telegram na lista de permissões; toda decisão é verificada por versão." }, { "name": "Gateway events", "description": "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." } ], "security": [], "x-disabled-route-prefixes": [ "/api/payments", "/api/payouts", "/api/gateway", "/api/linzapay" ], "x-disabled-route-behavior": "Legacy unscoped direct-money routes and payout execution remain disabled. Authenticated /api/v1/payments creates invoices; /api/checkout/{token} exposes the separate buyer checkout flow. POST /api/gateway/webhook accepts signed gateway events.", "paths": { "/api/config": { "get": { "tags": [ "Service" ], "operationId": "getConfig", "summary": "Prontidão atual de integração", "responses": { "200": { "description": "Configuração sem segredos.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Config" } } } }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/health": { "get": { "tags": [ "Service" ], "operationId": "getHealth", "summary": "Status da API e da tabela D1", "description": "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.", "responses": { "200": { "description": "O armazenamento está pronto ou not_configured.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "D1 está indisponível ou ocorreu um erro de serviço inesperado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Health" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/api/auth/me": { "get": { "tags": [ "Auth" ], "operationId": "getCurrentSession", "summary": "Sessão atual e CSRF", "security": [ {}, { "cookieSession": [] } ], "responses": { "200": { "description": "authenticated=false quando não existe uma sessão válida.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Anonymous" }, { "$ref": "#/components/schemas/CurrentSession" } ] } } } }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/telegram/start": { "post": { "tags": [ "Auth" ], "operationId": "startTelegramLogin", "summary": "Iniciar entrada ou registro", "description": "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.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "201": { "description": "Solicitação de entrada criada; o cookie de prova a vincula ao navegador original.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Seguro; HttpOnly; SameSite=Lax; Path=/. JavaScript não pode acessar o valor da sessão. Concluir a entrada também limpa o cookie de prova do navegador." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginChallenge" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/telegram/complete": { "post": { "tags": [ "Auth" ], "operationId": "completeTelegramLogin", "summary": "Concluir uma entrada verificada", "description": "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.", "security": [ { "browserProof": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "challengeId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Conta criada ou atualizada e sessão emitida.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Seguro; HttpOnly; SameSite=Lax; Path=/. JavaScript não pode acessar o valor da sessão. Concluir a entrada também limpa o cookie de prova do navegador." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompletedLogin" } } } }, "202": { "description": "Aguardando confirmação no Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "pending" } }, "required": [ "status" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "A solicitação de entrada de cinco minutos expirou.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_EXPIRED" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/auth/logout": { "post": { "tags": [ "Auth" ], "operationId": "logoutCurrentSession", "summary": "Encerrar a sessão atual", "description": "Nenhum corpo é necessário ou lido. O comando /logout do bot encerra separadamente todas as sessões da conta.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "responses": { "200": { "description": "Sessão removida e cookie limpo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Set-Cookie": { "schema": { "type": "string" }, "description": "Seguro; HttpOnly; SameSite=Lax; Path=/. JavaScript não pode acessar o valor da sessão. Concluir a entrada também limpa o cookie de prova do navegador." } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "loggedOut": { "type": "boolean", "const": true } }, "required": [ "loggedOut" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/account/settings": { "get": { "tags": [ "Account" ], "operationId": "getAccountSettings", "summary": "Configurações do usuário atual", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Campos públicos do perfil do usuário atual.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ] }, "patch": { "tags": [ "Account" ], "operationId": "updateAccountSettings", "summary": "Alterar o nome da loja, o pagador de IVA ou notificações", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettingsPatch" } } } }, "responses": { "200": { "description": "Perfil atualizado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/ask": { "post": { "tags": [ "Support" ], "operationId": "askDocumentation", "summary": "Resposta da base de conhecimento pública completa", "description": "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.", "parameters": [ { "name": "Origin", "in": "header", "required": false, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON de até 65.536 bytes. Campos desconhecidos são rejeitados. Os comprimentos de texto são verificados após o corte de espaços.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportQuestion" } } } }, "responses": { "200": { "description": "Uma resposta ou documentação correspondente com links de artigos validados.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SupportAnswer" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/tickets": { "get": { "tags": [ "Support" ], "operationId": "listOwnTickets", "summary": "As 30 solicitações de suporte próprias mais recentes", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Mais recentes primeiro por createdAt; retorna os 30 registros mais recentes.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "tickets": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Ticket" } } }, "required": [ "tickets" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Support" ], "operationId": "createOwnTicket", "summary": "Salvar uma solicitação de suporte", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Espaç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." }, "message": { "type": "string", "minLength": 5, "x-trimmedMaxLength": 4000, "x-trimmedMinLength": 5, "description": "Espaç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." } }, "required": [ "subject", "message" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Solicitação de suporte salva.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/support/tickets/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^tkt_[a-f0-9-]{36}$" }, "description": "Identificador de uma solicitação de suporte própria." } ], "get": { "tags": [ "Support" ], "operationId": "getOwnTicket", "summary": "Ler uma solicitação de suporte própria", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "A solicitação de outro usuário e uma solicitação ausente retornam 404.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TicketResponse" } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "patch": { "tags": [ "Support" ], "operationId": "closeOwnTicket", "summary": "Fechar uma solicitação de suporte própria", "description": "A única alteração permitida é status=closed. Esta API não reabre solicitações, edita mensagens nem envia respostas de operador.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "closed" } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Solicitação de suporte fechada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "closed": { "type": "boolean", "const": true } }, "required": [ "closed" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications": { "get": { "tags": [ "Notifications" ], "operationId": "listOwnNotifications", "summary": "Uma página de notificações próprias", "description": "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.", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "unread", "in": "query", "description": "1 seleciona apenas não lidas; 0 ou um valor omitido seleciona todos os eventos.", "schema": { "type": "string", "enum": [ "0", "1" ], "default": "0" } }, { "name": "cursor", "in": "query", "description": "nextCursor da resposta anterior. Passe inalterado via URLSearchParams; formato createdAt:id, com createdAt como um inteiro seguro em milissegundos.", "schema": { "type": "string", "pattern": "^\\d{1,16}:ntf_[A-Za-z0-9-]{1,80}$" } } ], "responses": { "200": { "description": "Eventos com estados de leitura e entrega independentes.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationsPage" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications/read": { "patch": { "tags": [ "Notifications" ], "operationId": "markOwnNotificationsRead", "summary": "Marcar notificações próprias como lidas", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadNotifications" } } } }, "responses": { "200": { "description": "O número de eventos recém-lidos, o tempo de operação e a contagem atual de não lidas.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadNotificationsResult" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/notifications/test": { "post": { "tags": [ "Notifications" ], "operationId": "testOwnNotification", "summary": "Enviar uma notificação de teste para o Telegram da conta", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "202": { "description": "Resultado da fila.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "type": "boolean" }, "id": { "type": [ "string", "null" ] } }, "required": [ "queued" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/telegram/webhook": { "post": { "tags": [ "Telegram" ], "operationId": "receiveTelegramUpdate", "summary": "Receber um evento da API do Bot do Telegram", "description": "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.", "security": [ { "telegramWebhookSecret": [] } ], "requestBody": { "required": true, "description": "Update do Telegram, máximo de 65.536 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramUpdate" } } } }, "responses": { "200": { "description": "Processado, ignorado ou já tratado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Solicitação do Telegram falhou.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TELEGRAM_UNAVAILABLE", "TELEGRAM_INVALID_RESPONSE", "TELEGRAM_RATE_LIMITED", "TELEGRAM_DELIVERY_FAILED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/payments": { "post": { "tags": [ "Disabled payments" ], "operationId": "paymentsUnavailable", "summary": "Operação financeira indisponível", "description": "Retorna 503 GATEWAY_NOT_CONNECTED. Operações financeiras estão indisponíveis. O corpo não é processado e nenhuma solicitação ao gateway é feita.", "security": [], "responses": { "503": { "description": "Operações financeiras estão indisponíveis.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "GATEWAY_NOT_CONNECTED" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/payouts": { "post": { "tags": [ "Disabled payments" ], "operationId": "payoutsUnavailable", "summary": "Operação financeira indisponível", "description": "Retorna 503 GATEWAY_NOT_CONNECTED. Operações financeiras estão indisponíveis. O corpo não é processado e nenhuma solicitação ao gateway é feita.", "security": [], "responses": { "503": { "description": "Operações financeiras estão indisponíveis.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "const": "GATEWAY_NOT_CONNECTED" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/openapi.json": { "get": { "tags": [ "Service" ], "operationId": "getOpenApi", "summary": "Contrato público legível por máquina", "description": "Somente leitura. Não contém segredos, sessões, registros de usuário nem contrato operacional com provedor de pagamento.", "responses": { "200": { "description": "Este documento OpenAPI 3.1.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "public, max-age=300" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "openapi", "info", "paths" ], "additionalProperties": true } } } } } } }, "/api/payment-links": { "get": { "tags": [ "Payment links" ], "operationId": "listOwnPaymentLinks", "summary": "Listar links de pagamento próprios", "security": [ { "cookieSession": [] } ], "description": "Ordenados por createdAt DESC, id DESC. Links públicos funcionam em dispositivos; listar requer uma conta.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor da resposta anterior. O serviço usa JSON em base64 [createdAt,id]; passe inalterado via URLSearchParams." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "responses": { "200": { "description": "Uma página de links de pagamento próprios.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Payment links" ], "operationId": "createOwnPaymentLink", "summary": "Criar uma fatura com termos imutáveis", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Uma 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." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "description": "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.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Repetição idempotente; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Fatura criada; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/payment-links/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Identificador de link próprio, não o token público." } ], "get": { "tags": [ "Payment links" ], "operationId": "getOwnPaymentLink", "summary": "Link próprio e cálculo salvo", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "O ID de outro usuário e um ID ausente retornam 404.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ] }, "patch": { "tags": [ "Payment links" ], "operationId": "changePaymentLinkStatus", "summary": "Pausar, retomar ou cancelar um link", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "description": "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.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Estado atual do link próprio.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura." } ], "get": { "tags": [ "Checkout" ], "operationId": "getPublicCheckout", "summary": "Detalhes públicos da fatura para o cliente", "description": "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.", "parameters": [ { "name": "method", "in": "query", "schema": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "description": "Deve estar presente nos métodos salvos da fatura." } ], "responses": { "200": { "description": "Fatura pública e o pagamento existente, se enviado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "$ref": "#/components/schemas/CheckoutInvoice" }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] } }, "required": [ "invoice", "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/pay": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura." } ], "post": { "tags": [ "Checkout" ], "operationId": "startCheckoutPayment", "summary": "Iniciar ou recuperar o pagamento da fatura", "description": "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.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartCheckoutPayment" } } } }, "responses": { "200": { "description": "Operação existente recuperada; nenhum segundo pagamento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "202": { "description": "Operação enviada; a conclusão é assíncrona.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "A 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.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/v1/payments": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnPaymentLinksViaPayments", "summary": "Listar links de pagamento próprios", "security": [ { "merchantKey": [] } ], "description": "Ordenados por createdAt DESC, id DESC. Links públicos funcionam em dispositivos; listar requer uma conta.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor da resposta anterior. O serviço usa JSON em base64 [createdAt,id]; passe inalterado via URLSearchParams." } ], "responses": { "200": { "description": "Uma página de links de pagamento próprios.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:read" }, "post": { "tags": [ "Merchant API" ], "operationId": "createOwnPaymentLinkViaPayments", "summary": "Criar uma fatura com termos imutáveis", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Uma 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." } ], "description": "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.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Repetição idempotente; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Fatura criada; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payments/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Identificador de link próprio, não o token público." } ], "get": { "tags": [ "Merchant API" ], "operationId": "getOwnPaymentLinkViaPayments", "summary": "Link próprio e cálculo salvo", "security": [ { "merchantKey": [] } ], "responses": { "200": { "description": "O ID de outro usuário e um ID ausente retornam 404.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [], "x-required-scope": "invoices:read" }, "patch": { "tags": [ "Merchant API" ], "operationId": "changePaymentLinkStatusViaPayments", "summary": "Pausar, retomar ou cancelar um link", "security": [ { "merchantKey": [] } ], "parameters": [], "description": "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.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Estado atual do link próprio.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payment-links": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnPaymentLinksViaLinks", "summary": "Listar links de pagamento próprios", "security": [ { "merchantKey": [] } ], "description": "Ordenados por createdAt DESC, id DESC. Links públicos funcionam em dispositivos; listar requer uma conta.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor da resposta anterior. O serviço usa JSON em base64 [createdAt,id]; passe inalterado via URLSearchParams." } ], "responses": { "200": { "description": "Uma página de links de pagamento próprios.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinksPage" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:read" }, "post": { "tags": [ "Merchant API" ], "operationId": "createOwnPaymentLinkViaLinks", "summary": "Criar uma fatura com termos imutáveis", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Uma 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." } ], "description": "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.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLink" } } } }, "responses": { "200": { "description": "Repetição idempotente; replayed=true.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "201": { "description": "Fatura criada; replayed=false.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/v1/payment-links/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "description": "Identificador de link próprio, não o token público." } ], "get": { "tags": [ "Merchant API" ], "operationId": "getOwnPaymentLinkViaLinks", "summary": "Link próprio e cálculo salvo", "security": [ { "merchantKey": [] } ], "responses": { "200": { "description": "O ID de outro usuário e um ID ausente retornam 404.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [], "x-required-scope": "invoices:read" }, "patch": { "tags": [ "Merchant API" ], "operationId": "changePaymentLinkStatusViaLinks", "summary": "Pausar, retomar ou cancelar um link", "security": [ { "merchantKey": [] } ], "parameters": [], "description": "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.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused", "cancelled" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Estado atual do link próprio.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkResponse" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "invoices:write" } }, "/api/api-keys": { "get": { "tags": [ "Merchant API" ], "operationId": "listMerchantKeys", "summary": "Listar metadados das próprias chaves", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Segredos e hashes de segredos são omitidos.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantKey" } } }, "required": [ "keys" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ] }, "post": { "tags": [ "Merchant API" ], "operationId": "createMerchantKey", "summary": "Criar uma chave com escopo; revelar seu segredo uma vez", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "description": "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.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 60 }, "scopes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoices:read", "invoices:write", "events:read" ] } }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Armazene o segredo com segurança no seu servidor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/MerchantKey" }, "secret": { "type": "string", "pattern": "^kv_live_[A-Za-z0-9_-]{43}$" } }, "required": [ "key", "secret" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/api-keys/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^key_[0-9a-f-]{36}$" } } ], "delete": { "tags": [ "Merchant API" ], "operationId": "revokeMerchantKey", "summary": "Revogar a própria chave", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "responses": { "200": { "description": "Usos futuros da chave são rejeitados.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "const": true } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/events": { "get": { "tags": [ "Merchant API" ], "operationId": "listOwnEvents", "summary": "Ler o histórico imutável de eventos próprios", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "description": "Limite de timestamp exclusivo legado. Não pode ser combinado com cursor. Use nextCursor para paginação sem perdas." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor opaco retornado pela página anterior. Codifica [createdAt,id] e preserva eventos que compartilham o mesmo timestamp." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "responses": { "200": { "description": "Mais recentes primeiro; até 50 eventos. Siga nextCursor até null.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MerchantEvent" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "events", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/v1/events": { "get": { "tags": [ "Merchant API" ], "operationId": "listMerchantEventsWithKey", "summary": "Ler o histórico imutável de eventos próprios", "security": [ { "merchantKey": [] } ], "parameters": [ { "name": "before", "in": "query", "schema": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "description": "Limite de timestamp exclusivo legado. Não pode ser combinado com cursor. Use nextCursor para paginação sem perdas." }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor opaco retornado pela página anterior. Codifica [createdAt,id] e preserva eventos que compartilham o mesmo timestamp." } ], "responses": { "200": { "description": "Mais recentes primeiro; até 50 eventos. Siga nextCursor até null.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/MerchantEvent" } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "events", "nextCursor" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "x-required-scope": "events:read" } }, "/api/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "Listar endpoints e as últimas 30 entregas", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Nenhum segredo de assinatura é retornado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "available": { "type": "boolean" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "endpoints", "deliveries", "available", "eventTypes" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ] }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Registrar um destino HTTPS público", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "description": "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.", "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": "string", "maxLength": 120 }, "events": { "type": "array", "minItems": 1, "maxItems": 8, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "url" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Salve o segredo de assinatura de uso único.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$", "description": "Exibido apenas na criação/rotação. Armazenado criptografado no lado do servidor." } }, "required": [ "endpoint", "secret" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Listar endpoints e as últimas 30 entregas", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Nenhum segredo de assinatura é retornado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "available": { "type": "boolean" }, "eventTypes": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } } }, "required": [ "endpoints", "deliveries", "available", "eventTypes" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } }, "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ] }, "patch": { "tags": [ "Webhooks" ], "operationId": "setWebhookStatus", "summary": "Pausar ou retomar um endpoint verificado", "description": "Endpoints verificados pausados mantêm eventos elegíveis na fila; retomar processa entregas devidas.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } }, "required": [ "status" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Status salvo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "const": true } }, "required": [ "updated" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Remover endpoint e cancelar trabalhos não entregues", "description": "Cancela trabalhos pendentes, com falha e alugados. Uma solicitação já enviada pela rede não pode ser recuperada.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "responses": { "200": { "description": "Endpoint removido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "const": true } }, "required": [ "deleted" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/verify": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "verifyWebhookEndpoint", "summary": "Enviar um desafio de verificação de endpoint assinado", "description": "Máximo de 5 tentativas de verificação/hora/usuário. Seu servidor deve validar Kevmi-Signature e retornar JSON 2xx {\"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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Verificado e ativo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "verified": { "const": true }, "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "required": [ "verified", "endpoint" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "422": { "description": "O destino não pôde ser verificado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "WEBHOOK_UNREACHABLE", "WEBHOOK_VERIFICATION_FAILED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/rotate": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Substituir o segredo de assinatura e exigir verificação novamente", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Novo segredo exibido uma vez.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "pattern": "^whsec_[A-Za-z0-9_-]{43}$", "description": "Exibido apenas na criação/rotação. Armazenado criptografado no lado do servidor." }, "requiresVerification": { "const": true } }, "required": [ "secret", "requiresVerification" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/webhooks/{id}/deliveries/{deliveryId}/retry": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" } }, { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^del_[a-f0-9]{40}$" } } ], "post": { "tags": [ "Webhooks" ], "operationId": "retryWebhookDelivery", "summary": "Tentar novamente uma entrega com falha para um endpoint ativo", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "202": { "description": "Nova tentativa agendada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "queued": { "const": true } }, "required": [ "queued" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications": { "get": { "tags": [ "Applications" ], "operationId": "listOwnApplications", "summary": "Listar até 30 aplicações próprias", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "URL de 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." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "responses": { "200": { "description": "Mais recentes primeiro.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Application" } } }, "required": [ "applications" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Applications" ], "operationId": "submitWebsiteApplication", "summary": "Enviar informações do site e receber uma URL de rastreamento", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,100}$" }, "description": "Uma 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." }, { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "URL 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." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Domínio HTTPS público sem credenciais, parâmetros de consulta, literais de IP ou portas personalizadas. Um fragmento é removido durante a normalização." }, "businessName": { "type": "string", "minLength": 1, "maxLength": 100 }, "businessType": { "type": "string", "enum": [ "digital_goods", "software", "services", "physical_goods", "education", "other" ] }, "description": { "type": "string", "minLength": 40, "maxLength": 3000 }, "contactTelegram": { "type": "string", "description": "Um 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." }, "consent": { "type": "boolean", "const": true } }, "required": [ "websiteUrl", "businessName", "businessType", "description", "contactTelegram", "consent" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Envio existente.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "url": { "type": "string", "format": "uri" }, "replayed": { "type": "boolean" } }, "required": [ "application", "url", "replayed" ], "additionalProperties": false } } } }, "202": { "description": "Aceito; o processamento continua no servidor.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "url": { "type": "string", "format": "uri" }, "replayed": { "type": "boolean" } }, "required": [ "application", "url", "replayed" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "get": { "tags": [ "Applications" ], "operationId": "getOwnApplication", "summary": "Ler os próprios estágios de revisão e histórico de eventos", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "URL de 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." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "responses": { "200": { "description": "Projeção privada do solicitante. Evidências e saída do modelo não são expostas.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "events": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/ApplicationEvent" } } }, "required": [ "application", "events" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/applications/{id}/resume": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "post": { "tags": [ "Applications" ], "operationId": "resumeApplicationJob", "summary": "Retomar um estágio de fundo elegível", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "X-Kevmi-Locale", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ] }, "description": "URL de 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." }, { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "description": "Selecione 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." } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Nenhum processamento necessário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" } }, "required": [ "application" ], "additionalProperties": false } } } }, "202": { "description": "Processamento agendado.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "scheduled": { "type": "boolean", "const": true } }, "required": [ "application", "scheduled" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications": { "get": { "tags": [ "Moderation" ], "operationId": "listModerationApplications", "summary": "Listar até 100 aplicações para moderação", "description": "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.", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Fila de moderador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "applications": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Application" } } }, "required": [ "applications" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "get": { "tags": [ "Moderation" ], "operationId": "getModerationApplication", "summary": "Ler evidências de revisão e histórico de estágios", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "Evidências privadas de moderador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" }, "events": { "type": "array", "maxItems": 40, "items": { "$ref": "#/components/schemas/ApplicationEvent" } }, "evidence": { "type": "object", "additionalProperties": true } }, "required": [ "application", "events", "evidence" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/moderation/applications/{id}/decision": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" } } ], "post": { "tags": [ "Moderation" ], "operationId": "decideApplicationStage", "summary": "Aprovar o estágio de revisão atual ou recusar com um motivo público", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "const": "approve_step" }, "reason": { "type": "string", "maxLength": 0 } }, "required": [ "expectedVersion", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "expectedVersion": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "const": "reject" }, "reason": { "type": "string", "minLength": 10, "maxLength": 1500 } }, "required": [ "expectedVersion", "action", "reason" ], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Decisão salva.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "$ref": "#/components/schemas/Application" } }, "required": [ "application" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/gateway/webhook": { "post": { "tags": [ "Gateway events" ], "operationId": "receiveGatewayEvent", "summary": "Receber eventos de gateway nativos assinados", "description": "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.", "security": [ { "nativeGatewaySignature": [] }, { "gatewaySignature": [] } ], "parameters": [ { "name": "X-Gateway-Timestamp", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[0-9]{10}$" }, "description": "Obrigatório para eventos nativos v3." }, { "name": "X-Gateway-Event-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Obrigatório para nativo v3; deve corresponder a body.id." } ], "requestBody": { "required": true, "description": "Corpo JSON assinado exato; limite nativo v3: 524288 bytes. Não analise e resserealize antes da verificação da assinatura.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NativeGatewayEvent" }, { "$ref": "#/components/schemas/LegacyGatewayEvent" } ] } } } }, "responses": { "200": { "description": "Recebido, deduplicado ou ignorado com segurança.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" }, "ignored": { "type": "boolean" }, "applied": { "type": "boolean" } }, "required": [ "received" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "A assinatura do gateway está ausente, inválida ou fora da janela de tempo aceita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_GATEWAY_SIGNATURE", "INVALID_SIGNATURE", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "Um ID de evento foi reutilizado com conteúdo alterado ou um ID de pagamento conflita com o vínculo de fatura salvo.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_EVENT_CONFLICT", "PAYMENT_ID_CONFLICT" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "O gateway está ocupado; tente novamente a entrega do webhook com o mesmo ID de evento.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_BUSY" ] }, "502": { "description": "Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "A configuração do gateway ou o segredo de assinatura está ausente.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_NOT_CONNECTED", "DATABASE_NOT_CONFIGURED" ] } } } }, "/api/jobs/dispatch": { "post": { "tags": [ "Service" ], "operationId": "dispatchBackgroundJobs", "summary": "Executar trabalhos de entrega e aplicação devidos", "description": "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.", "security": [ { "jobSecret": [] } ], "responses": { "200": { "description": "Concluído sem um contexto de segundo plano.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "202": { "description": "Aceito em um contexto de execução em segundo plano.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "accepted": { "const": true } }, "required": [ "accepted" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/status": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura." } ], "get": { "tags": [ "Checkout" ], "operationId": "getCheckoutPaymentStatus", "summary": "Ler e atualizar o mesmo pagamento", "description": "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.", "responses": { "200": { "description": "Estado de pagamento saneado atual.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/reconcile": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura." } ], "post": { "tags": [ "Checkout" ], "operationId": "reconcileCheckoutPayment", "summary": "Solicitar uma conciliação de status autoritativa", "description": "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.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyObject" } } } }, "responses": { "200": { "description": "Pagamento conciliado ou null.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "A 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.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/card-intent": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura." } ], "post": { "tags": [ "Checkout" ], "operationId": "createCardEncryptionIntent", "summary": "Obter uma chave pública do gateway e uma intenção de criptografia vinculada", "description": "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.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON, no máximo 2048 bytes.", "content": { "application/json": { "schema": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "payment", "code" ], "default": "payment" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Intenção de curta duração e chave RSA pública apenas.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardIntent" } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "A 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.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/code": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura." } ], "post": { "tags": [ "Checkout" ], "operationId": "submitEncryptedBankCode", "summary": "Retransmitir um código criptografado para o desafio bancário atual", "description": "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.", "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sealed": { "$ref": "#/components/schemas/SealedCardData" } }, "required": [ "sealed" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Código enviado; estado de pagamento atual.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutPayment" }, { "type": "null" } ] }, "replayed": { "type": "boolean" } }, "required": [ "payment" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "410": { "description": "A 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.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CARD_SESSION_INVALID" ] }, "413": { "description": "Corpo excede 16.384 bytes; o limite é de 65.536 bytes para /api/support/ask e o webhook do Telegram.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "REQUEST_TOO_LARGE" ] }, "415": { "description": "Content-Type: application/json é obrigatório.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "JSON_REQUIRED" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/checkout/{token}/crypto-services": { "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "description": "Identificador público aleatório da URL de checkout. Concede acesso de leitura apenas a esta fatura." } ], "get": { "tags": [ "Checkout" ], "operationId": "getCheckoutCryptoServices", "summary": "Ler o catálogo atual de moedas e redes", "description": "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.", "responses": { "200": { "description": "Catálogo fornecido pelo gateway, com disponibilidade atual e limites de transferência.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "services": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "network": { "type": "string" }, "networkLabel": { "type": "string" }, "available": { "type": "boolean" }, "minAmount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Valor decimal exato na moeda de transferência selecionada." }, "maxAmount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Valor decimal exato na moeda de transferência selecionada." }, "confirmations": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "currency", "network", "networkLabel", "available", "minAmount", "maxAmount", "confirmations" ], "additionalProperties": false } }, "fetchedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "services", "fetchedAt" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "502": { "description": "Resposta do gateway indisponível, malformada ou não verificável. Leia o status do pagamento existente antes de tentar qualquer nova tentativa.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "GATEWAY_REQUEST_UNCERTAIN", "GATEWAY_INVALID_RESPONSE" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/stores": { "get": { "tags": [ "Account" ], "operationId": "listStores", "summary": "Listar todas as lojas pertencentes à conta atual", "security": [ { "cookieSession": [] } ], "responses": { "200": { "description": "IDs de loja são distintos de IDs de conta. Nenhum segredo é exposto.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "stores": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Store" } }, "defaultStoreId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "stores", "defaultStoreId" ], "additionalProperties": false } } } }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } }, "post": { "tags": [ "Account" ], "operationId": "createStore", "summary": "Criar uma loja separada", "description": "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.", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Criada.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/Store" } }, "required": [ "store" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "409": { "description": "A solicitação de entrada foi usada ou cancelada, a identidade não foi confirmada ou uma solicitação de suporte conflita.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "CHALLENGE_UNAVAILABLE", "IDENTITY_INCOMPLETE", "TICKET_CONFLICT", "IDEMPOTENCY_CONFLICT", "LINK_CANCELLED", "LINK_EXPIRED", "LINK_UNAVAILABLE" ] }, "429": { "description": "Limite de taxa excedido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string", "const": "60" }, "description": "O servidor sempre retorna 60; isso não garante que uma cota horária expirou." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "RATE_LIMITED" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/stores/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } } ], "patch": { "tags": [ "Account" ], "operationId": "updateStore", "summary": "Renomear uma loja própria ou alterar seu padrão de IVA", "security": [ { "cookieSession": [], "csrfToken": [] } ], "parameters": [ { "name": "Origin", "in": "header", "required": true, "description": "Deve corresponder exatamente a APP_ORIGIN. Sec-Fetch-Site: cross-site é rejeitado. O servidor não fornece acesso CORS.", "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "description": "Token da sessão atual de GET /api/auth/me ou conclusão bem-sucedida da entrada.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Cotações de fatura existentes permanecem inalteradas.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/Store" } }, "required": [ "store" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "403": { "description": "Falha na validação de Origin, CSRF ou vínculo com navegador.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_ORIGIN", "CSRF_REQUIRED", "BROWSER_PROOF_REQUIRED", "INVALID_CHALLENGE" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/exchange-rates": { "get": { "tags": [ "Payments" ], "operationId": "getReferenceExchangeRate", "summary": "Obter a taxa de referência atual USD/RUB", "description": "Cacheada no servidor por uma hora. A taxa numérica usa milionésimos de RUB por USD. Nenhuma cotação de fallback é inventada. Usada na criação de fatura; uma fatura existente retém sua própria taxa.", "security": [], "responses": { "200": { "description": "Fonte oficial, data de publicação e horário de recuperação.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "rate": { "$ref": "#/components/schemas/ExchangeRate" } }, "required": [ "rate" ], "additionalProperties": false } } } }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } }, "/api/account/dashboard": { "get": { "tags": [ "Account" ], "operationId": "getAccountDashboard", "summary": "Ler recibos verificados para uma loja ou todas as lojas próprias", "description": "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.", "security": [ { "cookieSession": [] } ], "parameters": [ { "name": "X-Kevmi-Store", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Selecione 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." }, { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30 ], "default": 7 } } ], "responses": { "200": { "description": "Resumo contábil somente leitura.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "storeId": { "type": [ "string", "null" ] }, "stores": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "name": { "type": "string" }, "currency": { "type": [ "string", "null" ] }, "invoices": { "type": "integer" }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." } }, "required": [ "id", "name", "currency", "invoices", "netMinor" ], "additionalProperties": false } }, "totals": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "invoices": { "type": "integer" }, "succeeded": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." } }, "required": [ "currency", "invoices", "succeeded", "grossMinor", "netMinor" ], "additionalProperties": false } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "day": { "type": "string" }, "count": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." } }, "required": [ "currency", "day", "count", "grossMinor" ], "additionalProperties": false } }, "methods": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string" }, "method": { "type": "string" }, "count": { "type": "integer" }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." } }, "required": [ "currency", "method", "count", "grossMinor" ], "additionalProperties": false } }, "days": { "type": "integer", "enum": [ 7, 30 ] }, "from": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "generatedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "accountingBasis": { "type": "string", "const": "verified_receipts" }, "withdrawableBalance": { "type": "null" }, "payoutCreationAvailable": { "type": "boolean", "const": false } }, "required": [ "storeId", "stores", "totals", "daily", "methods", "days", "from", "generatedAt", "accountingBasis", "withdrawableBalance", "payoutCreationAvailable" ], "additionalProperties": false } } } }, "400": { "description": "JSON inválido, campo desconhecido ou valor inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "INVALID_JSON", "UNKNOWN_FIELD", "INVALID_INPUT", "INVALID_VAT_PAYER", "INVALID_NOTIFICATIONS", "INVALID_TICKET_STATUS", "INVALID_UPDATE", "INVALID_HISTORY", "INVALID_PAGE_CONTEXT", "INVALID_LOCALE", "INVALID_FILTER", "INVALID_NOTIFICATION_SELECTION", "INVALID_AMOUNT", "INVALID_CURRENCY", "INVALID_METHODS", "INVALID_EXPIRY", "INVALID_QUOTE", "INVALID_LIMIT", "INVALID_CURSOR", "INVALID_STATUS", "IDEMPOTENCY_KEY_REQUIRED", "METHOD_UNAVAILABLE" ] }, "401": { "description": "Nenhuma sessão válida; para um webhook, um segredo inválido.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "AUTH_REQUIRED", "SESSION_EXPIRED", "WEBHOOK_UNAUTHORIZED" ] }, "404": { "description": "O registro está ausente, o token público é inválido ou o registro solicitado pertence a outro usuário.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "TICKET_NOT_FOUND", "LINK_NOT_FOUND" ] }, "503": { "description": "Uma integração ou armazenamento está indisponível, um evento está sendo processado ou o serviço está indisponível.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "x-error-codes": [ "DATABASE_NOT_CONFIGURED", "ORIGIN_NOT_CONFIGURED", "TELEGRAM_NOT_CONFIGURED", "UPDATE_IN_PROGRESS", "SERVICE_UNAVAILABLE", "GATEWAY_NOT_CONNECTED" ] } } } } }, "components": { "securitySchemes": { "cookieSession": { "type": "apiKey", "in": "cookie", "name": "__Host-kevmi-session", "description": "Token de sessão aleatório, Secure/HttpOnly/SameSite=Lax, válido por 24 horas. Um hash é armazenado no banco de dados. Emitido somente após login verificado do Telegram." }, "browserProof": { "type": "apiKey", "in": "cookie", "name": "__Host-kevmi-login", "description": "Cookie HttpOnly desde o início: challengeId.proof, válido por 300 segundos. Excluído do link profundo do Telegram." }, "csrfToken": { "type": "apiKey", "in": "header", "name": "X-CSRF-Token", "description": "Token CSRF de sessão emitido por /api/auth/me ou /api/auth/telegram/complete. Mutações também exigem o Origin exato." }, "telegramWebhookSecret": { "type": "apiKey", "in": "header", "name": "X-Telegram-Bot-Api-Secret-Token", "description": "Segredo de webhook separado configurado no servidor. Seu valor é privado. Este não é o token do bot." }, "merchantKey": { "type": "http", "scheme": "bearer", "bearerFormat": "kv_live_…", "description": "Chave de API de comerciante com escopo. Apenas seu hash é armazenado. Uso apenas servidor-para-servidor; nunca a coloque em um widget ou pacote de navegador." }, "gatewaySignature": { "type": "apiKey", "in": "header", "name": "Kevmi-Signature", "description": "t=,v1=. Tolerância máxima de horário: 300 segundos." }, "jobSecret": { "type": "http", "scheme": "bearer", "description": "JOBS_SECRET separado, somente servidor. Não é uma chave de API de comerciante." }, "nativeGatewaySignature": { "type": "apiKey", "in": "header", "name": "X-Gateway-Signature", "description": "v1=; separado da Kevmi-Signature de comerciante." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "EmptyObject": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "Config": { "type": "object", "properties": { "telegram": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botUsername": { "type": [ "string", "null" ] } }, "required": [ "enabled", "botUsername" ], "additionalProperties": false }, "support": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "search", "ai" ] }, "available": { "type": "boolean", "const": true } }, "required": [ "mode", "available" ], "additionalProperties": false }, "gateway": { "type": "object", "properties": { "configured": { "type": "boolean" }, "connected": { "type": "boolean", "const": false, "description": "O endpoint público de configuração não verifica a saúde do gateway. Configuração não é uma verificação bem-sucedida de conexão ao vivo." }, "status": { "type": "string", "enum": [ "configured", "not_configured" ] } }, "required": [ "configured", "connected", "status" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "server": { "type": "boolean", "const": true }, "account": { "type": "boolean" }, "notifications": { "type": "boolean" }, "tickets": { "type": "boolean" }, "directPaymentsOnly": { "type": "boolean", "const": true }, "paymentLinks": { "type": "boolean", "description": "D1 está configurado para faturas de servidor. Isso não indica prontidão de pagamento." }, "apiKeys": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "widgets": { "type": "boolean" }, "applications": { "type": "boolean" }, "applicationNotifications": { "type": "boolean" } }, "required": [ "server", "account", "notifications", "tickets", "directPaymentsOnly", "paymentLinks", "apiKeys", "webhooks", "widgets", "applications", "applicationNotifications" ], "additionalProperties": false } }, "required": [ "telegram", "support", "gateway", "capabilities" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "telegram": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "botUsername": { "type": [ "string", "null" ] } }, "required": [ "enabled", "botUsername" ], "additionalProperties": false }, "support": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "search", "ai" ] }, "available": { "type": "boolean", "const": true } }, "required": [ "mode", "available" ], "additionalProperties": false }, "gateway": { "type": "object", "properties": { "configured": { "type": "boolean" }, "connected": { "type": "boolean", "const": false, "description": "O endpoint público de configuração não verifica a saúde do gateway. Configuração não é uma verificação bem-sucedida de conexão ao vivo." }, "status": { "type": "string", "enum": [ "configured", "not_configured" ] } }, "required": [ "configured", "connected", "status" ], "additionalProperties": false }, "capabilities": { "type": "object", "properties": { "server": { "type": "boolean", "const": true }, "account": { "type": "boolean" }, "notifications": { "type": "boolean" }, "tickets": { "type": "boolean" }, "directPaymentsOnly": { "type": "boolean", "const": true }, "paymentLinks": { "type": "boolean", "description": "D1 está configurado para faturas de servidor. Isso não indica prontidão de pagamento." }, "apiKeys": { "type": "boolean" }, "webhooks": { "type": "boolean" }, "widgets": { "type": "boolean" }, "applications": { "type": "boolean" }, "applicationNotifications": { "type": "boolean" } }, "required": [ "server", "account", "notifications", "tickets", "directPaymentsOnly", "paymentLinks", "apiKeys", "webhooks", "widgets", "applications", "applicationNotifications" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "storage": { "type": "string", "enum": [ "ready", "not_configured", "unavailable" ] } }, "required": [ "telegram", "support", "gateway", "capabilities", "status", "storage" ], "additionalProperties": false }, "NotificationPreferences": { "type": "object", "properties": { "payments": { "type": "boolean" }, "payouts": { "type": "boolean" }, "support": { "type": "boolean" }, "security": { "type": "boolean" } }, "required": [ "payments", "payouts", "support", "security" ], "additionalProperties": false }, "SettingsPatch": { "type": "object", "properties": { "storeName": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 80, "x-trimmedMinLength": 1, "description": "Espaç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." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "notifications": { "type": "object", "properties": { "payments": { "type": "boolean" }, "payouts": { "type": "boolean" }, "support": { "type": "boolean" }, "security": { "type": "boolean" } }, "required": [], "additionalProperties": false } }, "required": [], "additionalProperties": false }, "User": { "type": "object", "properties": { "id": { "type": "string" }, "displayName": { "type": "string" }, "username": { "type": [ "string", "null" ] }, "storeName": { "type": "string" }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "notifications": { "$ref": "#/components/schemas/NotificationPreferences" }, "isModerator": { "type": "boolean", "description": "Se esta identidade do Telegram pertence à lista de permissão de moderadores configurada." } }, "required": [ "id", "displayName", "username", "storeName", "vatPayer", "notifications", "isModerator" ], "additionalProperties": false }, "UserResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/User" } }, "required": [ "user" ], "additionalProperties": false }, "Anonymous": { "type": "object", "properties": { "authenticated": { "type": "boolean", "const": false } }, "required": [ "authenticated" ], "additionalProperties": false }, "CurrentSession": { "type": "object", "properties": { "authenticated": { "type": "boolean", "const": true }, "user": { "$ref": "#/components/schemas/User" }, "csrfToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "authenticated", "user", "csrfToken", "expiresAt" ], "additionalProperties": false }, "LoginChallenge": { "type": "object", "properties": { "challengeId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "code": { "type": "string", "pattern": "^[0-9]{6}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "telegramUrl": { "type": "string", "format": "uri", "pattern": "^https://t\\.me/" } }, "required": [ "challengeId", "code", "expiresAt", "telegramUrl" ], "additionalProperties": false }, "CompletedLogin": { "type": "object", "properties": { "status": { "type": "string", "const": "authenticated" }, "user": { "$ref": "#/components/schemas/User" }, "csrfToken": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "status", "user", "csrfToken", "expiresAt" ], "additionalProperties": false }, "SupportQuestion": { "type": "object", "properties": { "question": { "type": "string", "minLength": 2, "x-trimmedMaxLength": 2000, "x-trimmedMinLength": 2, "description": "Espaç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." }, "locale": { "type": "string", "enum": [ "ru", "en", "es", "de", "fr", "pt", "tr", "kk" ], "default": "en", "description": "Idioma 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." }, "history": { "type": "array", "maxItems": 6, "description": "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.", "items": { "oneOf": [ { "type": "object", "properties": { "role": { "type": "string", "const": "user" }, "content": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 1800, "x-trimmedMinLength": 1, "description": "Espaços ao redor são removidos. Comprimento após remoção: 1–1.800 caracteres. Caracteres de controle exceto tabs e quebras de linha são proibidos." } }, "required": [ "role", "content" ], "additionalProperties": false }, { "type": "object", "properties": { "role": { "type": "string", "const": "assistant" }, "content": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 3000, "x-trimmedMinLength": 1, "description": "Espaços ao redor são removidos. Comprimento após remoção: 1–3.000 caracteres. Caracteres de controle exceto tabs e quebras de linha são proibidos." } }, "required": [ "role", "content" ], "additionalProperties": false } ] } }, "pageContext": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 80, "x-trimmedMinLength": 1, "description": "Ró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.", "pattern": "^[\\p{L}\\p{N}\\s·.,—–\\-:()]+$", "not": { "pattern": "[\\r\\n]" } } }, "required": [ "question" ], "additionalProperties": false }, "SupportSource": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "pattern": "^/(?:ru/|en/)?docs/[^/]+$", "description": "Link relativo a um artigo de conhecimento publicado." } }, "required": [ "id", "title", "url" ], "additionalProperties": false }, "SearchSupportAnswer": { "type": "object", "properties": { "mode": { "type": "string", "const": "search" }, "answer": { "type": "string" }, "sources": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/SupportSource" } }, "knowledgeVersion": { "type": [ "string", "null" ] }, "needsHuman": { "type": "boolean" }, "aiUnavailable": { "type": "boolean", "const": true } }, "required": [ "mode", "answer", "sources", "knowledgeVersion", "needsHuman" ], "additionalProperties": false }, "AISupportAnswer": { "type": "object", "properties": { "mode": { "type": "string", "const": "ai" }, "answer": { "type": "string", "minLength": 1, "maxLength": 6000, "description": "Somente texto simples; URLs e HTML são rejeitados. Links são retornados apenas em fontes." }, "sources": { "type": "array", "maxItems": 25, "uniqueItems": true, "items": { "$ref": "#/components/schemas/SupportSource" } }, "knowledgeVersion": { "type": "string" }, "needsHuman": { "type": "boolean" } }, "required": [ "mode", "answer", "sources", "knowledgeVersion", "needsHuman" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "needsHuman": { "const": false } } }, "then": { "properties": { "sources": { "minItems": 1 } } } } ] }, "SupportAnswer": { "oneOf": [ { "$ref": "#/components/schemas/SearchSupportAnswer" }, { "$ref": "#/components/schemas/AISupportAnswer" } ] }, "Ticket": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tkt_[a-f0-9-]{36}$" }, "subject": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "answered", "closed" ], "description": "answered denota uma solicitação respondida. A API pública permite que um usuário feche apenas sua própria solicitação." }, "source": { "type": "string", "enum": [ "web", "telegram" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "id", "subject", "message", "status", "source", "createdAt", "updatedAt" ], "additionalProperties": false }, "TicketResponse": { "type": "object", "properties": { "ticket": { "$ref": "#/components/schemas/Ticket" } }, "required": [ "ticket" ], "additionalProperties": false }, "Notification": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^ntf_[A-Za-z0-9-]{1,80}$" }, "kind": { "type": "string", "enum": [ "payments", "payouts", "support", "security", "test" ] }, "message": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sending", "sent", "failed" ], "description": "Estado de entrega do Telegram, independente do estado de leitura no site." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "sentAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "readAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Momento da primeira leitura no site; null significa não lido. Isso não confirma que foi lido no Telegram." } }, "required": [ "id", "kind", "message", "status", "createdAt", "sentAt", "readAt" ], "additionalProperties": false }, "NotificationsPage": { "type": "object", "properties": { "notifications": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/Notification" } }, "unreadCount": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor da próxima página; null se não houver mais registros." } }, "required": [ "notifications", "unreadCount", "nextCursor" ], "additionalProperties": false }, "ReadNotifications": { "oneOf": [ { "type": "object", "properties": { "ids": { "type": "array", "minItems": 1, "maxItems": 100, "description": "Duplicatas são permitidas e contadas uma vez.", "items": { "type": "string", "pattern": "^ntf_[A-Za-z0-9-]{1,80}$" } } }, "required": [ "ids" ], "additionalProperties": false }, { "type": "object", "properties": { "all": { "type": "boolean", "const": true }, "before": { "type": "integer", "minimum": 0, "description": "createdAt do último evento exibido. O servidor também exige before <= Date.now().", "maximum": 9007199254740991 } }, "required": [ "all", "before" ], "additionalProperties": false } ] }, "ReadNotificationsResult": { "type": "object", "properties": { "updated": { "type": "integer", "minimum": 0 }, "readAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "unreadCount": { "type": "integer", "minimum": 0 } }, "required": [ "updated", "readAt", "unreadCount" ], "additionalProperties": false }, "TelegramUpdate": { "type": "object", "properties": { "update_id": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "message": { "type": "object", "additionalProperties": true, "description": "Mensagem do Telegram: o manipulador usa message_id, text, from e chat." }, "callback_query": { "type": "object", "additionalProperties": true, "description": "Telegram CallbackQuery: o manipulador usa id, from, data e message.chat." } }, "required": [ "update_id" ], "additionalProperties": true }, "IncomingQuote": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "baseMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "percentageFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "fixedFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "nominalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "feeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "merchantVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "merchantDeductionMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "totalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de fatura: centavos de USD, copeques de RUB ou centésimos de USDT. Sem conversão automática de moeda." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Versão do cálculo salva com a fatura." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota 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." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.", "default": 0 }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "merchantFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "settlement": { "$ref": "#/components/schemas/SettlementQuote" } }, "required": [ "amountMinor", "baseMinor", "grossMinor", "percentageFeeMinor", "fixedFeeMinor", "nominalFeeMinor", "feeMinor", "vatMinor", "customerVatMinor", "merchantVatMinor", "customerTotalMinor", "merchantDeductionMinor", "totalFeeMinor", "netMinor", "currency", "method", "vatPayer", "vatApplies", "pricingVersion" ], "additionalProperties": false }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": { "type": "string", "maxLength": 500 }, "merchantName": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de fatura: centavos de USD, copeques de RUB ou centésimos de USDT. Sem conversão automática de moeda." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "quotes": { "type": "object", "properties": { "card": { "$ref": "#/components/schemas/IncomingQuote" }, "alipay": { "$ref": "#/components/schemas/IncomingQuote" }, "sbp": { "$ref": "#/components/schemas/IncomingQuote" }, "crypto": { "$ref": "#/components/schemas/IncomingQuote" } }, "required": [], "additionalProperties": false }, "status": { "type": "string", "enum": [ "active", "paused", "expired", "cancelled" ], "description": "expired é derivado de expiresAt na leitura. cancelled é definitivo." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "url": { "type": "string", "format": "uri", "description": "Página pública /pay/{token} em APP_ORIGIN." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota 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." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referência do pedido visível ao comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público." }, "checkoutUrl": { "type": "string", "format": "uri" }, "payment": { "oneOf": [ { "$ref": "#/components/schemas/PaymentSummary" }, { "type": "null" } ], "description": "Incluído nas solicitações GET de listagem/detalhes do proprietário. O ciclo de vida da fatura é independente do status de pagamento verificado. Não contém cartão, código bancário, QR nem detalhes do comprador." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "pricingMode": { "type": "string", "enum": [ "native", "universal" ] }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/ExchangeRate" }, { "type": "null" } ] }, "usdtPerUsd": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "description", "merchantName", "amountMinor", "currency", "vatPayer", "methods", "quotes", "status", "createdAt", "updatedAt", "expiresAt", "url", "vatCustomerPercent", "feeCustomerPercent", "orderId", "metadata", "checkoutUrl" ], "additionalProperties": false }, "CreatePaymentLink": { "oneOf": [ { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Espaç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." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "Opcional; uma string vazia é permitida. Até 500 caracteres após o trim." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Limite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Quando omitido, a regra atual da loja é salva." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Um horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura." }, "currency": { "type": "string", "const": "USD" }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "crypto" ] }, "description": "O 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." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota 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." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referência do pedido visível ao comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público." }, "pricingMode": { "type": "string", "const": "native", "description": "Preço legado específico por moeda. Omita para compatibilidade com integrações existentes." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Espaç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." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "Opcional; uma string vazia é permitida. Até 500 caracteres após o trim." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Limite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Quando omitido, a regra atual da loja é salva." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Um horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura." }, "currency": { "type": "string", "const": "RUB" }, "methods": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "const": "sbp" } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota 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." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referência do pedido visível ao comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público." }, "pricingMode": { "type": "string", "const": "native", "description": "Preço legado específico por moeda. Omita para compatibilidade com integrações existentes." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Espaç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." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "Opcional; uma string vazia é permitida. Até 500 caracteres após o trim." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Limite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Quando omitido, a regra atual da loja é salva." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Um horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura." }, "currency": { "type": "string", "const": "USDT" }, "methods": { "type": "array", "minItems": 1, "maxItems": 1, "uniqueItems": true, "items": { "type": "string", "const": "crypto" } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota 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." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referência do pedido visível ao comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público." }, "pricingMode": { "type": "string", "const": "native", "description": "Preço legado específico por moeda. Omita para compatibilidade com integrações existentes." } }, "required": [ "title", "amountMinor", "currency", "methods" ], "additionalProperties": false }, { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "x-trimmedMaxLength": 120, "x-trimmedMinLength": 1, "description": "Espaç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." }, "description": { "type": "string", "x-trimmedMaxLength": 500, "description": "Opcional; uma string vazia é permitida. Até 500 caracteres após o trim." }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 10000000000, "description": "Limite inteiro técnico, não um limite comercial do provedor. Um crédito negativo do comerciante é rejeitado." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ], "description": "Quando omitido, a regra atual da loja é salva." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Um horário futuro, no máximo 90 dias após a criação. O padrão é sete dias. Salvo no snapshot da fatura." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidade 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." }, "methods": { "type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota 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." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referência do pedido visível ao comprador." }, "metadata": { "type": "object", "maxProperties": 10, "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,40}$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Metadados privados do comerciante. No máximo 3000 bytes UTF-8 após serialização JSON. Nunca expostos no checkout público." }, "pricingMode": { "type": "string", "const": "universal" } }, "required": [ "title", "amountMinor", "currency", "methods", "pricingMode" ], "additionalProperties": false } ], "description": "Valores usam unidades menores. Taxa e IVA são calculados sobre o valor base do pedido. A parcela do cliente é arredondada para cima; o comerciante cobre o restante exato. Um vatPayer e vatCustomerPercent legados conflitantes são rejeitados. A alocação é imutável após a criação; emita uma nova fatura para alterá-la. Cartão/Alipay ao vivo exige vatCustomerPercent=100 e feeCustomerPercent=0 porque o gateway configurado não pode substituir seu imposto exclusivo. Outras alocações salvas retornam unsupported_allocation; elas nunca são alteradas silenciosamente. SBP e cripto USDT suportam alocação de taxa. Use o objeto público de disponibilidade de fatura antes de coletar dados de pagamento. O modo universal armazena um preço base em USD e cotações de cobrança nativas separadas: USD para cartões/Alipay, RUB para SBP, USDT para cripto. A conversão RUB usa uma taxa de referência salva do Banco da Rússia. Cripto usa a regra explícita de fatura 1 USD = 1 USDT, não uma cotação de mercado. Faturas que envolvem conversão RUB são limitadas a 24 horas mesmo quando expiresAt solicita uma data posterior. Falha na fonte FX retorna 503 FX_UNAVAILABLE. Omita pricingMode para comportamento nativo legado.", "examples": [ { "pricingMode": "universal", "title": "Pedido 1042", "amountMinor": 1000, "currency": "USD", "methods": [ "card", "alipay", "sbp", "crypto" ], "vatCustomerPercent": 100, "feeCustomerPercent": 0 }, { "title": "Pedido 1042", "amountMinor": 500, "currency": "USD", "methods": [ "card", "alipay" ], "vatCustomerPercent": 100, "feeCustomerPercent": 0, "orderId": "1042" }, { "title": "Pedido 1043", "amountMinor": 1000, "currency": "USDT", "methods": [ "crypto" ], "feeCustomerPercent": 23, "orderId": "1043" } ] }, "PaymentLinkResponse": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/PaymentLink" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "Incluído nas respostas de atualização de status; o link aninhado sempre contém seu checkoutUrl." } }, "required": [ "link" ], "additionalProperties": false }, "CreatePaymentLinkResponse": { "type": "object", "properties": { "link": { "$ref": "#/components/schemas/PaymentLink" }, "replayed": { "type": "boolean" }, "checkoutUrl": { "type": "string", "format": "uri", "description": "O link de pagamento está disponível imediatamente; nenhuma sondagem é necessária." } }, "required": [ "link", "replayed", "checkoutUrl" ], "additionalProperties": false }, "PaymentLinksPage": { "type": "object", "properties": { "links": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/PaymentLink" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor opaco para a próxima página. Passe como um parâmetro de consulta codificado em URL; null marca o fim." } }, "required": [ "links", "nextCursor" ], "additionalProperties": false }, "CheckoutQuote": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Versão do cálculo salva com a fatura." }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "merchantCoveredMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." } }, "required": [ "method", "amountMinor", "vatMinor", "customerVatMinor", "customerTotalMinor", "vatApplies", "pricingVersion", "customerFeeMinor", "merchantCoveredMinor" ], "additionalProperties": false }, "CheckoutInvoice": { "type": "object", "properties": { "token": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "title": { "type": "string" }, "description": { "type": "string" }, "merchantName": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de fatura: centavos de USD, copeques de RUB ou centésimos de USDT. Sem conversão automática de moeda." }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "methods": { "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] } }, "status": { "type": "string", "enum": [ "active", "paused", "expired", "cancelled" ], "description": "expired é derivado de expiresAt na leitura. cancelled é definitivo." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "quote": { "$ref": "#/components/schemas/CheckoutQuote" }, "gatewayConnected": { "type": "boolean", "description": "Alias de compatibilidade para availability.available, não uma sonda de saúde do gateway." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota 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." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.", "default": 0 }, "orderId": { "type": "string", "maxLength": 100, "description": "Referência do pedido visível ao comprador." }, "availability": { "$ref": "#/components/schemas/CheckoutAvailability" }, "baseAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "baseCurrency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ] }, "fx": { "oneOf": [ { "$ref": "#/components/schemas/ExchangeRate" }, { "type": "null" } ] }, "usdtPerUsd": { "type": [ "string", "null" ] } }, "required": [ "token", "title", "description", "merchantName", "amountMinor", "currency", "vatPayer", "methods", "status", "expiresAt", "createdAt", "quote", "gatewayConnected", "vatCustomerPercent", "feeCustomerPercent", "orderId", "availability" ], "additionalProperties": false }, "MerchantKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9a-f-]{36}$" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "type": "string", "enum": [ "invoices:read", "invoices:write", "events:read" ] } }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "revokedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "lastUsedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "name", "prefix", "scopes", "createdAt", "expiresAt" ], "additionalProperties": false }, "MerchantEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[a-f0-9]{40}$" }, "type": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] }, "apiVersion": { "type": "string", "const": "2026-10-21" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "livemode": { "type": "boolean" }, "data": { "type": "object", "additionalProperties": true, "description": "invoice.created/updated: fatura do comerciante persistida, incluindo metadados privados. eventos de pagamento: fatos de pagamento verificados. Consulte o guia de webhook para exemplos." } }, "required": [ "id", "type", "apiVersion", "createdAt", "livemode", "data" ], "additionalProperties": false }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9a-f-]{36}$" }, "url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] } }, "status": { "type": "string", "enum": [ "unverified", "active", "paused" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "verifiedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "url", "description", "events", "status", "createdAt", "verifiedAt" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "event_id": { "type": "string" }, "endpoint_id": { "type": "string" }, "type": { "type": "string", "enum": [ "invoice.created", "invoice.updated", "payment.succeeded", "payment.failed", "payment.refunded", "payment.partially_refunded", "payment.disputed", "payment.review_required" ] }, "status": { "type": "string", "enum": [ "pending", "sending", "delivered", "failed", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0, "maximum": 6 }, "next_attempt_at": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "last_status": { "type": [ "integer", "null" ] }, "last_error": { "type": [ "string", "null" ] }, "created_at": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "delivered_at": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "id", "event_id", "endpoint_id", "type", "status", "attempts" ], "additionalProperties": false }, "Application": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^app_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$" }, "websiteUrl": { "type": "string", "format": "uri", "maxLength": 2048 }, "businessName": { "type": "string", "minLength": 1, "maxLength": 100 }, "businessType": { "type": "string", "enum": [ "digital_goods", "software", "services", "physical_goods", "education", "other" ] }, "description": { "type": "string", "minLength": 40, "maxLength": 3000 }, "contactTelegram": { "type": "string", "pattern": "^@[A-Za-z][A-Za-z0-9_]{4,31}$" }, "status": { "type": "string", "enum": [ "processing", "needs_review", "approved", "rejected" ] }, "currentStage": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "version": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "description": "Mensagem de etapa voltada ao usuário ou motivo de recusa editado pelo moderador. Evidência interna é excluída." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "stages": { "type": "array", "minItems": 4, "maxItems": 4, "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "state": { "type": "string", "enum": [ "pending", "running", "complete", "review", "rejected" ] }, "message": { "type": "string" }, "updatedAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "id", "state", "message", "updatedAt" ], "additionalProperties": false } }, "url": { "type": "string", "format": "uri", "description": "URL de rastreamento privada com localidade explícita. Saber a URL não concede acesso." }, "notificationCategory": { "type": "string", "const": "support" }, "canResume": { "type": "boolean" }, "storeId": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" } }, "required": [ "id", "websiteUrl", "businessName", "businessType", "description", "contactTelegram", "status", "currentStage", "version", "reason", "createdAt", "updatedAt", "stages", "url", "notificationCategory", "canResume" ], "additionalProperties": false }, "ApplicationEvent": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 1 }, "stage": { "type": "string", "enum": [ "received", "ai_review", "technical_review", "manual_review" ] }, "state": { "type": "string", "enum": [ "pending", "running", "complete", "review", "rejected" ] }, "message": { "type": "string" }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "version", "stage", "state", "message", "createdAt" ], "additionalProperties": false }, "PaymentSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "ID de pagamento canônico do gateway quando conhecido; caso contrário, o ID local da operação gwp_." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "failed", "expired", "review_required", "partially_paid", "partially_refunded", "refunded", "disputed" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de fatura: centavos de USD, copeques de RUB ou centésimos de USDT. Sem conversão automática de moeda." }, "fulfillmentReady": { "type": "boolean" }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "refundedAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." } }, "required": [ "id", "method", "status", "amountMinor", "currency", "fulfillmentReady", "updatedAt" ], "additionalProperties": false }, "CheckoutAvailability": { "type": "object", "properties": { "available": { "type": "boolean" }, "code": { "type": "string", "enum": [ "ready", "not_configured", "unsupported_allocation", "crypto_requires_usdt", "amount_out_of_range", "merchant_not_approved" ] }, "flow": { "type": "string", "enum": [ "encrypted_card", "qr", "crypto" ] }, "minAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "maxAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "limitsSource": { "type": "string", "const": "adapter", "description": "Limites conservadores aplicados por esta integração, não uma afirmação sobre os limites comerciais upstream." } }, "required": [ "available", "code", "flow", "minAmountMinor", "maxAmountMinor", "limitsSource" ], "additionalProperties": false }, "CheckoutAction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "redirect", "qr", "crypto" ] }, "url": { "type": [ "string", "null" ], "format": "uri" }, "qrImage": { "type": [ "string", "null" ] }, "qrPayload": { "type": [ "string", "null" ] }, "address": { "type": "string" }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Valor exato da transferência na moeda selecionada; preserve a string decimal sem arredondamento nem conversão de ponto flutuante." }, "currency": { "type": "string" }, "network": { "type": "string" }, "networkLabel": { "type": "string" }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "addressQrImage": { "type": [ "string", "null" ] }, "amountQrImage": { "type": [ "string", "null" ] }, "amountQrPayload": { "type": [ "string", "null" ] }, "networkFeePaidByCustomer": { "type": "boolean" } }, "required": [ "type", "expiresAt" ], "additionalProperties": false }, "CheckoutPayment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^gwp_[0-9a-f-]{36}$" }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "status": { "type": "string", "enum": [ "pending", "requires_action", "processing", "succeeded", "failed", "expired", "review_required", "partially_paid", "partially_refunded", "refunded", "disputed" ] }, "providerStatus": { "type": "string" }, "fulfillmentReady": { "type": "boolean", "description": "Somente verdadeiro após a vinculação exata de valor/moeda/pedido e sucesso confirmado pelo provedor. Um redirecionamento do navegador nunca é confirmação de pagamento." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de fatura: centavos de USD, copeques de RUB ou centésimos de USDT. Sem conversão automática de moeda." }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "nextAction": { "oneOf": [ { "$ref": "#/components/schemas/CheckoutAction" }, { "type": "null" } ] }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "authentication": { "type": "object", "properties": { "required": { "type": "boolean" }, "expiresAt": { "type": [ "integer", "null" ], "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "attempt": { "type": "integer", "minimum": 0 } }, "required": [ "required", "expiresAt", "attempt" ], "additionalProperties": false }, "reason": { "type": "string", "enum": [ "amount_mismatch", "confirmation_required", "refund_mismatch", "settlement_unverified" ] }, "refundedAmountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." } }, "required": [ "id", "method", "status", "providerStatus", "fulfillmentReady", "amountMinor", "currency", "createdAt", "updatedAt", "nextAction", "expiresAt" ], "additionalProperties": false }, "SealedCardData": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 32, "maxLength": 8192, "description": "Intenção de operação assinada e de curta duração de /card-intent; encaminhe inalterada." }, "jwe": { "type": "string", "maxLength": 14000, "pattern": "^[A-Za-z0-9_-]+(?:\\.[A-Za-z0-9_-]+){4}$", "description": "JWE compacto usando RSA-OAEP-256 e A256GCM. Cabeçalho protegido: kid da chave pública, typ=kevmi-card+jwe. Somente o texto cifrado é enviado à Kevmi. Nunca envie campos de cartão ou código bancário em texto claro." } }, "required": [ "intent", "jwe" ], "additionalProperties": false }, "CardIntent": { "type": "object", "properties": { "intent": { "type": "string", "minLength": 32, "maxLength": 8192 }, "intentId": { "type": "string", "maxLength": 100 }, "expiresAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "key": { "type": "object", "properties": { "kid": { "type": "string" }, "kty": { "type": "string", "const": "RSA" }, "n": { "type": "string" }, "e": { "type": "string" }, "alg": { "type": "string", "const": "RSA-OAEP-256" }, "use": { "type": "string", "const": "enc" } }, "required": [ "kid", "kty", "n", "e", "alg", "use" ], "additionalProperties": false }, "algorithm": { "type": "string", "const": "RSA-OAEP-256" }, "encryption": { "type": "string", "const": "A256GCM" }, "protocol": { "type": "string", "const": "kevmi-card-v1" } }, "required": [ "intent", "intentId", "expiresAt", "key", "algorithm", "encryption", "protocol" ], "additionalProperties": false }, "StartCheckoutPayment": { "oneOf": [ { "type": "object", "properties": { "method": { "type": "string", "const": "card" }, "sealed": { "$ref": "#/components/schemas/SealedCardData" } }, "required": [ "method", "sealed" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "alipay" }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "country": { "type": "string", "const": "CN" }, "email": { "type": "string", "format": "email", "maxLength": 254 } }, "required": [ "method", "name", "country" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "sbp" } }, "required": [ "method" ], "additionalProperties": false }, { "type": "object", "properties": { "method": { "type": "string", "const": "crypto" }, "payerCurrency": { "type": "string", "pattern": "^[A-Z0-9]{2,16}$" }, "network": { "type": "string", "pattern": "^[a-z0-9_-]{2,32}$" } }, "required": [ "method", "payerCurrency", "network" ], "additionalProperties": false } ] }, "LegacyGatewayEvent": { "type": "object", "properties": { "eventId": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9_.:-]+$" }, "paymentId": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9_.:-]+$" }, "invoiceId": { "type": "string", "pattern": "^lnk_[0-9a-f-]{36}$" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "refunded" ] }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de fatura: centavos de USD, copeques de RUB ou centésimos de USDT. Sem conversão automática de moeda." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "occurredAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "eventId", "paymentId", "invoiceId", "status", "amountMinor", "currency", "method", "occurredAt" ], "additionalProperties": false }, "NativeGatewayEvent": { "type": "object", "required": [ "id", "api_version", "mode", "type", "data" ], "properties": { "id": { "type": "string", "format": "uuid" }, "api_version": { "type": "string", "const": "3" }, "mode": { "type": "string", "const": "live" }, "type": { "type": "string", "pattern": "^[a-z_.]{1,80}$" }, "data": { "type": "object", "required": [ "id", "version" ], "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 0 }, "merchant_order_id": { "type": "string" } } } } }, "Store": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sto_[A-Za-z0-9_-]+$" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant" ] }, "createdAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "updatedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." } }, "required": [ "id", "name", "vatPayer", "createdAt", "updatedAt" ], "additionalProperties": false }, "ExchangeRate": { "type": "object", "properties": { "rubPerUsdMicros": { "type": "integer", "minimum": 1000000 }, "effectiveAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "fetchedAt": { "type": "integer", "minimum": 0, "description": "Carimbo de tempo Unix em milissegundos, UTC." }, "source": { "type": "string", "const": "https://www.cbr.ru/scripts/XML_daily.asp" }, "usdtPerUsd": { "type": "string", "const": "1.00" } }, "required": [ "rubPerUsdMicros", "effectiveAt", "fetchedAt", "source", "usdtPerUsd" ], "additionalProperties": false }, "SettlementQuote": { "type": "object", "properties": { "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "baseMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "grossMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "percentageFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "fixedFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "nominalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "feeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "vatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "customerVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "merchantVatMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "customerTotalMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "merchantDeductionMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "totalFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "netMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "currency": { "type": "string", "enum": [ "USD", "RUB", "USDT" ], "description": "Unidades de fatura: centavos de USD, copeques de RUB ou centésimos de USDT. Sem conversão automática de moeda." }, "method": { "type": "string", "enum": [ "card", "alipay", "sbp", "crypto" ] }, "vatPayer": { "type": "string", "enum": [ "customer", "merchant", "shared" ] }, "vatApplies": { "type": "boolean" }, "pricingVersion": { "type": "integer", "minimum": 1, "description": "Versão do cálculo salva com a fatura." }, "vatCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota 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." }, "feeCustomerPercent": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Cota do cliente, como porcentagem inteira. 0 significa que o comerciante cobre tudo; 100 significa que o cliente cobre tudo.", "default": 0 }, "customerFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." }, "merchantFeeMinor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991, "description": "Valor inteiro em unidades monetárias menores." } }, "required": [ "amountMinor", "baseMinor", "grossMinor", "percentageFeeMinor", "fixedFeeMinor", "nominalFeeMinor", "feeMinor", "vatMinor", "customerVatMinor", "merchantVatMinor", "customerTotalMinor", "merchantDeductionMinor", "totalFeeMinor", "netMinor", "currency", "method", "vatPayer", "vatApplies", "pricingVersion" ], "additionalProperties": false } } }, "webhooks": { "merchantEvent": { "post": { "summary": "Entrega verificada ao servidor do comerciante", "description": "Entregue apenas a endpoints ativos e verificados por desafio. O JSON bruto é assinado; verifique o carimbo de data/hora e a assinatura antes de analisar ou alterar o estado do pedido. Retorne 2xx após aceitar de forma durável o evento. Persista IDs de eventos para lidar com duplicatas. Erros de rede, tempo limite e status não-2xx acionam novas tentativas.", "parameters": [ { "name": "Kevmi-Signature", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kevmi-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Kevmi-Delivery-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "description": "Objeto JSON. Máximo de 16.384 bytes. Campos desconhecidos são rejeitados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantEvent" } } } }, "responses": { "2XX": { "description": "Aceito de forma durável pelo servidor do comerciante." } } } } } }