API de Campanhas

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 Campanhas permite que o seu backend leia as campanhas de incentivo da sua empresa no SalesOS — quais estão vigentes, o que a vitrine oferece, quanto cada colaborador tem para gastar e quantos prêmios ele já alcança. Foi feita para compor as suas próprias telas antes 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 campanhas vigentes e o estado de cada pessoa nelas.

Uma campanha é configurada pela sua empresa: nome, vitrine, preços em pontos, categorias, regras de nível e até o nome da moeda. Esta API devolve o que estiver configurado — ela não conhece nenhuma campanha específica.

Como funciona

Você recebe uma API Key com o escopo campaigns:read (Admin > Integrações > API Keys)
Seu backend consulta o estado de um ou vários colaboradores (por CPF ou e-mail)
O SalesOS responde com as campanhas vigentes — os dados da campanha uma vez, e o estado de cada colaborador em seguida

Os metadados da campanha saem uma vez no topo da resposta, não repetidos por pessoa. Num lote de 500 colaboradores isso é a diferença entre uma resposta enxuta e uma de megabytes.

Este endpoint não resgata prêmios nem aceita termos. É leitura — combine com a página da campanha (access.url) na hora da ação — veja Abrir a página da campanha.

Autenticação

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

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

Propriedade	Detalhes
Cabeçalho	`Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
Escopo exigido	`campaigns: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/campaigns-partner-api

Duas ações no campo action: campaign_status e campaign_catalog. Cada colaborador é identificado por CPF (qualquer formato — os dígitos são normalizados) ou e-mail. Quando os dois vêm, o CPF prevalece.

Ação: campaign_status

As campanhas vigentes da sua empresa e o estado de cada colaborador nelas.

Esquema da requisição

string

obrigatório

Deve ser "campaign_status"

array

obrigatório

Lista de referências de colaboradores (máximo 500)

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

string

Filtra uma campanha específica. Ausente = todas as vigentes.

string

Idioma dos textos configuráveis. Ausente = o padrão da campanha.

Exemplo

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

Resposta (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-08-12",
    "campaigns": [
      {
        "id": "aaaaaaaa-0000-0000-0000-000000000001",
        "slug": "campanha-do-cliente",
        "name": "Campanha do Cliente",
        "tagline": "Sua vitrine de prêmios",
        "status": "active",
        "default_locale": "pt",
        "locales": ["pt"],
        "currency": { "label": "Moedas", "label_singular": "Moeda", "icon": "🪙" },
        "access": {
          "url": "https://app.play2sell.com/campanha",
          "path": "/campanha",
          "requires_session": true,
          "return_param": "next",
          "login_url": "https://app.play2sell.com/login/sso?connection=conexao-da-sua-empresa&next=%2Fcampanha"
        },
        "catalog": {
          "rewards": 22,
          "awarded_only": 2,
          "categories": 6,
          "cheapest_points": 200,
          "priciest_points": 22000
        }
      }
    ],
    "collaborators": [
      {
        "cpf": "52998224725",
        "found": true,
        "user_id": "8f14e45f-0000-0000-0000-000000000001",
        "name": "Maria Santos",
        "membership_status": "active",
        "balance": {
          "spendable": 1500,
          "source": "playcoin",
          "wallet_enabled": true
        },
        "score": {
          "xp": 1800,
          "level": 3,
          "level_detail": {
            "order": 3, "key": "level_03", "name": "Avançado",
            "description": "Você já pegou o ritmo.",
            "appearance": { "color": "#7B2D8E", "image_url": "/storage/v1/object/public/level-assets/…/….png", "image_alt": "Avançado" }
          },
          "note": "diverges_from_balance"
        },
        "campaigns": [
          {
            "campaign_id": "aaaaaaaa-0000-0000-0000-000000000001",
            "slug": "campanha-do-cliente",
            "eligible_rewards": 18,
            "affordable_rewards": 7,
            "next_reachable_points": 2000,
            "redemptions": { "open": 1, "fulfilled": 3 }
          }
        ]
      }
    ],
    "total": 1,
    "found": 1
  },
  "meta": {
    "request_id": "1f6c1b2e-0000-4a1b-8c2d-000000000001",
    "timestamp": "2026-08-12T13:45:00.000Z"
  }
}

Campos da campanha

Campo	Significado
`slug` · `name` · `tagline`	Identificação e textos configurados pela sua empresa
`currency.label`	O nome da moeda, como a sua empresa o configurou. Renderize este valor — não fixe um nome no app
`currency.label_singular` · `currency.icon`	Singular e ícone da moeda, quando a sua empresa os configurou. Ausentes caso contrário
`access.url`	Onde a página da campanha abre no app do SalesOS deste ambiente — veja Abrir a página da campanha
`access.path` · `access.return_param`	O caminho da página e o nome do parâmetro de retorno (`next`) dos links de entrada do SalesOS
`access.login_url`	Link para entrar pelo provedor de login da sua empresa e cair na página da campanha. `null` quando o login pelo seu provedor não está configurado neste ambiente — veja Entrar de novo pelo provedor da sua empresa
`catalog.rewards`	Prêmios que podem ser resgatados com saldo
`catalog.awarded_only`	Prêmios concedidos (por ranking ou gatilho), que não estão à venda
`catalog.categories`	Categorias distintas na vitrine
`catalog.cheapest_points` / `priciest_points`	Faixa de preço da vitrine
`terms`	Presente só quando a campanha exige aceite, com a versão vigente

O nome da moeda é resolvido nesta ordem: o rótulo configurado na campanha, depois a moeda cadastrada para a sua empresa (com singular e ícone), depois pontos. É o mesmo nome que a página da campanha mostra.

Campos do colaborador

Campo	Significado
`balance.spendable`	O saldo que dá para gastar agora
`balance.wallet_enabled`	Se a carteira está habilitada para a sua empresa — leia antes de exibir zero
`score.xp` · `score.level`	Pontuação e nível. O nível determina quais prêmios o colaborador alcança
`score.level_detail`	O nível como a sua empresa o configurou: `name`, `description` e `appearance` (cor e selo). Ausente quando o nível não tem degrau na escada
`score.note`	`diverges_from_balance` quando pontuação e saldo não coincidem
`campaigns[].eligible_rewards`	Prêmios que ele alcança (regra de nível atendida)
`campaigns[].affordable_rewards`	Prêmios que ele consegue pagar com o saldo atual
`campaigns[].next_reachable_points`	Quanto custa o próximo prêmio fora do alcance — o “falta X”
`campaigns[].terms_accepted`	Presente só quando a campanha exige aceite
`campaigns[].redemptions`	Resgates em aberto e concluídos

spendable: 0 não significa “não tem pontos”. A carteira é habilitada por empresa; enquanto não estiver, o saldo vem zerado mesmo para quem tem pontuação. Sempre leia wallet_enabled antes de escrever “sem saldo” na tela — do contrário ela vai afirmar uma ausência que não existe.

Alcançar e poder pagar são contas diferentes. Um prêmio pode estar liberado pelo nível e ainda assim custar mais do que o colaborador tem. Por isso eligible_rewards e affordable_rewards são campos separados.

Ação: campaign_catalog

O mesmo conteúdo com o recorte de catálogo. Como a vitrine cresce por colaborador, o limite de lote cai para 100.

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

Abrir a página da campanha

Toda campanha vem com um bloco access: onde a página dela mora no app do SalesOS e como levar o usuário até lá. É na página que o usuário vê a vitrine e resgata os prêmios, e ela exige usuário autenticado. Há dois caminhos:

Caminho	Como
Login e senha	Abra `access.url`. Quem não tem sessão passa pelo login do SalesOS e volta para a página
Provedor de login da sua empresa	Abra `access.login_url` quando ele vier preenchido. O usuário entra pelo provedor de login da sua empresa, sem senha do SalesOS, e cai na página da campanha

Leia access.url e access.login_url da resposta — não os fixe no seu código. A URL muda por ambiente (produção e staging têm apps diferentes).

O parâmetro de retorno só aceita um caminho dentro do app do SalesOS. URL completa, outro host ou qualquer outra coisa é ignorada, e o usuário cai na tela inicial.

Entrar de novo pelo provedor da sua empresa

O guia completo desse login (os dois jeitos, o que enviar e as recusas) está em SSO (Single Sign-On). Quando a sua empresa autentica os usuários no próprio provedor de login (OAuth 2.0 / OpenID Connect) e a Play2sell liga esse provedor ao SalesOS, a resposta traz access.login_url. Use-o como o link padrão para a página da campanha. Ele resolve o caso em que o usuário precisa se autenticar de novo:

Situação do usuário	O que acontece ao abrir `access.login_url`
Já tem sessão no SalesOS	Abre a página da campanha direto
Sessão do SalesOS vencida, mas logado no seu provedor	Passa pelo seu provedor sem digitar nada e volta para a página
Sem sessão em lugar nenhum	Faz login no seu provedor e volta para a página

https://app.play2sell.com/login/sso?connection=<conexão>&next=%2Fcampanha

Quem entrou por esse caminho e tem a sessão vencida dentro do app também volta pelo seu provedor, na mesma página onde estava, em vez de cair na tela de senha do SalesOS.

Leia access.login_url da resposta — não monte a URL no seu código. Ela muda por ambiente e só vem preenchida quando a ligação com o seu provedor está ativa naquele ambiente. Com null, use um dos outros caminhos.

Para ativar: a sua empresa cadastra a Play2sell como cliente OAuth 2.0 no seu provedor, um cliente por ambiente, com o endereço de retorno que passamos (https://auth.play2sell.com/login/callback em produção). Precisamos dos endereços de autorização e de token, do client ID e do secret (por canal seguro) e do identificador estável de cada usuário: o id interno do seu provedor, o CPF ou CNPJ ou o e-mail. Com CPF ou CNPJ, o usuário continua sendo a mesma pessoa no SalesOS mesmo se trocar de e-mail.

O login pelo seu provedor não abre a conta de quem não é da sua empresa: uma conta do SalesOS ligada a outra empresa, uma conta da equipe Play2sell ou um acesso desativado pelo seu gestor é recusado com uma mensagem que diz o que fazer.

Modo self (token do usuário do SSO)

Com o token de um usuário que entrou pelo SSO, envie Authorization: Bearer <jwt> e omita collaborators. A resposta cobre apenas o próprio usuário do token.

Enviar collaborators 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 autenticado poderia ler o saldo de outras pessoas por CPF.

Tratamento de erros

{ "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, item sem cpf e sem email, ou campaign_slug malformado. A lista details indica o index do item.

400 — SELF_MODE_NO_COLLABORATORS

Uma lista collaborators foi enviada junto com um token de usuário.

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 campaigns:read.

405 — METHOD_NOT_ALLOWED

Apenas POST é aceito.

429 — RATE_LIMITED

Requisições demais nesta hora. Aguarde retry_after segundos.

500 — SERVER_ERROR

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

Nenhuma campanha vigente não é erro. A resposta vem com campaigns: [] e status 200 — a empresa pode simplesmente não ter campanha no ar.

Limites de uso

Limite	Valor
Requisições por hora (padrão)	1000
Máximo de colaboradores por `campaign_status`	500
Máximo de colaboradores por `campaign_catalog`	100

Segurança

Somente leitura: esta API nunca cria resgates, nem aceita termos, nem altera saldo
Cada chave pertence a uma única empresa — um CPF de outra empresa responde found: false, e campanhas de outras empresas nunca aparecem
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 Campanhas

API de Campanhas

Como funciona

Autenticação

Ambientes

Referência do endpoint

Ação: campaign_status

Esquema da requisição

Exemplo

Campos da campanha

Campos do colaborador

Ação: campaign_catalog

Abrir a página da campanha

Entrar de novo pelo provedor da sua empresa

Modo self (token do usuário do SSO)

Tratamento de erros

Limites de uso

Segurança

Próximos passos

API de Missões

Autenticação

​API de Campanhas

​Como funciona

​Autenticação

​Ambientes

​Referência do endpoint

​Ação: campaign_status

​Esquema da requisição

​Exemplo

​Campos da campanha

​Campos do colaborador

​Ação: campaign_catalog

​Abrir a página da campanha

​Entrar de novo pelo provedor da sua empresa

​Modo self (token do usuário do SSO)

​Tratamento de erros

​Limites de uso

​Segurança

​Próximos passos

API de Missões

Autenticação

API de Campanhas

Como funciona

Autenticação

Ambientes

Referência do endpoint

Ação: campaign_status

Esquema da requisição

Exemplo

Campos da campanha

Campos do colaborador

Ação: campaign_catalog

Abrir a página da campanha

Entrar de novo pelo provedor da sua empresa

Modo self (token do usuário do SSO)

Tratamento de erros

Limites de uso

Segurança

Próximos passos