Integracion Activities
Los ejemplos siguientes muestran el header en formato wire
Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. Para calcular la firma en tu código, usa el helper signedRequest en Autenticación.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
1
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...2
Registrar tu equipo de ventas
Antes de enviar actividades, indica a SalesOS quienes son tus vendedores:Respuesta:
3
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).
4
Mapear codigos a misiones en el Dashboard
En el Dashboard, ve a Misiones > Configurar. Selecciona “Activities” 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”.
Autenticacion
Todas las solicitudes requieren una API Key en el headerAuthorization:
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
string
requerido
Debe ser
"sync_collaborators"array
requerido
Array de objetos de colaborador (max 500)
string
requerido
ID unico en tu sistema (max 255 caracteres)
string
requerido
Nombre completo (max 255 caracteres)
string
requerido
Email valido — se usa para vincular actividades posteriormente
string
Numero de telefono (cualquier formato)
string
Documento de identidad como CPF (max 20 caracteres)
string
Nombre del equipo (max 100 caracteres)
string
Rol en tu organizacion (max 50 caracteres)
object
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
string
requerido
Debe ser
"sync_activities"array
requerido
Array de objetos de actividad (max 1000)
string
requerido
Codigo de 3 digitos:
"001" a "999"string
requerido
ID unico para deduplicacion (max 255 caracteres)
string
requerido
Email del vendedor que realizo la actividad
object
Cualquier contexto adicional (formato libre)
string
Cuando ocurrio (ISO 8601). Por defecto es ahora.
Ejemplo: Enviar las actividades de un dia
Respuesta (200 — Exitosa)
Campos de respuesta explicados
number
Actividades registradas exitosamente
number
Actividades donde el email del colaborador no fue encontrado en SalesOS
number
Actividades con un
external_id que ya fue enviado anteriormentearray
Array de mensajes de error para los elementos que fallaron
number
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:
Ejemplo de mapeo para una empresa SaaS:
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.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:
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.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

