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
- Voce obtem uma Chave de API no Dashboard do SalesOS (Admin > Integracoes > Chaves de API)
- Voce sincroniza seu time — cadastra colaboradores (vendedores) para que o SalesOS saiba quem sao
- Voce envia atividades numeradas de 001-999 por um unico endpoint REST
- Seu administrador mapeia cada numero de atividade para uma missao do SalesOS no Dashboard
- 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
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...Cadastre seu time de vendas
Antes de enviar atividades, informe ao SalesOS quem sao seus vendedores:Resposta:
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).
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:
Clique em Salvar. A partir de agora, toda atividade “001” enviada via API contara para a missao “Ligacoes Realizadas”.
| Atividade | Mapear para Missao |
|---|---|
| Atividade 001 | Ligacoes Realizadas |
| Atividade 002 | Reunioes Agendadas |
| Atividade 003 | Propostas Enviadas |
Autenticacao
Todas as requisicoes exigem uma Chave de API no headerAuthorization:
| Propriedade | Detalhes |
|---|---|
| Header | Authorization: Bearer sk_live_xxx |
| Escopo necessario | default:sync |
| Limite de requisicoes | Configuravel por chave (padrao: 1000 requisicoes/hora) |
| Formato da chave | sk_live_ (producao) ou sk_test_ (teste) |
Ambientes
- Production
- Staging
URL Base:
https://api.play2sell.comDashboard: https://dashboard.play2sell.comApp: https://app.play2sell.comReferencia do Endpoint
URL Base: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
Deve ser
"sync_collaborators"Array de objetos de colaborador (max 500)
ID unico no seu sistema (max 255 caracteres)
Nome completo (max 255 caracteres)
Email valido — usado para vincular atividades depois
Numero de telefone (qualquer formato)
Documento de identificacao como CPF (max 20 caracteres)
Nome do time (max 100 caracteres)
Cargo na organizacao (max 50 caracteres)
Quaisquer dados extras em chave-valor
Exemplo: Sincronizar um time completo
Resposta (200 — Sucesso)
created: 2— Maria e Joao eram novos, entao foram criadosexisting: 1— Ana ja existia (encontrada pelo email), entao foi atualizadaerrors: []— nenhuma falha neste lote
Exemplo: Falhas parciais em um lote
Se alguns colaboradores possuem dados invalidos, eles falham individualmente sem bloquear os demais: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
Deve ser
"sync_activities"Array de objetos de atividade (max 1000)
Codigo de 3 digitos:
"001" ate "999"ID unico para deduplicacao (max 255 caracteres)
Email do vendedor que realizou a atividade
Qualquer contexto adicional (formato livre)
Quando aconteceu (ISO 8601). Padrao: agora.
Exemplo: Enviar as atividades de um dia
Resposta (200 — Sucesso)
Campos da resposta explicados
Atividades registradas com sucesso
Atividades cujo email do colaborador nao foi encontrado no SalesOS
Atividades com
external_id que ja foi enviado anteriormenteArray de mensagens de erro para itens que falharam
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 viasync_collaboratorsduplicates: 2— duas atividades tinham valores deexternal_idja 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:| Codigo | Atividade no CRM | Missao no SalesOS | Pontos |
|---|---|---|---|
| 001 | Ligacao para prospecto | Ligacoes Realizadas | 5 pts |
| 002 | Reuniao (presencial ou video) | Reunioes Agendadas | 15 pts |
| 003 | Proposta enviada | Propostas Enviadas | 20 pts |
| 004 | Contrato assinado | Contratos Fechados | 50 pts |
| 005 | Visita ao imovel com cliente | Visitas Realizadas | 25 pts |
| 006 | Email de follow-up enviado | Follow-ups Enviados | 3 pts |
| 007 | Qualificacao de lead concluida | Leads Qualificados | 10 pts |
| Codigo | Atividade no CRM | Missao no SalesOS | Pontos |
|---|---|---|---|
| 001 | Ligacao de descoberta | Ligacoes de Descoberta | 10 pts |
| 002 | Demo de produto agendada | Demos Agendadas | 20 pts |
| 003 | Trial iniciado | Trials Iniciados | 15 pts |
| 004 | Proposta enviada | Propostas Enviadas | 25 pts |
| 005 | Negocio fechado | Deals Fechados | 100 pts |
Idempotencia
O campoexternal_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:
external_id) — deduplicada com seguranca:
Tratamento de Erros
Formato da Resposta de Erro
Todos os erros seguem uma estrutura consistente:Referencia de Codigos de Erro
400 — VALIDATION_ERROR
400 — VALIDATION_ERROR
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.401 — UNAUTHORIZED
401 — UNAUTHORIZED
403 — FORBIDDEN
403 — FORBIDDEN
Quando acontece: Chave de API nao possui o escopo
default:sync.O que fazer: Edite a chave no Dashboard e adicione o escopo necessario.405 — METHOD_NOT_ALLOWED
405 — METHOD_NOT_ALLOWED
Quando acontece: Usou GET, PUT, etc. ao inves de POST.O que fazer: Altere para
POST.429 — RATE_LIMITED
429 — RATE_LIMITED
Quando acontece: Muitas requisicoes nesta hora.O que fazer: Aguarde
retry_after segundos e tente novamente.500 — SERVER_ERROR
500 — SERVER_ERROR
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
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
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
Oexternal_id e sua chave de deduplicacao. Escolha algo estavel e unico do seu sistema de origem:
| Origem | Bom external_id | Mau external_id |
|---|---|---|
| CRM | crm-event-12345 | random-uuid-each-time |
| Banco de dados | db-row-id-789 | timestamp-only |
| Webhook | webhook-delivery-abc | user-email (nao e unico) |
Lidando com falhas
- Erros 400: Corrija os dados e reenvie. Verifique o array
detailspara erros a nivel de campo. - Erros 429: Aguarde
retry_aftersegundos 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_idevita 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.| Limite | Valor |
|---|---|
| Requisicoes por hora (padrao) | 1000 |
| Max de colaboradores por requisicao | 500 |
| Max de atividades por requisicao | 1000 |
| Timeout por requisicao | 120 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
Proximos Passos
Autenticacao
Saiba como criar e gerenciar Chaves de API
Suporte
Precisa de ajuda? Entre em contato com nosso time de suporte

