API de Campañas

Los ejemplos siguientes muestran el encabezado en formato de red Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. Para calcular la firma en su código, use el helper signedRequest en Autenticación.

La API de Campañas permite que su backend lea las campañas de incentivo de su empresa en SalesOS — cuáles están vigentes, qué ofrece el catálogo, cuánto tiene cada colaborador para gastar y cuántos premios ya alcanza. Fue diseñada para componer sus propias pantallas antes de que el usuario abra el módulo de SalesOS. Es una API de solo lectura, servidor a servidor: usted consulta colaboradores por CPF o correo, en lote, y SalesOS responde con las campañas vigentes y el estado de cada persona en ellas.

Una campaña la configura su empresa: nombre, catálogo, precios en puntos, categorías, reglas de nivel e incluso el nombre de la moneda. Esta API devuelve lo que esté configurado — no conoce ninguna campaña específica.

Cómo funciona

Usted recibe una API Key con el alcance campaigns:read (Admin > Integraciones > API Keys)
Su backend consulta el estado de uno o varios colaboradores (por CPF o correo)
SalesOS responde con las campañas vigentes — los datos de la campaña una vez, y luego el estado de cada colaborador

Los metadatos de la campaña 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.

Este endpoint no canjea premios ni acepta términos. Es de lectura — combínelo con un enlace profundo al módulo de SalesOS para la acción en sí.

Autenticación

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

Consulte la página de Autenticación para crear y gestionar API Keys.

Propiedad	Detalles
Encabezado	`Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE`
Alcance requerido	`campaigns:read`
Límite de uso	Configurable por clave (predeterminado: 1000 solicitudes/hora)
Formato de clave	`sk_live_` (producción) o `sk_test_` (pruebas)

Entornos

Producción
Staging

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

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

Referencia del endpoint

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

Dos acciones en el campo action: campaign_status y campaign_catalog. Cada colaborador se identifica por CPF (en cualquier formato — los dígitos se normalizan) o correo. Cuando se envían ambos, prevalece el CPF.

Acción: campaign_status

Las campañas vigentes de su empresa y el estado de cada colaborador en ellas.

Esquema de la solicitud

string

requerido

Debe ser "campaign_status"

array

requerido

Lista de referencias de colaboradores (máximo 500)

string

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

string

Correo — usado solo cuando cpf está ausente

string

Filtra una campaña específica. Ausente = todas las vigentes.

string

Idioma de los textos configurables. Ausente = el predeterminado de la campaña.

Ejemplo

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

Respuesta (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-08-12",
    "campaigns": [
      {
        "id": "aaaaaaaa-0000-0000-0000-000000000001",
        "slug": "su-campana",
        "name": "Su Campaña",
        "tagline": "Su catálogo de premios",
        "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": "su-campana",
            "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 de la campaña

Campo	Significado
`slug` · `name` · `tagline`	Identificación y textos configurados por su empresa
`currency.label`	El nombre de la moneda, tal como su empresa lo configuró. Renderice este valor — nunca fije un nombre en su app
`catalog.rewards`	Premios que pueden canjearse con saldo
`catalog.awarded_only`	Premios otorgados (por ranking o disparador), que no están a la venta
`catalog.categories`	Categorías distintas en el catálogo
`catalog.cheapest_points` / `priciest_points`	Rango de precios del catálogo
`terms`	Presente solo cuando la campaña exige aceptación, con la versión vigente

Campos del colaborador

Campo	Significado
`balance.spendable`	El saldo disponible para gastar ahora
`balance.wallet_enabled`	Si la billetera está habilitada para su empresa — léalo antes de mostrar un cero
`score.xp` · `score.level`	Puntuación y nivel. El nivel determina qué premios alcanza el colaborador
`score.note`	`diverges_from_balance` cuando puntuación y saldo no coinciden
`campaigns[].eligible_rewards`	Premios que alcanza (regla de nivel satisfecha)
`campaigns[].affordable_rewards`	Premios que puede pagar con el saldo actual
`campaigns[].next_reachable_points`	Cuánto cuesta el próximo premio fuera de alcance — el “faltan X”
`campaigns[].terms_accepted`	Presente solo cuando la campaña exige aceptación
`campaigns[].redemptions`	Canjes abiertos y completados

spendable: 0 no significa “sin puntos”. La billetera se habilita por empresa; mientras no lo esté, el saldo llega en cero incluso para quien tiene puntuación. Lea siempre wallet_enabled antes de escribir “sin saldo” en la pantalla — de lo contrario afirmará una ausencia que no es cierta.

Alcanzar y poder pagar son cuentas distintas. Un premio puede estar liberado por nivel y aun así costar más de lo que el colaborador tiene. Por eso eligible_rewards y affordable_rewards son campos separados.

Acción: campaign_catalog

El mismo contenido con el recorte de catálogo. Como el catálogo crece por colaborador, el límite de lote baja a 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": "su-campana"
  }'

Modo self (sesión federada)

Con un token de usuario federado, envíe Authorization: Bearer <jwt> y omita collaborators. La respuesta cubre solo al propio usuario del token.

Enviar collaborators con un token de usuario se rechaza con SELF_MODE_NO_COLLABORATORS. Las consultas en lote requieren una API Key de socio — de lo contrario, cualquier usuario autenticado podría leer el saldo de otras personas por CPF.

Manejo de errores

{ "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

Cuerpo inválido, lote por encima del límite, CPF sin 11 dígitos, un elemento sin cpf ni email, o campaign_slug malformado. La lista details indica el index del elemento.

400 — SELF_MODE_NO_COLLABORATORS

Se envió una lista collaborators junto con un token de usuario.

401 — UNAUTHORIZED

API Key ausente, inválida o expirada, o firma que no coincide.

403 — FORBIDDEN

API Key válida, pero sin el alcance campaigns:read.

405 — METHOD_NOT_ALLOWED

Solo se acepta POST.

429 — RATE_LIMITED

Demasiadas solicitudes en esta hora. Espere retry_after segundos.

500 — SERVER_ERROR

Error interno. Reintente con espera progresiva (2s, 4s, 8s).

Ninguna campaña vigente no es un error. La respuesta llega con campaigns: [] y estado 200 — la empresa simplemente puede no tener nada en el aire.

Límites de uso

Límite	Valor
Solicitudes por hora (predeterminado)	1000
Máximo de colaboradores por `campaign_status`	500
Máximo de colaboradores por `campaign_catalog`	100

Seguridad

Solo lectura: esta API nunca crea canjes, ni acepta términos, ni altera saldos
Cada clave pertenece a una sola empresa — un CPF de otra empresa responde found: false, y las campañas de otras empresas nunca aparecen
Las solicitudes se firman con HMAC (P2S-SIGN-V1) y se registran para auditoría; los documentos nunca se escriben en los logs

Nunca exponga su API Key en código del lado del cliente. Esta API debe llamarse únicamente desde su servidor.

Descripción General

Integraciones

API de Campañas

API de Campañas

Cómo funciona

Autenticación

Entornos

Referencia del endpoint

Acción: campaign_status

Esquema de la solicitud

Ejemplo

Campos de la campaña

Campos del colaborador

Acción: campaign_catalog

Modo self (sesión federada)

Manejo de errores

Límites de uso

Seguridad

Próximos pasos

API de Misiones

Autenticación

​API de Campañas

​Cómo funciona

​Autenticación

​Entornos

​Referencia del endpoint

​Acción: campaign_status

​Esquema de la solicitud

​Ejemplo

​Campos de la campaña

​Campos del colaborador

​Acción: campaign_catalog

​Modo self (sesión federada)

​Manejo de errores

​Límites de uso

​Seguridad

​Próximos pasos

API de Misiones

Autenticación

API de Campañas

Cómo funciona

Autenticación

Entornos

Referencia del endpoint

Acción: campaign_status

Esquema de la solicitud

Ejemplo

Campos de la campaña

Campos del colaborador

Acción: campaign_catalog

Modo self (sesión federada)

Manejo de errores

Límites de uso

Seguridad

Próximos pasos