Ir al contenido
SShalom API

Autenticación y API keys

Cómo autenticar tus peticiones a Shalom API Perú con el header x-api-key, validar tu API key, qué consume cuota y el rate limit de 60 peticiones por minuto.

Toda petición, salvo las rutas /public/*, se autentica con una API key personal que empieza con sk_. Con ella la plataforma te identifica y mide tu consumo mensual según tu plan.

Cómo obtener tu key

Crea tu cuenta en shalom-api.lat: al registrarte se genera tu primera key. En el panel, en API Key, puedes copiarla, crear otras y eliminarlas; tu plan puede limitar cuántas tienes.

Una cuenta sin plan usa el plan gratuito: 5 operaciones al mes y sin instancias de Shalom Pro, así que no puede crear guías (sí puede rastrear y consultar agencias).

Dónde va la API key

Envíala en el header x-api-key de cada petición. También se acepta Authorization: Bearer, pero en ese caso el rate limit se cuenta por IP y no por key, así que x-api-key es la forma recomendada. No la pongas en la URL ni en el cuerpo: las URLs quedan en logs, proxies y analítica.

Si tu cliente es una app web, la key nunca debe llegar al navegador. Las llamadas salen desde tu backend.

Qué consume cuota

Cada llamada exitosa a un endpoint que consume cuota suma una operación al mes de tu cuenta, sin importar qué key uses. Las respuestas con error no suman. Cada endpoint de esta documentación dice si consume cuota o no; la lista completa está en la Referencia de la API.

Si tu plan vence, los endpoints que consumen cuota responden 403, y si agotas la cuota, 429. Los que no consumen cuota siguen funcionando en los dos casos.

Buenas prácticas para producción

Guarda la key en variables de entorno, nunca en el repositorio. Usa una key distinta para pruebas y para producción, así puedes eliminar una sin afectar a la otra. Si sospechas una filtración, crea una nueva y elimina la anterior desde el panel.

Validar tu API key

GET /validate

Confirma que la key es válida y devuelve el límite mensual de tu plan y el consumo del mes. Úsala como health check de tu integración. No consume cuota y responde aunque tu plan haya vencido o hayas agotado la cuota.

curl -X GET "https://api.shalom-api.lat/validate" \
  -H "x-api-key: TU_API_KEY"
Respuesta
{
  "valid": true,
  "userId": "b7c9d1e2-4f6a-4c3b-9d2e-1a2b3c4d5e6f",
  "message": "API key válida",
  "limit": 1000,
  "currentUsage": 137,
  "remaining": 863
}
limit y remaining llegan en null cuando el plan no tiene límite mensual.

Errores

CódigoSignificado
401Falta la API key o es inválida.
403El plan asociado a la key venció (solo en las rutas que consumen cuota).
429Superaste el rate limit o agotaste la cuota mensual (ver Errores y límites).

Preguntas frecuentes

Relacionado