Skip to main content

Integracao Activities

Teste requisições assinadas no navegador no Sandbox da API — cole sua API key e secret, e o playground assina as requisições automaticamente.
Os exemplos abaixo mostram o header no formato wire Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. Para computar a assinatura no seu código, use o helper signedRequest em Autenticação.
A integracao Activities 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:
Resposta:
3

Envie atividades do seu CRM

Agora envie as atividades que seus vendedores realizaram hoje:
Resposta:
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 “Activities” no dropdown de CRM. Voce vera as atividades 001 ate 999. Mapeie as que voce usa: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:
Consulte a pagina de Autenticacao para detalhes sobre como criar e gerenciar Chaves de API.

Ambientes

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

Referencia do Endpoint

URL Base:
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

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

Exemplo: Sincronizar um time completo

Resposta (200 — Sucesso)

  • 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:
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

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

Exemplo: Enviar as atividades de um dia

Resposta (200 — Sucesso)

Campos da resposta explicados

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

Exemplo: Resultados mistos (alguns ignorados, alguns duplicados)

Se voce reenvia o mesmo lote ou inclui emails desconhecidos:
  • 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: Exemplo de mapeamento para uma empresa SaaS:
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:
Segunda chamada (mesmo external_id) — deduplicada com seguranca:
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:

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

Resposta (400):
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

Aguarde 1847 segundos (~31 minutos) antes de tentar novamente. O limite de requisicoes reinicia a cada hora.

Exemplo: Chave de API invalida


Exemplos Completos de Codigo


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:

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.

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