Perguntas frequentes
Respostas curtas para as dúvidas mais comuns de quem faz a primeira integração com a API da Venddor.
As perguntas abaixo aparecem em quase toda primeira integração. Cada resposta é curta e aponta para a página que explica a fundo.
Credenciais
Qual usuário devo usar para a integração?
Crie um usuário administrador só para a integração, com os privilégios mínimos de que ela precisa. Assim, quando alguém da equipe sai, a integração continua funcionando. O passo a passo está em Autenticação.
O meu token expirou rápido. Como renovo?
O access_token é de curta duração. Use o refresh_token em POST /api/v1/auth/refresh antes de expires_at, e guarde o par novo, porque o refresh_token anterior deixa de valer.
Por que o login responde 429?
Dois motivos possíveis: o limite de 5 logins por minuto por IP (rate limit exceeded), ou o bloqueio da conta por senhas erradas (account_locked). Em ambos, espere o Retry-After. Para não bater no limite, faça login uma vez e reutilize o token.
Um parceiro precisa de acesso só de leitura aos pedidos. Dou a minha senha?
Não. Use um token de app com o escopo read_orders: o administrador aprova a instalação e pode revogá-la na hora. Veja Tokens e escopos.
Lojas e ambientes
Preciso mandar o X-Tenant-ID?
Se você chama o endereço da loja (https://minhaloja.io.venddor.com.br), não. O cabeçalho serve para escolher a loja quando o endereço não a identifica. Veja Endereço e ambientes.
Existe um ambiente de testes?
Sim, a Venddor pode disponibilizar um ambiente de homologação com o mesmo contrato e um endereço próprio. Peça ao seu contato. Não teste escrita numa loja de produção com dados reais.
Dados
Por que o preço veio 100 vezes maior?
O dinheiro é inteiro em centavos: 11500 é R$ 115,00. Veja Convenções.
Pedi per_page=500 e vieram 20 itens. Por quê?
Valores acima do máximo (100) não são cortados: a plataforma volta para o padrão. Peça até 100 e confira o per_page da resposta.
Pedidos
Como evito criar o mesmo pedido duas vezes?
Envie o campo idempotency_key em POST /api/v1/admin/orders, com um valor seu e único por pedido (o número no seu ERP). Repetir a chamada devolve o pedido original. Veja Limites e boas práticas.
Como fico sabendo quando um pedido muda de status?
Prefira webhooks a consultar a lista de tempos em tempos. Se precisar consultar, filtre por data e ordene do mais antigo ao mais novo, e descarte repetidos pelo id. Veja Pedidos e os fundamentos.