> ## Documentation Index
> Fetch the complete documentation index at: https://docs.play2sell.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API de Ganancias
> Lea lo que cada colaborador ya recibió, lo que está en camino y lo que aún se le debe — en centavos, desglosado por tipo y por estado.
# API de Ganancias
Esta página presupone las reglas comunes en [Convenciones de la API](/es/api/conventions) — 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
1. **Usted recibe una API Key** con el alcance `earnings:read`
2. **Su backend consulta** uno o varios colaboradores (por CPF o correo)
3. **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
Debe ser `"earnings_status"`
Lista de referencias de colaboradores (máximo 500)
### Ejemplo
```bash theme={null}
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):**
```json theme={null}
{
"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](/es/api/conventions#formatos-de-error) para los dos formatos y la tabla de códigos.
Cuerpo inválido, lote por encima de 500, CPF sin 11 dígitos, o un elemento sin `cpf` ni `email`.
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
***
## Próximos pasos
Nivel, XP, monedas y ranking
El catálogo de donde vienen esos premios