Saltar para o conteúdo principal

Integracao Default

A integracao Default permite conectar qualquer CRM ou sistema externo ao SalesOS — mesmo que nao exista uma integracao dedicada disponivel. Voce envia atividades numeradas (001-999) via API e as mapeia para missoes do SalesOS no Dashboard.

Como Funciona

  1. Voce obtem uma Chave de API no Dashboard do SalesOS (Admin > Integracoes > Chaves de API)
  2. Voce sincroniza seu time — cadastra colaboradores (vendedores) para que o SalesOS saiba quem sao
  3. Voce envia atividades numeradas de 001-999 por um unico endpoint REST
  4. Seu administrador mapeia cada numero de atividade para uma missao do SalesOS no Dashboard
  5. O SalesOS processa as atividades como conclusoes de missao, atribuindo pontos e acompanhando o progresso
Os codigos de atividade sao apenas numeros (001 ate 999). O significado de cada codigo e definido pela sua equipe ao mapea-los para missoes no Dashboard. Por exemplo, “001” pode significar “Ligacao telefonica” e “002” pode significar “Reuniao agendada”.

Inicio Rapido

1

Obtenha sua Chave de API

Va ate Admin > Integracoes > Chaves de API no Dashboard do SalesOS. Crie uma nova chave com o escopo default:sync. Copie a chave — ela sera exibida apenas uma vez.Sua chave tera este formato: sk_live_a1b2c3d4e5f6g7h8i9j0...
2

Cadastre seu time de vendas

Antes de enviar atividades, informe ao SalesOS quem sao seus vendedores:
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",
        "team": "Sales Team A",
        "role": "sales_rep"
      },
      {
        "external_id": "emp-102",
        "name": "Joao Silva",
        "email": "joao@yourcompany.com",
        "team": "Sales Team A",
        "role": "sales_rep"
      },
      {
        "external_id": "emp-103",
        "name": "Ana Oliveira",
        "email": "ana@yourcompany.com",
        "team": "Sales Team B",
        "role": "team_lead"
      }
    ]
  }'
Resposta:
{
  "data": { "created": 3, "existing": 0, "errors": [], "total": 3 },
  "meta": { "request_id": "a1b2c3d4-...", "timestamp": "2026-03-17T10:00:00.000Z" }
}
3

Envie atividades do seu CRM

Agora envie as atividades que seus vendedores realizaram hoje:
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_activities",
    "activities": [
      {
        "activity_code": "001",
        "external_id": "crm-evt-10001",
        "collaborator_email": "maria@yourcompany.com",
        "data": { "client": "Acme Corp", "duration_min": 12 },
        "occurred_at": "2026-03-17T09:15:00Z"
      },
      {
        "activity_code": "002",
        "external_id": "crm-evt-10002",
        "collaborator_email": "joao@yourcompany.com",
        "data": { "client": "Beta Inc", "type": "video_call" },
        "occurred_at": "2026-03-17T10:30:00Z"
      },
      {
        "activity_code": "001",
        "external_id": "crm-evt-10003",
        "collaborator_email": "maria@yourcompany.com",
        "data": { "client": "Gamma Ltd" },
        "occurred_at": "2026-03-17T11:00:00Z"
      }
    ]
  }'
Resposta:
{
  "data": { "processed": 3, "skipped": 0, "duplicates": 0, "errors": [], "total": 3 },
  "meta": { "request_id": "d4e5f6g7-...", "timestamp": "2026-03-17T11:05:00.000Z" }
}
Maria recebeu 2 atividades (duas ligacoes telefonicas) e Joao recebeu 1 (uma reuniao).
4

Mapeie codigos para missoes no Dashboard

No Dashboard, va ate Missoes > Configurar. Selecione “Default” no dropdown de CRM. Voce vera as atividades 001 ate 999. Mapeie as que voce usa:
AtividadeMapear para Missao
Atividade 001Ligacoes Realizadas
Atividade 002Reunioes Agendadas
Atividade 003Propostas Enviadas
Clique em Salvar. A partir de agora, toda atividade “001” enviada via API contara para a missao “Ligacoes Realizadas”.

Autenticacao

Todas as requisicoes exigem uma Chave de API no header Authorization:
Authorization: Bearer sk_live_YOUR_API_KEY
Consulte a pagina de Autenticacao para detalhes sobre como criar e gerenciar Chaves de API.
PropriedadeDetalhes
HeaderAuthorization: Bearer sk_live_xxx
Escopo necessariodefault:sync
Limite de requisicoesConfiguravel por chave (padrao: 1000 requisicoes/hora)
Formato da chavesk_live_ (producao) ou sk_test_ (teste)

Ambientes

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

Referencia do Endpoint

URL Base:
POST https://api.play2sell.com/functions/v1/default-integration
O endpoint aceita duas acoes pelo campo action: sync_collaborators e sync_activities.

Acao: sync_collaborators

Cadastre ou atualize colaboradores (vendedores) no SalesOS. Os colaboradores devem existir antes que voce possa atribuir atividades a eles.

Schema da Requisicao

action
string
obrigatório
Deve ser "sync_collaborators"
collaborators
array
obrigatório
Array de objetos de colaborador (max 500)
collaborators[].external_id
string
obrigatório
ID unico no seu sistema (max 255 caracteres)
collaborators[].name
string
obrigatório
Nome completo (max 255 caracteres)
collaborators[].email
string
obrigatório
Email valido — usado para vincular atividades depois
collaborators[].phone
string
Numero de telefone (qualquer formato)
collaborators[].document
string
Documento de identificacao como CPF (max 20 caracteres)
collaborators[].team
string
Nome do time (max 100 caracteres)
collaborators[].role
string
Cargo na organizacao (max 50 caracteres)
collaborators[].metadata
object
Quaisquer dados extras em chave-valor

Exemplo: Sincronizar um time completo

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",
        "phone": "+5511999001001",
        "document": "12345678901",
        "team": "Equipe Vendas SP",
        "role": "vendedor",
        "metadata": { "crm_id": "CRM-2001", "hire_date": "2024-06-15" }
      },
      {
        "external_id": "emp-102",
        "name": "Joao Silva",
        "email": "joao@yourcompany.com",
        "phone": "+5511999002002",
        "team": "Equipe Vendas SP",
        "role": "vendedor"
      },
      {
        "external_id": "emp-103",
        "name": "Ana Oliveira",
        "email": "ana@yourcompany.com",
        "team": "Equipe Vendas RJ",
        "role": "gerente",
        "metadata": { "crm_id": "CRM-2003", "is_manager": true }
      }
    ]
  }'

Resposta (200 — Sucesso)

{
  "data": {
    "created": 2,
    "existing": 1,
    "errors": [],
    "total": 3
  },
  "meta": {
    "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "timestamp": "2026-03-17T14:30:00.000Z"
  }
}
  • created: 2 — Maria e Joao eram novos, entao foram criados
  • existing: 1 — Ana ja existia (encontrada pelo email), entao foi atualizada
  • errors: [] — nenhuma falha neste lote

Exemplo: Falhas parciais em um lote

Se alguns colaboradores possuem dados invalidos, eles falham individualmente sem bloquear os demais:
{
  "data": {
    "created": 8,
    "existing": 1,
    "errors": [
      "Collaborator emp-110 (invalid-email): Invalid email format"
    ],
    "total": 10
  },
  "meta": {
    "request_id": "b2c3d4e5-...",
    "timestamp": "2026-03-17T14:30:00.000Z"
  }
}
Ressincronizar e seguro. Voce pode enviar os mesmos colaboradores varias vezes. Os existentes sao atualizados (nao duplicados) com base no email. Isso facilita executar uma sincronizacao completa noturna a partir do seu CRM.

Acao: sync_activities

Envie eventos de atividade atribuidos a colaboradores. Cada atividade usa um codigo de 3 digitos (001-999) que voce mapeia para missoes no Dashboard.

Schema da Requisicao

action
string
obrigatório
Deve ser "sync_activities"
activities
array
obrigatório
Array de objetos de atividade (max 1000)
activities[].activity_code
string
obrigatório
Codigo de 3 digitos: "001" ate "999"
activities[].external_id
string
obrigatório
ID unico para deduplicacao (max 255 caracteres)
activities[].collaborator_email
string
obrigatório
Email do vendedor que realizou a atividade
activities[].data
object
Qualquer contexto adicional (formato livre)
activities[].occurred_at
string
Quando aconteceu (ISO 8601). Padrao: agora.

Exemplo: Enviar as atividades de um dia

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_activities",
    "activities": [
      {
        "activity_code": "001",
        "external_id": "crm-20260317-001",
        "collaborator_email": "maria@yourcompany.com",
        "data": {
          "client_name": "Acme Corp",
          "client_phone": "+5511988887777",
          "duration_minutes": 12,
          "outcome": "interested"
        },
        "occurred_at": "2026-03-17T09:15:00-03:00"
      },
      {
        "activity_code": "001",
        "external_id": "crm-20260317-002",
        "collaborator_email": "maria@yourcompany.com",
        "data": {
          "client_name": "Beta Inc",
          "duration_minutes": 8,
          "outcome": "no_answer"
        },
        "occurred_at": "2026-03-17T09:30:00-03:00"
      },
      {
        "activity_code": "002",
        "external_id": "crm-20260317-003",
        "collaborator_email": "joao@yourcompany.com",
        "data": {
          "client_name": "Gamma Ltd",
          "meeting_type": "video_call",
          "duration_minutes": 45
        },
        "occurred_at": "2026-03-17T10:00:00-03:00"
      },
      {
        "activity_code": "003",
        "external_id": "crm-20260317-004",
        "collaborator_email": "joao@yourcompany.com",
        "data": {
          "client_name": "Gamma Ltd",
          "proposal_value": 25000.00,
          "currency": "BRL"
        },
        "occurred_at": "2026-03-17T14:00:00-03:00"
      },
      {
        "activity_code": "001",
        "external_id": "crm-20260317-005",
        "collaborator_email": "ana@yourcompany.com",
        "data": {
          "client_name": "Delta SA",
          "duration_minutes": 20,
          "outcome": "scheduled_meeting"
        },
        "occurred_at": "2026-03-17T15:30:00-03:00"
      }
    ]
  }'

Resposta (200 — Sucesso)

{
  "data": {
    "processed": 5,
    "skipped": 0,
    "duplicates": 0,
    "errors": [],
    "total": 5
  },
  "meta": {
    "request_id": "c3d4e5f6-7890-abcd-ef01-234567890abc",
    "timestamp": "2026-03-17T16:00:00.000Z"
  }
}

Campos da resposta explicados

processed
number
Atividades registradas com sucesso
skipped
number
Atividades cujo email do colaborador nao foi encontrado no SalesOS
duplicates
number
Atividades com external_id que ja foi enviado anteriormente
errors
array
Array de mensagens de erro para itens que falharam
total
number
Total de itens recebidos na requisicao

Exemplo: Resultados mistos (alguns ignorados, alguns duplicados)

Se voce reenvia o mesmo lote ou inclui emails desconhecidos:
{
  "data": {
    "processed": 2,
    "skipped": 1,
    "duplicates": 2,
    "errors": [],
    "total": 5
  },
  "meta": {
    "request_id": "d4e5f6g7-...",
    "timestamp": "2026-03-17T16:05:00.000Z"
  }
}
  • skipped: 1 — um email nao estava cadastrado via sync_collaborators
  • duplicates: 2 — duas atividades tinham valores de external_id ja existentes no sistema

Codigos de Atividade (001-999)

Os codigos de atividade sao identificadores abstratos. O significado deles e inteiramente definido por voce. Exemplo de mapeamento para uma imobiliaria:
CodigoAtividade no CRMMissao no SalesOSPontos
001Ligacao para prospectoLigacoes Realizadas5 pts
002Reuniao (presencial ou video)Reunioes Agendadas15 pts
003Proposta enviadaPropostas Enviadas20 pts
004Contrato assinadoContratos Fechados50 pts
005Visita ao imovel com clienteVisitas Realizadas25 pts
006Email de follow-up enviadoFollow-ups Enviados3 pts
007Qualificacao de lead concluidaLeads Qualificados10 pts
Exemplo de mapeamento para uma empresa SaaS:
CodigoAtividade no CRMMissao no SalesOSPontos
001Ligacao de descobertaLigacoes de Descoberta10 pts
002Demo de produto agendadaDemos Agendadas20 pts
003Trial iniciadoTrials Iniciados15 pts
004Proposta enviadaPropostas Enviadas25 pts
005Negocio fechadoDeals Fechados100 pts
Voce nao precisa usar todos os 999 codigos. A maioria dos times usa de 5 a 20 codigos. Comece com poucos e adicione mais conforme necessario.

Idempotencia

O campo external_id garante idempotencia. Se voce enviar a mesma atividade duas vezes com o mesmo external_id, a segunda requisicao a reporta como duplicata — ela nao e processada novamente. Primeira chamada — atividade e processada:
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_activities",
    "activities": [{
      "activity_code": "001",
      "external_id": "crm-call-5001",
      "collaborator_email": "maria@yourcompany.com"
    }]
  }'
{ "data": { "processed": 1, "skipped": 0, "duplicates": 0, "errors": [], "total": 1 } }
Segunda chamada (mesmo external_id) — deduplicada com seguranca:
{ "data": { "processed": 0, "skipped": 0, "duplicates": 1, "errors": [], "total": 1 } }
Use o ID do evento do seu CRM como external_id. Isso garante que, mesmo se seu job de sincronizacao rodar duas vezes (ex: apos uma falha e retry), as atividades nunca serao contadas em duplicidade.

Tratamento de Erros

Formato da Resposta de Erro

Todos os erros seguem uma estrutura consistente:
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": []
  }
}

Referencia de Codigos de Erro

Quando acontece: Body invalido, campos ausentes, codigo de atividade invalido.O que fazer: Corrija o payload da requisicao — verifique o array details para detalhes especificos.
Quando acontece: Chave de API ausente, invalida ou expirada.O que fazer: Verifique sua chave de API. Gere uma nova se estiver expirada.
Quando acontece: Chave de API nao possui o escopo default:sync.O que fazer: Edite a chave no Dashboard e adicione o escopo necessario.
Quando acontece: Usou GET, PUT, etc. ao inves de POST.O que fazer: Altere para POST.
Quando acontece: Muitas requisicoes nesta hora.O que fazer: Aguarde retry_after segundos e tente novamente.
Quando acontece: Erro interno.O que fazer: Tente novamente com backoff exponencial. Entre em contato com o suporte se persistir.

Exemplo: Erro de validacao com detalhes

# Enviando um activity_code invalido e um email invalido
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_activities",
    "activities": [
      { "activity_code": "abc", "external_id": "e1", "collaborator_email": "maria@co.com" },
      { "activity_code": "001", "external_id": "e2", "collaborator_email": "not-an-email" },
      { "activity_code": "001", "external_id": "e3", "collaborator_email": "joao@co.com" }
    ]
  }'
Resposta (400):
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid activities payload",
    "details": [
      { "index": 0, "field": "activity_code", "message": "Required 3-digit string (001-999), e.g. \"001\"" },
      { "index": 1, "field": "collaborator_email", "message": "Required valid email" }
    ]
  }
}
O campo index indica qual item do array tem o problema. O item no indice 2 (joao) era valido — apenas os itens invalidos sao listados.

Exemplo: Limite de requisicoes excedido

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after": 1847
  }
}
Aguarde 1847 segundos (~31 minutos) antes de tentar novamente. O limite de requisicoes reinicia a cada hora.

Exemplo: Chave de API invalida

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Exemplos Completos de Codigo

# Step 1: Set your API key
export SALESOS_KEY="sk_live_YOUR_API_KEY"
export SALESOS_URL="https://api.play2sell.com/functions/v1/default-integration"

# Step 2: Register your team (run once, or nightly to keep in sync)
curl -s -X POST "$SALESOS_URL" \
  -H "Authorization: Bearer $SALESOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_collaborators",
    "collaborators": [
      { "external_id": "emp-101", "name": "Maria Santos", "email": "maria@co.com", "team": "SP" },
      { "external_id": "emp-102", "name": "Joao Silva", "email": "joao@co.com", "team": "SP" },
      { "external_id": "emp-103", "name": "Ana Oliveira", "email": "ana@co.com", "team": "RJ" }
    ]
  }' | jq .

# Step 3: Send today's activities
curl -s -X POST "$SALESOS_URL" \
  -H "Authorization: Bearer $SALESOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_activities",
    "activities": [
      { "activity_code": "001", "external_id": "call-1001", "collaborator_email": "maria@co.com", "data": {"client": "Acme"} },
      { "activity_code": "001", "external_id": "call-1002", "collaborator_email": "maria@co.com", "data": {"client": "Beta"} },
      { "activity_code": "002", "external_id": "meet-2001", "collaborator_email": "joao@co.com", "data": {"client": "Gamma", "type": "video"} },
      { "activity_code": "003", "external_id": "prop-3001", "collaborator_email": "joao@co.com", "data": {"value": 50000} },
      { "activity_code": "001", "external_id": "call-1003", "collaborator_email": "ana@co.com", "data": {"client": "Delta"} }
    ]
  }' | jq .

Boas Praticas

Estrategia de Sincronizacao

  • Colaboradores: Sincronize todo o time diariamente a noite. A API e idempotente — usuarios existentes sao atualizados, nao duplicados.
  • Atividades: Sincronize a cada 5-15 minutos, ou em tempo real via webhooks do seu CRM. Sempre use o ID do evento do seu CRM como external_id.
  • Tamanho do lote: Envie ate 1000 atividades por requisicao. Para grandes volumes, divida em lotes sequenciais.

Escolhendo o external_id

O external_id e sua chave de deduplicacao. Escolha algo estavel e unico do seu sistema de origem:
OrigemBom external_idMau external_id
CRMcrm-event-12345random-uuid-each-time
Banco de dadosdb-row-id-789timestamp-only
Webhookwebhook-delivery-abcuser-email (nao e unico)

Lidando com falhas

  • Erros 400: Corrija os dados e reenvie. Verifique o array details para erros a nivel de campo.
  • Erros 429: Aguarde retry_after segundos e tente novamente. Considere reduzir a frequencia de sincronizacao.
  • Erros 500: Tente novamente com backoff exponencial (2s, 4s, 8s). Entre em contato com o suporte se persistir.
  • Erros de rede: Tente novamente com seguranca — a idempotencia via external_id evita duplicatas.

Limites de Requisicoes

Cada chave de API possui um limite configuravel de requisicoes (padrao: 1000 requisicoes por hora). O contador reinicia a cada hora.
LimiteValor
Requisicoes por hora (padrao)1000
Max de colaboradores por requisicao500
Max de atividades por requisicao1000
Timeout por requisicao120 segundos

Seguranca

  • As chaves de API sao hasheadas com bcrypt — nunca armazenadas em texto puro
  • Cada chave tem escopo de um unico tenant — sem acesso entre tenants
  • Listas de IPs permitidos podem ser configuradas por chave
  • Todas as requisicoes sao registradas em log para auditoria
  • As chaves podem ser revogadas instantaneamente pelo Dashboard
Nunca exponha sua chave de API em codigo client-side (JavaScript rodando no navegador). A API deve ser chamada apenas a partir do seu servidor backend.

Proximos Passos

Autenticacao

Saiba como criar e gerenciar Chaves de API

Suporte

Precisa de ajuda? Entre em contato com nosso time de suporte