API de Missões

Os exemplos abaixo mostram o cabeçalho no formato de rede 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 Missões permite que o seu backend leia o estado das missões de gamificação dos seus vendedores no SalesOS — quais objetivos estão abertos hoje, quanto já avançou cada um, o que já foi concluído e qual missão destacar em seguida. Ela foi feita para compor as suas próprias telas (por exemplo, um bloco na home mostrando “3 de 6 missões concluídas”) antes mesmo de o usuário abrir o módulo do SalesOS. É uma API somente leitura, servidor a servidor: você consulta colaboradores por CPF ou e-mail, em lote, e o SalesOS responde com as missões cuja janela de período contém o dia de hoje, calculado no fuso horário da sua empresa.

Como funciona

Você recebe uma API Key com o escopo missions:read (Admin > Integrações > API Keys)
Seu backend consulta o estado das missões de um ou vários colaboradores (por CPF ou e-mail)
O SalesOS responde com as missões de hoje por colaborador — contadores de progresso, a lista completa e a próxima missão ativa

As missões avançam pela atividade dentro do SalesOS: o motor escuta eventos (uma visita agendada, uma venda fechada) e incrementa a missão correspondente. Esta API é para ler esse estado — combine com um deep link para o módulo do SalesOS na hora da ação.

Este endpoint nunca cria missões. Se as missões do dia de um colaborador ainda não foram provisionadas, a resposta é uma lista vazia com progress.total = 0 — não é erro, e não é uma escrita silenciosa.

Autenticação

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

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

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

Propriedade	Detalhes
Cabeçalho	`Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
Escopo exigido	`missions:read`
Limite de uso	Configurável por chave (padrão: 1000 requisições/hora)
Formato da chave	`sk_live_` (produção) ou `sk_test_` (testes)

Ambientes

Produção
Staging

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

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

Referência do endpoint

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

O endpoint aceita duas ações no campo action: missions_status e missions_summary. Cada colaborador é identificado por CPF (em qualquer formato — os dígitos são normalizados) ou e-mail. Quando os dois são enviados, o CPF prevalece.

Ação: missions_status

As missões cuja janela de período contém o dia de hoje, por colaborador. “Hoje” é calculado no fuso horário da sua empresa (devolvido em timezone / reference_date na resposta) — nunca em UTC.

Esquema da requisição

string

obrigatório

Deve ser "missions_status"

array

obrigatório

Lista de referências de colaboradores (máximo 500 — 100 quando include_missions está ligado)

boolean

padrão:"false"

Devolve a lista completa missions[]. Desligado por padrão: cada colaborador tem várias missões, então um lote grande com a lista ligada vira uma resposta de megabytes. progress e next_mission vêm sempre.

string

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

string

E-mail — usado apenas quando o cpf está ausente

Exemplo

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

Resposta (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-08-11",
    "collaborators": [
      {
        "cpf": "52998224725",
        "found": true,
        "user_id": "8f14e45f-0000-0000-0000-000000000001",
        "name": "Maria Santos",
        "membership_status": "active",
        "progress": {
          "total": 6,
          "completed": 3,
          "pending_approval": 1,
          "active": 2,
          "expired": 0,
          "points_earned": 90,
          "points_available": 235,
          "points_pending_approval": 0
        },
        "next_mission": {
          "id": "b1a2c3d4-0000-0000-0000-000000000010",
          "key": "schedule_visit",
          "name": "Agendar 1 visita",
          "description": "Agende uma visita com um lead",
          "category": "sales",
          "icon": "calendar",
          "current_count": 0,
          "target_count": 1,
          "points_reward": 35,
          "nominal_reward": 70,
          "action": { "route": "/leads", "label": "Ver leads", "params": null }
        },
        "missions": [
          {
            "id": "b1a2c3d4-0000-0000-0000-000000000009",
            "key": "call_3_leads",
            "name": "Ligar para 3 leads",
            "category": "sales",
            "period_type": "daily",
            "period_start": "2026-08-11",
            "period_end": "2026-08-11",
            "icon": "phone",
            "status": "completed",
            "current_count": 3,
            "target_count": 3,
            "points_reward": 30,
            "nominal_reward": 30,
            "points_credited_so_far": 30,
            "points_awarded": 30,
            "completed_at": "2026-08-11T13:20:04Z",
            "action": null
          }
        ]
      },
      { "email": "joao@suaempresa.com", "found": false }
    ],
    "total": 2,
    "found": 1
  },
  "meta": {
    "request_id": "1f6c1b2e-0000-4a1b-8c2d-000000000001",
    "timestamp": "2026-08-11T13:45:00.000Z"
  }
}

Campos da resposta

Campo	Significado
`timezone` / `reference_date`	O fuso da sua empresa e o dia local a que a resposta se refere
`found`	Se o CPF/e-mail resolveu para um colaborador da sua empresa
`membership_status`	Situação do vínculo do colaborador com a sua empresa
`progress.total`	Missões cuja janela de período contém hoje
`progress.completed`	Concluídas e recompensadas
`progress.pending_approval`	Concluídas pelo colaborador, aguardando o gestor — pontos ainda não creditados
`progress.active`	Ainda em andamento
`progress.expired`	Período encerrado sem conclusão
`progress.points_earned`	Pontos efetivamente creditados até agora: a recompensa cheia das missões concluídas mais as parcelas já pagas nas que estão em andamento
`progress.points_available`	O que ainda dá para conquistar nas missões ativas — a recompensa efetiva menos as parcelas já creditadas. Missões de penalidade (recompensa negativa) ficam de fora: penalidade é risco, não ganho
`progress.points_pending_approval`	Recompensas travadas aguardando aprovação do gestor. Nada foi creditado ainda
`next_mission`	A missão ativa de menor ordem de exibição — a que deve ser destacada. Ausente quando não há nenhuma ativa
`missions[]`	A lista completa, na ordem de exibição configurada pela empresa
`missions[].points_reward`	A recompensa efetiva — o que este colaborador vai receber de fato, escalada pelo alvo dele (veja abaixo)
`missions[].nominal_reward`	A recompensa configurada na definição da missão, antes da escala. Mesmos nomes de campo que o evento `mission.completed` usa
`missions[].points_credited_so_far`	Quanto da recompensa desta missão já foi pago pelo progresso
`missions[].action`	Deep link opcional configurado para a missão (`route`, `label`, `params`). `null` quando não houver

A lista completa é opt-in. Por padrão a resposta traz apenas progress e next_mission — o suficiente para desenhar uma tela inicial. Peça include_missions: true quando precisar de todas as missões, e conte com um limite de lote menor (100 em vez de 500), porque cada colaborador carrega várias missões.

As recompensas são personalizadas — exiba sempre points_reward, nunca nominal_reward. O alvo de uma missão pode ser adaptado por colaborador, e a recompensa acompanha: quem teve o alvo reduzido pela metade ganha metade dos pontos. points_reward é o que será realmente creditado; nominal_reward é o número configurado na definição, enviado só para você poder indicar “meta reduzida” se quiser. São os mesmos nomes de campo que o webhook mission.completed usa, então os dois canais concordam.

A recompensa é paga em parcelas, então “conquistado” e “ainda a conquistar” são números diferentes. Uma missão de 100 pontos com meta 5 credita 20 a cada passo. Depois de um passo, o colaborador conquistou 20 e ainda tem 80 a conquistar — points_earned conta os 20, points_available conta os 80. Somar os 100 cheios nos dois lados contaria os mesmos pontos duas vezes.

pending_approval não é completed. Algumas missões exigem aprovação do gestor antes de creditar os pontos, e o crédito acontece na data da aprovação. Reportar em separado permite exibir “aguardando aprovação” sem inventar a distinção.

Nomes de missão, categorias, ícones, recompensas, metas e ordem de exibição são configurados por empresa. Nunca deixe esses valores fixos no seu cliente — renderize o que vier na resposta, para que uma mudança no SalesOS não exija uma nova versão do app.

Ação: missions_summary

Tudo o que missions_status devolve, mais os contadores de conclusão da semana e do mês. Útil para uma faixa de “seu mês até aqui”. As missões são contadas no período a que pertencem (a janela delas), não na data em que foram aprovadas — então uma missão aprovada com atraso continua contando na semana em que foi conquistada.

Exemplo

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

Resposta (200) — bloco adicional por colaborador:

{
  "summary": {
    "week":  { "completed": 8,  "points": 240 },
    "month": { "completed": 31, "points": 980 }
  }
}

missions_summary varre um mês de registros por colaborador, por isso o limite de lote é 100 em vez de 500.

Modo self (sessão federada)

Quando o seu app já tem um token de usuário federado do SalesOS, envie-o como Authorization: Bearer <jwt> e omita collaborators. A resposta cobre apenas o próprio usuário do token.

curl -X POST https://api.play2sell.com/functions/v1/missions-partner-api \
  -H "Authorization: Bearer <jwt-federado>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "missions_status" }'

Enviar collaborators junto com um token de usuário é rejeitado com SELF_MODE_NO_COLLABORATORS. Consultas em lote exigem uma API Key de parceiro — do contrário, qualquer usuário logado poderia ler o progresso de outras pessoas por CPF.

Tratamento de erros

Todos os erros seguem a mesma estrutura:

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

São dois formatos, não um. O bloco acima é o erro do endpoint. Falhas na camada de autenticação respondem antes de o endpoint rodar, com error como string:

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

Código que assume error.code lê undefined em toda falha de autenticação. Ramifique pelo tipo — veja Convenções da API.

400 — VALIDATION_ERROR

Corpo inválido, lote acima do limite, CPF sem 11 dígitos, ou item sem cpf e sem email. A lista details aponta o index do item.

400 — SELF_MODE_NO_COLLABORATORS

Uma lista collaborators foi enviada junto com um token de usuário. Omita-a, ou use uma API Key de parceiro.

401 — UNAUTHORIZED

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

403 — FORBIDDEN

API Key válida, mas sem o escopo missions:read.

405 — METHOD_NOT_ALLOWED

Apenas POST é aceito.

429 — RATE_LIMITED

Requisições demais nesta hora. Aguarde retry_after segundos e tente de novo.

500 — SERVER_ERROR

Erro interno. Tente novamente com espera progressiva (2s, 4s, 8s).

Um colaborador desconhecido não é erro. A requisição é bem-sucedida com found: false para aquele item, então um CPF errado nunca derruba a renderização da tela inteira.

Limites de uso

Limite	Valor
Requisições por hora (padrão)	1000
Máximo de colaboradores por `missions_status`	500 (100 com `include_missions`)
Máximo de colaboradores por `missions_summary`	100 (50 com `include_missions`)

Segurança

Somente leitura: esta API nunca cria, avança ou provisiona missões
Cada chave pertence a uma única empresa — um CPF de outra empresa responde found: false
As requisições são assinadas por HMAC (P2S-SIGN-V1) e registradas para auditoria; documentos nunca são gravados nos logs

Nunca exponha sua API Key em código do lado do cliente. Esta API deve ser chamada apenas pelo seu servidor.

Visão Geral

Integrações

API de Missões

API de Missões

Como funciona

Autenticação

Ambientes

Referência do endpoint

Ação: missions_status

Esquema da requisição

Exemplo

Campos da resposta

Ação: missions_summary

Exemplo

Modo self (sessão federada)

Tratamento de erros

Limites de uso

Segurança

Próximos passos

API de Check-in

Autenticação

​API de Missões

​Como funciona

​Autenticação

​Ambientes

​Referência do endpoint

​Ação: missions_status

​Esquema da requisição

​Exemplo

​Campos da resposta

​Ação: missions_summary

​Exemplo

​Modo self (sessão federada)

​Tratamento de erros

​Limites de uso

​Segurança

​Próximos passos

API de Check-in

Autenticação

API de Missões

Como funciona

Autenticação

Ambientes

Referência do endpoint

Ação: missions_status

Esquema da requisição

Exemplo

Campos da resposta

Ação: missions_summary

Exemplo

Modo self (sessão federada)

Tratamento de erros

Limites de uso

Segurança

Próximos passos