API de Check-in

Los ejemplos muestran el header en formato de transmisión Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. Para calcular la firma en tu código, usa el helper signedRequest en Autenticación.

La API de Check-in permite que tu backend lea el estado de presencia en el turno de tus vendedores en SalesOS — si hicieron check-in hoy, dónde, en qué turno y hasta cuándo es válido. Fue creada para componer tus propias pantallas (por ejemplo, un widget en la Home de un superapp) antes de que el usuario abra el módulo SalesOS. Es una API de solo lectura, servidor-a-servidor: consultas colaboradores por CPF o email, en lote, y SalesOS responde con el estado de hoy calculado en la zona horaria de tu empresa.

Cómo funciona

Obtienes una API Key con el scope checkin:read (Admin > Integraciones > API Keys)
Tu backend consulta el estado de check-in de uno o varios colaboradores (por CPF o email)
SalesOS responde con el último check-in de hoy por colaborador — y, opcionalmente, conteos de engagement semana/mes

El check-in se sigue ejecutando dentro de la app SalesOS (la validación de GPS ocurre en el contexto del usuario). Esta API es para leer el estado de presencia — combínala con un deep link al módulo SalesOS en la acción “Hacer check-in”.

Autenticación

Todas las solicitudes requieren una API Key en el header Authorization:

Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE

Consulta la página de Autenticación para detalles sobre creación y gestión de API Keys.

Propiedad	Detalles
Header	`Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
Scope requerido	`checkin:read`
Rate limit	Configurable por key (por defecto: 1000 solicitudes/hora)
Formato de la key	`sk_live_` (producción) o `sk_test_` (pruebas)

Ambientes

Producción
Staging

Base URL: https://api.play2sell.com

Base URL: https://api-staging.play2sell.com

Referencia del Endpoint

POST https://api.play2sell.com/functions/v1/checkin-partner-api

El endpoint acepta dos actions mediante el campo action: checkin_status y checkin_engagement. Cada colaborador se identifica por CPF (cualquier formato — los dígitos se normalizan) o email. Cuando se envían ambos, el CPF prevalece.

Action: checkin_status

Último check-in de hoy por colaborador. “Hoy” se calcula en la zona horaria de tu empresa (devuelta como timezone / reference_date en la respuesta) — nunca en UTC.

Schema de la solicitud

string

requerido

Debe ser "checkin_status"

array

requerido

Array de referencias de colaborador (máx. 500)

string

CPF, cualquier formato (52998224725 o 529.982.247-25). Debe contener exactamente 11 dígitos.

string

Email — usado solo cuando cpf no se envía

Ejemplo

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkin_status",
    "collaborators": [
      { "cpf": "529.982.247-25" },
      { "email": "joao@tuempresa.com" }
    ]
  }'

Respuesta (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-07-19",
    "collaborators": [
      {
        "cpf": "52998224725",
        "found": true,
        "user_id": "8f14e45f-...",
        "name": "Maria Santos",
        "membership_status": "active",
        "checked_in_today": true,
        "on_duty_now": true,
        "latest_checkin": {
          "status": "active",
          "mode": "geo",
          "shift": "afternoon",
          "checked_in_at": "2026-07-19T16:03:21+00:00",
          "shift_expires_at": "2026-07-19T21:00:00+00:00",
          "location_id": "c81e728d-...",
          "location_name": "Plantão Morumbi"
        },
        "org_unit_id": "a87ff679-..."
      },
      {
        "email": "joao@tuempresa.com",
        "found": true,
        "user_id": "45c48cce-...",
        "name": "Joao Silva",
        "membership_status": "active",
        "checked_in_today": false,
        "on_duty_now": false
      }
    ],
    "total": 2,
    "found": 2
  },
  "meta": { "request_id": "a1b2c3d4-...", "timestamp": "2026-07-19T18:00:00.000Z" }
}

Campos de la respuesta

boolean

Si el CPF/email correspondió a un colaborador de tu empresa. Un colaborador desconocido viene como found: false — no es un error, y el array mantiene el mismo orden de la solicitud.

boolean

Si el colaborador tiene al menos un check-in no rechazado hoy (zona horaria de la empresa).

boolean

true cuando el último check-in está activo/aprobado y el turno aún no expiró — es decir, el colaborador está de turno ahora.

object

Check-in más reciente de hoy. Omitido cuando no hay ninguno. mode es geo (presencial con GPS), home (home office) u offline. status puede ser active, approved, pending (esperando aprobación del líder), expired (turno finalizado normalmente) o checkout.

string

Vínculo del colaborador con tu empresa (active, inactive, …). Un colaborador puede ser encontrado y estar inactivo.

Recorrido del dia (`include_day`)

Envie "include_day": true en checkin_status para recibir, ademas del estado actual, como va el dia turno por turno y cuando se habilita el boton de nuevo. Es lo que una pantalla de inicio necesita para componer el bloque de check-in sin abrir el modulo de SalesOS.

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkin_status",
    "collaborators": [{ "cpf": "52998224725" }],
    "include_day": true
  }'

Respuesta (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-08-13",
    "shifts": [
      { "key": "morning",   "label": "Manha", "start": "09:00", "end": "13:59" },
      { "key": "afternoon", "label": "Tarde", "start": "14:00", "end": "18:59" }
    ],
    "collaborators": [
      {
        "cpf": "52998224725",
        "found": true,
        "day": {
          "shifts": [
            { "key": "morning",   "label": "Manha", "start": "09:00", "end": "13:59",
              "state": "completed", "checked_in_at": "2026-08-13T12:04:00.000Z" },
            { "key": "afternoon", "label": "Tarde", "start": "14:00", "end": "18:59",
              "state": "upcoming", "checked_in_at": null }
          ],
          "shifts_source": "tenant_default",
          "action": { "state": "waiting", "opens_at": "2026-08-13T17:00:00.000Z" }
        }
      }
    ]
  }
}

Los turnos salen una sola vez arriba, no repetidos por persona. En un lote de 500 colaboradores esa es la diferencia entre una respuesta liviana y una de megabytes.

Campos

Campo	Significado
`shifts[]` (nivel superior)	Los turnos habilitados de su empresa, ordenados por hora de inicio
`shifts[].label`	El nombre del turno tal como su empresa lo configuro — renderice este valor
`day.shifts[].state`	`completed` · `open` · `upcoming` · `missed`
`day.shifts[].checked_in_at`	Cuando ocurrio el check-in de ese turno; `null` si no hubo
`day.action.state`	`available` cuando hay un turno abierto sin check-in; si no, `waiting`
`day.action.opens_at`	Cuando abre el proximo turno. Ausente cuando el dia termino
`day.shifts_source`	Qué horario se usó: `location` o `tenant_default`
`day.location_id`	La unidad cuyo horario se usó, cuando `shifts_source` es `location`

Una unidad puede tener horarios propios, y esos ganan. El arreglo shifts de arriba es el predeterminado de su empresa. Cuando la persona hace check-in en una unidad con horario propio, day.shifts sigue a esa unidad y day.shifts_source lo declara. Al dibujar la pantalla de alguien, lea el recorrido de la persona, no el arreglo de arriba.Antes del primer check-in del día no hay unidad que resolver, así que se usa el predeterminado de la empresa.

La cantidad de turnos es de su empresa, no es fija. Puede tener dos, tres o ninguno, con sus propias etiquetas y horarios. Construya la pantalla a partir del arreglo; nunca asuma tres posiciones ni horarios especificos.

Un opens_at ausente significa que el dia termino, no que el boton se habilito. state es waiting y no hay proxima apertura hoy — la pantalla no debe mostrar una cuenta regresiva que cruce la medianoche.

Action: checkin_engagement

Todo lo que devuelve checkin_status, más conteos de engagement semana/mes por colaborador. Lotes limitados a 100.

string

requerido

Debe ser "checkin_engagement"

array

requerido

Array de referencias de colaborador (máx. 100)

Ejemplo

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "checkin_engagement",
    "collaborators": [{ "cpf": "52998224725" }]
  }'

Cada colaborador encontrado gana un objeto engagement:

{
  "engagement": {
    "week":  { "checkins": 9,  "presence_days": 5 },
    "month": { "checkins": 34, "presence_days": 17 }
  }
}

checkins — check-ins en la semana/mes corriente (zona horaria de la empresa; expired cuenta — es el fin normal de un turno)
presence_days — días distintos con al menos un check-in

Modo self (sesión federada)

Si tu app ya posee una sesión federada de SalesOS — el JWT devuelto por un login personalizado, como la federación del Superapp — el mismo endpoint responde por el propio usuario del token, sin API key:

curl -X POST https://api.play2sell.com/functions/v1/checkin-partner-api \
  -H "Authorization: Bearer SESSION_JWT" \
  -H "Content-Type: application/json" \
  -d '{ "action": "checkin_status" }'

La identidad viene exclusivamente del token verificado — no envíes collaborators. Una solicitud con ese campo se rechaza con SELF_MODE_NO_COLLABORATORS: un token de usuario nunca consulta a otras personas.
El alcance de empresa viene de la sesión; la respuesta tiene exactamente el mismo formato, con un único ítem en collaborators.
checkin_engagement funciona de la misma manera ({ "action": "checkin_engagement" }).

Usa el modo self en pantallas renderizadas dentro de la app autenticada; usa la API key (S2S) cuando tu backend compone pantallas antes de que el usuario tenga sesión en SalesOS — como un widget en la Home de un superapp.

Manejo de Errores

Todos los errores siguen la estructura compartida:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descripción legible",
    "details": []
  }
}

Son dos formatos, no uno. El bloque anterior es el error del endpoint. Las fallas en la capa de autenticación responden antes de que el endpoint corra, con error como cadena:

{ "error": "Missing Authorization header", "code": "header_missing" }

El código que asume error.code lee undefined en toda falla de autenticación. Ramifique por el tipo — vea Convenciones de la API.

400 — VALIDATION_ERROR

Body inválido, lote sobre el límite, CPF sin 11 dígitos, o ítem sin cpf ni email. El array details indica el index del ítem.

401 — UNAUTHORIZED

API key ausente, inválida o expirada, o la firma no coincide.

403 — FORBIDDEN

API key válida, pero sin el scope checkin:read.

405 — METHOD_NOT_ALLOWED

Solo se acepta POST.

429 — RATE_LIMITED

Demasiadas solicitudes en esta hora. Espera retry_after segundos y reintenta.

500 — SERVER_ERROR

Error interno. Reintenta con backoff exponencial (2s, 4s, 8s).

Un colaborador desconocido no es un error. La solicitud responde 200 con found: false en ese ítem — un CPF equivocado nunca rompe la renderización de la Home entera.

Rate Limits

Límite	Valor
Solicitudes por hora (por defecto)	1000
Máx. colaboradores por `checkin_status`	500
Máx. colaboradores por `checkin_engagement`	100

Seguridad

Solo lectura: esta API nunca crea ni modifica check-ins
Cada key está limitada a una única empresa — un CPF de otra empresa responde found: false
Solicitudes firmadas con HMAC (P2S-SIGN-V1) y registradas para auditoría; los documentos nunca se escriben en logs

Nunca expongas tu API key en código client-side. Esta API debe llamarse solo desde tu backend.

Descripción General

Integraciones

API de Check-in

API de Check-in

Cómo funciona

Autenticación

Ambientes

Referencia del Endpoint

Action: checkin_status

Schema de la solicitud

Ejemplo

Campos de la respuesta

Recorrido del dia (`include_day`)

Campos

Action: checkin_engagement

Ejemplo

Modo self (sesión federada)

Manejo de Errores

Rate Limits

Seguridad

Próximos pasos

Autenticación

Soporte

​API de Check-in

​Cómo funciona

​Autenticación

​Ambientes

​Referencia del Endpoint

​Action: checkin_status

​Schema de la solicitud

​Ejemplo

​Campos de la respuesta

​Recorrido del dia (include_day)

​Campos

​Action: checkin_engagement

​Ejemplo

​Modo self (sesión federada)

​Manejo de Errores

​Rate Limits

​Seguridad

​Próximos pasos

Autenticación

Soporte

API de Check-in

Cómo funciona

Autenticación

Ambientes

Referencia del Endpoint

Action: checkin_status

Schema de la solicitud

Ejemplo

Campos de la respuesta

Recorrido del dia (`include_day`)

Campos

Action: checkin_engagement

Ejemplo

Modo self (sesión federada)

Manejo de Errores

Rate Limits

Seguridad

Próximos pasos