Referência da API

Afiliados

Código de apoiador, como nos jogos: o cliente digita o código de um criador no carrinho ou com /apoiar, e cada compra paga dá comissão a ele. Vendas com afiliado disparam AFFILIATE_SALE.

Rotas deste grupo7

GET/affiliatesListar afiliadosaffiliates:read
POST/affiliatesCriar afiliadoaffiliates:create
GET/affiliates/{id}Ver um afiliadoaffiliates:read
PATCH/affiliates/{id}Editar afiliadoaffiliates:update
DELETE/affiliates/{id}Apagar afiliadoaffiliates:delete
GET/affiliates/{id}/payoutsPagamentos de comissãoaffiliates:read
POST/affiliates/{id}/payoutsMarcar comissão como pagaaffiliates:update

Listar afiliados

GET/api/v1/affiliates

Com as métricas: vendas, comissão a pagar e já paga, apoiadores.

Permissão: affiliates:read

Parâmetros da URL

`active`	booleano	Valendo ou pausados.
`page`	inteiro	Página, a partir de 1. Padrão 1.
`per_page`	inteiro	Itens por página, de 1 a 100. Padrão 20.

Exemplo

curl

curl https://zolvibot.app/api/v1/affiliates \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "data": [
    {
      "id": "cmw9a1b2c0001ss11aaaa1111",
      "name": "Dusty",
      "code": "DUSTY",
      "discord_id": "1390611228354809977",
      "commission_percent": 10,
      "active": true,
      "metrics": {
        "sales": 14,
        "revenue_cents": 41860,
        "commission_total_cents": 4186,
        "commission_pending_cents": 1290,
        "commission_paid_cents": 2896,
        "supporters": 9
      },
      "created_at": "2026-11-01T12:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "last_page": 1
  }
}

Criar afiliado

POST/api/v1/affiliates

Até 200 por loja.

Permissão: affiliates:create

Corpo (JSON)

`name`obrigatório	texto	Nome que o cliente vê no carrinho.
`code`obrigatório	texto	3 a 20 letras, números, - ou _.
`commission_percent`obrigatório	inteiro	Comissão, de 1 a 90.
`discord_id`	texto \| null	ID do Discord do afiliado (ele recebe uma DM a cada venda).
`active`	booleano	Valendo (padrão true).

Exemplo

curl

curl -X POST https://zolvibot.app/api/v1/affiliates \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"Dusty","code":"DUSTY","commission_percent":10}'

Resposta 201

{
  "id": "cmw9a1b2c0001ss11aaaa1111",
  "name": "Dusty",
  "code": "DUSTY",
  "discord_id": "1390611228354809977",
  "commission_percent": 10,
  "active": true,
  "metrics": {
    "sales": 14,
    "revenue_cents": 41860,
    "commission_total_cents": 4186,
    "commission_pending_cents": 1290,
    "commission_paid_cents": 2896,
    "supporters": 9
  },
  "created_at": "2026-11-01T12:00:00.000Z"
}

Ver um afiliado

GET/api/v1/affiliates/{id}

Pelo id ou pelo código.

Permissão: affiliates:read

Exemplo

curl

curl https://zolvibot.app/api/v1/affiliates/ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "id": "cmw9a1b2c0001ss11aaaa1111",
  "name": "Dusty",
  "code": "DUSTY",
  "discord_id": "1390611228354809977",
  "commission_percent": 10,
  "active": true,
  "metrics": {
    "sales": 14,
    "revenue_cents": 41860,
    "commission_total_cents": 4186,
    "commission_pending_cents": 1290,
    "commission_paid_cents": 2896,
    "supporters": 9
  },
  "created_at": "2026-11-01T12:00:00.000Z"
}

Editar afiliado

PATCH/api/v1/affiliates/{id}

name, code, discord_id, commission_percent e active. A comissão nova vale para as próximas vendas.

Permissão: affiliates:update

Exemplo

curl

curl -X PATCH https://zolvibot.app/api/v1/affiliates/ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"commission_percent":15}'

Resposta 200

{
  "id": "cmw9a1b2c0001ss11aaaa1111",
  "name": "Dusty",
  "code": "DUSTY",
  "discord_id": "1390611228354809977",
  "commission_percent": 15,
  "active": true,
  "metrics": {
    "sales": 14,
    "revenue_cents": 41860,
    "commission_total_cents": 4186,
    "commission_pending_cents": 1290,
    "commission_paid_cents": 2896,
    "supporters": 9
  },
  "created_at": "2026-11-01T12:00:00.000Z"
}

Apagar afiliado

DELETE/api/v1/affiliates/{id}

Só sem vendas; com vendas, pause com active: false.

Permissão: affiliates:delete

Exemplo

curl

curl -X DELETE https://zolvibot.app/api/v1/affiliates/ID \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "deleted": true,
  "id": "cmw9a1b2c0001ss11aaaa1111"
}

Pagamentos de comissão

GET/api/v1/affiliates/{id}/payouts

Os 100 mais recentes.

Permissão: affiliates:read

Exemplo

curl

curl https://zolvibot.app/api/v1/affiliates/ID/payouts \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE"

Resposta 200

{
  "data": [
    {
      "id": "cmw9p4y0u0001sspayout0001",
      "amount_cents": 2896,
      "orders": 9,
      "paid_by": "API: Financeiro",
      "created_at": "2026-11-05T18:00:00.000Z"
    }
  ]
}

Marcar comissão como paga

POST/api/v1/affiliates/{id}/payouts

Marca toda a comissão em aberto. Envie expected_cents igual ao commission_pending_cents que você viu: se entrou venda nova no meio, nada é marcado e a resposta é 409.

Permissão: affiliates:update

Corpo (JSON)

expected_centsobrigatório inteiro O valor que você vai pagar.

Exemplo

curl

curl -X POST https://zolvibot.app/api/v1/affiliates/ID/payouts \
  -H "Authorization: Bearer zv_sk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"expected_cents":1290}'

Resposta 201

{
  "id": "cmw9q8z1v0001sspayout0002",
  "amount_cents": 1290,
  "orders": 4,
  "created_at": "2026-11-08T22:00:00.000Z"
}