# Introducció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](/api/webhooks.md) para notificaciones en tiempo real
* Revisa nuestros ejemplos de integración


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.salescaling.com/api/introduction.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.