A API usa uma chave estática, enviada no cabeçalho Authorization: Bearer <chave>. Não há OAuth, token de curta duração nem refresh. Todas as chamadas usam a base https://app.dotfy.com.br, no prefixo /api.
Como gerar e testar
- No painel, em Configurações, crie uma chave de API. A autenticação em duas etapas é exigida para emitir chaves.
- Guarde a chave num cofre de segredos. Ela aparece uma única vez.
- Chame
GET /api/auth/me. Se responder200, a chave é válida e você vê de qual conta ela é.
Cuidados com a chave
- A chave é credencial de saque. Autenticado por chave, o saque não pede a segunda prova que o painel exige.
- Nunca coloque a chave no repositório ou no front-end. Troque-a ao menor sinal de exposição.
- A API é só de servidor para servidor. Ela não envia cabeçalhos CORS, então chamadas pelo navegador são bloqueadas.
- Chaves de API são pessoais e intransferíveis.
Não existe ambiente de teste
O prefixo vk_test_ é apenas um rótulo. Ele não aponta para um sandbox e não impede movimentação de dinheiro. Cobranças criadas com ele são reais, e saques saem de verdade.
A simulação de pagamento funciona só em contas sandbox. Em conta comum, ela responde 403.
Escopos
Cada chave carrega escopos no formato recurso:ação, como charges:read e charges:write. Eles cobrem cobranças, clientes, saldo, saques, chaves PIX, webhooks, produtos, splits e subcontas.
O escopo só é verificado em parte das rotas. Não use o escopo como sua única camada de controle de acesso.
Quando a chave é recusada
401comtype: authentication_error: chave ausente, inválida, inativa ou expirada, ou rota que não aceita chave de API. A lista de rotas que aceitam está no guia.403comtype: insufficient_scope: falta um escopo. O camporequired_scopediz qual.
Para a lista completa de escopos e rotas, veja o guia de Autenticação.