Autenticación

Prueba peticiones firmadas en el navegador en el Sandbox de la API — pega tu API key y secret, y el playground firma las peticiones automáticamente.

La API de Integración de SalesOS usa el esquema de peticiones firmadas P2S-SIGN-V1 en el header Authorization. Las API Keys tienen alcance a un solo tenant, se hashean con bcrypt y soportan límites de tasa y listas de IPs permitidas.

Esquema	Cuándo usar	Formato
P2S-SIGN-V1	Llamadas server-to-server — firmadas con el secret de la API key	`P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`

Entornos

Production
Staging

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

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

Inicio Rápido

1. Crear una API Key

Ve a Integraciones > API Keys en el Dashboard de SalesOS:

Haz clic en Crear API Key
Nombra tu clave (ej., “Sincronización Nocturna CRM”, “Integración Formulario Web”)
Selecciona el alcance: default:sync
Haz clic en Crear
Copia los dos valores inmediatamente — solo se muestran una vez:
- API Key — identificador público, ej. sk_live_a1b2c3d4...
- API Key Secret — usado para firmar peticiones, nunca se envía por la red

2. Firma y Envía una Petición

Para llamadas server-to-server, construye el header Authorization como P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. La SIGNATURE es el HMAC-SHA256 hex de una cadena de claves derivadas en 5 pasos:

k1 = HMAC_SHA256(key=API_KEY_SECRET, msg=API_KEY)
k2 = HMAC_SHA256(key=k1, msg=TIMESTAMP)
k3 = HMAC_SHA256(key=k2, msg=METHOD)
k4 = HMAC_SHA256(key=k3, msg=PATH)
SIG = HMAC_SHA256_HEX(key=k4, msg=PAYLOAD_SHA256_HEX)

TIMESTAMP es Unix epoch en segundos, válido por 30 segundos. PAYLOAD_SHA256_HEX es el SHA-256 hex en minúsculas del cuerpo bruto de la petición (usa el digest de la cadena vacía e3b0c4...b855 cuando no haya body).

Node.js
Python
Bash

import crypto from 'node:crypto';

const API_KEY = process.env.SALESOS_API_KEY;
const SECRET  = process.env.SALESOS_API_SECRET;

const hmac = (key, msg) =>
  crypto.createHmac('sha256', key).update(msg).digest();

async function signedRequest(method, path, body) {
  const ts          = Math.floor(Date.now() / 1000).toString();
  const bodyStr     = body ? JSON.stringify(body) : '';
  const payloadHash = crypto.createHash('sha256').update(bodyStr).digest('hex');

  const k1  = hmac(SECRET, API_KEY);
  const k2  = hmac(k1, ts);
  const k3  = hmac(k2, method);
  const k4  = hmac(k3, path);
  const sig = hmac(k4, payloadHash).toString('hex');

  const res = await fetch(`https://api.play2sell.com${path}`, {
    method,
    headers: {
      Authorization: `P2S-SIGN-V1 ${API_KEY}:${ts}:${sig}`,
      'Content-Type': 'application/json',
    },
    body: bodyStr || undefined,
  });
  return res.json();
}

import hashlib, hmac, json, os, time, requests

API_KEY = os.environ['SALESOS_API_KEY']
SECRET  = os.environ['SALESOS_API_SECRET']

def hmac_raw(key: bytes, msg: str) -> bytes:
    return hmac.new(key, msg.encode(), hashlib.sha256).digest()

def signed_request(method: str, path: str, body=None):
    ts           = str(int(time.time()))
    body_str     = json.dumps(body) if body else ''
    payload_hash = hashlib.sha256(body_str.encode()).hexdigest()

    k1  = hmac_raw(SECRET.encode(), API_KEY)
    k2  = hmac_raw(k1, ts)
    k3  = hmac_raw(k2, method)
    k4  = hmac_raw(k3, path)
    sig = hmac_raw(k4, payload_hash).hex()

    return requests.request(
        method, f'https://api.play2sell.com{path}',
        headers={
            'Authorization': f'P2S-SIGN-V1 {API_KEY}:{ts}:{sig}',
            'Content-Type': 'application/json',
        },
        data=body_str or None,
    ).json()

API_KEY="sk_live_..."
SECRET="..."
METHOD="POST"
PATH_="/functions/v1/default-integration/sync_collaborators"
BODY='{"action":"sync_collaborators","collaborators":[{"external_id":"emp-101","name":"Maria Santos","email":"maria@yourcompany.com"}]}'
TS=$(date +%s)

PAYLOAD=$(printf '%s' "$BODY"        | openssl dgst -sha256 -hex                                  | awk '{print $2}')
K1=$(printf '%s'      "$API_KEY"     | openssl dgst -sha256 -hmac "$SECRET" -hex                  | awk '{print $2}')
K2=$(printf '%s'      "$TS"          | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$K1" -hex   | awk '{print $2}')
K3=$(printf '%s'      "$METHOD"      | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$K2" -hex   | awk '{print $2}')
K4=$(printf '%s'      "$PATH_"       | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$K3" -hex   | awk '{print $2}')
SIG=$(printf '%s'     "$PAYLOAD"     | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$K4" -hex   | awk '{print $2}')

curl -X "$METHOD" "https://api.play2sell.com$PATH_" \
  -H "Authorization: P2S-SIGN-V1 $API_KEY:$TS:$SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

¿No quieres escribir el código de firma todavía? El Sandbox de la API firma las peticiones por ti en el navegador — pega tu API key y secret, luego haz clic en Try it out.

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" }
}

Firma inválida o timestamp fuera de la ventana (401):

{ "error": "Signature does not match", "code": "signature_invalid" }

Propiedades de la API Key

Propiedad	Detalles
Prefijo	`sk_live_` (producción) o `sk_test_` (pruebas)
Alcance	`default:sync` — habilita `sync_collaborators` y `sync_activities`
Límite de tasa	Configurable por clave (por defecto: 1000 solicitudes/hora)
Expiración	Opcional — establece una fecha de vencimiento o déjala sin expirar
Lista de IPs permitidas	Opcional — restringe a direcciones IP específicas
Almacenamiento	Hasheada con bcrypt — la clave en texto plano nunca se almacena

Formatos de Clave

SalesOS usa dos prefijos de clave para distinguir ambientes:

Prefijo	Ambiente	Caso de uso
`sk_live_`	Producción	Datos reales, misiones reales, puntos reales
`sk_test_`	Pruebas	Seguro 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

Todo rechazo de la capa de autenticación tiene el mismo formato: error es un string legible y code es estable — ramifica por code, nunca por el texto.

{ "error": "Signature does not match", "code": "signature_invalid" }

Estado HTTP	`code`	Significado	Qué hacer
401	`header_missing`	Sin header `Authorization`	Envía `Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
401	`header_malformed`	Header fuera del formato `P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`	Revisa el esquema, los dos puntos y que el timestamp sea entero
401	`api_key_not_found`	Clave inexistente o revocada	Confirma la clave en el Dashboard; una revocada no vuelve — pide otra
401	`key_expired`	La clave pasó su fecha de expiración	Pide una clave nueva
401	`signature_invalid`	La firma no coincide	Firma los bytes crudos del cuerpo y el path exacto, con el secret correcto
401	`timestamp_too_old`	Timestamp con más de 30 segundos	Firma de nuevo en cada intento; sincroniza el reloj (NTP)
401	`timestamp_in_future`	Timestamp adelantado respecto al reloj del servidor	Sincroniza el reloj (NTP) — cualquier segundo en el futuro se rechaza
403	`scope_insufficient`	Clave válida sin el alcance requerido	Lee `missing_scopes` y pide el alcance en la clave

Ejemplo: Clave sin el alcance requerido

{
  "error": "API key missing required scopes: checkin:write",
  "code": "scope_insufficient",
  "missing_scopes": ["checkin:write"]
}

missing_scopes solo aparece en este caso.

Límites de Tasa

Cada API key tiene un contador de límite de tasa independiente que se reinicia cada hora:

Configuración	Por defecto	Rango
Solicitudes por hora	1000	10 — 100.000

Cómo funciona:

Cada petición autenticada y autorizada cuenta en la ventana de la clave (los rechazos de autenticación no cuentan)
La ventana es de una hora desde la primera petición
Hoy el límite se mide, pero no bloquea. Cuando se active el bloqueo, el exceso responderá 429 con code: "rate_limited" y el header Retry-After en segundos — manéjalo desde ya

Manejo de límites de tasa en código:

// signedRequest() es el helper del Inicio Rápido de arriba.
async function callWithRetry(method, path, body) {
  const response = await signedRequest(method, path, body);

  if (response.status === 429) {
    const waitSeconds = Number(response.headers.get("Retry-After")) || 60;
    console.log(`Rate limited. Retrying in ${waitSeconds}s...`);
    await new Promise(r => setTimeout(r, waitSeconds * 1000));
    return callWithRetry(method, path, body); // firma de nuevo: el timestamp vale 30 s
  }

  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. Crea una nueva clave en el Dashboard → copia ambos valores:
#    - SALESOS_API_KEY=sk_live_NEW_KEY
#    - SALESOS_API_SECRET=NEW_SECRET
# 2. Actualiza ambas variables de entorno en tu deployment.
# 3. Verifica que funciona usando el helper de petición firmada del Inicio
#    Rápido (Node, Python o Bash). Payload de ejemplo:
#    { "action": "sync_collaborators",
#      "collaborators": [{"external_id":"test","name":"Test","email":"test@co.com"}] }
# 4. Revoca la clave antigua en el Dashboard.

Descripción General

Integraciones

Autenticación

Autenticación

Entornos

Inicio Rápido

1. Crear una API Key

2. Firma y Envía una Petición

3. Verificar la Respuesta

Propiedades de la API Key

Formatos de Clave

Errores de Autenticación

Ejemplo: Clave sin el alcance requerido

Límites de Tasa

Mejores Prácticas de Seguridad

Ejemplo de rotación de claves

Proximos Pasos

Integracion por Defecto

API Keys

​Autenticación

​Entornos

​Inicio Rápido

​1. Crear una API Key

​2. Firma y Envía una Petición

​3. Verificar la Respuesta

​Propiedades de la API Key

​Formatos de Clave

​Errores de Autenticación

​Ejemplo: Clave sin el alcance requerido

​Límites de Tasa

​Mejores Prácticas de Seguridad

​Ejemplo de rotación de claves

​Proximos Pasos

Integracion por Defecto

API Keys

Autenticación

Entornos

Inicio Rápido

1. Crear una API Key

2. Firma y Envía una Petición

3. Verificar la Respuesta

Propiedades de la API Key

Formatos de Clave

Errores de Autenticación

Ejemplo: Clave sin el alcance requerido

Límites de Tasa

Mejores Prácticas de Seguridad

Ejemplo de rotación de claves

Proximos Pasos