Autenticação

Teste requisições assinadas no navegador no Sandbox da API — cole sua API key e secret, e o playground assina as requisições automaticamente.

A API de Integração SalesOS usa o esquema de requisições assinadas P2S-SIGN-V1 no header Authorization. As API Keys têm escopo em um único tenant, são hasheadas com bcrypt e suportam rate limiting e listas de IPs permitidos.

Esquema	Quando usar	Formato
P2S-SIGN-V1	Chamadas server-to-server — assinadas com o secret da API key	`P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`

Ambientes

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

Início Rápido

1. Crie uma API Key

Acesse Integracoes > API Keys no Dashboard SalesOS:

Clique em Criar API Key
Nomeie sua chave (ex.: “Sincronização CRM Noturna”, “Integração Formulário Website”)
Selecione o escopo: default:sync
Clique em Criar
Copie os dois valores imediatamente — só são exibidos uma vez:
- API Key — identificador público, ex. sk_live_a1b2c3d4...
- API Key Secret — usado para assinar requisições, nunca é enviado pela rede

2. Assine e Envie uma Requisição

Para chamadas server-to-server, monte o header Authorization como P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. A SIGNATURE é o HMAC-SHA256 hex de uma cadeia de chaves derivada em 5 passos:

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 é Unix epoch em segundos, válido por 30 segundos. PAYLOAD_SHA256_HEX é o SHA-256 hex em minúsculas do corpo bruto da requisição (use o digest da string vazia e3b0c4...b855 quando não houver 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"

Não quer escrever o código de assinatura ainda? O Sandbox da API assina as requisições para você no navegador — cole sua API key e secret, depois clique em Try it out.

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

Assinatura inválida ou timestamp fora da janela (401):

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

Propriedades da API Key

Propriedade	Detalhes
Prefixo	`sk_live_` (produção) ou `sk_test_` (testes)
Escopo	`default:sync` — habilita `sync_collaborators` e `sync_activities`
Rate limit	Configurável por chave (padrão: 1000 requisições/hora)
Expiração	Opcional — defina uma data de expiração ou deixe como sem expiração
Lista de IPs permitidos	Opcional — restrinja a endereços IP específicos
Armazenamento	Hasheada com bcrypt — a chave em texto puro nunca é armazenada

Formatos de Chave

O SalesOS usa dois prefixos de chave para distinguir ambientes:

Prefixo	Ambiente	Caso de uso
`sk_live_`	Produção	Dados reais, missões reais, pontos reais
`sk_test_`	Testes	Seguro 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

Toda recusa da camada de autenticação tem o mesmo formato: error é uma string legível e code é estável — ramifique pelo code, nunca pelo texto.

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

Status HTTP	`code`	Significado	O que fazer
401	`header_missing`	Sem header `Authorization`	Envie `Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
401	`header_malformed`	Header fora do formato `P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`	Confira o esquema, os dois-pontos e se o timestamp é inteiro
401	`api_key_not_found`	Chave inexistente ou revogada	Confirme a chave no Dashboard; revogada não volta — peça outra
401	`key_expired`	Chave passou da data de expiração	Peça uma chave nova
401	`signature_invalid`	A assinatura não confere	Assine os bytes crus do corpo, o path exato e use o secret certo
401	`timestamp_too_old`	Timestamp com mais de 30 segundos	Assine de novo a cada tentativa; sincronize o relógio (NTP)
401	`timestamp_in_future`	Timestamp à frente do relógio do servidor	Sincronize o relógio (NTP) — qualquer segundo no futuro é recusado
403	`scope_insufficient`	Chave válida sem o escopo exigido	Veja `missing_scopes` e peça o escopo na chave

Exemplo: Chave sem o escopo necessário

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

missing_scopes só aparece neste caso.

Rate Limits

Cada API key possui um contador de rate limit independente que é reiniciado a cada hora:

Configuração	Padrão	Faixa
Requisições por hora	1000	10 — 100.000

Como funciona:

Cada requisição autenticada e autorizada conta na janela da chave (recusas de autenticação não contam)
A janela é de uma hora a partir da primeira requisição
Hoje o limite é medido, mas não bloqueia. Quando o bloqueio for ligado, o excesso responderá 429 com code: "rate_limited" e o header Retry-After em segundos — trate isso desde já

Tratando rate limits no código:

// signedRequest() é o helper do Início Rápido acima.
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); // assina de novo: o timestamp vale 30 s
  }

  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. Crie uma nova chave no Dashboard → copie ambos os valores:
#    - SALESOS_API_KEY=sk_live_NEW_KEY
#    - SALESOS_API_SECRET=NEW_SECRET
# 2. Atualize ambas as variáveis de ambiente no seu deployment.
# 3. Verifique se funciona usando o helper de requisição assinada do Início
#    Rápido (Node, Python ou Bash). Exemplo de payload:
#    { "action": "sync_collaborators",
#      "collaborators": [{"external_id":"test","name":"Test","email":"test@co.com"}] }
# 4. Revogue a chave antiga no Dashboard.

Visão Geral

Integrações

Autenticação

Autenticação

Ambientes

Início Rápido

1. Crie uma API Key

2. Assine e Envie uma Requisição

3. Verifique a Resposta

Propriedades da API Key

Formatos de Chave

Erros de Autenticação

Exemplo: Chave sem o escopo necessário

Rate Limits

Boas Práticas de Segurança

Exemplo de rotação de chaves

Proximos Passos

Integracao Padrao

API Keys

​Autenticação

​Ambientes

​Início Rápido

​1. Crie uma API Key

​2. Assine e Envie uma Requisição

​3. Verifique a Resposta

​Propriedades da API Key

​Formatos de Chave

​Erros de Autenticação

​Exemplo: Chave sem o escopo necessário

​Rate Limits

​Boas Práticas de Segurança

​Exemplo de rotação de chaves

​Proximos Passos

Integracao Padrao

API Keys

Autenticação

Ambientes

Início Rápido

1. Crie uma API Key

2. Assine e Envie uma Requisição

3. Verifique a Resposta

Propriedades da API Key

Formatos de Chave

Erros de Autenticação

Exemplo: Chave sem o escopo necessário

Rate Limits

Boas Práticas de Segurança

Exemplo de rotação de chaves

Proximos Passos