La API de tu tienda, lista para tu propia web

Es una API REST: recibe y devuelve JSON y usa los verbos y los códigos de estado de HTTP. Sirve para llevar tu tienda a una web hecha a tu medida, con su catálogo, el contenido del Site Builder, las cuentas de tus compradores, sus pedidos y el checkout.

Todas las rutas cuelgan de esta dirección. La tienda no se elige por el dominio: la identifica la API key con la que llamas.

https://vendiq.pe/api/v1

La API responde también en el dominio de tu tienda, que es el que usa la documentación de tu panel. De las rutas de la referencia, solo /api/checkout/token vive fuera de /api/v1.

Cada petición lleva tu API key en la cabecera x-api-key. Si tu cliente no puede enviar cabeceras propias, la API también la acepta como Authorization: Bearer.

Los endpoints marcados como «Sesión del comprador» piden además el token que devuelve POST /api/v1/auth/login. En ellos la key va en x-api-key y el token en Authorization: Bearer.

curl "https://vendiq.pe/api/v1/products?limit=10" \
  -H "x-api-key: vnd_live_xxxxxxxxxxxx"

curl -X POST "https://vendiq.pe/api/v1/auth/login" \
  -H "x-api-key: vnd_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "email": "cliente@correo.com", "password": "********" }'

curl "https://vendiq.pe/api/v1/users/me" \
  -H "x-api-key: vnd_live_xxxxxxxxxxxx" \
  -H "Authorization: Bearer <token>"

Las keys empiezan por vnd_live_ y siguen con 64 caracteres hexadecimales. Las emitidas antes con el prefijo lum_live_ siguen funcionando.

Las API keys vienen en los planes Business Pro y White label, y solo las gestiona un administrador de la tienda.

• En el navegador, solo lectura

  La API acepta llamadas desde cualquier origen. Una key que va en el código de tu web la puede leer cualquiera: usa ahí una de solo lectura y guarda las de escritura en tu servidor.

• Cuándo deja de funcionar

  Una key revocada o vencida responde 401 UNAUTHORIZED. Si la operación exige un scope que la key no tiene, la respuesta es 403 FORBIDDEN.

Cada API key tiene hasta 100 peticiones por minuto. Algunos endpoints sensibles, como el inicio de sesión o el envío de correos, tienen además un límite propio más bajo.

Al pasarte llega un 429 RATE_LIMIT_EXCEEDED. Espera antes de reintentar: cuando la respuesta trae Retry-After, ahí están los segundos.

Consulta tu cuota con estas cabeceras cuando vengan en la respuesta:

Todo error trae error.code y error.message. Programa contra error.code, que es estable, y no contra el texto, que puede cambiar.

Los endpoints del contrato común añaden los campos de Problem Details (RFC 9457): type, title, status, detail e instance, más un requestId para rastrear la petición.

{
  "type": "https://vendiq.pe/docs/api#not_found",
  "title": "Not found",
  "status": 404,
  "detail": "No existe un producto publicado con el slug \"xyz\".",
  "instance": "/api/v1/products/xyz",
  "requestId": "req_3f9c2a7b1e4d8c6a5b0f2e1d",
  "error": {
    "code": "NOT_FOUND",
    "message": "No existe un producto publicado con el slug \"xyz\"."
  }
}

• Paginación

  Las listas paginadas aceptan ?page=1&limit=20, con un máximo de 100 por página, y responden { object: "list", data, pagination }.

• Versión

  Cada respuesta indica su versión en X-API-Version. Antes de retirar una versión se avisa con Deprecation y Sunset; después, la API responde 410 Gone.

• Trazabilidad

  Las respuestas del contrato común traen X-Request-Id. Inclúyelo cuando escribas a soporte por un error.

• CORS

  Se aceptan llamadas desde cualquier origen, con las cabeceras Authorization, Content-Type y x-api-key.

Sale del mismo catálogo que anuncia GET /api/v1 y que usa la documentación de tu panel: las tres listas dicen lo mismo.