Saltar al contenido principal

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.

Contrato publicadoGET /openapi/v1.json

Inicio rápido

Tres pasos para tu primera lectura del catálogo:

  1. 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.
  2. Envíala en la cabecera X-Api-Key en cada petición — tu tenant se resuelve desde la clave, nunca desde el host.
  3. 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:read

Paginació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.