Skip to main content

Integracion Activities

Prueba peticiones firmadas en el navegador en el Sandbox de la API — pega tu API key y secret, y el playground firma las peticiones automáticamente.
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.
La integracion Activities 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

  1. Obtienes una API Key desde el Dashboard de SalesOS (Admin > Integraciones > API Keys)
  2. Sincronizas tu equipo — registras colaboradores (vendedores) para que SalesOS los reconozca
  3. Envias actividades numeradas 001-999 mediante un unico endpoint REST
  4. Tu administrador mapea cada numero de actividad a una mision de SalesOS en el Dashboard
  5. 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 header Authorization:
Consulta la pagina de Autenticacion para detalles sobre como crear y administrar API Keys.

Entornos

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

Referencia del Endpoint

URL Base:
El endpoint acepta dos acciones mediante el campo 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 creados
  • existing: 1 — Ana ya existia (coincidio por email), por lo que fue actualizada
  • errors: [] — sin fallos en este lote

Ejemplo: Fallos parciales en un lote

Si algunos colaboradores tienen datos invalidos, fallan individualmente sin bloquear al resto:
Resincronizar es seguro. Puedes enviar los mismos colaboradores multiples veces. Los existentes se actualizan (no se duplican) en base a su email. Esto facilita ejecutar una sincronizacion completa nocturna desde tu CRM.

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 anteriormente
array
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 via sync_collaborators
  • duplicates: 2 — dos actividades tenian valores de external_id que 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:
No necesitas usar los 999 codigos. La mayoria de los equipos usan entre 5 y 20 codigos. Comienza con pocos y agrega mas segun sea necesario.

Idempotencia

El campo external_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:
Segunda llamada (mismo external_id) — deduplicada de forma segura:
Usa el ID de evento de tu CRM como external_id. Esto asegura que incluso si tu trabajo de sincronizacion se ejecuta dos veces (por ejemplo, despues de una falla y reintento), las actividades nunca se cuenten doble.

Manejo de Errores

Formato de Respuesta de Error

Todos los errores siguen una estructura consistente:

Referencia de Codigos de 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.
Cuando ocurre: API key faltante, invalida o expirada.Que hacer: Verifica tu API key. Genera una nueva si expiro.
Cuando ocurre: La API key no tiene el scope default:sync.Que hacer: Edita la clave en el Dashboard y agrega el scope requerido.
Cuando ocurre: Se uso GET, PUT, etc. en lugar de POST.Que hacer: Cambia a POST.
Cuando ocurre: Demasiadas solicitudes en esta hora.Que hacer: Espera retry_after segundos, luego reintenta.
Cuando ocurre: Error interno.Que hacer: Reintenta con backoff exponencial. Contacta a soporte si persiste.

Ejemplo: Error de validacion con detalles

Respuesta (400):
El campo 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

Espera 1847 segundos (~31 minutos) antes de reintentar. El limite de solicitudes se reinicia cada hora.

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

El external_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 details para errores a nivel de campo.
  • Errores 429: Espera retry_after segundos, 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_id previene 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
Nunca expongas tu API key en codigo del lado del cliente (JavaScript ejecutandose en el navegador). La API solo debe ser llamada desde tu servidor backend.

Proximos Pasos

Autenticacion

Aprende a crear y administrar API Keys

Soporte

Necesitas ayuda? Contacta a nuestro equipo de soporte