Saltar al contenido principal

​
Autenticación

La API de Integración de SalesOS utiliza API Keys para la autenticación. Cada clave tiene alcance a un solo tenant, se hashea con bcrypt y soporta límites de tasa y listas de IPs permitidas.

​
Entornos

URL Base: https://api.play2sell.comDashboard: https://dashboard.play2sell.comApp: https://app.play2sell.com

​
Inicio Rápido

​
1. Crear una API Key

Ve a Integraciones > API Keys en el Dashboard de SalesOS:
  1. Haz clic en Crear API Key
  2. Nombra tu clave (ej., “Sincronización Nocturna CRM”, “Integración Formulario Web”)
  3. Selecciona el alcance: default:sync
  4. Haz clic en Crear
  5. Copia la clave inmediatamente — solo se mostrará una vez
Tu clave se ve así: 
sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​
2. Usar la Clave en las Solicitudes

Incluye la clave en el header Authorization de cada solicitud a la API: 
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_collaborators",
    "collaborators": [
      {
        "external_id": "emp-101",
        "name": "Maria Santos",
        "email": "maria@yourcompany.com"
      }
    ]
  }'

​
3. Verificar la Respuesta

Éxito (200): 
{
  "data": { "created": 1, "existing": 0, "errors": [], "total": 1 },
  "meta": { "request_id": "f47ac10b-...", "timestamp": "2026-03-17T10:30:00.000Z" }
}
Clave inválida (401): 
{
  "error": { "code": "UNAUTHORIZED", "message": "Invalid or expired API key" }
}

​
Propiedades de la API Key

PropiedadDetalles
Prefijosk_live_ (producción) o sk_test_ (pruebas)
Alcancedefault:sync — habilita sync_collaborators y sync_activities
Límite de tasaConfigurable por clave (por defecto: 1000 solicitudes/hora)
ExpiraciónOpcional — establece una fecha de vencimiento o déjala sin expirar
Lista de IPs permitidasOpcional — restringe a direcciones IP específicas
AlmacenamientoHasheada con bcrypt — la clave en texto plano nunca se almacena

​
Formatos de Clave

SalesOS usa dos prefijos de clave para distinguir ambientes:
PrefijoAmbienteCaso de uso
sk_live_ProducciónDatos reales, misiones reales, puntos reales
sk_test_PruebasSeguro para usar durante desarrollo — sin impacto en producción
Usa claves sk_test_ durante el desarrollo y las pruebas de integración. Cambia a sk_live_ cuando pases a producción.

​
Errores de Autenticación

Estado HTTPCódigo de ErrorSignificadoQué hacer
401UNAUTHORIZEDLa clave falta, es inválida o expiróVerifica el header Authorization. Confirma la clave en el Dashboard.
403FORBIDDENLa clave es válida pero no tiene el alcance requeridoEdita la clave y agrega el alcance default:sync
429RATE_LIMITEDDemasiadas solicitudes en esta horaEspera retry_after segundos, luego reintenta

​
Ejemplo: Header Authorization faltante

curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Content-Type: application/json" \
  -d '{"action": "sync_collaborators", "collaborators": [...]}'

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or malformed Authorization header. Expected: Bearer sk_live_xxx"
  }
}

​
Ejemplo: Prefijo de clave incorrecto

# Using "Bearer mytoken123" instead of "Bearer sk_live_..."
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: Bearer mytoken123456789" \
  -H "Content-Type: application/json" \
  -d '{"action": "sync_collaborators", "collaborators": [...]}'

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key prefix. Expected sk_live_ or sk_test_"
  }
}

​
Ejemplo: Clave sin el alcance requerido

Si tu clave solo tiene leads:read pero el endpoint requiere default:sync: 
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing required scopes: default:sync"
  }
}

​
Ejemplo: Límite de tasa excedido

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after": 1847
  }
}
El campo retry_after indica cuántos segundos debes esperar. La ventana de límite de tasa se reinicia cada hora.

​
Límites de Tasa

Cada API key tiene un contador de límite de tasa independiente que se reinicia cada hora:
ConfiguraciónPor defectoRango
Solicitudes por hora10001 — 100,000
Cómo funciona:
  1. Cada solicitud exitosa incrementa el contador
  2. Cuando el contador alcanza el límite, las solicitudes siguientes retornan 429
  3. El contador se reinicia a 0 una hora después de la primera solicitud en la ventana
Manejo de límites de tasa en código: 
async function callWithRetry(payload) {
  const response = await fetch(API_URL, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });

  if (response.status === 429) {
    const { error } = await response.json();
    const waitSeconds = error.retry_after || 60;
    console.log(`Rate limited. Retrying in ${waitSeconds}s...`);
    await new Promise(r => setTimeout(r, waitSeconds * 1000));
    return callWithRetry(payload); // retry
  }

  return response.json();
}

​
Mejores Prácticas de Seguridad

Nunca expongas API keys en código del lado del cliente. JavaScript en el navegador, aplicaciones móviles y repositorios públicos pueden filtrar tu clave. Siempre llama a la API de SalesOS desde tu servidor backend.
  • Usa variables de entorno — Almacena SALESOS_API_KEY en variables de entorno o un gestor de secretos, nunca en el código fuente
  • Rota las claves periódicamente — Crea una nueva clave, actualiza tu integración, luego revoca la anterior
  • Usa listas de IPs permitidas — Si tu integración se ejecuta desde IPs fijas, restringe la clave solo a esas IPs
  • Monitorea el uso — Revisa los logs de uso de la API en el Dashboard para detectar patrones inesperados
  • Usa sk_test_ para desarrollo — Las claves de prueba aíslan tu ambiente de desarrollo de producción
  • Revoca claves comprometidas inmediatamente — Ve a Dashboard > Admin > API Keys > Revocar

​
Ejemplo de rotación de claves

# 1. Create new key in Dashboard → copy sk_live_NEW_KEY
# 2. Update your env var
export SALESOS_API_KEY=sk_live_NEW_KEY

# 3. Verify it works
curl -s -X POST "$API_URL" \
  -H "Authorization: Bearer $SALESOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"sync_collaborators","collaborators":[{"external_id":"test","name":"Test","email":"test@co.com"}]}' | jq .

# 4. Revoke old key in Dashboard

​
Gestion Self-Service de API Keys

Ademas de crear claves en el Dashboard, los administradores del tenant pueden gestionar API keys programaticamente via la API. Esto permite:
  • Rotacion automatizada de claves en pipelines CI/CD
  • Workflows de onboarding de socios que provisionan claves bajo demanda
  • Paneles admin personalizados que integran gestion de claves

Gestion de API Keys

Crea, lista y revoca claves via API usando tu token JWT del Dashboard

​
Proximos Pasos

Integracion por Defecto

Comienza a enviar actividades a SalesOS

API Keys

Gestiona claves programaticamente