Skip to main content

​
Autenticação

Cada requisição à Business API deve incluir uma API key válida no header X-API-Key.

​
Obter uma API Key

As API keys são gerenciadas pelo Dashboard da YaVendio — não existe um endpoint programático para gerenciamento de keys.
1

Navegar até configurações de APIs

Faça login no Dashboard da YaVendio e vá para Configurações → Chaves API.
2

Criar uma nova key

Clique em “Criar API Key”. Atribua um nome descritivo (ex. “Integração ERP”).
3

Copiar sua key

A key completa é exibida apenas uma vez no momento da criação. Copie-a e armazene-a de forma segura. Depois o dashboard mantém apenas o prefixo (yv_live_v1_Xk3Rt9pQz...) para identificação.

​
Formato da Key

Uma key tem a forma yv_live_v1_ seguida de 43 caracteres aleatórios:
O dashboard sempre cria keys do tipo live. Não existe ambiente sandbox: uma key de teste operaria sobre os mesmos dados produtivos, então não há uma versão “segura” da credencial para experimentar.

​
Usar a API Key

Inclua a key em cada requisição através do header X-API-Key:

​
Escopos

Hoje todas as API keys possuem acesso completo a todos os endpoints: o dashboard cria as keys sem escopos atribuídos e ainda não oferece onde escolhê-los. O modelo de escopos já está implementado na API. Cada endpoint declara o seu — orders:read, products:read, products:write, conversations:read, contacts:read, company:read, webhooks:read, webhooks:write, outbound:send, outbound:read — e a página de referência de cada um indica qual corresponde. Se uma key tivesse escopos atribuídos e faltasse o que o endpoint exige, a requisição receberia 403 Forbidden:
403 Forbidden
Enquanto não for possível escolher escopos, trate cada key como uma credencial de acesso total: crie uma por integração e exclua-a quando parar de usá-la.

​
Estados da Key

As keys visíveis no dashboard possuem dois estados possíveis:

​
Informações no Dashboard

A tabela de API keys no dashboard mostra:
  • Nome — o nome que você atribuiu ao criar a key
  • Escopo — hoje sempre mostra “Pedidos e Produtos”, porque todas as keys são criadas com acesso completo
  • Status — Ativa ou Revogada
  • Secret Key — apenas o prefixo (yv_live_v1_Xk3Rt9pQz...)
  • Criada — quando a key foi criada
  • Último uso — data da última requisição feita com a key
Para excluir uma key, clique no ícone de lixeira ao lado dela. Esta ação é irreversível — qualquer integração usando a key começará a receber erros 401 imediatamente.

​
Respostas de Erro

401 Unauthorized

​
Boas Práticas

Nunca exponha sua API key em código do lado do cliente (JavaScript no navegador, apps móveis). Sempre chame a API pelo seu backend.
  • Use variáveis de ambiente para armazenar API keys — nunca as escreva diretamente no código fonte.
  • Crie keys separadas para cada integração ou ambiente (desenvolvimento, staging, produção).
  • Rotacione as keys periodicamente — exclua a key anterior e crie uma nova pelo dashboard.