API de Ganancias

Esta página presupone las reglas comunes en Convenciones de la API — autenticación, los dos formatos de error, lotes y resolución de identidad. Aquí queda solo lo específico de las ganancias.

La API de Ganancias permite que su backend lea el dinero de cada colaborador: lo que ya se pagó, lo que está en camino y lo que aún se debe. Fue hecha para el bloque de ganancias de una pantalla de inicio — el que tiene un total y un botón para ocultar.

Esta API no decide qué cuenta como “comisión”. La palabra significa cosas distintas en empresas distintas: unas llaman comisión a todo pago, otras separan premio de comisión con rigor. Por eso la respuesta viene desglosada, y su pantalla suma lo que su empresa llama comisión.

Cómo funciona

Usted recibe una API Key con el alcance earnings:read
Su backend consulta uno o varios colaboradores (por CPF o correo)
SalesOS responde con los totales, desglosados por tipo de pago y por estado de lo pendiente

Autenticación

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

Propiedad	Detalles
Alcance requerido	`earnings:read`
Método	Solo `POST`
Límite de uso	Configurable por clave (predeterminado: 1000 solicitudes/hora)

Referencia del endpoint

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

Una acción: earnings_status.

Esquema de la solicitud

string

requerido

Debe ser "earnings_status"

array

requerido

Lista de referencias de colaboradores (máximo 500)

Ejemplo

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

Respuesta (200):

{
  "data": {
    "timezone": "America/Sao_Paulo",
    "reference_date": "2026-08-15",
    "collaborators": [
      {
        "cpf": "52998224725",
        "found": true,
        "user_id": "8f14e45f-0000-0000-0000-000000000001",
        "name": "Maria Santos",
        "membership_status": "active",
        "earnings": {
          "currency": "BRL",
          "paid": {
            "total_cents": 382000,
            "count": 2,
            "by_type": { "PRIZE": 380000, "COMMISSION": 2000 }
          },
          "in_transit": { "total_cents": 29000, "count": 1 },
          "receivable": {
            "total_cents": 150000,
            "count": 2,
            "by_status": { "A_RECEBER": 100000, "ATRASO": 50000 }
          },
          "last_paid_at": "2026-08-14T12:00:00.000Z"
        }
      }
    ],
    "total": 1,
    "found": 1
  },
  "meta": {
    "request_id": "1f6c1b2e-0000-4a1b-8c2d-000000000001",
    "timestamp": "2026-08-15T13:45:00.000Z"
  }
}

Campos

Campo	Significado
`currency`	Código ISO de la moneda de todos los valores del bloque — viene del propio pago, o de la moneda configurada de su empresa para quien aún no ha recibido
`paid.total_cents`	Dinero que ya salió — pagos liquidados
`paid.by_type`	El mismo dinero separado por tipo de pago — vea abajo
`in_transit.total_cents`	Pagos ya emitidos, aún no liquidados
`receivable.total_cents`	Calculado, aún sin pago generado
`receivable.by_status`	El mismo valor separado por etapa — vea abajo
`last_paid_at`	Cuándo se completó el pago liquidado más reciente

Todo valor viene en centavos, como entero. Nunca lo parsee como decimal: la aritmética de punto flotante sobre dinero es un defecto, no una preferencia de redondeo. Divida por 100 solo al momento de mostrar.

Tipos de pago

El paid.by_type separa el dinero liquidado en los tres tipos que el sistema registra:

Tipo	Qué es
`COMMISSION`	Comisión sobre una venta
`PRIZE`	Premio — campaña, ranking, incentivo
`BONUS`	Pago discrecional

Sume los tipos que su empresa llama comisión — no presuponga. En una empresa todo pago se llama comisión, y el total_cents entero es el número correcto. En otra, solo COMMISSION va en esa línea, y mostrar el total la inflaría en órdenes de magnitud.Un tipo ausente de by_type significa que la persona no tiene ninguno de ese tipo — no es cero por convención.

Etapas de lo pendiente

El receivable cubre todo lo que aún se debe. El by_status lo separa por etapa:

Estado	Significado
`A_RECEBER`	Calculado, esperando pago
`ATRASO`	Atrasado — debido y fuera de plazo
`A_LIBERAR`	Esperando liberación
`DISPONIVEL`	Disponible para pago

Dos etapas nunca aparecen aquí: PAGO (ya salió, contado en paid) y CANCELADO (nunca se pagará).

ATRASO es dinero debido, no un estado de error. Entra en receivable.total_cents a propósito. Filtrarlo escondería, justo de quien más necesita verlo, dinero que está atrasado.

Los valores cancelados quedan fuera en todas partes. Mostrarlos sería prometer dinero que nunca llegará.

Manejo de errores

Vea Convenciones de la API para los dos formatos y la tabla de códigos.

400 — VALIDATION_ERROR

Cuerpo inválido, lote por encima de 500, CPF sin 11 dígitos, o un elemento sin cpf ni email.

403 — FORBIDDEN

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

Quien nunca recibió no es un error. La respuesta llega con ceros y desgloses vacíos, en estado 200 — y ese cero es una medición: la persona existe y no tiene pagos. Distinto de found: false.

Límites de uso

Límite	Valor
Solicitudes por hora (predeterminado)	1000
Máximo de colaboradores por solicitud	500

Seguridad

Solo lectura: esta API nunca crea, aprueba ni altera un pago
Cada clave pertenece a una sola empresa — el dinero de otra empresa nunca aparece, ni para la misma persona
Los valores y documentos nunca se escriben en los logs; solo los conteos

Descripción General

Integraciones

API de Ganancias

API de Ganancias

Cómo funciona

Autenticación

Referencia del endpoint

Esquema de la solicitud

Ejemplo

Campos

Tipos de pago

Etapas de lo pendiente

Manejo de errores

Límites de uso

Seguridad

Próximos pasos

API de Progreso

API de Campañas

​API de Ganancias

​Cómo funciona

​Autenticación

​Referencia del endpoint

​Esquema de la solicitud

​Ejemplo

​Campos

​Tipos de pago

​Etapas de lo pendiente

​Manejo de errores

​Límites de uso

​Seguridad

​Próximos pasos

API de Progreso

API de Campañas

API de Ganancias

Cómo funciona

Autenticación

Referencia del endpoint

Esquema de la solicitud

Ejemplo

Campos

Tipos de pago

Etapas de lo pendiente

Manejo de errores

Límites de uso

Seguridad

Próximos pasos