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 um deep link para o módulo do SalesOS na hora da ação.

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": "pontos" },
        "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, "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
`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

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.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"
  }'

Modo self (sessão federada)

Com um token de usuário federado, 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

Modo self (sessão federada)

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

​Modo self (sessão federada)

​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

Modo self (sessão federada)

Tratamento de erros

Limites de uso

Segurança

Próximos passos