API de Check-in

Os exemplos abaixo mostram o header no formato de transmissão Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. Para calcular a assinatura no seu código, use o helper signedRequest em Autenticação.

A API de Check-in permite que o seu backend leia o estado de presença no plantão dos seus vendedores no SalesOS — fizeram check-in hoje, onde, em qual turno e até quando ele vale. Ela foi criada para compor as suas próprias telas (por exemplo, um widget na Home de um superapp) antes mesmo de o usuário abrir o módulo SalesOS. É uma API somente leitura, servidor-a-servidor: você consulta colaboradores por CPF ou email, em lote, e o SalesOS responde com o estado de hoje calculado no fuso horário da sua empresa.

Como funciona

Você obtém uma API Key com o scope checkin:read (Admin > Integrações > API Keys)
Seu backend consulta o estado de check-in de um ou vários colaboradores (por CPF ou email)
O SalesOS responde com o último check-in de hoje por colaborador — e, opcionalmente, contagens de engajamento semana/mês

O check-in continua sendo executado dentro do app SalesOS (a validação de GPS acontece no contexto do usuário). Esta API é para ler o estado de presença — combine-a com um deep link para o módulo SalesOS na ação “Fazer check-in”.

Autenticação

Todas as requisições exigem uma API Key no header Authorization:

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

Veja a página de Autenticação para detalhes sobre criação e gestão de API Keys.

Propriedade	Detalhes
Header	`Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
Scope exigido	`checkin:read`
Rate limit	Configurável por key (padrão: 1000 requisições/hora)
Formato da key	`sk_live_` (produção) ou `sk_test_` (teste)

Ambientes

Produção
Staging

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

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

Referência do Endpoint

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

O endpoint aceita duas actions pelo campo action: checkin_status e checkin_engagement. Cada colaborador é identificado por CPF (qualquer formato — os dígitos são normalizados) ou email. Quando os dois são enviados, o CPF prevalece.

Action: checkin_status

Último check-in de hoje por colaborador. “Hoje” é calculado no fuso horário da sua empresa (retornado como timezone / reference_date na resposta) — nunca em UTC.

Schema da requisição

string

obrigatório

Deve ser "checkin_status"

array

obrigatório

Array de referências de colaborador (máx. 500)

string

CPF, qualquer formato (52998224725 ou 529.982.247-25). Deve conter exatamente 11 dígitos.

string

Email — usado apenas quando cpf não é enviado

Exemplo

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@suaempresa.com" }
    ]
  }'

Resposta (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@suaempresa.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 da resposta

boolean

Se o CPF/email correspondeu a um colaborador da sua empresa. Colaborador desconhecido vem como found: false — não é erro, e o array mantém a mesma ordem da requisição.

boolean

Se o colaborador tem ao menos um check-in não-rejeitado hoje (fuso da empresa).

boolean

true quando o último check-in está ativo/aprovado e o turno ainda não expirou — ou seja, o colaborador está em plantão agora.

object

Check-in mais recente de hoje. Omitido quando não há nenhum. mode é geo (presencial com GPS), home (home office) ou offline. status pode ser active, approved, pending (aguardando aprovação do líder), expired (turno encerrado normalmente) ou checkout.

string

Vínculo do colaborador com a sua empresa (active, inactive, …). Um colaborador pode ser encontrado e estar inativo.

Action: checkin_engagement

Tudo que checkin_status retorna, mais contagens de engajamento semana/mês por colaborador. Lotes limitados a 100.

string

obrigatório

Deve ser "checkin_engagement"

array

obrigatório

Array de referências de colaborador (máx. 100)

Exemplo

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 ganha um objeto engagement:

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

checkins — check-ins na semana/mês corrente (fuso da empresa; expired conta — é o fim normal de um turno)
presence_days — dias distintos com ao menos um check-in

Modo self (sessão federada)

Se o seu app já possui uma sessão federada do SalesOS — o JWT devolvido por um login customizado, como a federation do Superapp — o mesmo endpoint responde pelo próprio usuário do token, sem 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" }'

A identidade vem exclusivamente do token verificado — não envie collaborators. Requisição com esse campo é rejeitada com SELF_MODE_NO_COLLABORATORS: token de usuário nunca consulta outras pessoas.
O escopo de empresa vem da sessão; a resposta tem exatamente o mesmo formato, com um único item em collaborators.
checkin_engagement funciona da mesma forma ({ "action": "checkin_engagement" }).

Use o modo self em telas renderizadas dentro do app autenticado; use a API key (S2S) quando o seu backend compõe telas antes de o usuário ter sessão no SalesOS — como um widget na Home de um superapp.

Tratamento de Erros

Todos os erros seguem a estrutura compartilhada:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descrição legível",
    "details": []
  }
}

400 — VALIDATION_ERROR

Body inválido, lote acima do limite, CPF sem 11 dígitos, ou item sem cpf nem email. O array details aponta o index do item.

401 — UNAUTHORIZED

API key ausente, inválida ou expirada, ou assinatura não confere.

403 — FORBIDDEN

API key válida, mas sem o scope checkin:read.

405 — METHOD_NOT_ALLOWED

Apenas POST é aceito.

429 — RATE_LIMITED

Muitas requisições nesta hora. Aguarde retry_after segundos e tente de novo.

500 — SERVER_ERROR

Erro interno. Faça retry com backoff exponencial (2s, 4s, 8s).

Colaborador desconhecido não é erro. A requisição responde 200 com found: false naquele item — um CPF errado nunca quebra a renderização da Home inteira.

Rate Limits

Limite	Valor
Requisições por hora (padrão)	1000
Máx. colaboradores por `checkin_status`	500
Máx. colaboradores por `checkin_engagement`	100

Segurança

Somente leitura: esta API nunca cria nem altera check-ins
Cada key é limitada a uma única empresa — CPF de outra empresa responde found: false
Requisições assinadas com HMAC (P2S-SIGN-V1) e logadas para auditoria; documentos nunca são escritos em logs

Nunca exponha a sua API key em código client-side. Esta API deve ser chamada apenas do seu backend.

Visão Geral

Integrações

API de Check-in

API de Check-in

Como funciona

Autenticação

Ambientes

Referência do Endpoint

Action: checkin_status

Schema da requisição

Exemplo

Campos da resposta

Action: checkin_engagement

Exemplo

Modo self (sessão federada)

Tratamento de Erros

Rate Limits

Segurança

Próximos passos

Autenticação

Suporte

​API de Check-in

​Como funciona

​Autenticação

​Ambientes

​Referência do Endpoint

​Action: checkin_status

​Schema da requisição

​Exemplo

​Campos da resposta

​Action: checkin_engagement

​Exemplo

​Modo self (sessão federada)

​Tratamento de Erros

​Rate Limits

​Segurança

​Próximos passos

Autenticação

Suporte

API de Check-in

Como funciona

Autenticação

Ambientes

Referência do Endpoint

Action: checkin_status

Schema da requisição

Exemplo

Campos da resposta

Action: checkin_engagement

Exemplo

Modo self (sessão federada)

Tratamento de Erros

Rate Limits

Segurança

Próximos passos