Splits de recebíveis

Os splits dividem a receita de cada cobrança da assinatura entre destinatários (recipients). Cada

Os splits dividem a receita de cada cobrança da assinatura entre destinatários (recipients). Cada split define um percentual ou um valor fixo para um destinatário. Os IDs de split usam o prefixo ssp_ (também aceitamos o legado split_).

Operação	Método	Endpoint	Retorna
Adicionar	POST	`/v1/subscriptions/{id}/splits`	coleção de splits (`201`)
Listar	GET	`/v1/subscriptions/{id}/splits`	lista paginada de splits
Consultar	GET	`/v1/subscriptions/{id}/splits/{splitId}`	split
Atualizar	PATCH	`/v1/subscriptions/{id}/splits/{splitId}`	split
Remover	DELETE	`/v1/subscriptions/{id}/splits/{splitId}`	coleção de splits

Campos do split

Na requisição (adicionar/atualizar):

Campo	Tipo	Descrição
`recipient`	string	`publicId` da empresa destinatária (ex.: `bus_...`). Apenas no adicionar
`type`	enum	`percentage` ou `flat`
`value`	number	Percentual (0–100) quando `type=percentage`, ou valor fixo quando `type=flat` (0–999999,99)

Na resposta, cada split também traz chargeProcessingFee e liable (booleans, regras de taxa e responsabilidade por chargeback), além de id, updatedAt, createdAt.

Adicionar split

POST /v1/subscriptions/{subscriptionId}/splits

curl -X POST "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{ "recipient": "bus_other", "type": "percentage", "value": 30 }'

A resposta 201 Created é a coleção completa de splits da assinatura + totais (não a assinatura inteira). remainingAmount é uma string (centavos restantes da base recorrente após os splits flat).

{
  "subscription": "subs_01hqzvabc",
  "splits": [
    {
      "id": "ssp_01hqzvabc",
      "recipient": "bus_other",
      "type": "percentage",
      "value": 30,
      "chargeProcessingFee": true,
      "liable": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "totalPercentage": 30,
  "remainingPercentage": 70,
  "remainingAmount": "6930",
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": {
    "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "POST" },
    "list": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "GET" }
  }
}

O campo subscription é o publicId (string) da assinatura, não um objeto. remainingPercentage/remainingAmount indicam quanto da receita ainda não foi alocado.

Listar splits

GET /v1/subscriptions/{subscriptionId}/splits

{
  "offset": 0, "limit": 20, "total": 1, "hasMore": false,
  "page": { "current": 1, "total": 1, "offset": { "first": 0, "prev": null, "next": null, "last": 0 } },
  "data": [
    {
      "id": "ssp_01hqzvabc",
      "recipient": "bus_other",
      "type": "percentage",
      "value": 30,
      "chargeProcessingFee": true,
      "liable": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "merchant": { "name": "Seller Name", "merchantId": "bus_1234567890", "isSubAccount": false },
  "_links": { "self": { "href": "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits", "method": "GET" } }
}

Consultar / Atualizar / Remover split

GET /v1/subscriptions/{subscriptionId}/splits/{splitId} — retorna o objeto do split.
PATCH /v1/subscriptions/{subscriptionId}/splits/{splitId} — atualiza type e value (o destinatário não muda) e retorna o split atualizado (200 OK).
DELETE /v1/subscriptions/{subscriptionId}/splits/{splitId} — remove o split e retorna a coleção atualizada (com remainingPercentage/remainingAmount recalculados).

Exemplo de atualização:

curl -X PATCH "https://api.selectwin.io/v1/subscriptions/subs_01hqzvabc/splits/ssp_01hqzvabc" \
  -H "SelectKey: sk_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{ "type": "percentage", "value": 25 }'

Erros

`error.code`	HTTP	Quando
`subscriptionNotFound`	404	Assinatura inexistente
`splitNotFound`	404	Split inexistente
`splitRecipientNotFound`	404	Destinatário inexistente
`duplicateSplitRecipient`	422	Já existe split para esse destinatário
`subscriptionNotModifiable`	422	A assinatura está cancelada