> ## 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 Ganhos
> Leia o que cada colaborador já recebeu, o que está a caminho e o que ainda tem a receber — em centavos, decomposto por tipo e por status.
# API de Ganhos
Esta página pressupõe as regras comuns em [Convenções da API](/pt/api/conventions) — autenticação, os dois formatos de erro, lotes e resolução de identidade. Aqui fica só o que é específico dos ganhos.
A API de Ganhos permite que o seu backend leia o dinheiro de cada colaborador: **o que já foi pago**, **o que está a caminho** e **o que ainda é devido**.
Foi feita para o bloco de ganhos de uma tela inicial — aquele com um total e um botão de ocultar.
**Esta API não decide o que conta como "comissão".** A palavra significa coisas diferentes em empresas diferentes: umas chamam todo pagamento de comissão, outras separam prêmio de comissão com rigor. Por isso a resposta vem **decomposta**, e a sua tela soma o que a sua empresa chama de comissão.
## Como funciona
1. **Você recebe uma API Key** com o escopo `earnings:read`
2. **Seu backend consulta** um ou vários colaboradores (por CPF ou e-mail)
3. **O SalesOS responde** com os totais, decompostos por tipo de pagamento e por status do a receber
***
## Autenticação
```
Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE
```
| Propriedade | Detalhes |
| ------------------ | ------------------------------------------------------ |
| **Escopo exigido** | `earnings:read` |
| **Método** | Apenas `POST` |
| **Limite de uso** | Configurável por chave (padrão: 1000 requisições/hora) |
***
## Referência do endpoint
```
POST https://api.play2sell.com/functions/v1/earnings-partner-api
```
Uma ação: `earnings_status`.
### Esquema da requisição
Deve ser `"earnings_status"`
Lista de referências de colaboradores (máximo 500)
### Exemplo
```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" }]
}'
```
**Resposta (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 da moeda de todos os valores do bloco — vem do próprio pagamento, ou da **moeda configurada da sua empresa** para quem ainda não recebeu |
| `paid.total_cents` | Dinheiro que já saiu — pagamentos liquidados |
| `paid.by_type` | O mesmo dinheiro separado por tipo de pagamento — veja abaixo |
| `in_transit.total_cents` | Pagamentos já disparados, ainda não liquidados |
| `receivable.total_cents` | Apurado, ainda sem pagamento gerado |
| `receivable.by_status` | O mesmo valor separado por estágio — veja abaixo |
| `last_paid_at` | Quando o pagamento liquidado mais recente foi concluído |
**Todo valor vem em centavos, como inteiro.** Nunca faça o parse como decimal: aritmética de ponto flutuante em dinheiro é defeito, não preferência de arredondamento. Divida por 100 apenas na hora de exibir.
***
## Tipos de pagamento
O `paid.by_type` separa o dinheiro liquidado nos três tipos que o sistema registra:
| Tipo | O que é |
| ------------ | ---------------------------------------- |
| `COMMISSION` | Comissão sobre uma venda |
| `PRIZE` | Premiação — campanha, ranking, incentivo |
| `BONUS` | Pagamento discricionário |
**Some os tipos que a sua empresa chama de comissão — não presuma.** Numa empresa todo pagamento é chamado de comissão, e o `total_cents` inteiro é o número certo. Noutra, só o `COMMISSION` entra naquela linha, e mostrar o total a inflaria em ordens de grandeza.
Um tipo ausente do `by_type` significa que a pessoa não tem nenhum daquele tipo — não é zero por convenção.
***
## Estágios do a receber
O `receivable` cobre tudo que ainda é devido. O `by_status` separa por estágio:
| Status | Significado |
| ------------ | -------------------------------------- |
| `A_RECEBER` | Apurado, aguardando pagamento |
| `ATRASO` | **Em atraso** — devido e fora do prazo |
| `A_LIBERAR` | Aguardando liberação |
| `DISPONIVEL` | Disponível para pagamento |
Dois estágios nunca aparecem aqui: `PAGO` (já saiu, contado em `paid`) e `CANCELADO` (nunca será pago).
**`ATRASO` é dinheiro devido, não estado de erro.** Ele entra no `receivable.total_cents` de propósito. Filtrá-lo esconderia, justamente de quem mais precisa ver, dinheiro que está atrasado.
Valores cancelados ficam de fora em todo lugar. Mostrá-los seria prometer dinheiro que nunca vai chegar.
***
## Tratamento de erros
Veja [Convenções da API](/pt/api/conventions#formatos-de-erro) para os dois formatos e a tabela de códigos.
Corpo inválido, lote acima de 500, CPF sem 11 dígitos, ou item sem `cpf` e sem `email`.
API Key válida, mas sem o escopo `earnings:read`.
**Quem nunca recebeu não é erro.** A resposta vem com zeros e decomposições vazias, em status 200 — e esse zero é uma medição: a pessoa existe e não tem pagamento. Diferente de `found: false`.
***
## Limites de uso
| Limite | Valor |
| -------------------------------------- | ----- |
| Requisições por hora (padrão) | 1000 |
| Máximo de colaboradores por requisição | 500 |
***
## Segurança
* Somente leitura: esta API nunca cria, aprova ou altera um pagamento
* Cada chave pertence a uma única empresa — dinheiro de outra empresa nunca aparece, nem para a mesma pessoa
* Valores e documentos **nunca** vão para os logs; apenas contagens
***
## Próximos passos
Nível, XP, moedas e ranking
A vitrine de onde vêm esses prêmios