Perguntas frequentes
Respostas curtas para as dúvidas mais comuns de quem faz a primeira integração com a API legada 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
Como consigo a chave de API?
No painel, em Usuários, abra o usuário, abra o menu de ações (engrenagem) e escolha Gerar API Key. A chave aparece uma vez. O passo a passo está em Autenticação.
Perdi a chave. Posso recuperá-la?
Não. A plataforma guarda só o hash. Gere uma nova, lembrando que isso revoga a anterior na hora.
O meu token da rota auth_tokens venceu. Como renovo?
Não há renovação nessa rota: chame POST /api/v1.0/auth_tokens de novo. O campo ttl da resposta diz por quantos segundos o token vale. Se você não quer lidar com token, use a chave de API com HTTP Basic.
Por que recebo 403 com uma chave válida?
As rotas administrativas exigem um usuário administrador. Com a chave de um comprador a resposta é 403 Forbidden: admin scope required. Gere a chave num usuário administrador.
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.
Qual a diferença entre /api/v1.0/... e /api/...?
As duas respondem as mesmas operações. A diferença está nos ids: /api/v1.0 usa UUID em texto, e /api/ usa ids decimais, para conectores antigos. Escolha uma e não misture na mesma integração.
Dados
O preço veio como texto. Posso somar direto?
Não. "115.00" é uma string decimal. Converta para um tipo decimal exato (ou para centavos inteiros) antes de somar. Veja Convenções.
Pedi items_per_page=500 e não vieram 500 itens. Por quê?
Valores acima do máximo (100) não são cortados: a plataforma volta para o padrão da rota. Peça até 100 e confira o params.items_per_page da resposta.
Pedidos
Como evito criar o mesmo pedido duas vezes?
A API legada não tem chave de idempotência. Guarde o order_id assim que receber a resposta 201 e, se a chamada deu timeout, consulte antes de criar de novo. Veja Limites e boas práticas.
Como fico sabendo quando um pedido muda de status?
Consulte a lista filtrando por data (time_from) e pelo status, e descarte repetidos pelo order_id. Veja Pedidos e Listar pedidos.