Saltar al contenido

API pública: autenticación, errores y límites

Cómo enviar la clave, cómo leer los errores y cuántas peticiones por minuto admite cada clave.

Dirección y documentación

Todas las rutas empiezan por /api/v1/public/v1/ en la misma dirección que usa tu ERP. La documentación completa (OpenAPI, con ejemplos) está en /api/v1/public/docs y el fichero en /api/v1/public/openapi.json. En API y desarrolladores tienes el botón Documentación de la API.

Autenticación

Envía la clave en cada petición con la cabecera Authorization: Bearer bzk_TU_CLAVE. La tienda sale de la clave: no hace falta indicarla. Prueba la clave con GET /api/v1/public/v1/me, que devuelve la tienda, los permisos de la clave y el límite.

Errores

Los errores llegan en JSON con statusCode, errorCode y message. Decide siempre por el errorCode (el texto está en español y puede cambiar):

  • API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED (401): la clave no vale.
  • API_KEY_IP_NOT_ALLOWED (403): la petición llega desde una IP que no está en la lista de la clave.
  • API_SCOPE_MISSING (403): a la clave le falta el permiso de esa ruta.
  • API_PERMISSION_MISSING (403) o API_KEY_OWNER_UNAVAILABLE (401): la persona que creó la clave ya no tiene ese permiso o ya no puede entrar en la tienda.
  • MODULE_SUBSCRIPTION_REQUIRED o MODULE_DISABLED (403): el servicio de la API o el módulo del recurso no está activo en la tienda.
  • API_NOT_FOUND (404): no existe en esta tienda.

Límite de peticiones

Cada clave admite 120 peticiones por minuto. Todas las respuestas llevan X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos hasta que se reinicia el minuto). Por encima del límite recibes 429 API_RATE_LIMITED con la cabecera Retry-After: espera esos segundos antes de repetir.

Volver al centro de ayuda