Desarrolladores
API de Comerciantes
Una API REST de solo lectura para tu tienda VeeBoost: un contrato publicado, autenticación por clave y paginación predecible — pensada para integraciones que se mantienen sincronizadas.
Un único contrato, publicado como fuente de verdad
Tu tienda publica el contrato completo legible por máquinas (OpenAPI 3.1): cada endpoint, parámetro, respuesta y código de error de la API de comerciantes. Esta página enlaza a él y nunca reproduce las tablas de endpoints — el contrato no puede desviarse, y tu integración tampoco.
GET /openapi/v1.jsonInicio rápido
Tres pasos para tu primera lectura del catálogo:
- Crea una clave de API en tu administrador (sección Desarrolladores) con los permisos de lectura que necesites. Empieza por vbk_ y se muestra una sola vez.
- Envíala en la cabecera X-Api-Key en cada petición — tu tenant se resuelve desde la clave, nunca desde el host.
- Llama a tu primer endpoint, por ejemplo GET /products, y sigue el contrato para todo lo demás.
Autenticación
Cada petición lleva tu clave en la cabecera X-Api-Key. La v1 ofrece exactamente cuatro permisos de lectura — productos, pedidos, clientes y entregas de webhooks. Un permiso ausente responde 403; una clave revocada se rechaza de inmediato. Guarda las claves en el servidor: nunca deben estar en un navegador o en un repositorio público.
products:readorders:readcustomers:readwebhooks:readPaginación
Los endpoints de listas paginan: recórrelos con el parámetro page y lee el sobre devuelto con cada colección — indica dónde estás para resincronizar tu integración sin adivinar. Los parámetros exactos de cada endpoint están documentados en el contrato.
Errores y límites de tasa
Los errores devuelven un cuerpo JSON estructurado que puedes procesar, nunca un párrafo que haya que raspar. Una respuesta 429 es un contrato estable: siempre la misma forma, con las cabeceras X-RateLimit-* y un Retry-After que indica exactamente cuándo volver. Insistir no desbloquea datos — retrocede.
Claves sandbox
Durante el periodo previo al lanzamiento, las claves sandbox se emiten tras validación de nuestro equipo y funcionan con un presupuesto de tasa dedicado, separado de las claves de producción — explora la API sobre tu tienda sin tocar el tráfico real ni las cuotas.
Ejemplos por lenguaje
Un fragmento por plataforma, solo permisos de lectura: cada uno recupera tu catálogo de productos. Sustituye <api-base> por el host de API de tu tienda indicado en el administrador → sección Desarrolladores.
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()La v1 es de solo lectura por diseño: products:read, orders:read, customers:read y webhooks:read son los únicos permisos que existen. Los permisos de escritura serían una decisión v1.x documentada explícitamente — nada se planea en silencio.