API de parceiros

API de servidor a servidor para parceiros: emita uma chave, leia a configuração da vitrine e os locais, crie clientes, conceda planos e gerencie os links de assinatura no seu próprio site ou bot do Telegram.

A API de parceiros permite criar o seu próprio site, o seu próprio painel ou um bot do Telegram sobre o CreateYourVPN.

A API abrange clientes, assinaturas, planos e a configuração da vitrine. A infraestrutura, como servidores, nós, painéis e credenciais SSH, fica fora do contrato público.

Somente servidor a servidor. Guarde as chaves de API no seu servidor e não as inclua no código do frontend. Solicitações com cabeçalhos de navegador são rejeitadas com 403 browser_forbidden.

Como obter uma chave

Abra o painel → menu da conta → "API", aba "Chaves".

Dê um nome à chave (bot do Telegram, landing page) e escolha só as permissões de que ela precisa.

Clique em "Emitir chave" e copie o valor completo. O segredo é exibido uma única vez, porque só o hash dele fica armazenado.

Cada parceiro pode ter até 5 chaves ativas. Para trocar uma chave, emita uma nova, atualize a integração e depois revogue a antiga.

Autenticação

Envie a chave como token bearer:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… também funciona, para clientes em que um proxy ocupa o Authorization.

Uma chave tem o formato cyv_live_<key_id>_<secret>. A primeira metade (key_id) é pública: é ela que você vê no painel e que pode informar ao suporte sem risco. A segunda metade é o segredo.

Permissões (scopes)

Permissão	O que permite
`config:read`	Ler a configuração da vitrine, os planos, os locais e `/me`.
`users:read`	Ler os clientes, as assinaturas deles e o tráfego.
`users:write`	Criar clientes, conceder planos, redefinir links de assinatura, excluir clientes.

config:read basta para integrações que só leem dados da vitrine. Adicione users:read ou users:write apenas quando a integração precisar das operações correspondentes com clientes.

Contrato da API e exemplos

O contrato completo e executável fica na coleção pública do Postman. Ela contém todos os endpoints, permissões, parâmetros, corpos de solicitação, exemplos de resposta e códigos de erro estáveis. A coleção é gerada a partir do contrato do backend e é a fonte atual dos esquemas de solicitação e resposta.

Abrir a coleção pública do Postman

Explore a API e copie a coleção para seu workspace.

Limites de solicitações

Os limites são contados separadamente para cada chave, independentemente do endereço IP da solicitação.

120 solicitações/minuto por chave no total.
10 solicitações/minuto especificamente para GET /users.

GET /users tem um limite próprio porque cada solicitação carrega a lista completa de clientes. Para consultas regulares, use GET /users/{id} ou a busca por externalId.

Padrão de acesso recomendado. Guarde o ID de cliente do CreateYourVPN retornado na criação e use GET /users/{id} nas consultas seguintes. Você pode associá-lo ao seu próprio identificador por meio de externalId.

Idempotência

Três operações exigem o cabeçalho Idempotency-Key: conceder um plano, redefinir um link de assinatura e excluir um cliente.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

Repetir uma solicitação com a mesma chave dentro de 24 horas retorna a resposta armazenada em vez de executar a operação de novo. Isso evita alterações duplicadas quando uma integração tenta de novo após um timeout.

Crie uma chave para cada evento de negócio (por exemplo, um pagamento ou uma ação) e reutilize-a em todas as novas tentativas desse evento.

Se a primeira tentativa ainda estiver em andamento, ou se o resultado dela for temporariamente desconhecido, a API retorna 409 conflict sem executar a operação de novo. Verifique o estado atual do cliente antes de decidir se vai tentar de novo.

Use a coleção pública do Postman acima como referência para os esquemas de solicitação e resposta.