Saltar al contenido principal

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

  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:
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_collaborators",
    "collaborators": [
      {
        "external_id": "emp-101",
        "name": "Maria Santos",
        "email": "maria@yourcompany.com",
        "team": "Sales Team A",
        "role": "sales_rep"
      },
      {
        "external_id": "emp-102",
        "name": "Joao Silva",
        "email": "joao@yourcompany.com",
        "team": "Sales Team A",
        "role": "sales_rep"
      },
      {
        "external_id": "emp-103",
        "name": "Ana Oliveira",
        "email": "ana@yourcompany.com",
        "team": "Sales Team B",
        "role": "team_lead"
      }
    ]
  }'
Respuesta:
{
  "data": { "created": 3, "existing": 0, "errors": [], "total": 3 },
  "meta": { "request_id": "a1b2c3d4-...", "timestamp": "2026-03-17T10:00:00.000Z" }
}
3

Enviar actividades desde tu CRM

Ahora envia las actividades que tus vendedores realizaron hoy:
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_activities",
    "activities": [
      {
        "activity_code": "001",
        "external_id": "crm-evt-10001",
        "collaborator_email": "maria@yourcompany.com",
        "data": { "client": "Acme Corp", "duration_min": 12 },
        "occurred_at": "2026-03-17T09:15:00Z"
      },
      {
        "activity_code": "002",
        "external_id": "crm-evt-10002",
        "collaborator_email": "joao@yourcompany.com",
        "data": { "client": "Beta Inc", "type": "video_call" },
        "occurred_at": "2026-03-17T10:30:00Z"
      },
      {
        "activity_code": "001",
        "external_id": "crm-evt-10003",
        "collaborator_email": "maria@yourcompany.com",
        "data": { "client": "Gamma Ltd" },
        "occurred_at": "2026-03-17T11:00:00Z"
      }
    ]
  }'
Respuesta:
{
  "data": { "processed": 3, "skipped": 0, "duplicates": 0, "errors": [], "total": 3 },
  "meta": { "request_id": "d4e5f6g7-...", "timestamp": "2026-03-17T11:05:00.000Z" }
}
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 “Default” en el dropdown de CRM. Veras las actividades 001 a 999. Mapea las que utilices:
ActividadMapear a Mision
Atividade 001Ligacoes Realizadas
Atividade 002Reunioes Agendadas
Atividade 003Propostas Enviadas
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:
Authorization: Bearer sk_live_YOUR_API_KEY
Consulta la pagina de Autenticacion para detalles sobre como crear y administrar API Keys.
PropiedadDetalles
HeaderAuthorization: Bearer sk_live_xxx
Scope requeridodefault:sync
Limite de solicitudesConfigurable por clave (por defecto: 1000 solicitudes/hora)
Formato de clavesk_live_ (produccion) o sk_test_ (pruebas)

Entornos

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

Referencia del Endpoint

URL Base:
POST https://api.play2sell.com/functions/v1/default-integration
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

action
string
requerido
Debe ser "sync_collaborators"
collaborators
array
requerido
Array de objetos de colaborador (max 500)
collaborators[].external_id
string
requerido
ID unico en tu sistema (max 255 caracteres)
collaborators[].name
string
requerido
Nombre completo (max 255 caracteres)
collaborators[].email
string
requerido
Email valido — se usa para vincular actividades posteriormente
collaborators[].phone
string
Numero de telefono (cualquier formato)
collaborators[].document
string
Documento de identidad como CPF (max 20 caracteres)
collaborators[].team
string
Nombre del equipo (max 100 caracteres)
collaborators[].role
string
Rol en tu organizacion (max 50 caracteres)
collaborators[].metadata
object
Cualquier dato adicional clave-valor

Ejemplo: Sincronizar un equipo completo

curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_collaborators",
    "collaborators": [
      {
        "external_id": "emp-101",
        "name": "Maria Santos",
        "email": "maria@yourcompany.com",
        "phone": "+5511999001001",
        "document": "12345678901",
        "team": "Equipe Vendas SP",
        "role": "vendedor",
        "metadata": { "crm_id": "CRM-2001", "hire_date": "2024-06-15" }
      },
      {
        "external_id": "emp-102",
        "name": "Joao Silva",
        "email": "joao@yourcompany.com",
        "phone": "+5511999002002",
        "team": "Equipe Vendas SP",
        "role": "vendedor"
      },
      {
        "external_id": "emp-103",
        "name": "Ana Oliveira",
        "email": "ana@yourcompany.com",
        "team": "Equipe Vendas RJ",
        "role": "gerente",
        "metadata": { "crm_id": "CRM-2003", "is_manager": true }
      }
    ]
  }'

Respuesta (200 — Exitosa)

{
  "data": {
    "created": 2,
    "existing": 1,
    "errors": [],
    "total": 3
  },
  "meta": {
    "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "timestamp": "2026-03-17T14:30:00.000Z"
  }
}
  • 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:
{
  "data": {
    "created": 8,
    "existing": 1,
    "errors": [
      "Collaborator emp-110 (invalid-email): Invalid email format"
    ],
    "total": 10
  },
  "meta": {
    "request_id": "b2c3d4e5-...",
    "timestamp": "2026-03-17T14:30:00.000Z"
  }
}
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

action
string
requerido
Debe ser "sync_activities"
activities
array
requerido
Array de objetos de actividad (max 1000)
activities[].activity_code
string
requerido
Codigo de 3 digitos: "001" a "999"
activities[].external_id
string
requerido
ID unico para deduplicacion (max 255 caracteres)
activities[].collaborator_email
string
requerido
Email del vendedor que realizo la actividad
activities[].data
object
Cualquier contexto adicional (formato libre)
activities[].occurred_at
string
Cuando ocurrio (ISO 8601). Por defecto es ahora.

Ejemplo: Enviar las actividades de un dia

curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_activities",
    "activities": [
      {
        "activity_code": "001",
        "external_id": "crm-20260317-001",
        "collaborator_email": "maria@yourcompany.com",
        "data": {
          "client_name": "Acme Corp",
          "client_phone": "+5511988887777",
          "duration_minutes": 12,
          "outcome": "interested"
        },
        "occurred_at": "2026-03-17T09:15:00-03:00"
      },
      {
        "activity_code": "001",
        "external_id": "crm-20260317-002",
        "collaborator_email": "maria@yourcompany.com",
        "data": {
          "client_name": "Beta Inc",
          "duration_minutes": 8,
          "outcome": "no_answer"
        },
        "occurred_at": "2026-03-17T09:30:00-03:00"
      },
      {
        "activity_code": "002",
        "external_id": "crm-20260317-003",
        "collaborator_email": "joao@yourcompany.com",
        "data": {
          "client_name": "Gamma Ltd",
          "meeting_type": "video_call",
          "duration_minutes": 45
        },
        "occurred_at": "2026-03-17T10:00:00-03:00"
      },
      {
        "activity_code": "003",
        "external_id": "crm-20260317-004",
        "collaborator_email": "joao@yourcompany.com",
        "data": {
          "client_name": "Gamma Ltd",
          "proposal_value": 25000.00,
          "currency": "BRL"
        },
        "occurred_at": "2026-03-17T14:00:00-03:00"
      },
      {
        "activity_code": "001",
        "external_id": "crm-20260317-005",
        "collaborator_email": "ana@yourcompany.com",
        "data": {
          "client_name": "Delta SA",
          "duration_minutes": 20,
          "outcome": "scheduled_meeting"
        },
        "occurred_at": "2026-03-17T15:30:00-03:00"
      }
    ]
  }'

Respuesta (200 — Exitosa)

{
  "data": {
    "processed": 5,
    "skipped": 0,
    "duplicates": 0,
    "errors": [],
    "total": 5
  },
  "meta": {
    "request_id": "c3d4e5f6-7890-abcd-ef01-234567890abc",
    "timestamp": "2026-03-17T16:00:00.000Z"
  }
}

Campos de respuesta explicados

processed
number
Actividades registradas exitosamente
skipped
number
Actividades donde el email del colaborador no fue encontrado en SalesOS
duplicates
number
Actividades con un external_id que ya fue enviado anteriormente
errors
array
Array de mensajes de error para los elementos que fallaron
total
number
Total de elementos recibidos en la solicitud

Ejemplo: Resultados mixtos (algunos omitidos, algunos duplicados)

Si reenvias el mismo lote o incluyes emails desconocidos:
{
  "data": {
    "processed": 2,
    "skipped": 1,
    "duplicates": 2,
    "errors": [],
    "total": 5
  },
  "meta": {
    "request_id": "d4e5f6g7-...",
    "timestamp": "2026-03-17T16:05:00.000Z"
  }
}
  • 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:
CodigoActividad del CRMMision en SalesOSPuntos
001Llamada telefonica a prospectoLigacoes Realizadas5 pts
002Reunion (presencial o video)Reunioes Agendadas15 pts
003Propuesta enviadaPropostas Enviadas20 pts
004Contrato firmadoContratos Fechados50 pts
005Visita a propiedad con clienteVisitas Realizadas25 pts
006Email de seguimiento enviadoFollow-ups Enviados3 pts
007Calificacion de lead completadaLeads Qualificados10 pts
Ejemplo de mapeo para una empresa SaaS:
CodigoActividad del CRMMision en SalesOSPuntos
001Llamada de descubrimientoLigacoes de Descoberta10 pts
002Demo de producto agendadaDemos Agendadas20 pts
003Prueba gratuita iniciadaTrials Iniciados15 pts
004Propuesta enviadaPropostas Enviadas25 pts
005Negocio cerradoDeals Fechados100 pts
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:
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_activities",
    "activities": [{
      "activity_code": "001",
      "external_id": "crm-call-5001",
      "collaborator_email": "maria@yourcompany.com"
    }]
  }'
{ "data": { "processed": 1, "skipped": 0, "duplicates": 0, "errors": [], "total": 1 } }
Segunda llamada (mismo external_id) — deduplicada de forma segura:
{ "data": { "processed": 0, "skipped": 0, "duplicates": 1, "errors": [], "total": 1 } }
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:
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": []
  }
}

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

# Enviando un activity_code invalido y un email incorrecto
curl -X POST https://api.play2sell.com/functions/v1/default-integration \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_activities",
    "activities": [
      { "activity_code": "abc", "external_id": "e1", "collaborator_email": "maria@co.com" },
      { "activity_code": "001", "external_id": "e2", "collaborator_email": "not-an-email" },
      { "activity_code": "001", "external_id": "e3", "collaborator_email": "joao@co.com" }
    ]
  }'
Respuesta (400):
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid activities payload",
    "details": [
      { "index": 0, "field": "activity_code", "message": "Required 3-digit string (001-999), e.g. \"001\"" },
      { "index": 1, "field": "collaborator_email", "message": "Required valid email" }
    ]
  }
}
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

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded",
    "retry_after": 1847
  }
}
Espera 1847 segundos (~31 minutos) antes de reintentar. El limite de solicitudes se reinicia cada hora.

Ejemplo: API key invalida

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API key"
  }
}

Ejemplos de Codigo Completos

# Step 1: Set your API key
export SALESOS_KEY="sk_live_YOUR_API_KEY"
export SALESOS_URL="https://api.play2sell.com/functions/v1/default-integration"

# Step 2: Register your team (run once, or nightly to keep in sync)
curl -s -X POST "$SALESOS_URL" \
  -H "Authorization: Bearer $SALESOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_collaborators",
    "collaborators": [
      { "external_id": "emp-101", "name": "Maria Santos", "email": "maria@co.com", "team": "SP" },
      { "external_id": "emp-102", "name": "Joao Silva", "email": "joao@co.com", "team": "SP" },
      { "external_id": "emp-103", "name": "Ana Oliveira", "email": "ana@co.com", "team": "RJ" }
    ]
  }' | jq .

# Step 3: Send today's activities
curl -s -X POST "$SALESOS_URL" \
  -H "Authorization: Bearer $SALESOS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync_activities",
    "activities": [
      { "activity_code": "001", "external_id": "call-1001", "collaborator_email": "maria@co.com", "data": {"client": "Acme"} },
      { "activity_code": "001", "external_id": "call-1002", "collaborator_email": "maria@co.com", "data": {"client": "Beta"} },
      { "activity_code": "002", "external_id": "meet-2001", "collaborator_email": "joao@co.com", "data": {"client": "Gamma", "type": "video"} },
      { "activity_code": "003", "external_id": "prop-3001", "collaborator_email": "joao@co.com", "data": {"value": 50000} },
      { "activity_code": "001", "external_id": "call-1003", "collaborator_email": "ana@co.com", "data": {"client": "Delta"} }
    ]
  }' | jq .

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:
OrigenBuen external_idMal external_id
CRMcrm-event-12345random-uuid-each-time
Base de datosdb-row-id-789timestamp-only
Webhookwebhook-delivery-abcuser-email (no es unico)

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.
LimiteValor
Solicitudes por hora por defecto1000
Max colaboradores por solicitud500
Max actividades por solicitud1000
Timeout por solicitud120 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
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