{"openapi":"3.0.0","info":{"title":"Alktea Pay API","version":"1.0.0","description":"API de pagamentos para vendedores: cobranças por PIX e cartão, consulta de saldo, extrato, estornos e saques. Tudo se resolve pela API, inclusive a habilitação da conta para receber.\n\n**Valores em centavos.** Todo campo monetário é inteiro: R$ 10,50 é `1050`. A API recusa número quebrado de propósito, porque quem envia `10.5` quase sempre está mandando reais achando que a API espera reais, e aceitar isso criaria uma cobrança de valor errado.\n\n**Idempotência.** Envie `Idempotency-Key` em toda criação. Se a resposta se perder e você repetir a chamada com a mesma chave, devolvemos o mesmo recurso em vez de criar outro. Sem isso, um timeout de rede vira cobrança duplicada.\n\n**Webhooks.** Configure em `PUT /v1/account/webhook`. A entrega é ao menos uma vez, nunca exatamente uma vez: trate repetição usando o `event.id`, que é estável entre as tentativas. Confira a assinatura do header `X-Alktea-Signature` antes de confiar no conteúdo.\n\n**Erros.** Sempre no formato `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`. Programe contra o `code`, que é contrato estável; a `message` pode melhorar a qualquer momento.\n\n**Cartão no seu próprio checkout.** Você pode redirecionar o comprador para o `checkout_url` que toda cobrança devolve, ou manter ele no seu site e usar o nosso campo apenas para os dados do cartão. Nesse caso, carregue `/v1/alktea.js` e monte o campo com o `client_token` e a `publishable_key` que vêm na criação da cobrança. Há um exemplo funcional em `/exemplo-checkout`.\n\nAutentique as chamadas com o header `x-api-key`."},"servers":[{"url":"https://pay.alktea.com.br","description":"Ambiente configurado"},{"url":"http://localhost:3000","description":"Local"}],"tags":[{"name":"Cobranças","description":"Criar, consultar, cancelar e acompanhar cobranças"},{"name":"Estornos","description":"Devolver valores ao comprador, total ou parcialmente"},{"name":"Saldo","description":"Saldo disponível, saldo a liberar e extrato de movimentações"},{"name":"Saques","description":"Enviar o saldo para a sua conta"},{"name":"Conta","description":"Cadastro, habilitação para receber e chaves de API"},{"name":"Checkout","description":"Campo de cartão embutido no seu próprio checkout"},{"name":"Parceiros","description":"Para quem revende a plataforma: vendedores próprios e comissões"},{"name":"Taxas","description":"Tabela de taxas e simulação do líquido"},{"name":"Webhooks","description":"Notificações enviadas ao seu sistema"},{"name":"Contestações","description":"Contestações de cartão abertas pelo comprador"},{"name":"Auth","description":"Login dos painéis"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Chave gerada em POST /v1/account/api-keys ou na página API Keys do painel"}},"schemas":{"Erro":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"insufficient_balance"},"message":{"type":"string","example":"Saldo disponível insuficiente para esta operação."}}}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/charges":{"post":{"tags":["Cobranças"],"summary":"Cria uma cobrança","description":"Cria uma cobrança e devolve o que o comprador precisa para pagar: o código PIX copia e cola, ou o link do checkout hospedado.\n\nOs valores são sempre inteiros em centavos. R$ 10,50 é `1050`. A API recusa número quebrado de propósito: quem envia `10.5` quase sempre está mandando reais achando que a API espera reais, e aceitar isso criaria uma cobrança de valor errado.\n\nEnvie o header `Idempotency-Key` com um valor único por tentativa. Se a resposta se perder e você repetir a chamada com a mesma chave, devolvemos a mesma cobrança em vez de criar outra.\n","parameters":[{"in":"header","name":"Idempotency-Key","schema":{"type":"string"},"description":"Identificador único desta tentativa. Recomendado em toda criação."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","example":15000,"description":"Valor em centavos"},"payment_method":{"type":"string","enum":["pix","card"],"default":"pix"},"installments":{"type":"integer","default":1,"description":"Somente no cartão"},"description":{"type":"string","example":"Pedido 4471"},"external_id":{"type":"string","description":"O identificador deste pedido no seu sistema"},"expires_at":{"type":"string","format":"date-time","description":"Padrão: 1 hora para PIX"},"statement_descriptor":{"type":"string","maxLength":22,"description":"O que o comprador lê na fatura"},"payer":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"document":{"type":"string","description":"CPF ou CNPJ, com ou sem pontuação"},"external_id":{"type":"string"}}},"metadata":{"type":"object","description":"Campos livres, devolvidos em toda consulta e webhook"}}}}}},"responses":{"201":{"description":"Cobrança criada.\n\nNo PIX, a resposta traz `pix.qrcode` (o copia e cola) e `pix.qrcode_image_url` (PNG pronto, para quem não quer gerar a imagem).\n\nNo cartão, traz `client_token` e `publishable_key`, que são o que o campo embutido precisa para montar no seu próprio checkout. Veja GET /v1/alktea.js. Nenhum dos dois é a sua chave de API: o `client_token` vale só para esta cobrança e a `publishable_key` não autoriza nada sozinha, então os dois podem ir para o HTML.\n\nEm ambos os casos, `checkout_url` é a página de pagamento hospedada por nós, com a sua marca, para quem não quer construir tela nenhuma.\n","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"ch_7fKq2mXbnR4tZsWe"},"object":{"type":"string","example":"charge"},"status":{"type":"string","example":"pending"},"amount":{"type":"integer","example":15000},"fee":{"type":"integer","example":299,"description":"Retido pela plataforma"},"net":{"type":"integer","example":14701,"description":"O que entra no seu saldo"},"pix":{"type":"object","description":"Somente quando payment_method é pix","properties":{"qrcode":{"type":"string","description":"Código copia e cola"},"qrcode_image_url":{"type":"string","description":"PNG do QR Code"}}},"client_token":{"type":"string","example":"ctk_a1b2c3...","description":"Somente no cartão. Autoriza montar o campo embutido desta cobrança."},"publishable_key":{"type":"string","example":"apk_9f2c...","description":"Somente no cartão. Identifica a sua conta no navegador."},"checkout_url":{"type":"string","description":"Página de pagamento hospedada, com a sua marca"}}}}}},"403":{"description":"Conta não habilitada para este meio de pagamento"},"422":{"description":"Dados inválidos"}}},"get":{"tags":["Cobranças"],"summary":"Lista as cobranças","parameters":[{"in":"query","name":"status","schema":{"type":"string"},"description":"Aceita vários separados por vírgula: pending,paid,expired,canceled,refunded,partially_refunded,failed,disputed,chargeback"},{"in":"query","name":"payment_method","schema":{"type":"string","enum":["pix","card"]}},{"in":"query","name":"external_id","schema":{"type":"string"}},{"in":"query","name":"q","schema":{"type":"string"},"description":"Busca por identificador, descrição, nome ou documento do pagador"},{"in":"query","name":"start_date","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"end_date","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":500}},{"in":"query","name":"offset","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Lista paginada"}}}},"/v1/charges/{id}":{"get":{"tags":["Cobranças"],"summary":"Consulta uma cobrança","description":"Aceita o identificador da cobrança (`ch_...`) ou o `external_id` que você enviou na criação, para você não precisar guardar os dois.\n\nEnquanto a cobrança estiver aberta, a consulta reconfirma a situação junto ao processador. É a rede de segurança para o caso de o webhook ter se perdido: a venda aparece como paga aqui mesmo que a notificação não tenha chegado.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cobrança"},"404":{"description":"Cobrança não encontrada"}}}},"/v1/charges/{id}/cancel":{"post":{"tags":["Cobranças"],"summary":"Cancela uma cobrança ainda não paga","description":"Cobrança já paga não se cancela, se estorna. Use POST /v1/charges/{id}/refunds.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cobrança cancelada"},"409":{"description":"A cobrança não está em situação que permita cancelamento"}}}},"/v1/charges/{id}/qrcode.png":{"get":{"tags":["Cobranças"],"summary":"QR Code do PIX como imagem PNG","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"size","schema":{"type":"integer","default":320}}],"responses":{"200":{"description":"Imagem PNG","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}}}}},"/v1/charges/{id}/refunds":{"post":{"tags":["Estornos"],"summary":"Estorna uma cobrança, total ou parcialmente","description":"Sem `amount`, estorna o valor que ainda resta. A taxa cobrada é devolvida na proporção do que foi estornado: uma venda desfeita não gera receita para a plataforma.\n\nO valor sai do seu saldo no momento do pedido, mesmo que a venda ainda estivesse em liberação. O dinheiro já voltou ao comprador, então precisa sair de algum lugar.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Em centavos. Ausente estorna o restante."},"reason":{"type":"string"}}}}}},"responses":{"201":{"description":"Estorno criado"},"409":{"description":"A cobrança não está paga"},"422":{"description":"Valor maior que o disponível para estorno"}}},"get":{"tags":["Estornos"],"summary":"Lista os estornos de uma cobrança","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de estornos"}}}},"/v1/refunds":{"get":{"tags":["Estornos"],"summary":"Lista todos os estornos da conta","parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["pending","processing","completed","failed","canceled"]}}],"responses":{"200":{"description":"Lista paginada"}}}},"/v1/payers":{"post":{"tags":["Pagadores"],"summary":"Cadastra ou atualiza um pagador","description":"Opcional. Você pode mandar os dados do pagador direto na criação da cobrança, e nós cuidamos do cadastro. Esta rota existe para quem prefere manter o cadastro separado e referenciar depois.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"document":{"type":"string"},"external_id":{"type":"string"},"metadata":{"type":"object"}}}}}},"responses":{"201":{"description":"Pagador criado"}}},"get":{"tags":["Pagadores"],"summary":"Lista os pagadores","parameters":[{"in":"query","name":"q","schema":{"type":"string"}}],"responses":{"200":{"description":"Lista paginada"}}}},"/v1/payers/{id}":{"get":{"tags":["Cobranças"],"summary":"Um pagador e o histórico de compras dele","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Pagador"},"404":{"description":"Pagador não encontrado"}}}},"/v1/balance":{"get":{"tags":["Saldo"],"summary":"Consulta o saldo","description":"`available` é o que pode ser sacado agora. `pending` é o que já foi recebido mas ainda cumpre o prazo de liberação, que existe no cartão por causa do risco de contestação. `reserved` é o que está preso em saque ainda não concluído.\n","responses":{"200":{"description":"Saldo"}}}},"/v1/balance/transactions":{"get":{"tags":["Saldo"],"summary":"Extrato de movimentações","description":"Uma linha por lançamento, com o saldo depois de cada um. Venda e taxa aparecem separadas, para você conferir o que vendeu e o que pagou sem precisar recalcular.\n","parameters":[{"in":"query","name":"type","schema":{"type":"string"},"description":"charge_paid, platform_fee, refund, refund_fee_return, withdrawal, withdrawal_fee, chargeback, adjustment. Vários separados por vírgula."},{"in":"query","name":"start_date","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"end_date","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Extrato paginado"}}}},"/v1/withdrawals":{"post":{"tags":["Saques"],"summary":"Solicita um saque","description":"Envia o saldo disponível para a chave PIX cadastrada na sua conta. Sem `amount`, saca tudo o que estiver disponível.\n\nA resposta é sempre uma lista. Um saque grande pode ser atendido por mais de uma transferência para o mesmo destino, e devolver lista desde o começo evita que a sua integração quebre no dia em que isso acontecer.\n","parameters":[{"in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","description":"Em centavos. Ausente saca todo o disponível."}}}}}},"responses":{"201":{"description":"Saque solicitado"},"422":{"description":"Saldo insuficiente","valor abaixo do mínimo ou chave PIX não cadastrada":null}}},"get":{"tags":["Saques"],"summary":"Lista os saques","parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["pending","processing","paid","failed","canceled"]}}],"responses":{"200":{"description":"Lista paginada"}}}},"/v1/withdrawals/{id}":{"get":{"tags":["Saques"],"summary":"Situação de um saque","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Saque"},"404":{"description":"Saque não encontrado"}}}},"/v1/withdrawals/{id}/cancel":{"post":{"tags":["Saques"],"summary":"Cancela um saque ainda não enviado","description":"Só vale enquanto o saque está em `pending`. Depois de enviado, o dinheiro já está a caminho.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Saque cancelado e valor devolvido ao saldo"}}}},"/v1/withdrawals/settings":{"put":{"tags":["Saques"],"summary":"Liga ou desliga o saque automático","description":"Com o automático ligado, o saldo que fica disponível é enviado sozinho, sem você precisar pedir. Pode não estar habilitado nesta instalação.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["enabled"],"properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Preferência salva"},"422":{"description":"Saque automático indisponível nesta instalação"}}}},"/v1/account":{"get":{"tags":["Conta"],"summary":"Dados da sua conta e situação da habilitação","description":"Traz também `publishable_key`, a chave usada pelo campo de cartão embutido no seu checkout. Ela não é segredo: pode ficar no HTML da sua página, porque sozinha não consulta, não cria e não move dinheiro. Diferente da chave de API, que nunca pode ir para o navegador.\n","responses":{"200":{"description":"Conta"}}},"put":{"tags":["Conta"],"summary":"Atualiza o cadastro","description":"Trocar a chave PIX derruba a habilitação do PIX e exige novo envio do cadastro: a conta de recebimento é identificada pela própria chave, então mudá-la cria outra conta em vez de editar a existente.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"legal_name":{"type":"string","description":"Razão social ou nome completo"},"trade_name":{"type":"string","description":"Nome fantasia"},"document":{"type":"string","description":"CPF ou CNPJ"},"birth_date":{"type":"string","format":"date","description":"Obrigatório para CPF que vende no cartão"},"phone":{"type":"string"},"website":{"type":"string"},"pix_key":{"type":"string","description":"Chave PIX que receberá os saques"},"statement_descriptor":{"type":"string","maxLength":22},"address":{"type":"object","properties":{"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"district":{"type":"string"},"city":{"type":"string"},"state":{"type":"string","maxLength":2},"zipcode":{"type":"string"}}},"brand":{"type":"object","description":"Marca usada no checkout hospedado","properties":{"name":{"type":"string"},"color":{"type":"string","example":"#16a34a"},"logo_url":{"type":"string"}}}}}}}},"responses":{"200":{"description":"Conta atualizada"}}}},"/v1/account/onboarding":{"post":{"tags":["Conta"],"summary":"Envia o cadastro para habilitar o recebimento","description":"Habilita a conta para receber nos meios de pagamento indicados. A habilitação é por meio de pagamento: quem só vende no PIX não passa pela verificação mais longa exigida para o cartão.\n\nPode ser chamado quantas vezes for preciso. Cada envio atualiza a análise em andamento em vez de recomeçar.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payment_methods":{"type":"array","items":{"type":"string","enum":["pix","card"]},"description":"Ausente habilita todos os disponíveis"}}}}}},"responses":{"200":{"description":"Cadastro enviado"},"422":{"description":"Faltam dados; a resposta traz a lista em requirements"}}}},"/v1/business-categories":{"get":{"tags":["Conta"],"summary":"Os ramos de atividade aceitos","description":"O ramo de atividade não é texto livre: vai como um código de uma tabela fechada da indústria de cartões. Esta rota devolve os que aceitamos, com o rótulo já escrito do jeito que o vendedor reconhece o próprio negócio.\n\nMande o `code` em `PUT /v1/account`, no campo `mcc`. Informar o ramo evita uma pergunta no formulário de verificação.\n","responses":{"200":{"description":"Lista","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"list"},"data":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"5691"},"label":{"type":"string","example":"Roupas e acessórios"}}}}}}}}}}}},"/v1/account/representative":{"get":{"tags":["Conta"],"summary":"Quem responde legalmente pela conta","description":"O CPF sai mascarado, como a chave PIX.","responses":{"200":{"description":"Responsável"},"404":{"description":"Nenhum responsável cadastrado"}}},"put":{"tags":["Conta"],"summary":"Cadastra ou corrige o responsável","description":"A verificação de identidade do cartão pergunta quem responde pela empresa, e pergunta bastante. Cada campo informado aqui é uma pergunta a menos no formulário de `POST /v1/account/onboarding/session`.\n\nMedido contra o provedor: com o responsável enviado por aqui, o que sobra para o formulário cai de dezoito itens para sete. O que resta é a prova de vida, que é selfie ou credencial eletrônica e não existe por API.\n\nO `document` é o CPF da pessoa, nunca o CNPJ da empresa. Na primeira chamada os campos de nome, sobrenome e CPF são obrigatórios; depois dela, mande só o que muda.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"given_name":{"type":"string"},"surname":{"type":"string"},"document":{"type":"string","description":"CPF da pessoa"},"birth_date":{"type":"string","format":"date"},"email":{"type":"string"},"phone":{"type":"string"},"title":{"type":"string","description":"Cargo","como \"Sócio administrador\"":null},"political_exposure":{"type":"string","enum":["none","existing","former"],"description":"Se exerce ou exerceu cargo público relevante"},"percent_ownership":{"type":"number","description":"Participação","de 0 a 100":null},"address_street":{"type":"string"},"address_number":{"type":"string"},"address_complement":{"type":"string"},"address_district":{"type":"string"},"address_city":{"type":"string"},"address_state":{"type":"string"},"address_zipcode":{"type":"string"}}}}}},"responses":{"200":{"description":"Responsável gravado"},"422":{"description":"Dado inválido; a resposta diz qual campo"}}}},"/v1/account/onboarding/session":{"post":{"tags":["Conta"],"summary":"Abre o formulário de verificação de identidade","description":"A habilitação no cartão tem uma etapa que não se resolve por API: a verificação de identidade de quem responde pela conta, que envolve documento e prova de vida. Esta rota devolve o necessário para exibir esse formulário dentro da sua tela.\n\nEnvie o cadastro por POST /v1/account/onboarding antes: sem a conta criada não há o que verificar, e a resposta aqui é 403.\n\nPara montar: carregue o script indicado em `embed.script`, chame `init` no objeto que ele publica em `window` sob o nome de `embed.global`, passando a `publishable_key` e uma função que busque um `client_secret` nesta rota. Depois insira na página um elemento com o nome que vem em `embed.element`.\n\nO endereço do script vem na resposta em vez de fixo no seu código de propósito. É a única parte do produto em que a plataforma por trás do cartão aparece, e ela aparece porque roda no navegador do vendedor. Lendo daqui, o seu código continua igual se um dia ela mudar.\n\nO `client_secret` é de uso único e expira em minutos. Peça um novo a cada vez que montar o formulário, em vez de guardar. Ele vale apenas para esta conta.\n","responses":{"200":{"description":"Sessão aberta","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"verification_session"},"client_secret":{"type":"string","description":"Uso único","expira em minutos":null},"publishable_key":{"type":"string","description":"Chave pública","usada só no navegador":null},"expires_at":{"type":"string","format":"date-time"},"embed":{"type":"object","description":"O que carregar no navegador","properties":{"script":{"type":"string","description":"Endereço do script a carregar"},"global":{"type":"string","description":"Nome do objeto que o script publica em window"},"element":{"type":"string","description":"Nome do elemento a inserir na página"}}}}}}}},"403":{"description":"O cadastro ainda não foi enviado"},"503":{"description":"Cartão não disponível nesta instalação"}}}},"/v1/account/requirements":{"get":{"tags":["Conta"],"summary":"O que ainda falta para a conta ficar habilitada","description":"Cada item traz o campo, o rótulo e uma instrução do que fazer. É esta a rota para consultar enquanto acompanha a análise, em vez da conta inteira.\n\nO `source` diz onde a pendência se resolve. `account` é campo do cadastro e se preenche em PUT /v1/account, um a um. `verification` é coletado de uma vez pelo formulário de POST /v1/account/onboarding/session, e não existe como campo do cadastro: procurar por ele ali não leva a lugar nenhum.\n","responses":{"200":{"description":"Pendências","content":{"application/json":{"schema":{"type":"object","properties":{"onboarding_status":{"type":"string"},"capabilities":{"type":"object"},"data":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"label":{"type":"string"},"instruction":{"type":"string"},"source":{"type":"string","enum":["account","verification"]},"blocking":{"type":"boolean"},"due_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}}}}},"/v1/account/sync":{"post":{"tags":["Conta"],"summary":"Reconsulta a situação da habilitação","description":"A situação também é atualizada sozinha, em varredura periódica. Esta rota serve para quem acabou de enviar um documento e não quer esperar a próxima.\n","responses":{"200":{"description":"Situação atual","com o que ainda falta em requirements":null}}}},"/v1/account/webhook":{"get":{"tags":["Webhooks"],"summary":"Configuração do webhook e o segredo de assinatura","responses":{"200":{"description":"Configuração"}}},"put":{"tags":["Webhooks"],"summary":"Define a URL e os eventos do webhook","description":"Toda notificação vai assinada no header `X-Alktea-Signature`, no formato `t=<epoch>,v1=<hmac>`. O HMAC é SHA-256 sobre `<t>.<corpo cru>` com o seu segredo. Confira a assinatura antes de confiar no conteúdo, e recuse eventos com `t` muito antigo para evitar reenvio malicioso de uma notificação antiga.\n\nA entrega é ao menos uma vez, nunca exatamente uma vez: trate repetição usando o `event.id`, que é estável entre as tentativas.\n\nSe você é parceiro, este mesmo webhook recebe os eventos dos vendedores que trouxe, sem precisar configurar nada por vendedor. A cópia deles traz um campo `seller` no topo do evento, com o identificador e o nome de quem vendeu; evento sem `seller` é venda da sua própria conta.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"},"description":"Ausente ou nulo assina todos"}}}}}},"responses":{"200":{"description":"Webhook atualizado"}}}},"/v1/account/webhook/secret":{"post":{"tags":["Webhooks"],"summary":"Gera um segredo de assinatura novo","description":"O segredo anterior para de valer na hora. Troque no seu servidor antes de chamar, senão as notificações passam a chegar com assinatura que o seu código não reconhece.\n","responses":{"200":{"description":"Segredo novo"}}}},"/v1/account/bank-account":{"put":{"tags":["Conta"],"summary":"Conta bancária que recebe o repasse do cartão","description":"No cartão o dinheiro não é sacado: o processador repassa sozinho para esta conta. No Brasil esse repasse é sempre automático e diário, e sem a conta cadastrada o valor fica parado sem nunca chegar em você. Informe o número com o dígito, sem separador.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bank_code","branch","account","holder_name"],"properties":{"bank_code":{"type":"string","example":"341","description":"Três dígitos"},"branch":{"type":"string","example":"0001","description":"Sem o dígito verificador"},"account":{"type":"string","example":"123456","description":"Com o dígito","sem separador":null},"holder_name":{"type":"string","example":"Salão da Ana LTDA"},"type":{"type":"string","enum":["checking","savings"],"default":"checking"}}}}}},"responses":{"200":{"description":"Conta registrada"},"403":{"description":"Envie o cadastro para habilitação antes"},"422":{"description":"Dados bancários inválidos"}}}},"/v1/account/webhook/test":{"post":{"tags":["Webhooks"],"summary":"Dispara uma entrega de teste","description":"Manda um evento `webhook.test` para o endereço cadastrado, assinado do mesmo jeito que os de verdade. Serve para conferir a conferência de assinatura antes da primeira venda.\n","responses":{"200":{"description":"Resultado da entrega","com o código que o seu servidor respondeu":null},"422":{"description":"Nenhum endereço cadastrado"}}}},"/v1/account/api-keys":{"get":{"tags":["Conta"],"summary":"Lista as chaves de API","responses":{"200":{"description":"Lista de chaves","sem o valor delas":null}}},"post":{"tags":["Conta"],"summary":"Cria uma chave de API","description":"A chave em texto aparece uma única vez, nesta resposta. Guardamos apenas o hash, então nem o suporte consegue recuperá-la depois: quem perder a chave gera outra e revoga a antiga.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"environment":{"type":"string","enum":["live","test"],"default":"live"}}}}}},"responses":{"201":{"description":"Chave criada"}}}},"/v1/account/api-keys/{id}":{"delete":{"tags":["Conta"],"summary":"Revoga uma chave de API","description":"A revogação vale na hora e não tem volta. Crie a chave nova e troque no seu sistema antes de revogar a antiga, senão a integração fica fora do ar no meio.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Chave revogada"},"404":{"description":"Chave não encontrada"}}}},"/v1/fees":{"get":{"tags":["Taxas"],"summary":"Tabela de taxas da sua conta","responses":{"200":{"description":"Faixas de taxa por meio de pagamento"}}}},"/v1/fees/simulate":{"get":{"tags":["Taxas"],"summary":"Simula quanto você recebe por uma venda","parameters":[{"in":"query","name":"amount","required":true,"schema":{"type":"integer"},"description":"Valor em centavos"},{"in":"query","name":"payment_method","schema":{"type":"string","enum":["pix","card"],"default":"pix"}},{"in":"query","name":"installments","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Simulação com taxa","líquido e data de liberação":null}}}},"/v1/payment-methods":{"get":{"tags":["Taxas"],"summary":"Meios de pagamento que a sua conta pode usar agora","responses":{"200":{"description":"Lista com a situação de cada meio"}}}},"/v1/alktea.js":{"get":{"tags":["Checkout"],"summary":"SDK do campo de cartão embutido","security":[],"description":"Arquivo JavaScript público, carregado por uma tag `script` no seu checkout. Não exige autenticação: o que autoriza uma operação é o `client_token` da cobrança, que você busca no seu backend.\n\n**Para que serve.** Permite manter o comprador dentro do seu site e usar o nosso campo apenas para os dados do cartão. Layout, cores, tipografia, resumo do pedido, endereço, parcelas e botão continuam sendo seus.\n\n**Por que o campo é um quadro isolado.** O número do cartão não pode passar pelo seu servidor nem pelo seu JavaScript: se passasse, o seu questionário de conformidade PCI saltaria de 22 para 61 requisitos. Com o campo isolado, esse custo fica com a plataforma. O registro de domínio exigido por Apple Pay e Google Pay também é feito uma vez por nós, e não por cada loja.\n\n```html <script src=\"/v1/alktea.js\"></script> <div id=\"campo-cartao\"></div>\n<script>\n  const alktea = Alktea('apk_...');          // publishable_key da cobrança\n  const cartao = alktea.card({\n    clientToken: 'ctk_...',                  // client_token da cobrança\n    modo: 'cartao',                          // ou 'completo'\n    layout: 'empilhado',                     // ou 'linha'\n    aparencia: { fonte: \"'Inter'\", raio: '10px', borda: '1px solid #e2e8f0' }\n  });\n  cartao.mount('#campo-cartao');\n\n  cartao.on('mudou', e => botao.disabled = !e.completo);\n  cartao.on('erro',  e => mostrarErro(e.mensagem));\n\n  const { erro, cobranca } = await cartao.pagar({ titular: 'NOME NO CARTAO' });\n</script> ```\n\n`pagar()` nunca lança exceção: devolve `{ erro }` ou `{ cobranca }`. Quando o banco pede autenticação, o quadro se expande sozinho para o desafio caber na tela e volta ao normal depois.\n\n**Libere o pedido pelo webhook `charge.paid`**, e não por esta resposta: o navegador do comprador pode fechar entre a autorização e o retorno.\n\nExemplo completo e funcional em `/exemplo-checkout`.\n","responses":{"200":{"description":"O arquivo JavaScript","content":{"application/javascript":{"schema":{"type":"string"}}}}}}},"/v1/partner/sellers":{"get":{"tags":["Parceiros"],"summary":"Lista os vendedores que você traz","description":"Disponível apenas para contas habilitadas como parceiro. Um parceiro é um cliente que revende a plataforma: ele traz vendedores, cobra uma comissão sobre as vendas deles e recebe essa comissão no próprio saldo.\n\nA verificação de cadastro dos vendedores é feita pela plataforma, não por você: as contas nos processadores são da plataforma. Você envia os dados e acompanha as pendências, e os vendedores permanecem mesmo que a sua conta seja encerrada.\n","parameters":[{"in":"query","name":"q","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["active","inactive","suspended"]}}],"responses":{"200":{"description":"Lista paginada"},"403":{"description":"Esta conta não é parceira"}}},"post":{"tags":["Parceiros"],"summary":"Cadastra um vendedor sob a sua conta","description":"A senha é opcional: sem ela, o vendedor nunca acessa o painel e existe apenas como destino de repasse, operado pelo seu sistema. É o caso mais comum, e evita você inventar e guardar senha de terceiro.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"password":{"type":"string","description":"Opcional. Sem ela, o vendedor não acessa o painel."},"legal_name":{"type":"string"},"document":{"type":"string"},"phone":{"type":"string"},"pix_key":{"type":"string","description":"Onde o vendedor recebe os saques"}}}}}},"responses":{"201":{"description":"Vendedor criado"}}}},"/v1/partner/sellers/{id}":{"get":{"tags":["Parceiros"],"summary":"Consulta um vendedor seu","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Vendedor"},"404":{"description":"Não encontrado nesta conta"}}},"put":{"tags":["Parceiros"],"summary":"Atualiza o cadastro de um vendedor seu","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Vendedor atualizado"}}}},"/v1/partner/sellers/{id}/onboarding":{"post":{"tags":["Parceiros"],"summary":"Envia o cadastro do vendedor para habilitação","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Enviado"},"422":{"description":"Faltam dados; a resposta traz a lista em requirements"}}}},"/v1/partner/sellers/{id}/onboarding/session":{"post":{"tags":["Parceiros"],"summary":"Abre o formulário de verificação do vendedor","description":"O mesmo formulário de POST /v1/account/onboarding/session, aberto por você em nome do vendedor. É por aqui que o vendedor que nunca entra no nosso painel conclui a verificação de identidade, dentro do sistema que você entrega a ele.\n\nO `client_secret` vale apenas para a conta deste vendedor e expira em minutos.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Sessão aberta"},"403":{"description":"O cadastro do vendedor ainda não foi enviado"},"404":{"description":"Não encontrado nesta conta"}}}},"/v1/partner/sellers/{id}/representative":{"put":{"tags":["Parceiros"],"summary":"Cadastra o responsável legal do vendedor","description":"O mesmo de PUT /v1/account/representative, feito por você em nome do vendedor. Cada campo aqui é uma pergunta a menos no formulário de verificação que ele vai ver.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Responsável gravado"},"404":{"description":"Não encontrado nesta conta"}}}},"/v1/partner/sellers/{id}/api-keys":{"post":{"tags":["Parceiros"],"summary":"Emite uma chave de API do vendedor","description":"Você integra em nome dele, então a chave sai no seu nome mas pertence à conta dele. Ela dá acesso completo a essa conta: criar cobrança, estornar, consultar saldo e sacar. Guarde no momento da criação, porque não é possível exibi-la de novo. A emissão fica registrada no histórico do vendedor identificando que partiu de você.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Checkout do meu sistema"},"environment":{"type":"string","enum":["live","test"],"default":"live"}}}}}},"responses":{"201":{"description":"Chave criada; o valor aparece uma única vez"},"404":{"description":"Vendedor não encontrado nesta conta"}}},"get":{"tags":["Parceiros"],"summary":"As chaves de API daquele vendedor","description":"Sem o valor das chaves, que só existe como hash. Sai prefixo e final, o suficiente para reconhecer qual é qual antes de revogar a errada.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de chaves"}}}},"/v1/partner/sellers/{id}/api-keys/{keyId}":{"delete":{"tags":["Parceiros"],"summary":"Revoga uma chave do vendedor","description":"Vale na hora e não tem volta. Crie a nova e troque no seu sistema antes de revogar a antiga, senão a integração dele fica fora do ar no meio.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"keyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Chave revogada"},"404":{"description":"Chave não encontrada nesta conta"}}}},"/v1/partner/sellers/{id}/password":{"put":{"tags":["Parceiros"],"summary":"Redefine a senha do painel do vendedor","description":"O \"esqueci minha senha\" do vendedor final é seu, não nosso: você recebe o pedido no seu sistema, escolhe a senha nova e a define aqui. Não existe recuperação por e-mail do nosso lado, de propósito, porque o e-mail que o vendedor reconhece é o seu. A senha não volta na resposta, e a troca encerra as sessões que aquele vendedor tiver abertas.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["password"],"properties":{"password":{"type":"string","minLength":8}}}}}},"responses":{"200":{"description":"Senha redefinida"},"404":{"description":"Vendedor não encontrado nesta conta"},"422":{"description":"Senha com menos de 8 caracteres"}}}},"/v1/partner/sellers/{id}/bank-account":{"put":{"tags":["Parceiros"],"summary":"Conta bancária do vendedor, que recebe o repasse do cartão","description":"No cartão o dinheiro não é sacado: o processador repassa sozinho para esta conta. Sem ela cadastrada o valor fica parado sem chegar nele. Os campos são os mesmos de PUT /v1/account/bank-account.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Conta registrada"},"403":{"description":"Envie o cadastro para habilitação antes"}}}},"/v1/partner/sellers/{id}/commission":{"put":{"tags":["Parceiros"],"summary":"Define a sua comissão sobre um vendedor","description":"Sem comissão específica, vale o padrão definido na sua conta. Não há teto: quanto você cobra de quem você traz é acordo entre vocês. O único limite é aritmético, a comissão não passa do que sobra depois da taxa da plataforma.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_method","percent"],"properties":{"payment_method":{"type":"string","enum":["pix","card"]},"percent":{"type":"number","example":2.5},"fixed":{"type":"integer","description":"Em centavos","default":0}}}}}},"responses":{"200":{"description":"Comissão definida"},"422":{"description":"Percentual inválido"}}}},"/v1/partner/sellers/{id}/simulate":{"get":{"tags":["Parceiros"],"summary":"Simula uma venda e mostra as três fatias","description":"Numa venda de tanto, quanto fica com o vendedor, quanto fica com você e quanto fica com a plataforma. Usa o mesmo cálculo da venda de verdade, então o número aqui é o número que vai sair. `seller_fee` é a taxa única que o vendedor enxerga: a soma da nossa com a sua.\n","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"query","name":"amount","required":true,"schema":{"type":"integer"},"description":"Em centavos"},{"in":"query","name":"payment_method","schema":{"type":"string","enum":["pix","card"],"default":"pix"}},{"in":"query","name":"installments","schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Simulação"},"404":{"description":"Vendedor não encontrado nesta conta"}}}},"/v1/partner/commissions":{"get":{"tags":["Parceiros"],"summary":"Todas as comissões que você cobra","responses":{"200":{"description":"Padrão da conta e acordos por vendedor"}}}},"/v1/partner/revenue":{"get":{"tags":["Parceiros"],"summary":"Sua receita de comissão, por vendedor","description":"`held` é o que ainda está retido. A comissão libera depois do prazo da sua conta, e não junto com o dinheiro do vendedor: enquanto está retida, ela cobre uma eventual contestação de venda que você trouxe.\n","parameters":[{"in":"query","name":"start_date","schema":{"type":"string","format":"date-time"}},{"in":"query","name":"end_date","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Relatório de comissões"}}}},"/v1/partner/summary":{"get":{"tags":["Parceiros"],"summary":"Números gerais da sua carteira de vendedores","description":"Quantos vendedores você tem, quantos já estão habilitados a receber, e o volume que eles movimentaram com a sua comissão dentro.\n","responses":{"200":{"description":"Resumo"}}}},"/v1/disputes":{"get":{"tags":["Contestações"],"summary":"Lista as contestações de cartão","description":"Quando uma contestação é aberta, o valor sai do seu saldo imediatamente, porque o dinheiro já foi retido do outro lado. Se a contestação for ganha, o valor volta.\n","responses":{"200":{"description":"Lista paginada"}}}},"/auth/client/login":{"post":{"tags":["Auth"],"summary":"Login do painel do vendedor","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Token JWT válido por 24 horas"},"401":{"description":"Credenciais inválidas"}}}},"/auth/admin/login":{"post":{"tags":["Auth"],"summary":"Login do painel administrativo","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["username","password"],"properties":{"username":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Token JWT válido por 24 horas"},"401":{"description":"Credenciais inválidas"}}}}}}