Integracion Default
La integracion Default te permite conectar cualquier CRM o sistema externo a SalesOS, incluso si no existe una integracion dedicada. Envias actividades numeradas (001-999) via API y las mapeas a misiones de SalesOS en el Dashboard.Como Funciona
- Obtienes una API Key desde el Dashboard de SalesOS (Admin > Integraciones > API Keys)
- Sincronizas tu equipo — registras colaboradores (vendedores) para que SalesOS los reconozca
- Envias actividades numeradas 001-999 mediante un unico endpoint REST
- Tu administrador mapea cada numero de actividad a una mision de SalesOS en el Dashboard
- SalesOS procesa las actividades como completaciones de misiones, otorgando puntos y rastreando el progreso
Los codigos de actividad son simplemente numeros (001 a 999). El significado de cada codigo lo define tu equipo al mapearlos a misiones en el Dashboard. Por ejemplo, “001” podria significar “Llamada telefonica” y “002” podria significar “Reunion agendada”.
Inicio Rapido
Obtener tu API Key
Ve a Admin > Integraciones > API Keys en el Dashboard de SalesOS. Crea una nueva clave con el scope
default:sync. Copia la clave — solo se mostrara una vez.Tu clave luce asi: sk_live_a1b2c3d4e5f6g7h8i9j0...Registrar tu equipo de ventas
Antes de enviar actividades, indica a SalesOS quienes son tus vendedores:Respuesta:
Enviar actividades desde tu CRM
Ahora envia las actividades que tus vendedores realizaron hoy:Respuesta:Maria obtuvo 2 actividades (dos llamadas telefonicas) y Joao obtuvo 1 (una reunion).
Mapear codigos a misiones en el Dashboard
En el Dashboard, ve a Misiones > Configurar. Selecciona “Default” en el dropdown de CRM. Veras las actividades 001 a 999. Mapea las que utilices:
Haz clic en Guardar. A partir de ahora, cada actividad “001” enviada via API contara para la mision “Ligacoes Realizadas”.
| Actividad | Mapear a Mision |
|---|---|
| Atividade 001 | Ligacoes Realizadas |
| Atividade 002 | Reunioes Agendadas |
| Atividade 003 | Propostas Enviadas |
Autenticacion
Todas las solicitudes requieren una API Key en el headerAuthorization:
| Propiedad | Detalles |
|---|---|
| Header | Authorization: Bearer sk_live_xxx |
| Scope requerido | default:sync |
| Limite de solicitudes | Configurable por clave (por defecto: 1000 solicitudes/hora) |
| Formato de clave | sk_live_ (produccion) o sk_test_ (pruebas) |
Entornos
- Production
- Staging
URL Base:
https://api.play2sell.comDashboard: https://dashboard.play2sell.comApp: https://app.play2sell.comReferencia del Endpoint
URL Base:action: sync_collaborators y sync_activities.
Accion: sync_collaborators
Registra o actualiza colaboradores (vendedores) en SalesOS. Los colaboradores deben existir antes de que puedas atribuirles actividades.Esquema de Solicitud
Debe ser
"sync_collaborators"Array de objetos de colaborador (max 500)
ID unico en tu sistema (max 255 caracteres)
Nombre completo (max 255 caracteres)
Email valido — se usa para vincular actividades posteriormente
Numero de telefono (cualquier formato)
Documento de identidad como CPF (max 20 caracteres)
Nombre del equipo (max 100 caracteres)
Rol en tu organizacion (max 50 caracteres)
Cualquier dato adicional clave-valor
Ejemplo: Sincronizar un equipo completo
Respuesta (200 — Exitosa)
created: 2— Maria y Joao eran nuevos, por lo que fueron creadosexisting: 1— Ana ya existia (coincidio por email), por lo que fue actualizadaerrors: []— sin fallos en este lote
Ejemplo: Fallos parciales en un lote
Si algunos colaboradores tienen datos invalidos, fallan individualmente sin bloquear al resto:Accion: sync_activities
Envia eventos de actividad atribuidos a colaboradores. Cada actividad usa un codigo de 3 digitos (001-999) que mapeas a misiones en el Dashboard.Esquema de Solicitud
Debe ser
"sync_activities"Array de objetos de actividad (max 1000)
Codigo de 3 digitos:
"001" a "999"ID unico para deduplicacion (max 255 caracteres)
Email del vendedor que realizo la actividad
Cualquier contexto adicional (formato libre)
Cuando ocurrio (ISO 8601). Por defecto es ahora.
Ejemplo: Enviar las actividades de un dia
Respuesta (200 — Exitosa)
Campos de respuesta explicados
Actividades registradas exitosamente
Actividades donde el email del colaborador no fue encontrado en SalesOS
Actividades con un
external_id que ya fue enviado anteriormenteArray de mensajes de error para los elementos que fallaron
Total de elementos recibidos en la solicitud
Ejemplo: Resultados mixtos (algunos omitidos, algunos duplicados)
Si reenvias el mismo lote o incluyes emails desconocidos:skipped: 1— un email no estaba registrado viasync_collaboratorsduplicates: 2— dos actividades tenian valores deexternal_idque ya estaban en el sistema
Codigos de Actividad (001-999)
Los codigos de actividad son identificadores abstractos. Su significado depende completamente de ti. Ejemplo de mapeo para una empresa inmobiliaria:| Codigo | Actividad del CRM | Mision en SalesOS | Puntos |
|---|---|---|---|
| 001 | Llamada telefonica a prospecto | Ligacoes Realizadas | 5 pts |
| 002 | Reunion (presencial o video) | Reunioes Agendadas | 15 pts |
| 003 | Propuesta enviada | Propostas Enviadas | 20 pts |
| 004 | Contrato firmado | Contratos Fechados | 50 pts |
| 005 | Visita a propiedad con cliente | Visitas Realizadas | 25 pts |
| 006 | Email de seguimiento enviado | Follow-ups Enviados | 3 pts |
| 007 | Calificacion de lead completada | Leads Qualificados | 10 pts |
| Codigo | Actividad del CRM | Mision en SalesOS | Puntos |
|---|---|---|---|
| 001 | Llamada de descubrimiento | Ligacoes de Descoberta | 10 pts |
| 002 | Demo de producto agendada | Demos Agendadas | 20 pts |
| 003 | Prueba gratuita iniciada | Trials Iniciados | 15 pts |
| 004 | Propuesta enviada | Propostas Enviadas | 25 pts |
| 005 | Negocio cerrado | Deals Fechados | 100 pts |
Idempotencia
El campoexternal_id garantiza la idempotencia. Si envias la misma actividad dos veces con el mismo external_id, la segunda solicitud la reporta como duplicada — no se procesa nuevamente.
Primera llamada — la actividad se procesa:
external_id) — deduplicada de forma segura:
Manejo de Errores
Formato de Respuesta de Error
Todos los errores siguen una estructura consistente:Referencia de Codigos de Error
400 — VALIDATION_ERROR
400 — VALIDATION_ERROR
Cuando ocurre: Body invalido, campos faltantes, codigo de actividad incorrecto.Que hacer: Corrige el payload de la solicitud — revisa el array
details para detalles especificos.401 — UNAUTHORIZED
401 — UNAUTHORIZED
403 — FORBIDDEN
403 — FORBIDDEN
Cuando ocurre: La API key no tiene el scope
default:sync.Que hacer: Edita la clave en el Dashboard y agrega el scope requerido.405 — METHOD_NOT_ALLOWED
405 — METHOD_NOT_ALLOWED
Cuando ocurre: Se uso GET, PUT, etc. en lugar de POST.Que hacer: Cambia a
POST.429 — RATE_LIMITED
429 — RATE_LIMITED
Cuando ocurre: Demasiadas solicitudes en esta hora.Que hacer: Espera
retry_after segundos, luego reintenta.500 — SERVER_ERROR
500 — SERVER_ERROR
Cuando ocurre: Error interno.Que hacer: Reintenta con backoff exponencial. Contacta a soporte si persiste.
Ejemplo: Error de validacion con detalles
index te indica cual elemento del array tiene el problema. El elemento en el indice 2 (joao) era valido — solo se listan los elementos invalidos.
Ejemplo: Limite de solicitudes excedido
Ejemplo: API key invalida
Ejemplos de Codigo Completos
Mejores Practicas
Estrategia de Sincronizacion
- Colaboradores: Sincroniza tu equipo completo cada noche. La API es idempotente — los usuarios existentes se actualizan, no se duplican.
- Actividades: Sincroniza cada 5-15 minutos, o en tiempo real via webhooks desde tu CRM. Siempre usa el ID de evento de tu CRM como
external_id. - Tamano de lote: Envia hasta 1000 actividades por solicitud. Para grandes volumenes, divide en lotes secuenciales.
Elegir el external_id
Elexternal_id es tu clave de deduplicacion. Elige algo estable y unico de tu sistema de origen:
| Origen | Buen external_id | Mal external_id |
|---|---|---|
| CRM | crm-event-12345 | random-uuid-each-time |
| Base de datos | db-row-id-789 | timestamp-only |
| Webhook | webhook-delivery-abc | user-email (no es unico) |
Manejo de fallos
- Errores 400: Corrige los datos y reenvia. Revisa el array
detailspara errores a nivel de campo. - Errores 429: Espera
retry_aftersegundos, luego reintenta. Considera reducir la frecuencia de sincronizacion. - Errores 500: Reintenta con backoff exponencial (2s, 4s, 8s). Contacta a soporte si persiste.
- Errores de red: Reintenta de forma segura — la idempotencia via
external_idpreviene duplicados.
Limites de Solicitudes
Cada API key tiene un limite de solicitudes configurable (por defecto: 1000 solicitudes por hora). El contador se reinicia cada hora.| Limite | Valor |
|---|---|
| Solicitudes por hora por defecto | 1000 |
| Max colaboradores por solicitud | 500 |
| Max actividades por solicitud | 1000 |
| Timeout por solicitud | 120 segundos |
Seguridad
- Las API keys se hashean con bcrypt — nunca se almacenan en texto plano
- Cada clave esta limitada a un unico tenant — sin acceso entre tenants
- Se pueden configurar listas de IPs permitidas por clave
- Todas las solicitudes se registran con fines de auditoria
- Las claves pueden revocarse instantaneamente desde el Dashboard
Proximos Pasos
Autenticacion
Aprende a crear y administrar API Keys
Soporte
Necesitas ayuda? Contacta a nuestro equipo de soporte

