Saltar para o conteúdo principal

​
Autenticação

A API de Integração SalesOS usa API Keys para autenticação. Cada chave tem escopo em um único tenant, é hasheada com bcrypt e suporta rate limiting e listas de IPs permitidos.

​
Ambientes

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

​
Início Rápido

​
1. Crie uma API Key

Acesse Integracoes > API Keys no Dashboard SalesOS:
  1. Clique em Criar API Key
  2. Nomeie sua chave (ex.: “Sincronização CRM Noturna”, “Integração Formulário Website”)
  3. Selecione o escopo: default:sync
  4. Clique em Criar
  5. Copie a chave imediatamente — ela será exibida apenas uma vez
Sua chave terá este formato: 
sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​
2. Use a Chave nas Requisições

Inclua a chave no header Authorization de toda requisição à 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. Verifique a Resposta

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

​
Propriedades da API Key

PropriedadeDetalhes
Prefixosk_live_ (produção) ou sk_test_ (testes)
Escopodefault:sync — habilita sync_collaborators e sync_activities
Rate limitConfigurável por chave (padrão: 1000 requisições/hora)
ExpiraçãoOpcional — defina uma data de expiração ou deixe como sem expiração
Lista de IPs permitidosOpcional — restrinja a endereços IP específicos
ArmazenamentoHasheada com bcrypt — a chave em texto puro nunca é armazenada

​
Formatos de Chave

O SalesOS usa dois prefixos de chave para distinguir ambientes:
PrefixoAmbienteCaso de uso
sk_live_ProduçãoDados reais, missões reais, pontos reais
sk_test_TestesSeguro para usar durante o desenvolvimento — sem impacto na produção
Use chaves sk_test_ durante o desenvolvimento e testes de integração. Mude para sk_live_ quando for para produção.

​
Erros de Autenticação

Status HTTPCódigo do ErroSignificadoO que fazer
401UNAUTHORIZEDChave ausente, inválida ou expiradaVerifique o header Authorization. Confirme a chave no Dashboard.
403FORBIDDENChave válida mas sem o escopo necessárioEdite a chave e adicione o escopo default:sync
429RATE_LIMITEDMuitas requisições nesta horaAguarde retry_after segundos e tente novamente

​
Exemplo: Header Authorization ausente

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

​
Exemplo: Prefixo de chave incorreto

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

​
Exemplo: Chave sem o escopo necessário

Se sua chave possui apenas leads:read mas o endpoint requer default:sync: 
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key missing required scopes: default:sync"
  }
}

​
Exemplo: Rate limit excedido

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after": 1847
  }
}
O campo retry_after indica quantos segundos aguardar. A janela de rate limit é reiniciada a cada hora.

​
Rate Limits

Cada API key possui um contador de rate limit independente que é reiniciado a cada hora:
ConfiguraçãoPadrãoFaixa
Requisições por hora10001 — 100.000
Como funciona:
  1. Cada requisição bem-sucedida incrementa o contador
  2. Quando o contador atinge o limite, requisições seguintes retornam 429
  3. O contador é reiniciado para 0 uma hora após a primeira requisição na janela
Tratando rate limits no 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();
}

​
Boas Práticas de Segurança

Nunca exponha API keys em código client-side. JavaScript no navegador, aplicativos mobile e repositórios públicos podem vazar sua chave. Sempre chame a API SalesOS a partir do seu servidor backend.
  • Use variáveis de ambiente — Armazene SALESOS_API_KEY em variáveis de ambiente ou em um gerenciador de segredos, nunca no código-fonte
  • Rotacione as chaves periodicamente — Crie uma nova chave, atualize sua integração e depois revogue a antiga
  • Use listas de IPs permitidos — Se sua integração roda a partir de IPs fixos, restrinja a chave apenas a esses IPs
  • Monitore o uso — Verifique os logs de uso da API no Dashboard para padrões inesperados
  • Use sk_test_ para desenvolvimento — Chaves de teste isolam seu ambiente de desenvolvimento da produção
  • Revogue chaves comprometidas imediatamente — Acesse Dashboard > Admin > API Keys > Revogar

​
Exemplo de rotação de chaves

# 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

​
Gerenciamento Self-Service de API Keys

Alem de criar chaves no Dashboard, administradores do tenant podem gerenciar API keys programaticamente via API. Isso possibilita:
  • Rotacao automatizada de chaves em pipelines CI/CD
  • Workflows de onboarding de parceiros que provisionam chaves sob demanda
  • Paineis admin customizados que integram gerenciamento de chaves

Gerenciamento de API Keys

Crie, liste e revogue chaves via API usando seu token JWT do Dashboard

​
Proximos Passos

Integracao Padrao

Comece a enviar atividades para o SalesOS

API Keys

Gerencie chaves programaticamente