Claves API y autenticación
Cada llamada a la Connect API necesita una clave API en la cabecera X-Api-Key. La API pública de reservas (/public/v1) no necesita clave.
Claves publicables y secretas
Cada clave API que creas es un par:
| Parte | Prefijo | Dónde usarla | Acceso |
|---|---|---|---|
| Clave publicable | pk_ | Tu app de clientes o tu web | Solo lo que puede hacer un cliente: locales, inicio de sesión, la carta, pedidos de restaurante, el catálogo de productos, el estado del pago y la cuenta propia del cliente. |
| Clave secreta | cnct_ | Tu propio servidor | Todos los endpoints, incluidos el carrito, los pedidos de la tienda online y las consultas de envío. |
Trata la clave secreta como una contraseña. Nunca la pongas en una app ni en una página web.
Estos endpoints necesitan la clave secreta. Una clave publicable recibe 403 PUBLISHABLE_KEY_NOT_ALLOWED:
GET /store/shipping/locationsGET /store/shipping/delivery-optionsPOST /store/orders- todo lo que está bajo
/store/cart/…
Las claves pertenecen a tu organización y funcionan con cualquiera de sus canales de venta activos. No hay claves separadas de prueba y reales.
Crea una clave
- Inicia sesión en my.conciar.com como admin o manager. Los empleados no pueden gestionar claves.
- Abre Management → API Keys y haz clic en New API Key (o en Create first key si la lista está vacía).
- Introduce un Key Name, de hasta 100 caracteres, y haz clic en Create Key.
- En API Key Created, copia la clave publicable y la clave secreta con sus botones Copy y después haz clic en Done.
Las claves solo se muestran una vez
Conciar solo guarda un hash de cada clave. Si pierdes una clave, crea una nueva.
La lista muestra los primeros caracteres de cada clave, la fecha en que se creó y cuándo se usó por última vez.
Sustituye o revoca una clave
Conciar no tiene un botón de "rotar". Para sustituir una clave:
- Crea una clave nueva.
- Cambia tu app o tu servidor a la clave nueva.
- Revoca o elimina la clave antigua.
Revoke detiene la clave al instante; se queda en la lista como "Revoked" y no se puede volver a activar. Delete la quita de la lista. Ambas acciones afectan al par completo: revocar la clave publicable también revoca su clave secreta.
Llamadas desde un navegador
La Connect API no envía cabeceras CORS, así que un navegador bloquea las llamadas hechas desde JavaScript en otro dominio. Llámala desde tu servidor o desde una app nativa. Una tienda online puede pasar sus llamadas por su propio backend, lo que además mantiene la clave secreta fuera de la página.
Errores
Los errores llegan en JSON. Comprueba primero el estado HTTP.
| Estado | Cuerpo | Causa |
|---|---|---|
| 401 | {"message": "API key required."} | Falta la cabecera X-Api-Key. |
| 401 | {"message": "Invalid or expired API key."} | La clave es incorrecta, está revocada o se ha eliminado. |
| 401 | {"message": "Unauthenticated."} | Un endpoint de cliente sin un bearer token válido. |
| 403 | {"status": false, "message": "PUBLISHABLE_KEY_NOT_ALLOWED"} | Este endpoint necesita la clave secreta. |
| 404 | {"message": "X-Sales-Channel header is required."} | Falta la cabecera X-Sales-Channel en una llamada a /store/…. |
| 404 | {"message": "…"} | El token del canal es desconocido, está inactivo o es de otra organización. |
| 409 | {"status": false, "message": "IDEMPOTENCY_KEY_REUSED"} | Se reutilizó una Idempotency-Key para un pedido distinto, o el primer pedido aún se está creando (IDEMPOTENCY_KEY_IN_PROGRESS). |
| 422 | {"message": "…", "errors": {…}} | La validación ha fallado. Otros errores de la petición devuelven {"status": false, "message": "CODE"}. |
| 429 | {"message": "Too Many Attempts."} | Se ha superado un límite de peticiones. Espera el número de segundos de Retry-After. |
| 503 | {"maintenance": true, "message": "…"} | El canal de venta está en modo de mantenimiento. |
La API pública de reservas devuelve {"status": false, "code": "…"}, por ejemplo NOT_FOUND, UNAVAILABLE o INVALID.
Límites de peticiones
Las respuestas incluyen X-RateLimit-Limit y X-RateLimit-Remaining.
Connect API
| Límite | Se cuenta por |
|---|---|
| 300 peticiones por minuto, toda la API | dirección IP |
POST /app/init: 30 por minuto | clave |
POST /store/cart/init: 30 por minuto | clave |
| Otros cambios en el carrito: 120 por minuto | clave |
| Estado del pago: 60 por minuto | clave |
| Hacer, pagar o cancelar un pedido de restaurante: 10 por minuto | clave |
| Estado de un pedido de restaurante: 30 por minuto | clave |
| Todos los pedidos de restaurante de una tienda: 60 pedidos nuevos y 120 llamadas de pago o cancelación por minuto | tienda |
register, otp/request y otp/resend: 5 por minuto | dirección IP |
otp/verify: 20 por minuto | dirección IP |
| Códigos de inicio de sesión: 1 por minuto y 5 por hora | dirección de email |
Para una clave publicable, "por clave" significa por clave y dirección IP, de modo que un usuario muy activo de la app no agota el límite de todos los demás.
Pedir un código de inicio de sesión nuevo demasiado pronto devuelve 429 {"status": false, "message": "OTP_COOLDOWN", "retry_after": 42}.
API pública de reservas
| Límite | Se cuenta por |
|---|---|
| 120 lecturas y 10 reservas o cambios por minuto | restaurante y dirección IP |
| Tarjetas regalo: 60 lecturas y 6 compras por minuto | restaurante y dirección IP |