Desenvolvedores · Documentação técnica

Arena Upya

API Commissions

Relatório de comissões, regras e modo de cálculo. Sem endpoint de “pagar comissão”.

Leituracommissions.read

Escritacommissions.write

Endpoints

Método	Rota	Escopo	Descrição
`GET`	`/api/v1/commissions/report`	`commissions.read`	Relatório (?from,&to,&campaign_id,&format=csv)
`GET`	`/api/v1/commissions/rules`	`commissions.read`	Listar regras
`POST`	`/api/v1/commissions/rules`	`commissions.write`	Criar regra
`PATCH`	`/api/v1/commissions/rules/{id}`	`commissions.write`	Atualizar regra
`DELETE`	`/api/v1/commissions/rules/{id}`	`commissions.write`	Excluir regra
`GET`	`/api/v1/commissions/settings`	`commissions.read`	Modo de cálculo
`PATCH`	`/api/v1/commissions/settings`	`commissions.write`	Atualizar modo (flat\|progressive)

Por endpoint — assinaturas e exemplos

Parâmetros

Campo	Em	Tipo	Obrig.	Descrição
`from`	`query`	`string`	não	Y-m-d
`to`	`query`	`string`	não	Y-m-d
`campaign_id`	`query`	`integer`	não	Filtrar campanha
`format`	`query`	`string`	não	json (default) ou csv

CommissionReport

Objeto `report` retornado por `GET /commissions/report`.

Campo	Tipo	Obrig.	Descrição
`rows`	`array<CommissionReportRow>`	não	—
`totals`	`object`	não	—
`from`	`string (date)`	não	— ex.: `"2026-03-01"`
`to`	`string (date)`	não	— ex.: `"2026-03-31"`
`campaign_id`	`integer \| null`	não	—
`calc_mode`	`string · flat \| progressive`	não	— ex.: `"flat"`

CommissionReportRow

Linha do relatório por vendedor.

Campo	Tipo	Obrig.	Descrição
`seller_id`	`integer`	não	— ex.: `44`
`seller_name`	`string`	não	— ex.: `"Ana Silva"`
`seller_email`	`string \| null`	não	— ex.: `"ana@empresa.com"`
`entries_count`	`integer`	não	— ex.: `12`
`sales_total`	`number`	não	— ex.: `15000`
`percent`	`number`	não	— ex.: `3`
`commission`	`number`	não	— ex.: `450`
`rule_name`	`string`	não	— ex.: `"Padrão 3%"`
`rule_id`	`integer \| null`	não	— ex.: `2`
`breakdown`	`array<object>`	não	Faixas (modo progressive); vazio no flat.

data.report + data.from + data.to

Exemplo

Response 2xx

{
    "status": "success",
    "data": {
        "report": {
            "rows": [
                {
                    "seller_id": 44,
                    "seller_name": "Ana Silva",
                    "seller_email": "ana@empresa.com",
                    "entries_count": 12,
                    "sales_total": 15000,
                    "percent": 3,
                    "commission": 450,
                    "rule_name": "Padrão 3%",
                    "rule_id": 2,
                    "breakdown": []
                }
            ],
            "totals": {
                "sales_total": 15000,
                "commission": 450,
                "sellers": 1
            },
            "from": "2026-03-01",
            "to": "2026-03-31",
            "campaign_id": null,
            "calc_mode": "flat"
        },
        "from": "2026-03-01",
        "to": "2026-03-31"
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

CommissionRule

Regra de comissão.

Campo	Tipo	Obrig.	Descrição
`id`	`integer`	não	ID. ex.: `2`
`name`	`string`	não	Nome da regra. ex.: `"Padrão 3%"`
`percent`	`number`	não	Percentual. ex.: `3`
`campaign_id`	`integer \| null`	não	Escopo de campanha (`null` = geral).
`seller_id`	`integer \| null`	não	Escopo de seller (`null` = geral).
`is_active`	`integer`	não	`1` ativa. ex.: `1`

Exemplo

Response 2xx

{
    "status": "success",
    "data": {
        "items": [
            {
                "id": 2,
                "name": "Padrão 3%",
                "percent": 3,
                "is_active": 1
            }
        ]
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

CommissionRuleCreate — body

Body para criar regra de comissão.

Campo	Tipo	Obrig.	Descrição
`name`	`string`	sim	Nome. ex.: `"Padrão 3%"`
`percent`	`number`	sim	Percentual. ex.: `3`
`campaign_id`	`integer`	não	Restringir à campanha.
`seller_id`	`integer`	não	Restringir ao seller.
`min_amount`	`number`	não	Faixa mínima (opcional).
`max_amount`	`number`	não	Faixa máxima (opcional).
`priority`	`integer`	não	Prioridade de resolução.
`is_active`	`boolean`	não	Default `true`. ex.: `true`

CommissionRule

Regra de comissão.

Campo	Tipo	Obrig.	Descrição
`id`	`integer`	não	ID. ex.: `2`
`name`	`string`	não	Nome da regra. ex.: `"Padrão 3%"`
`percent`	`number`	não	Percentual. ex.: `3`
`campaign_id`	`integer \| null`	não	Escopo de campanha (`null` = geral).
`seller_id`	`integer \| null`	não	Escopo de seller (`null` = geral).
`is_active`	`integer`	não	`1` ativa. ex.: `1`

Exemplo

Request POST (body)

{
    "name": "Padrão 3%",
    "percent": 3,
    "is_active": true
}

Response 2xx

{
    "status": "success",
    "data": {
        "rule": {
            "id": 2,
            "name": "Padrão 3%",
            "percent": 3,
            "is_active": 1
        }
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

Parâmetros

Campo	Em	Tipo	Obrig.	Descrição
`id`	`path`	`integer`	sim	ID do recurso na empresa

CommissionRuleCreate — body

Body para criar regra de comissão.

Campo	Tipo	Obrig.	Descrição
`name`	`string`	sim	Nome. ex.: `"Padrão 3%"`
`percent`	`number`	sim	Percentual. ex.: `3`
`campaign_id`	`integer`	não	Restringir à campanha.
`seller_id`	`integer`	não	Restringir ao seller.
`min_amount`	`number`	não	Faixa mínima (opcional).
`max_amount`	`number`	não	Faixa máxima (opcional).
`priority`	`integer`	não	Prioridade de resolução.
`is_active`	`boolean`	não	Default `true`. ex.: `true`

CommissionRule

Regra de comissão.

Campo	Tipo	Obrig.	Descrição
`id`	`integer`	não	ID. ex.: `2`
`name`	`string`	não	Nome da regra. ex.: `"Padrão 3%"`
`percent`	`number`	não	Percentual. ex.: `3`
`campaign_id`	`integer \| null`	não	Escopo de campanha (`null` = geral).
`seller_id`	`integer \| null`	não	Escopo de seller (`null` = geral).
`is_active`	`integer`	não	`1` ativa. ex.: `1`

Exemplo

Request PATCH (body)

{
    "name": "Padrão 3%",
    "percent": 3.5
}

Response 2xx

{
    "status": "success",
    "data": {
        "rule": {
            "id": 2,
            "name": "Padrão 3%",
            "percent": 3.5,
            "is_active": 1
        }
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

Parâmetros

Campo	Em	Tipo	Obrig.	Descrição
`id`	`path`	`integer`	sim	ID do recurso na empresa

DeletedResult

Campo	Tipo	Obrig.	Descrição
`deleted`	`boolean`	não	Sempre `true` quando excluído. ex.: `true`

Exemplo

Response 2xx

{
    "status": "success",
    "data": {
        "deleted": true
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

CommissionSettings

Modo de cálculo de comissão.

Campo	Tipo	Obrig.	Descrição
`commission_calc`	`string · flat \| progressive`	não	`flat` = regra única; `progressive` = faixas. ex.: `"flat"`

Exemplo

Response 2xx

{
    "status": "success",
    "data": {
        "commission_calc": "progressive"
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

CommissionSettings — body

Modo de cálculo de comissão.

Campo	Tipo	Obrig.	Descrição
`commission_calc`	`string · flat \| progressive`	não	`flat` = regra única; `progressive` = faixas. ex.: `"flat"`

CommissionSettings

Modo de cálculo de comissão.

Campo	Tipo	Obrig.	Descrição
`commission_calc`	`string · flat \| progressive`	não	`flat` = regra única; `progressive` = faixas. ex.: `"flat"`

Exemplo

Request PATCH (body)

{
    "commission_calc": "flat"
}

Response 2xx

{
    "status": "success",
    "data": {
        "commission_calc": "flat"
    },
    "meta": {
        "request_id": "a1b2c3d4e5f6789012345678"
    }
}

curl — relatório

curl "https://arenaupya.com.br/api/v1/commissions/report?from=2026-03-01&to=2026-03-31" \
  -H "Authorization: Bearer arena_live_SEU_TOKEN"

Endpoints

Por endpoint — assinaturas e exemplos

GET /api/v1/commissions/reportRelatório de comissões

Parâmetros

CommissionReport

CommissionReportRow

Exemplo

GET /api/v1/commissions/rulesListar regras

CommissionRule

Exemplo

POST /api/v1/commissions/rulesCriar regra

CommissionRuleCreate — body

CommissionRule

Exemplo

PATCH /api/v1/commissions/rules/{id}Atualizar regra

Parâmetros

CommissionRuleCreate — body

CommissionRule

Exemplo

DELETE /api/v1/commissions/rules/{id}Excluir regra

Parâmetros

DeletedResult

Exemplo

GET /api/v1/commissions/settingsModo de cálculo

CommissionSettings

Exemplo

PATCH /api/v1/commissions/settingsAtualizar modo

CommissionSettings — body

CommissionSettings

Exemplo

curl — relatório