Autenticação e chaves de API

Toda requisição à API leva uma chave de API da loja. A chave identifica a loja e diz o que a requisição pode fazer. Não há usuário, senha nem sessão: quem tem a chave tem o acesso.

Criar uma chaveCopiar link da seção

1. Abra Geral›Configurações › Desenvolvedores.
2. Crie uma chave nova. Dê um nome que diga onde ela vai ser usada, como "ERP" ou "Servidor de produção", e escolha os escopos.
3. Copie o valor completo, vk_live_…. Ele aparece uma vez só. Depois disso, o painel mostra apenas os últimos quatro caracteres.

Cada chave fica presa a uma versão da API, a versão atual no dia em que ela foi criada. Veja Versão.

O passo a passo com o que o painel mostra está em Desenvolvedores: chaves e logs.

Formato da chaveCopiar link da seção

vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh

Letras e números, sem outros caracteres. Qualquer chave com outro formato é recusada com 401 invalid_api_key antes de consultar o banco.

Só existe o prefixo live. O Vipter não tem modo de teste; veja Testar sem modo de teste.

EscoposCopiar link da seção

Uma chave pode ter um ou os dois escopos. Uma requisição a um endpoint sem o escopo necessário recebe 403 insufficient_scope. Para uma integração que só lê dados, crie a chave só com read.

Usar a chaveCopiar link da seção

Envie a chave no cabeçalho Authorization, como um token Bearer:

curl https://api.vipter.com/v1/account \
  -H "Authorization: Bearer vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh"

A API também aceita HTTP Basic com a chave como usuário e senha vazia, o mesmo hábito dos exemplos da Stripe com -u. As duas formas são equivalentes:

curl https://api.vipter.com/v1/account \
  -u vk_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGh:

Os dois pontos no fim dizem ao curl que a senha é vazia. Sem eles, o curl pede a senha no terminal.

A chave vale para https://api.vipter.com/v1 e para https://app.vipter.com/api/v1; veja Endereço base.

Guardar a chaveCopiar link da seção

• Guarde a chave numa variável de ambiente ou num cofre de segredos. Nunca no código-fonte, num repositório ou numa página servida ao navegador.
• Use uma chave por sistema e por ambiente. Se uma vazar, você revoga só ela.
• A API não aceita chamadas do navegador com a chave: qualquer um que abrir a página teria a chave. Chame a API do seu servidor.
• Se uma chave apareceu num lugar público, revogue na hora e crie outra. O Vipter não tem como recuperar o valor de uma chave: só o hash do segredo fica gravado.

Revogar uma chaveCopiar link da seção

Na lista de chaves, use a ação de revogar. A chave para de funcionar na mesma hora: a próxima requisição com ela recebe 401 api_key_revoked. Não dá para desfazer. Para trocar uma chave sem parar a integração, crie a nova, publique, confira que a antiga parou de ser usada na coluna de último uso e só então revogue a antiga.

Chaves revogadas continuam na lista, para o histórico. Os logs de requisições mostram qual chave fez cada chamada.

A API vem ativa para toda lojaCopiar link da seção

Não há liberação a pedir: toda loja ativa responde à API assim que tem uma chave. O Vipter pode desligar a API de uma loja específica, por abuso ou pendência na conta. Nesse caso a aba Desenvolvedores avisa e toda requisição, mesmo com uma chave válida, recebe 403 api_not_enabled. Para reativar, fale com o suporte do Vipter e informe o nome da loja. As chaves existentes voltam a funcionar assim que a API é religada.

A API também só responde para lojas ativas. Uma loja suspensa ou em outro estado recebe 403 project_inactive.

Testar sem modo de testeCopiar link da seção

O Vipter não tem chaves de teste nem um ambiente separado. O teste acontece na mesma loja, com uma conexão de teste do provedor de pagamento:

1. Em Pagamentos›Provedores, crie uma conexão com Conexão de teste ligado. Ela usa o ambiente de testes do provedor e não cobra ninguém de verdade.
2. Faça uma compra pelo checkout com essa conexão. Veja Testar a sua loja.
3. Consulte o pedido pela API. Um pedido que passou por uma conexão de teste vem com "livemode": false. Clientes, assinaturas, ofertas e produtos não têm conexão, então vêm com "livemode": true.

Como o teste acontece na loja real, os pedidos de teste aparecem no painel e nos relatórios junto com os de verdade. Use o campo livemode para separá-los no seu sistema.

Erros de autenticaçãoCopiar link da seção

Todos vêm no formato padrão de erro. Um 401 é sobre a chave; um 403 é sobre o que a chave pode fazer ou sobre a loja.

Requisições sem chave válida são limitadas por endereço IP, a 10 por minuto. Passou disso, a resposta é 429 rate_limit até a janela liberar. Isso protege contra tentativa de adivinhar chaves e não afeta chamadas autenticadas, que têm o próprio limite.

O que fazer a seguirCopiar link da seção

• Leia as convenções da API: formato, erros, paginação e limites.
• Faça a primeira chamada e veja cada objeto na referência da API.