API e desenvolvedores

Autenticação

Como autenticar requisições usando API keys

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. 1

    Navegar até configurações de APIs

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

  2. 2

    Criar uma nova key

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

  3. 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:

yv_live_v1_Xk3Rt9pQzL7mN2vB8cD4fG6hJ1kM5nP0rS9tU3wY7xZ

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:

curl -H "X-API-Key: yv_live_v1_sua_api_key" \
  https://api.ya.onl/v1/orders

Escopos

Uma key criada no dashboard tem acesso a todos os endpoints exceto a criação de pedidos: ela é criada sem escopos atribuídos, o que concede todos menos orders:write.

O modelo de escopos já está implementado na API. Cada endpoint declara o seu — orders:read, orders:write, 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.

orders:write permite registrar vendas com POST /v1/orders, e é o único escopo que uma key não tem por padrão: só o tem a key à qual ele foi concedido explicitamente ao criá-la. Uma key sem o escopo que o endpoint exige recebe 403 Forbidden:

{
  "type": "ForbiddenError",
  "detail": "Missing required scope: orders:read"
}

Trate cada key como uma credencial de acesso total: crie uma por integração e exclua-a quando parar de usá-la. Uma key com orders:write também registra vendas em nome da sua loja: conceda-o só à integração que as envia.

Estados da Key

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

Estado Significado
Ativa A key é válida e aceita requisições
Revogada A key foi desativada e todas as requisições são rejeitadas com 401

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

Status Quando
401 Unauthorized API key ausente, inválida, expirada ou revogada
403 Forbidden A key é válida mas não tem o escopo que o endpoint exige. Com uma key do dashboard você só o verá em POST /v1/orders, se a key não tiver orders:write 
{
  "type": "UnauthorizedError",
  "detail": "Invalid or missing API key"
}

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.
Precisa de ajuda?