Desenvolvedores: chaves e logs

A aba Desenvolvedores é onde a loja se liga a um sistema externo pela API: o seu SaaS, um ERP, um CRM ou um script seu. Nela você cria as chaves que o sistema usa para entrar e vê o registro de cada chamada que ele fez. O que o sistema consegue fazer com a chave, e como programar a integração, está na seção para desenvolvedores, a partir de Visão geral para desenvolvedores.

Abrir a abaCopiar link da seção

Abra Geral›Configurações › Desenvolvedores. A aba tem duas partes: as chaves de API e os logs de requisições.

Chaves de APICopiar link da seção

Uma chave de API é a senha que o seu sistema usa para falar com a loja. Quem tem a chave acessa os dados da loja, então trate como uma senha.

Criar uma chaveCopiar link da seção

1. Clique no botão de criar chave.
2. Dê um nome que diga onde ela vai ser usada, como "ERP" ou "Servidor de produção".
3. Escolha os escopos: leitura deixa consultar clientes, assinaturas, pedidos, ofertas e produtos; escrita vai deixar criar e alterar dados quando os endpoints de escrita forem lançados. Para um sistema que só lê, marque só leitura.
4. Copie a chave, que começa com vk_live_. Ela aparece uma vez só: fechou a janela, não dá mais para ver. Se perder, revogue e crie outra.

Passe a chave a quem vai programar a integração por um canal seguro, nunca por e-mail ou mensagem em texto puro. Quem programa deve guardá-la numa variável de ambiente, como explica Autenticação e chaves de API.

A lista de chavesCopiar link da seção

Cada chave mostra o nome, os últimos quatro caracteres (o resto não é guardado), os escopos, a versão da API em que foi criada, quando foi criada e quando foi usada pela última vez. A data de último uso diz se a integração está viva e, na hora de trocar uma chave, se a antiga já parou de ser usada.

Revogar uma chaveCopiar link da seção

Use a ação de revogar na linha da chave. A chave para de funcionar na hora e o sistema que a usava passa a receber um erro de autenticação. Não dá para desfazer. Para trocar uma chave sem parar a integração: crie a nova, peça para publicarem, espere a antiga ficar sem uso e só então revogue a antiga.

Logs de requisiçõesCopiar link da seção

Cada chamada que um sistema faz à API fica registrada: a data e a hora, qual chave usou, o método e o caminho (como GET /v1/orders), o código de resposta, a duração e, quando deu erro, o tipo e o código do erro. Cada linha tem um identificador req_…, o mesmo valor que a API devolve no cabeçalho Request-Id.

Os logs servem para:

• Confirmar que a integração está chamando a API, e com qual chave.
• Ver por que uma chamada falhou, sem precisar de acesso aos logs do outro sistema. O código do erro está explicado em Erros.
• Localizar uma chamada específica pelo req_… que o desenvolvedor ou o suporte informou.

Os logs ficam guardados por 30 dias e depois são apagados. Chamadas feitas sem uma chave válida não aparecem: sem a chave, o Vipter não sabe de qual loja seria a chamada.

Os logs mostram o que foi pedido e o resultado, não o conteúdo das respostas. Os dados dos clientes não ficam duplicados aqui.

O que significa "API desativada"Copiar link da seção

A API vem ativa em toda loja ativa; não há liberação a pedir. O Vipter pode desligá-la para uma loja específica, por abuso ou pendência na conta. Nesse caso a aba mostra o aviso, não dá para criar chaves e qualquer chamada, mesmo com uma chave válida, recebe o erro 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.

Problemas comunsCopiar link da seção

• A integração recebe erro de autenticação logo depois de criar a chave

  Confira se a chave foi copiada inteira, sem espaços no começo ou no fim, e se a API não foi desativada para a loja. Se a chave aparece como revogada na lista, crie outra.

• A chave aparece como nunca usada, mas o sistema diz que está chamando

  O sistema pode estar chamando outro endereço ou com outra chave. Compare o endereço e os últimos quatro caracteres da chave no sistema com a lista. A data de último uso pode levar até um minuto para aparecer.

• Uma chamada aparece com erro 403 insufficient_scope

  A chave não tem o escopo que a chamada exige. Crie uma chave com o escopo certo e troque no sistema.

• Muitas chamadas com erro 429

  O sistema passou do limite de 100 requisições a cada 2 segundos por chave. Quem programa deve respeitar o cabeçalho Retry-After; veja Limites de requisições.

O que fazer a seguirCopiar link da seção

• Passe a quem vai programar a Visão geral para desenvolvedores e a referência da API.
• Para receber avisos do Vipter no seu sistema, em vez de consultar, configure um webhook.