API de Ganhos

Esta página pressupõe as regras comuns em Convenções da API — 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

Você recebe uma API Key com o escopo earnings:read
Seu backend consulta um ou vários colaboradores (por CPF ou e-mail)
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

string

obrigatório

Deve ser "earnings_status"

array

obrigatório

Lista de referências de colaboradores (máximo 500)

Exemplo

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):

{
  "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 para os dois formatos e a tabela de códigos.

400 — VALIDATION_ERROR

Corpo inválido, lote acima de 500, CPF sem 11 dígitos, ou item sem cpf e sem email.

403 — FORBIDDEN

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

Visão Geral

Integrações

API de Ganhos

API de Ganhos

Como funciona

Autenticação

Referência do endpoint

Esquema da requisição

Exemplo

Campos

Tipos de pagamento

Estágios do a receber

Tratamento de erros

Limites de uso

Segurança

Próximos passos

API de Progresso

API de Campanhas

​API de Ganhos

​Como funciona

​Autenticação

​Referência do endpoint

​Esquema da requisição

​Exemplo

​Campos

​Tipos de pagamento

​Estágios do a receber

​Tratamento de erros

​Limites de uso

​Segurança

​Próximos passos

API de Progresso

API de Campanhas

API de Ganhos

Como funciona

Autenticação

Referência do endpoint

Esquema da requisição

Exemplo

Campos

Tipos de pagamento

Estágios do a receber

Tratamento de erros

Limites de uso

Segurança

Próximos passos