Saltar para o conteúdo principal

Programadores

API de Comerciantes

Uma API REST apenas de leitura para a sua loja VeeBoost: um contrato publicado, autenticação por chave e paginação previsível — feita para integrações que se mantêm sincronizadas.

Um contrato único, publicado como fonte da verdade

A sua loja publica o contrato completo legível por máquinas (OpenAPI 3.1): cada endpoint, parâmetro, resposta e código de erro da API de comerciantes. Esta página liga a ele e nunca reproduz as tabelas de endpoints — o contrato não pode divergir, e a sua integração também não.

Contrato publicadoGET /openapi/v1.json

Início rápido

Três passos para a sua primeira leitura do catálogo:

  1. Crie uma chave de API no seu administrador (secção Programadores) com os âmbitos de leitura de que precisa. Começa por vbk_ e é apresentada apenas uma vez.
  2. Envie-a no cabeçalho X-Api-Key em todos os pedidos — o seu tenant é resolvido a partir da chave, nunca a partir do host.
  3. Chame o seu primeiro endpoint, por exemplo GET /products, e siga o contrato para todo o resto.

Autenticação

Cada pedido transporta a sua chave no cabeçalho X-Api-Key. A v1 oferece exatamente quatro âmbitos de leitura — produtos, encomendas, clientes e entregas de webhooks. Um âmbito em falta responde 403; uma chave revogada é recusada de imediato. Guarde as chaves no servidor: nunca pertencem a um navegador ou a um repositório público.

products:readorders:readcustomers:readwebhooks:read

Paginação

Os endpoints de listas paginam: percorra-os com o parâmetro page e leia o envelope devolvido com cada coleção — indica onde está para ressincronizar a integração sem adivinhar. Os parâmetros exatos de cada endpoint estão documentados no contrato.

Erros e limites de frequência

Os erros devolvem um corpo JSON estruturado que pode processar, nunca um parágrafo para raspar. Uma resposta 429 é um contrato estável: sempre a mesma forma, com os cabeçalhos X-RateLimit-* e um Retry-After que diz exatamente quando voltar. Insistir não desbloqueia dados — recue.

Chaves sandbox

Durante o período pré-lançamento, as chaves sandbox são emitidas após validação da nossa equipa e correm com um orçamento de frequência dedicado, separado das chaves de produção — explore a API na sua loja sem tocar no tráfego real nem nas quotas.

Exemplos por linguagem

Um excerto por plataforma, apenas âmbitos de leitura: cada um obtém o seu catálogo de produtos. Substitua <api-base> pelo host da API da sua loja indicado no administrador → secção Programadores.

curl

curl -H "X-Api-Key: vbk_your_key" \
  "https://<api-base>/products?page=1"

JavaScript

async function listProducts(page = 1) {
  const res = await fetch("https://<api-base>/products?page=" + page, {
    headers: { "X-Api-Key": "vbk_your_key" },
  });
  if (res.status === 429) {
    // Structured contract: honor Retry-After, never screen-scrape.
    const wait = Number(res.headers.get("Retry-After")) * 1000;
    await new Promise((done) => setTimeout(done, wait));
    return listProducts(page);
  }
  if (!res.ok) throw new Error("products:read failed with " + res.status);
  return res.json();
}

Python

import requests

def list_products(page=1):
    res = requests.get(
        "https://<api-base>/products",
        params={"page": page},
        headers={"X-Api-Key": "vbk_your_key"},
        timeout=10,
    )
    res.raise_for_status()
    return res.json()

A v1 é apenas de leitura por design: products:read, orders:read, customers:read e webhooks:read são os únicos âmbitos existentes. Âmbitos de escrita seriam uma decisão v1.x documentada explicitamente — nada é planeado em silêncio.