Convenciones de la API

Cada API de SalesOS sigue las reglas de esta página. Léala una vez y las páginas de cada endpoint quedan cortas: solo cuentan lo que es específico de ellas.

Esta página es el contrato al que nos sujetamos. Donde un endpoint se aparta de ella, su página lo dice explícitamente — una excepción silenciosa es un defecto, y queremos saberlo.

URLs base

Producción
Staging

https://api.play2sell.com

https://api-staging.play2sell.com

Cada endpoint vive en /functions/v1/<nombre>. No existe una superficie REST en /v1/... — si encuentra una página que la describa, está desactualizada; avísenos.

Autenticación

Dos esquemas, y son disjuntos — un endpoint acepta uno u otro, nunca ambos para el mismo llamador.

Socio (servidor a servidor)

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

La firma es una cadena HMAC-SHA256 sobre el método, el path, el timestamp y el SHA-256 del cuerpo. El paso a paso y el helper signedRequest están en Autenticación.

El timestamp vale 30 segundos y no puede estar en el futuro (protección contra replay) — mantén el reloj sincronizado (NTP) y firma de nuevo en cada intento
Firme los bytes crudos del cuerpo, antes de cualquier reserialización
Cada clave pertenece a una sola empresa; un documento de otra empresa responde found: false

Modo self (token del usuario del SSO)

Authorization: Bearer <jwt>

Se usa cuando su app ya tiene al usuario final autenticado. La respuesta cubre solo a ese usuario.

Enviar una lista collaborators junto 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 datos de otras personas por CPF.

Formatos de error

Las solicitudes fallan en dos capas distintas, y responden diferente. Maneje ambas — es el error de integración más común que vemos.

Capa de autenticación

Antes de que la solicitud llegue a la lógica del endpoint:

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

error es un string. Códigos (401): header_missing, header_malformed, api_key_not_found (incluye clave revocada), key_expired, signature_invalid, timestamp_too_old, timestamp_in_future. Sin el alcance: 403 scope_insufficient, con missing_scopes. Tabla completa en Autenticación.

Capa del endpoint

Una vez que la autenticación pasó:

{ "error": { "code": "VALIDATION_ERROR", "message": "Human-readable description", "details": [] } }

error es un objeto. details señala el ítem problemático por su index cuando la solicitud traía una lista.

error es una cadena en un caso y un objeto en el otro. El código que asume error.code leerá undefined en toda falla de autenticación — y el que asume error como cadena imprimirá [object Object] en las fallas de validación. Ramifique por el tipo:

const code = typeof body.error === "string" ? body.code : body.error?.code;

Sabemos que no es lo ideal. Está documentado en lugar de oculto porque las dos capas se despliegan por separado, y que un socio lo descubra en producción es peor que leerlo aquí.

Pagos

La API de Pagos responde en RFC 7807 problem+json:

{
  "type": "https://docs.play2sell.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Missing Authorization header",
  "instance": "099d23e0-5d6e-4882-9208-9e8038419c3c",
  "code": "unauthorized"
}

Es un servicio separado, con convenciones propias. instance es el id de la solicitud — cítelo al abrir un ticket.

Códigos de estado

Código	Significado	Qué hacer
`200`	Éxito. Incluye “no encontró nada”	Lea el payload — una lista vacía es una respuesta válida, no un error
`400`	Solicitud malformada o por encima de un límite	Corríjala; repetirla igual fallará otra vez
`401`	Clave ausente, inválida, expirada o firma que no coincide	Revise la clave y el reloj
`403`	Clave válida, sin el alcance	Solicite el alcance en la clave
`405`	Método incorrecto	Todo endpoint de socio es `POST`
`429`	Límite alcanzado	Espere los segundos del header `Retry-After`
`5xx`	Error nuestro	Reintente con espera progresiva (2s, 4s, 8s)

La ausencia no es un error. Ninguna campaña vigente, nadie en turno, ninguna misión hoy — todo responde 200 con una estructura vacía. Un endpoint que devolviera 404 para “nada hoy” haría que su pantalla dijera que algo se rompió cuando el día apenas empezó.

Lotes e identidad

Los endpoints de socio reciben un arreglo collaborators y responden en el mismo orden, un ítem por cada ítem enviado.

Resolución de identidad

La precedencia es user_id > cpf > email. Cuando llega más de uno, gana el primero presente — los demás se ignoran, no se usan como alternativa.

CPF se acepta en cualquier formato; los dígitos se normalizan. Debe tener exactamente 11 dígitos.
Una persona desconocida responde "found": false. Eso no es un error, y mantiene el arreglo alineado con su solicitud.
"ambiguous": true aparece cuando coincidió más de una persona — trátelo como no resuelto.

Límites

Los límites de lote son por acción y se declaran en cada página, porque siguen el payload que cada acción produce. Como regla: una acción de estado permite 500; una acción que expande una lista por persona permite 100 o menos.

Los datos compartidos — metadatos de la campaña, turnos de la empresa — salen una sola vez arriba de la respuesta, no repetidos por persona. En un lote de 500 personas esa es la diferencia entre una respuesta liviana y una de megabytes.

La configuración es de la empresa, nunca de su código

Esta es la regla que más rompe integraciones meses después de haberse desplegado. Nombres, etiquetas, cantidades, umbrales y monedas se configuran por empresa y se devuelven en la respuesta. No son constantes.

Lo que podría fijar en el código	Por qué se rompe
El nombre de la moneda	Cada empresa pone el suyo; la API devuelve la etiqueta configurada
Tres turnos, en horarios fijos	Cantidad, etiquetas y horarios vienen del horario de la empresa
Un número fijo de misiones diarias	Varía por día y por rol
Nombres y colores de nivel	La escalera es configuración, no un enum

Renderice lo que traiga la respuesta. Una pantalla que fija una etiqueta funciona hasta el día en que el cliente la renombra — y entonces miente, en silencio, sin ningún error.

Zonas horarias y fechas

Cada “hoy” se calcula en la zona horaria de la empresa, nunca en UTC. La respuesta declara cuál usó:

{ "timezone": "America/Sao_Paulo", "reference_date": "2026-08-13" }

Los timestamps son ISO 8601 en UTC. Conviértalos para mostrar usando el timezone de la misma respuesta — no el del dispositivo.

Límites de uso

Configurable por clave, con un valor predeterminado de 1000 solicitudes/hora. Hoy el límite por clave se mide, pero no bloquea; cuando bloquee, el exceso recibe 429 rate_limited con el header Retry-After en segundos. Espere; no insista en bucle.

Versionado

Los contratos se extienden, no se rompen. Podemos agregar campos en cualquier momento, así que haga un parseo permisivo e ignore lo que no conozca. El comportamiento nuevo que cambia un payload existente se despliega opt-in, detrás de una bandera en la solicitud (por ejemplo include_day). Omitirla mantiene la respuesta que usted ya maneja.

Seguridad

Las APIs de socio son solo lectura, salvo que la página diga lo contrario — nunca canjean, nunca alteran saldos, nunca aceptan términos
Las solicitudes se firman con HMAC y se registran para auditoría; los documentos y correos nunca se escriben en los logs
Nunca llame a estas APIs desde el lado del cliente: la clave quedaría expuesta

Próximos pasos

Autenticación

Crear claves y firmar solicitudes

API de Check-in

Presencia en turno y el recorrido de turnos del día

API de Misiones

Progreso, puntos logrados y puntos disponibles

API de Campañas

Catálogo de premios y saldo disponible

Descripción General

Integraciones

Convenciones de la API

Convenciones de la API

URLs base

Autenticación

Socio (servidor a servidor)

Modo self (token del usuario del SSO)

Formatos de error

Capa de autenticación

Capa del endpoint

Pagos

Códigos de estado

Lotes e identidad

Resolución de identidad

Límites

La configuración es de la empresa, nunca de su código

Zonas horarias y fechas

Límites de uso

Versionado

Seguridad

Próximos pasos

Autenticación

API de Check-in

API de Misiones

API de Campañas

​Convenciones de la API

​URLs base

​Autenticación

​Socio (servidor a servidor)

​Modo self (token del usuario del SSO)

​Formatos de error

​Capa de autenticación

​Capa del endpoint

​Pagos

​Códigos de estado

​Lotes e identidad

​Resolución de identidad

​Límites

​La configuración es de la empresa, nunca de su código

​Zonas horarias y fechas

​Límites de uso

​Versionado

​Seguridad

​Próximos pasos

Autenticación

API de Check-in

API de Misiones

API de Campañas

Convenciones de la API

URLs base

Autenticación

Socio (servidor a servidor)

Modo self (token del usuario del SSO)

Formatos de error

Capa de autenticación

Capa del endpoint

Pagos

Códigos de estado

Lotes e identidad

Resolución de identidad

Límites

La configuración es de la empresa, nunca de su código

Zonas horarias y fechas

Límites de uso

Versionado

Seguridad

Próximos pasos