SalescalingDocs
DemoApp

Introducción a la API

Aprende a autenticarte en la API pública de Salescaling con claves API, límites de uso y buenas prácticas de integración.

La API Pública de Salescaling proporciona acceso programático para gestionar tus llamadas, reuniones, usuarios, contactos y otros datos. Esta guía te ayudará a comenzar con la autenticación y entender las políticas de limitación de velocidad.

Autenticación

¿Qué es una API Key?

Las API keys son tokens seguros que autentican tus peticiones a la API Pública. Cada clave es única y está vinculada a tu cuenta, permitiéndote acceder a tus datos de forma programática.

Cómo Crear una API Key

  1. Ve a Configuración > API Keys en tu panel de Salescaling
  2. Haz clic en el botón "Crear Nueva API Key"
  3. Introduce un nombre para tu clave (ej., "Integración Producción", "Desarrollo")
  4. Opcionalmente, establece una fecha de expiración para mayor seguridad
  5. Haz clic en Crear
  6. Importante: Copia la clave inmediatamente - solo se mostrará una vez
  7. Guárdala de forma segura (recomendamos usar variables de entorno o un gestor de secretos)

Usar tu API Key

  • Incluye la API key en el header x-api-key para todas las peticiones
  • Todos los endpoints de la API Pública están disponibles en: https://api.salescaling.com/api/v1/
  • Ejemplo de header de petición: x-api-key: tu-api-key-aqui

Scopes (Permisos)

Las API keys utilizan un sistema de scopes para controlar qué acciones pueden realizar. Al crear una API key, debes seleccionar al menos un scope:

Scopes Disponibles

Voice Agents:

  • voice-agents:webhook - Permite iniciar llamadas mediante webhook
  • voice-agents:read - Permite leer información de voice agents
  • voice-agents:write - Permite crear y modificar voice agents

Contactos:

  • contacts:read - Permite leer información de contactos
  • contacts:write - Permite crear y modificar contactos

Empresas:

  • companies:read - Permite leer información de empresas
  • companies:write - Permite crear y modificar empresas

Llamadas:

  • calls:read - Permite leer información de llamadas
  • calls:write - Permite crear y modificar llamadas

Reuniones:

  • meetings:read - Permite leer información de reuniones
  • meetings:write - Permite crear y modificar reuniones

Oportunidades:

  • opportunities:read - Permite leer información de oportunidades
  • opportunities:write - Permite crear y modificar oportunidades

Calendario:

  • calendar:read - Permite leer información de calendarios
  • calendar:write - Permite crear y modificar eventos de calendario

Usuarios:

  • users:read - Permite leer información de usuarios

Ejemplo de Uso de Scopes

Si solo necesitas iniciar llamadas mediante webhook, selecciona únicamente el scope voice-agents:webhook. Esto sigue el principio de privilegio mínimo, otorgando solo los permisos necesarios.

Permisos y Propiedad

  • Las API keys actúan en nombre del usuario que las creó
  • Los scopes limitan qué acciones puede realizar la API key
  • Cualquier acción realizada usando una API key aparecerá como si la hubiera realizado el usuario creador
  • Por ejemplo, si creas una llamada usando una API key, aparecerás como el propietario de esa llamada
  • Solo crea API keys para usuarios con niveles de acceso apropiados
  • Asigna únicamente los scopes necesarios para cada API key

Mejores Prácticas de Seguridad

  • Nunca compartas tus API keys ni las incluyas en control de versiones
  • Guarda las claves en variables de entorno o un gestor de secretos seguro
  • Rota las claves regularmente (se recomienda cada 90 días)
  • Elimina inmediatamente las claves no utilizadas o comprometidas
  • Asigna únicamente los scopes necesarios (principio de privilegio mínimo)
  • Crea API keys diferentes para diferentes integraciones o propósitos
  • Monitorea el uso de tus API keys regularmente
  • Crea claves separadas para diferentes entornos (desarrollo, staging, producción)
  • Usa claves de solo lectura cuando solo necesites recuperar datos

Gestionar tus API Keys

  • Ve todas tus claves en Configuración > API Keys
  • Actualiza nombres de claves o fechas de expiración en cualquier momento
  • Elimina claves que ya no necesites
  • Nota: Una vez creada, el valor completo de la clave no se puede recuperar de nuevo

Limitación de Velocidad

Resumen

Para asegurar un uso justo y la estabilidad del sistema, la API implementa limitación de velocidad en todos los endpoints.

Límites de Velocidad

Tres límites concurrentes se aplican a tus peticiones:

  • Corto plazo: 20 peticiones por segundo
  • Medio plazo: 200 peticiones por 10 segundos
  • Largo plazo: 1,000 peticiones por minuto

Cómo Funciona

  • Los límites se rastrean por API key
  • Los tres límites están activos simultáneamente
  • Si excedes cualquier límite, recibirás una respuesta de error 429

Manejar Límites de Velocidad

Cuando recibas una respuesta 429 (Demasiadas Peticiones):

  • Revisa el header Retry-After para saber cuándo reintentar
  • Espera el tiempo especificado antes de hacer otra petición
  • Implementa retroceso exponencial en tu lógica de reintentos
  • Ejemplo: espera 1s, luego 2s, luego 4s, etc. entre reintentos

Mejores Prácticas

  • Cachea las respuestas de la API cuando sea posible para reducir peticiones
  • Usa webhooks en lugar de polling para actualizaciones en tiempo real
  • Agrupa operaciones cuando la API lo soporte
  • Distribuye las peticiones en el tiempo en lugar de enviar ráfagas
  • Monitorea tu uso para mantenerte dentro de los límites
  • Si necesitas límites más altos, contacta soporte

Ejemplos de Inicio Rápido

cURL

bash
curl -X GET \
  'https://api.salescaling.com/api/v1/users' \
  -H 'x-api-key: tu-api-key-aqui'

JavaScript/TypeScript

typescript
const response = await fetch("https://api.salescaling.com/api/v1/users", {
  headers: {
    "x-api-key": "tu-api-key-aqui",
    "Content-Type": "application/json",
  },
});

const data = await response.json();
console.log(data);

Python

python
import requests

headers = {
    'x-api-key': 'tu-api-key-aqui',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.salescaling.com/api/v1/users',
    headers=headers
)

data = response.json()
print(data)

Node.js con axios

javascript
const axios = require("axios");

const config = {
  headers: {
    "x-api-key": "tu-api-key-aqui",
  },
};

axios
  .get("https://api.salescaling.com/api/v1/users", config)
  .then((response) => {
    console.log(response.data);
  })
  .catch((error) => {
    console.error("Error:", error.message);
  });

Próximos Pasos

  • Explora los endpoints disponibles en la referencia de la API
  • Aprende sobre Webhooks para notificaciones en tiempo real
  • Revisa nuestros ejemplos de integración
AnteriorEstandarizar tu Metodología de VentasSiguienteServidor MCP (Model Context Protocol)