Autenticación
Autenticación con clave de API y límites de solicitudes
Autenticación
Todas las solicitudes a la API de Umbrella requieren autenticación. Hay dos métodos, según el endpoint.
Autenticación con encabezados de Shopify
Los endpoints públicos (datos de widgets, reclamos, consultas de pólizas) se autentican con encabezados del dominio de la tienda de Shopify:
X-Shopify-Shop-Domain: your-store.myshopify.com
X-Shopify-Customer-Id: 1234567890Al instalar la aplicación de Umbrella para Shopify, el dominio de tu tienda se registra automáticamente. No se necesita ninguna configuración manual para los endpoints de la tienda.
Autenticación con clave de API interna
Los endpoints del lado del servidor (evaluación de elegibilidad, sincronización de productos) se autentican con una clave de API en el cuerpo de la solicitud:
{
"internalApiKey": "your-internal-api-key",
"orgId": "your-org-id"
}Para generar o rotar una clave de API interna:
- Ve a Panel > Configuración > Integraciones
- Busca la sección Claves de API
- Haz clic en Generar clave nueva o Rotar clave
Rotar una clave invalida de inmediato la anterior. Actualiza todas tus integraciones antes de rotarla.
Entornos de prueba y producción
| Entorno | Dominio de la tienda | Comportamiento |
|---|---|---|
| Prueba | *.test, demo.myshopify.com, test.myshopify.com | Devuelve datos simulados, sin transacciones reales |
| Producción | Tu dominio *.myshopify.com real | Datos reales, transacciones reales |
Las solicitudes en modo de prueba devuelven "testingMode": true en las respuestas y usan datos de garantía de ejemplo.
Manejo de errores
Códigos de estado de error comunes en todos los endpoints:
| Estado | Significado |
|---|---|
400 | Parámetros faltantes o no válidos |
401 | No se proporcionaron credenciales de autenticación |
403 | Origen no autorizado o clave de API no válida |
404 | Recurso no encontrado |
408 | Tiempo de espera de la solicitud agotado (límite de 25 segundos) |
429 | Se superó el límite de solicitudes — espera y vuelve a intentarlo |
500 | Error interno del servidor |
Cuando recibas una respuesta 429, espera el periodo de reintento antes de enviar más solicitudes. Implementa un retroceso exponencial para escenarios de alto volumen.
Relacionado
- Resumen de endpoints — Lista completa de endpoints disponibles
- API de garantías — Endpoints para gestionar planes de garantía
- Referencia de webhooks — Integraciones basadas en eventos
