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) oAPI_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_REQUIREDoMODULE_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.